> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/openshell/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/openshell/_mcp/server. # Sandbox Compute Drivers > Reference for Docker, Podman, MicroVM, and Kubernetes sandbox compute drivers. The gateway's configured compute driver determines how OpenShell creates each sandbox. The CLI workflow stays the same across drivers: you create, connect to, inspect, and delete sandboxes through the gateway API. Every compute driver runs the OpenShell supervisor inside the sandbox workload. The supervisor launches the agent process, applies policy, routes egress through the proxy, injects configured credentials, and maintains the gateway session. ## Configure a Compute Driver Configure the compute driver on the gateway. Current releases accept one driver per gateway. Set `compute_drivers` in the gateway TOML file: ```toml [openshell.gateway] compute_drivers = ["docker"] ``` Reserved built-in values are `docker`, `podman`, `kubernetes`, and `vm`. Non-reserved names select an extension driver and require a `socket_path` in `[openshell.drivers.]`. When `compute_drivers` is unset, the gateway auto-detects Kubernetes, then Podman, then Docker by CLI availability or a local Unix socket. The VM driver is never auto-detected; configure it explicitly with `compute_drivers = ["vm"]` or set `OPENSHELL_DRIVERS=vm` in the launch environment. Common gateway options: | Gateway TOML option | Description | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `compute_drivers = [""]` | Select the compute driver. Built-in values are `docker`, `podman`, `kubernetes`, and `vm`; custom names require `[openshell.drivers.].socket_path`. | Set driver-specific values such as sandbox images, callback endpoints, network names, TLS material, and VM sizing in the gateway TOML file. See the [Gateway Configuration File](./gateway-config) reference for the full `[openshell.drivers.]` schema. Extension drivers use the same `compute_driver.proto` gRPC surface as the managed VM driver. For an out-of-tree driver, choose a driver name and point the gateway at the Unix socket the operator has already provisioned: ```toml [openshell.gateway] compute_drivers = ["kyma"] [openshell.drivers.kyma] socket_path = "/run/openshell/kyma.sock" ``` For a launch-time socket override, pass the same non-reserved driver name with the socket path: ```shell openshell-gateway --drivers kyma --compute-driver-socket /run/openshell/kyma.sock ``` The gateway does not spawn, supervise, or delete extension drivers. The operator must protect the socket so only the gateway uid can access it. Reserved built-in names cannot be selected through unmanaged socket endpoints. Sandbox create supports `--cpu` and `--memory` for per-sandbox compute sizing. Docker and Podman apply them as runtime limits. Kubernetes applies them as both container requests and limits. The VM driver accepts the fields but currently ignores them. Sandbox create also accepts experimental driver-owned config through `--driver-config-json`. The value is a JSON object keyed by driver name. The gateway forwards only the block for the active driver, so a Kubernetes gateway receives the `kubernetes` object from a value such as: Nested keys inside each driver block use snake\_case. The top-level envelope keys are driver names, such as `kubernetes`, and are not part of the nested schema. ```shell openshell sandbox create \ --driver-config-json '{"kubernetes":{"pod":{"runtime_class_name":"kata-containers","priority_class_name":"batch-low"}}}' \ -- claude ``` Driver config is for fields without a stable public flag. Prefer `--cpu`, `--memory`, and `--gpu` for supported resource intent. When `--gpu` is present without a count, OpenShell treats it as a request for one GPU. Pass `--gpu COUNT` when requesting more than one GPU. Kubernetes maps the GPU count to the `nvidia.com/gpu` pod resource limit. Docker and Podman satisfy count-only GPU requests by selecting the requested number of NVIDIA CDI devices from the local CDI inventory in round-robin order. The drivers refresh the CDI inventory before validating or creating the sandbox, so CDI devices added or removed after gateway start can affect later creates. On WSL2 all-only runtimes, Docker or Podman can use `nvidia.com/gpu=all` as a compatibility fallback, where it counts as one selectable device. Exact GPU device selection remains driver-owned and requires `--gpu`. Docker and Podman accept `cdi_devices` as opaque CDI device names; replace the top-level `docker` key with `podman` when using the Podman driver, for example `{"docker":{"cdi_devices":["nvidia.com/gpu=0"]}}`. Explicit CDI device lists must not contain duplicates, and their length must match the effective GPU count. A single exact CDI device is compatible with the default `--gpu` request. The VM driver accepts `gpu_device_ids`, for example `{"vm":{"gpu_device_ids":["0000:2d:00.0"]}}`; the current VM implementation accepts at most one entry and allows either `--gpu` or `--gpu 1` when `gpu_device_ids` is set. For Kubernetes, `pod.runtime_class_name` maps to PodSpec `runtimeClassName`. It overrides the gateway's configured default runtime class for that sandbox, while a typed `SandboxTemplate.runtime_class_name` value from the API still takes precedence. ## Docker Driver [Docker](https://www.docker.com/get-started/)-backed sandboxes run as containers on the gateway host. Use Docker for local development, single-machine gateways, and hosts that already use Docker Desktop or Docker Engine. The gateway talks to the Docker daemon to create sandbox containers. Docker is also required for local image builds from directories or Dockerfiles. For maintainer-level implementation details, refer to the [Docker driver README](https://github.com/NVIDIA/OpenShell/blob/main/crates/openshell-driver-docker/README.md). Select Docker with `compute_drivers = ["docker"]` in `[openshell.gateway]`. Configure Docker driver values such as `grpc_endpoint`, `network_name`, `supervisor_bin`, `supervisor_image`, `image_pull_policy`, `ssh_socket_path`, `sandbox_pids_limit`, and `guest_tls_*` in `[openshell.drivers.docker]`. For GPU-backed Docker sandboxes, configure Docker CDI before starting the gateway so OpenShell can detect the daemon capability. ### Docker Driver Config Mounts Docker driver config accepts user-supplied `volume` and `tmpfs` mounts. It also accepts `bind` mounts when `[openshell.drivers.docker]` sets `enable_bind_mounts = true` in `gateway.toml`. See Docker's [storage documentation](https://docs.docker.com/engine/storage/) for more information. Docker local-driver named volumes created with bind options also expose gateway-host paths, so OpenShell treats them like bind mounts and requires `enable_bind_mounts = true`. Use a `volume` mount for existing Docker named volumes: ```shell docker volume create openshell-work openshell sandbox create \ --driver-config-json '{"docker":{"mounts":[{"type":"volume","source":"openshell-work","target":"/sandbox/work","read_only":false}]}}' \ -- claude ``` Bind mounts share gateway-host filesystem resources with the sandbox. They may be considered insecure because they can negate OpenShell controls such as workspace isolation and filesystem policy. Use them only when you understand and accept that loss of isolation. Use a `bind` mount only after enabling it in the Docker driver table: ```toml [openshell.drivers.docker] enable_bind_mounts = true ``` ```shell openshell sandbox create \ --driver-config-json '{"docker":{"mounts":[{"type":"bind","source":"/srv/openshell/work","target":"/sandbox/work","read_only":false}]}}' \ -- claude ``` Docker mount schema: | Type | Fields | | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bind` | `source`, `target`, optional `read_only` (`true` by default), optional `selinux_label` (`shared` for `:z` or `private` for `:Z`). `source` must be an absolute host path. Requires `enable_bind_mounts = true`. | | `volume` | `source`, `target`, optional `read_only` (`true` by default), optional `subpath`. The named volume must already exist. Docker local-driver bind-backed volumes require `enable_bind_mounts = true`. | | `tmpfs` | `target`, optional `options`, optional `size_bytes`, optional `mode`. | OpenShell rejects mount `source`, `target`, and Docker volume `subpath` values with surrounding whitespace. OpenShell also rejects mount targets that replace the workspace root, container root, supervisor files, `/etc/openshell`, `/etc/openshell-tls`, authentication material, or network namespace paths. These checks do not make host bind mounts safe. ## Podman Driver [Podman](https://podman.io/)-backed sandboxes run as rootless containers on the gateway host. Use Podman for Linux workstation workflows that avoid a rootful Docker daemon. The gateway talks to the Podman API socket. The Podman driver requires Podman 5.x, cgroups v2, rootless networking, and an active Podman user socket. For maintainer-level implementation details, refer to the [Podman driver README](https://github.com/NVIDIA/OpenShell/blob/main/crates/openshell-driver-podman/README.md) and [Podman networking notes](https://github.com/NVIDIA/OpenShell/blob/main/crates/openshell-driver-podman/NETWORKING.md). Select Podman with `compute_drivers = ["podman"]` in `[openshell.gateway]`. Configure Podman driver values such as `socket_path`, `network_name`, `supervisor_image`, `stop_timeout_secs`, `image_pull_policy`, `grpc_endpoint`, `host_gateway_ip`, `sandbox_ssh_socket_path`, `sandbox_pids_limit`, and `guest_tls_*` in `[openshell.drivers.podman]`. On macOS with `podman machine`, the driver uses gvproxy's host-loopback IP, `192.168.127.254`, for sandbox host aliases by default. Set `host_gateway_ip` only when your Podman machine uses a non-standard host-loopback address. On Linux, an empty `host_gateway_ip` keeps Podman's `host-gateway` resolver behavior. ### Podman Driver Config Mounts Podman driver config accepts user-supplied `volume`, `tmpfs`, and `image` mounts. It also accepts `bind` mounts when `[openshell.drivers.podman]` sets `enable_bind_mounts = true` in `gateway.toml`. Podman local-driver named volumes created with bind options also expose gateway-host paths, so OpenShell treats them like bind mounts and requires `enable_bind_mounts = true`. Host bind mounts expose gateway host paths to sandbox requests, so they are disabled by default. Use a `volume` mount for existing Podman named volumes: ```shell podman volume create openshell-work openshell sandbox create \ --driver-config-json '{"podman":{"mounts":[{"type":"volume","source":"openshell-work","target":"/sandbox/work","read_only":false}]}}' \ -- claude ``` Bind mounts share gateway-host filesystem resources with the sandbox. They may be considered insecure because they can negate OpenShell controls such as workspace isolation and filesystem policy. Use them only when you understand and accept that loss of isolation. Use a `bind` mount only after enabling it in the Podman driver table: ```toml [openshell.drivers.podman] enable_bind_mounts = true ``` ```shell openshell sandbox create \ --driver-config-json '{"podman":{"mounts":[{"type":"bind","source":"/srv/openshell/work","target":"/sandbox/work","read_only":false}]}}' \ -- claude ``` Podman mount schema: | Type | Fields | | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bind` | `source`, `target`, optional `read_only` (`true` by default), optional `selinux_label` (`shared` for `:z` or `private` for `:Z`). `source` must be an absolute host path. Requires `enable_bind_mounts = true`. | | `volume` | `source`, `target`, optional `read_only` (`true` by default). The named volume must already exist. Podman local-driver bind-backed volumes require `enable_bind_mounts = true`. | | `tmpfs` | `target`, optional `options`, optional `size_bytes`, optional `mode`. | | `image` | `source`, `target`, optional `read_only` (`true` by default). | Podman `volume` and `image` mounts do not support `subpath` in OpenShell driver config, and OpenShell rejects `subpath` for those mount types. OpenShell rejects mount `source` and `target` values with surrounding whitespace. OpenShell also rejects mount targets that replace the workspace root, container root, supervisor files, `/etc/openshell`, `/etc/openshell-tls`, authentication material, or network namespace paths. These checks do not make host bind mounts safe. ## MicroVM Driver MicroVM-backed sandboxes run inside VM-backed isolation instead of a container boundary. Use MicroVM when workloads need a VM boundary instead of a local container boundary. The gateway uses the VM compute driver to create VM-backed sandboxes. MicroVM requires host virtualization support. It uses [libkrun](https://github.com/containers/libkrun) with Apple's [Hypervisor framework](https://developer.apple.com/documentation/hypervisor) on macOS, KVM on Linux, and [QEMU](https://www.qemu.org/) for GPU-backed sandboxes on Linux. The VM driver boots a cached immutable bootstrap ext4 root disk. When the requested sandbox image differs from the bootstrap image, the driver stages the registry image as an OCI layout, unpacks it inside a bootstrap VM with `umoci`, and caches the prepared image disk by image identity. Each sandbox receives that prepared disk read-only plus its own writable `overlay.ext4` disk for `/`, including `/sandbox` writes and runtime TLS material. The overlay persists for the sandbox lifetime and is deleted with the sandbox state directory. VM sandbox creation follows the same progress model as Kubernetes-backed sandboxes. The gateway accepts the sandbox, then the VM driver publishes watch events while it resolves the image, prepares or reuses the bootstrap and prepared image caches, creates the writable overlay, and starts the VM launcher. On gateway restart, the gateway starts a fresh VM driver process. The driver scans its state directory for accepted sandbox launch records, restarts those VMs, and reuses each sandbox's existing `overlay.ext4` so files written inside the sandbox remain available after the supervisor reconnects. For maintainer-level implementation details, refer to the [VM driver README](https://github.com/NVIDIA/OpenShell/blob/main/crates/openshell-driver-vm/README.md). ### Enable the VM Driver The VM driver is opt-in. Release packages can install `openshell-driver-vm`, but the gateway does not select it unless you configure the driver explicitly. Enable VM by setting `compute_drivers = ["vm"]` in the gateway TOML file: ```toml [openshell.gateway] compute_drivers = ["vm"] ``` For a launch-time override, set `OPENSHELL_DRIVERS=vm` in the gateway environment and restart the service. Configure VM driver values such as `grpc_endpoint`, `driver_dir`, `state_dir`, `default_image`, `bootstrap_image`, `vcpus`, `mem_mib`, `overlay_disk_mib`, `krun_log_level`, and `guest_tls_*` in `[openshell.drivers.vm]`. The VM `state_dir` stores overlay disks, console logs, runtime state, image-rootfs cache, and the private `run/compute-driver.sock` socket. The VM socket path is managed by the gateway and is not configurable through remote endpoint settings. The gateway starts `openshell-driver-vm` over a private Unix socket and passes its process ID so the driver can reject unexpected local clients. The driver's standalone TCP listener is disabled unless `--allow-unauthenticated-tcp` is set for local development. ### Local image resolution The VM driver resolves sandbox images from a local container engine before falling back to registry pulls. It tries Docker first, then falls back to the Podman socket (Docker-compatible API). On Linux with Podman, enable the API socket so the driver can find local images: ```shell systemctl --user start podman.socket ``` ### Host Firewall The VM driver creates nftables rules on the host for each sandbox VM's TAP network interface. These rules provide NAT for VM connectivity and defense-in-depth isolation: unsolicited inbound connections to the VM are dropped, and the VM can only reach the gateway port on the host. Primary security enforcement (proxy-only egress and bypass detection) is handled by the sandbox supervisor inside the VM guest. On hosts with restrictive firewalls (e.g. firewalld), the host firewall may additionally block VM traffic that the driver's rules accept. If VM sandboxes cannot reach the network, verify that the host firewall allows forwarding and input for `vmtap-*` interfaces. See the [VM driver README](https://github.com/NVIDIA/OpenShell/blob/main/crates/openshell-driver-vm/README.md#host-side-nftables-rules) for details. ## Kubernetes Driver Kubernetes-backed sandboxes run as pods in the configured sandbox namespace. Use Kubernetes for shared clusters, remote compute, GPU scheduling, and operator-managed environments. Helm deployments set Kubernetes driver values through the chart. For maintainer-level implementation details, refer to the [Kubernetes driver README](https://github.com/NVIDIA/OpenShell/blob/main/crates/openshell-driver-kubernetes/README.md). | Gateway configuration | Helm value | Description | | --------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `compute_drivers = ["kubernetes"]` | Not applicable | Select the Kubernetes compute driver. | | `[openshell.drivers.kubernetes].namespace` | `server.sandboxNamespace` | Set the namespace for sandbox resources. The Helm chart defaults to the release namespace when left empty. | | `service_account_name` | `sandboxServiceAccount.name` | Set the Kubernetes service account assigned to sandbox pods and accepted by the gateway TokenReview bootstrap path. The Helm chart creates a dedicated sandbox service account by default. | | `default_image` | `server.sandboxImage` | Set the default sandbox image. | | `image_pull_policy` | `server.sandboxImagePullPolicy` | Set the Kubernetes image pull policy for sandbox pods. | | `image_pull_secrets` | `server.sandboxImagePullSecrets` | Attach Kubernetes image pull secrets to sandbox pods. Referenced Secrets must exist in the sandbox namespace. | | `grpc_endpoint` | `server.grpcEndpoint` | Set the gateway callback endpoint reachable from sandbox pods. | | `client_tls_secret_name` | `server.tls.clientTlsSecretName` | Mount sandbox client TLS materials from a Kubernetes secret. | | `supervisor_image` | `supervisor.image.repository` / `supervisor.image.tag` | Override the supervisor image that provides the `openshell-sandbox` binary. The default repository with an empty tag uses the version-pinned image built into the gateway. Changing the repository uses the effective gateway image tag, while setting a tag pins that version explicitly. | | `supervisor_image_pull_policy` | `supervisor.image.pullPolicy` | Set the Kubernetes image pull policy for the supervisor image. | | `supervisor_sideload_method` | `supervisor.sideloadMethod` | How the supervisor binary is delivered into sandbox pods. Leave empty to auto-detect from cluster version. Set to `image-volume` to mount the supervisor OCI image directly as a volume (requires Kubernetes 1.33+ with the ImageVolume feature gate; GA in 1.36), or `init-container` to copy it through an init container on older clusters. | | `topology` | `supervisor.topology` | Set `combined` for the default single supervisor path, or `sidecar` to move pod-level network enforcement and the gateway session into a dedicated sidecar. | | `sidecar.proxy_uid` | `supervisor.sidecar.proxyUid` | Non-root UID used by the relaxed sidecar when process/binary-aware network policy is disabled. The default binary-aware sidecar runs as UID 0. The network init container exempts the effective sidecar UID from proxy redirection. | | `sidecar.process_binary_aware_network_policy` | `supervisor.sidecar.processBinaryAwareNetworkPolicy` | Keep process/binary-aware network policy enabled in `sidecar` topology. The default runs the sidecar as UID 0 with `SYS_PTRACE` and `DAC_READ_SEARCH`. Set false to run as `proxy_uid`, drop both capabilities, and enforce endpoint/L7 policy without matching `policy.binaries`. | | `app_armor_profile` | `server.appArmorProfile` | Set the sandbox agent container's AppArmor profile. Helm defaults this to `Unconfined` so AppArmor-enabled nodes do not block supervisor network namespace setup. Set the Helm value to an empty string to omit the field, or use `RuntimeDefault` or `Localhost/` for operator-managed profiles. | | `workspace_default_storage_size` | `server.workspaceDefaultStorageSize` | Set the default workspace PVC size for new sandboxes. | | `sa_token_ttl_secs` | `server.sandboxJwt.k8sSaTokenTtlSecs` | Set the projected ServiceAccount token TTL used for the bootstrap token exchange. | In `combined` topology, the agent container carries the Linux capabilities needed by the supervisor for network namespace setup, Landlock filesystem policy, process privilege changes, and network policy enforcement. In `sidecar` topology, the agent container runs as the resolved sandbox UID/GID with no added Linux capabilities. A root init container performs the nftables setup, and the long-running binary-aware sidecar runs as UID 0, drops default capabilities, and adds `SYS_PTRACE` plus `DAC_READ_SEARCH` for workload process identity resolution through shared `/proc`. The `sidecar.process_binary_aware_network_policy = false` setting runs it as the configured non-root `proxy_uid`, removes both capabilities, and relaxes network policy to endpoint/L7 matching only. The network sidecar owns gateway authentication and writes local policy/provider state to the process supervisor over a local control socket, so the agent container does not mount the sandbox bootstrap token or client TLS secret in the default sidecar path. The provider environment is refreshed by the network sidecar after settings polls and streamed to the process supervisor so future child processes can see updated provider env without gateway access in the agent container. Sidecar mode keeps gateway session and SSH behavior. The process supervisor applies Landlock filesystem policy and child seccomp filters where supported, but it does not perform root-to-sandbox privilege dropping or supervisor identity mount isolation. Network policy still runs in the sidecar, and sidecar pods set `shareProcessNamespace: true` so the network sidecar can resolve process/binary identity through `/proc/`. The Kubernetes driver creates namespaced `agents.x-k8s.io` `Sandbox` resources from the Kubernetes SIG Apps [agent-sandbox](https://github.com/kubernetes-sigs/agent-sandbox) project. It detects the served Sandbox API at runtime, caches the selected API version for the gateway process, and uses `v1beta1` when available before falling back to `v1alpha1`, so supported Agent Sandbox installations work without version-specific operator configuration. The Agent Sandbox controller turns those resources into sandbox pods and related storage. If Agent Sandbox is upgraded in place, restart the OpenShell gateway after the controller and CRD rollout completes so the gateway can detect the served API versions again. `Sandbox.spec.volumeClaimTemplates` is immutable after creation. To change storage configuration, delete the sandbox and create a new one with the updated spec. ### Kubernetes Driver Config PVC Mounts Kubernetes driver config can mount existing PersistentVolumeClaims into the agent container. Use this when storage is provisioned outside OpenShell and a sandbox should mount selected PVC subpaths instead of using the default OpenShell-created `/sandbox` workspace PVC. ```shell openshell sandbox create \ --driver-config-json '{ "kubernetes": { "volumes": [{ "name": "user-data", "persistent_volume_claim": { "claim_name": "pvc-user-data-123", "read_only": false } }], "containers": { "agent": { "volume_mounts": [ { "name": "user-data", "mount_path": "/sandbox/.openshell/workspace", "sub_path": "workspace", "read_only": false }, { "name": "user-data", "mount_path": "/sandbox/.openshell/memory", "sub_path": "memory", "read_only": false } ] } } } }' \ -- claude ``` Kubernetes PVC mount schema: | Field | Description | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------- | | `volumes[].name` | Pod volume name. It must be a DNS-1123 label, unique, and not use OpenShell-managed volume names. | | `volumes[].persistent_volume_claim.claim_name` | Existing PVC name in the sandbox namespace. It must be a DNS-1123 subdomain name. | | `volumes[].persistent_volume_claim.read_only` | Optional. Defaults to `true`. Set `false` to allow read-write mounts. | | `containers.agent.volume_mounts[].name` | References a volume declared in `volumes`. | | `containers.agent.volume_mounts[].mount_path` | Absolute, normalized container path for the agent mount. | | `containers.agent.volume_mounts[].sub_path` | Optional relative PVC subpath. Absolute paths and `..` are rejected. | | `containers.agent.volume_mounts[].read_only` | Optional. Defaults to `true`. It cannot be `false` when the PVC volume is read-only. | OpenShell rejects duplicate volume names, mounts that reference unknown volumes, protected mount targets, and mounts that replace OpenShell TLS, supervisor, ServiceAccount token, or SPIFFE paths. Read-write PVC access requires `read_only: false` on both the PVC volume and each writable mount. Any driver-config mount under `/sandbox` disables the default `/sandbox` workspace PVC injection for that sandbox. Only the explicit mount paths persist through the external PVC; other `/sandbox` paths come from the current sandbox image. ## Sandbox User Identity OpenShell accepts both the hardcoded username `"sandbox"` and numeric UIDs in `[1000, 2_000_000_000]` for the supervisor's process identity (the policy's `run_as_user` field). The driver resolves the UID at sandbox creation time and passes it to the supervisor via environment variables. ### Kubernetes / OpenShift The Kubernetes driver auto-detects the sandbox UID from OpenShift SCC namespace annotations: * `openshift.io/sa.scc.uid-range` (format: `/`, e.g. `1000000000/10000`) provides the UID. * `openshift.io/sa.scc.supplemental-groups` provides the GID when present; otherwise the resolved UID is used as the GID. * On non-OpenShift clusters, or when annotations are absent, the driver falls back to `1000`. You can override autodetection with explicit `sandbox_uid` / `sandbox_gid` config in `[openshell.drivers.kubernetes]`. When set, the driver skips namespace annotation lookup entirely. The resolved UID/GID appear in: * Supervisor container environment variables (`OPENSHELL_SANDBOX_UID`, `OPENSHELL_SANDBOX_GID`) for direct kernel-level privilege dropping without `/etc/passwd` lookups. * PVC init container `securityContext.runAsUser/runAsGroup/fsGroup` for workspace ownership operations. ### VM Driver The VM driver injects the sandbox UID into the rootfs guest's `/etc/passwd`, `/etc/group`, and `/etc/gshadow` during rootfs preparation. Default UID is `10001`; configure `sandbox_uid` in `[openshell.drivers.vm]` to use a different value. ### Custom Images Custom sandbox images no longer need a baked-in `"sandbox"` user. If your image requires a passwd entry for tools like `sudo` or `ssh`, add one manually (e.g. `RUN useradd -m -u 1500 deploy`). The supervisor resolves the numeric UID directly via `setuid()` without needing `/etc/passwd`.