Sandbox Runtimes
Each gateway runs agent workloads on one compute runtime, selected by its compute driver. Pick the runtime that matches the isolation boundary and infrastructure you need. The CLI workflow stays the same across runtimes: you create, connect to, stop, start, and delete sandboxes through the gateway.
The gateway owns main-process restart policy. Docker, Podman, Kubernetes, and MicroVM native restart mechanisms remain disabled. When policy selects a replacement, the gateway stops and starts the compute resource while retaining the sandbox record and driver-supported persistent storage.
Select a Compute Driver
Set compute_driver in the gateway TOML file. A gateway uses one driver at a time.
Every gateway TOML file must start with the [openshell] table and version = 2, or openshell-gateway config preflight rejects it with missing_version. The remaining examples on this page show only the tables they change.
When compute_driver is unset, the gateway auto-detects Kubernetes, then Podman, then Docker. The VM driver is never auto-detected.
Configure driver-specific values, such as images, endpoints, and sizing, under [openshell.drivers.<name>]. See the Gateway Configuration File reference for every option.
Docker, Podman, and Kubernetes also accept process overrides for the trusted
sandbox-runtime and supervisor images through
OPENSHELL_SANDBOX_RUNTIME_IMAGE and OPENSHELL_SUPERVISOR_IMAGE. The
environment overrides values in the selected driver’s TOML table, and the
driver TOML overrides the compiled release defaults. Helm renders Kubernetes
image fields into TOML, so they apply when these environment variables are
unset. Sandbox requests cannot override either trusted image.
When building your own gateway or supervisor image, the GATEWAY_BASE_IMAGE
and SUPERVISOR_BASE_IMAGE build arguments override their pinned bases. See
Container Image Base Overrides
for build commands and base compatibility requirements.
For TLS-enabled Docker, Podman, and MicroVM gateways, set guest_tls_ca in
[openshell.gateway] or use the package-managed local CA. Remove the retired
guest_tls_cert and guest_tls_key fields. Supervisors receive only the
CA and authenticate gateway RPCs with sandbox bearer tokens. Kubernetes
projects or stages only the gateway CA from its configured TLS Secret; user
client certificates and private keys stay outside the sandbox boundary.
Extension Drivers
Any name other than a built-in driver selects an extension driver. Point the gateway at the Unix socket where the driver listens:
The gateway does not start or supervise extension drivers. Restrict the socket so only the gateway user can access it.
Size Sandboxes
Use --cpu, --memory, and --gpu on openshell sandbox create to request resources. --gpu alone requests one GPU; --gpu COUNT requests more.
Pass Driver Config
--driver-config-json passes driver-specific settings that have no dedicated flag. The value is a JSON object keyed by driver name, and the gateway forwards only the block for the active driver:
Driver config is disabled by default. Enable it with allow_driver_config = true in the driver’s gateway configuration. Attached resources such as volumes must carry operator-approved labels. See External Resource Admission.
To pin specific GPUs, pass cdi_devices for Docker or Podman, or gpu_device_ids for MicroVM, together with --gpu:
Docker Driver
Docker runs sandboxes as containers on the Docker daemon host. The gateway accesses the daemon through its configured Unix socket. Docker is also required to build sandbox images from local directories or Dockerfiles.
Common options in [openshell.drivers.docker] are socket_path, grpc_endpoint, supervisor_network_mode, host_gateway_ip, sandbox_runtime_image, supervisor_image, image_pull_policy, and sandbox_pids_limit. When socket_path is unset, the driver uses the socket found by auto-detection.
supervisor_network_mode defaults to host. Set bridge to use Docker bridge networking; auto also selects host. The workload always retains network=none.
Host mode on Docker Desktop requires host networking enabled. Bridge mode automatically uses host.docker.internal for a gateway on the Desktop host. On native Linux, the gateway and host services must listen on bridge-reachable addresses. Set grpc_endpoint for remote gateways, remapped published ports, or other custom layouts. Endpoint selection preserves TLS verification and does not change the gateway’s listener. See Docker configuration.
OpenShell discovers Docker’s host address automatically in bridge mode. Set host_gateway_ip only to override discovery.
The sandbox must pass its Landlock and seccomp qualification in either network mode. For GPU sandboxes, configure Docker CDI before starting the gateway.
Docker Corporate Proxy Egress
For proxy-required networks, the Docker driver accepts https_proxy,
no_proxy, proxy_auth_file, proxy_auth_allow_insecure,
proxy_connect_by_hostname, and proxy_ca_bundle. The companion supervisor
chains policy-approved TLS tunnels through the proxy with HTTP CONNECT.
proxy_ca_bundle is an operator-owned gateway-host PEM path. Docker validates
and copies the bundle into its supervisor-only named volume, so this also works
with remote Docker daemons and does not expose the host path to the workload.
The supervisor uses the bundle for an HTTPS proxy connection and for upstream
certificates re-signed by a TLS-intercepting proxy. Workload processes receive
the same corporate roots through their generated combined trust bundle.
Sandbox environment, image contents, and template.driver_config.docker
cannot alter these settings. Invalid proxy relationships or CA files prevent
the gateway or sandbox from starting and never degrade to direct egress. See
the Gateway Configuration File for URL,
authentication, NO_PROXY, hostname CONNECT, and CA validation details.
Docker Mounts
Mount existing named volumes or tmpfs through driver config. Label volumes so resource admission accepts them:
Bind mounts expose gateway-host files to the sandbox and can bypass workspace isolation and filesystem policy. They require enable_bind_mounts = true and disabling resource admission for the driver:
Mount targets cannot replace the workspace root, the container root, or OpenShell paths under /opt/openshell, /etc/openshell, and /run/openshell.
Podman Driver
Podman runs sandboxes as rootless containers on the gateway host. It requires Podman 5.x, cgroups v2, and an active Podman user socket:
Common options in [openshell.drivers.podman] are socket_path, network_name, sandbox_runtime_image, supervisor_image, image_pull_policy, stop_timeout_secs, and grpc_endpoint. When socket_path is unset, the driver finds the socket automatically, including podman machine sockets on macOS.
On macOS, set host_gateway_ip only if your Podman machine uses a non-standard host-loopback address. Set grpc_endpoint when the gateway is remote.
For networks that require a corporate proxy, set https_proxy, no_proxy, and related proxy_* options. See the Gateway Configuration File reference.
To trust a private CA for direct, policy-inspected HTTPS egress without a corporate proxy — for example, because the supervisor container cannot inherit a private CA baked into the workload image — set additional_ca_bundle. Both the supervisor and the workload trust the CA for all destinations, so use a CA you control. See the Gateway Configuration File reference for details.
Podman Mounts
Podman supports the same volume, tmpfs, and bind mounts as Docker, using the podman key in driver config, and the same bind-mount warning applies. Podman volume mounts do not support subpath.
Podman also supports image mounts, which mount a container image read-only at target. Image mounts require disabling resource admission.
MicroVM Driver
The MicroVM driver runs each sandbox in its own lightweight VM. It requires host virtualization: Apple Hypervisor on macOS or KVM on Linux.
The VM driver is opt-in. Enable it in the gateway TOML file:
You can also set OPENSHELL_COMPUTE_DRIVER=vm in the gateway environment.
Common options in [openshell.drivers.vm] are default_image, bootstrap_image, vcpus, mem_mib, overlay_disk_mib, state_dir, and grpc_endpoint. The default image is nvcr.io/nvidia/base/ubuntu:24.04. Use an image that includes the agents and tools your workloads need.
The driver looks up sandbox images in local Docker or Podman before pulling from a registry. On Linux with Podman, start podman.socket so the driver can find local images.
Registry downloads must match the resolved image digest, including the selected platform for multi-platform images. A mismatch fails image preparation. After upgrading, the driver rebuilds older bootstrap and prepared-image cache entries on first use, so the first sandbox start can take longer.
VM sandboxes have no network interface. All traffic flows through the OpenShell supervisor on the host. For networks that require a corporate proxy, the VM driver accepts the same https_proxy and proxy_* options as Podman. To reach a proxy on the gateway host, use http://host.openshell.internal:<port>.
If the gateway is briefly unavailable while a VM starts, its supervisor retries the session connection. The sandbox stays in provisioning until the gateway accepts the session.
MicroVM Stop Durability
When you run openshell sandbox stop while the main process is running, OpenShell terminates the workload and flushes the guest root filesystem before acknowledging termination. The guest waits up to three seconds for the flush. The host allows up to 22 seconds for supervisor shutdown, then up to five seconds to stop the VM.
Flush errors and timeouts produce warnings while shutdown continues. If a signal kills the supervisor, the driver warns that the guest flush was not confirmed and recent writes may be lost. A completed stop does not guarantee persistence after a failed or timed-out flush. This flush does not cover stops after the main process has already exited.
MicroVM Mounts
The VM driver shares gateway-host directories into the guest with virtiofs. Each entry in mounts takes source (absolute host directory), target, optional read_only (default true), and optional type, which must be bind so Docker and Podman bind entries work unchanged:
A sandbox takes at most 32 mounts on an arm64 gateway host and three on an x86_64 host. Single-file sources, sources that are symbolic links, selinux_label, and other mount types are not supported. VM mounts work only with the libkrun backend, so GPU sandboxes cannot use them.
VM bind mounts expose host files to sandbox workloads. Additionally, libkrun does not confine a compromised guest kernel to the configured source directory; it may access other host files permitted by the gateway user’s permissions. VM mounts require the same opt-in as Docker bind mounts:
Targets cannot replace the workspace root, OpenShell paths, or VM-internal paths such as /tmp, /proc, /dev, and /srv, and cannot be nested inside one another. The guest refuses a target that passes through a symlink in the image.
On Linux with a non-root gateway, the sandbox can create files in a read-write mount only when its UID and GID match the gateway user’s. Set sandbox_uid and sandbox_gid under [openshell.drivers.vm] to match. Otherwise the sandbox cannot create files, and its access to existing files follows the host permission bits for its numeric UID and GID.
Kubernetes Driver
The Kubernetes driver runs sandboxes as pods in a sandbox namespace. It requires the Agent Sandbox controller. Install the gateway with the Helm chart; see Kubernetes setup.
The cluster CNI must enforce NetworkPolicy in every sandbox namespace. Without it, sandbox pods can bypass OpenShell network policy.
Only the OpenShell gateway and the Agent Sandbox controller should be able to manage sandbox pods and the sandbox ServiceAccount in those namespaces.
For the full list, see the Gateway Configuration File reference.
On OpenShift, copy the cluster proxy’s CA into the gateway namespace and set upstreamProxy.caBundle.configMapName to corporate-proxy-ca:
After upgrading Agent Sandbox, restart the gateway.
Workspace storage settings cannot change after a sandbox is created. Delete and recreate the sandbox to change them.
Kubernetes PVC Mounts
Mount existing PersistentVolumeClaims into the agent container through driver config. Any mount under /sandbox replaces the default workspace PVC for that sandbox.
Sandbox User Identity
On Docker and Podman, set process.run_as_user and process.run_as_group in the creation policy to choose the sandbox user. Selectors accept sandbox or numeric IDs from 1 through 4294967294. Kubernetes and MicroVM select the identity through driver configuration. When a field is unset, the driver supplies it:
MicroVM persists the resolved UID:GID with the writable overlay and retains it across restarts, even if driver defaults change. Explicit policy selectors must match that identity. For example, run_as_user: "10000" fails when the overlay owner is 1000:1000; OpenShell reports both values without changing file ownership. The symbolic selector sandbox refers to the guest account for that owner, and each omitted selector accepts its driver default. The WorkloadIdentity condition in openshell sandbox get <name> shows the resolved pair separately from workload readiness. Canonical and exec processes use this same pair; live policy updates cannot change it.
On Docker and Podman, the image’s WORKDIR becomes the workspace. Images with no WORKDIR, /, or /sandbox use /sandbox. Any other WORKDIR must exist in the image and be writable by the sandbox user. Kubernetes and MicroVM always use /sandbox.
Custom Docker and Podman workspaces use the workload container’s writable layer, not a managed named volume. Files survive stop/start of the same container, but removing or replacing that container removes its workspace changes. Export files you need to retain before deleting the sandbox.