Drivers

OpenShell uses drivers to connect the gateway to workload runtimes and credential stores. Drivers implement a stable capability boundary while the gateway owns the public API, authorization, workspace scoping, and resource lifecycle.

Compute Drivers

Compute drivers create, inspect, and delete sandbox workloads. OpenShell ships drivers for Kubernetes, Docker, Podman, virtual machines, and Windows MXC. An external compute driver communicates with the gateway over a Unix domain socket and negotiates its protocol version and capabilities before serving requests.

For built-in driver configuration and behavior, refer to Runtimes. For implementation details, refer to each driver crate:

Using an External Compute Driver

External compute drivers must implement compute_driver.proto. Refer to Protocol Negotiation for the metadata and capability requirements, and Isolation Backends for the workload runtime contract. Your driver must also acknowledge the gateway’s resource admission policy.

Run your driver as a separate service listening on a Unix domain socket. The gateway does not start or supervise it. Restrict socket access to the gateway user and make the socket accessible from the gateway’s host or container.

Select a name that is not reserved by a built-in driver, then add it and the socket path to your existing gateway.toml:

[openshell]
version = 2
[openshell.gateway]
compute_driver = "example-compute"
[openshell.drivers.example-compute]
socket_path = "/run/openshell/example-compute.sock"

Start the driver, then start or restart the gateway with this configuration. Use openshell gateway info from a CLI connected to that gateway to verify the active driver and negotiated capabilities. See the Extension Driver configuration reference for configuration details.

Credential Drivers

Credential drivers store provider credentials behind opaque handles. The gateway resolves those handles when a provider is attached without persisting the secret value in the provider record. OpenShell includes database, Kubernetes Secret, and Vault-compatible credential drivers.

Configure the active credential driver in the Gateway Configuration. For implementation details, refer to each driver crate:

External credential drivers implement credential_driver.proto.

Compatibility

Drivers exchange peer metadata with the gateway and advertise their extension family capability. Upgrade both peers together when the protocol version changes. Refer to Extension Protocol Negotiation for the negotiation contract.