feat(docker): enable CDI GPU sandboxes (#1036)

Author: elezar

architecture/sandbox.md

@@ -460,6 +460,16 @@ Kernel-level error behavior (e.g., Landlock ABI unavailable) depends on `Landloc
 
 **Baseline path filtering**: System-injected baseline paths (e.g., `/app`) are pre-filtered by `enrich_proto_baseline_paths()` / `enrich_sandbox_baseline_paths()` using `Path::exists()` before they reach Landlock. If a baseline `read_write` path is already present in `read_only`, enrichment skips the promotion so explicit policy intent is preserved. User-specified paths are not pre-filtered -- they are evaluated at Landlock apply time so misconfigurations surface as warnings or errors.
 
+**GPU baseline paths**: The supervisor currently infers GPU baseline paths from
+device nodes and NVIDIA runtime paths visible inside the sandbox container. The
+Docker compute driver can request CDI GPU injection, but this implementation
+does not pass CDI metadata into the supervisor. Future device-specific CDI
+selection may need follow-up work so the supervisor can enrich Landlock using
+the requested CDI device's actual device nodes and mounted library paths. That
+design must work for remote Docker daemons, where Docker-reported CDI spec
+directories are paths on the daemon host and may not be readable by the gateway
+process or the sandbox supervisor.
+
 ### Seccomp syscall filtering
 
 **File:** `crates/openshell-sandbox/src/sandbox/linux/seccomp.rs`

crates/openshell-driver-docker/src/lib.rs

@@ -8,16 +8,16 @@
 use bollard::Docker;
 use bollard::errors::Error as BollardError;
 use bollard::models::{
-    ContainerCreateBody, ContainerSummary, ContainerSummaryStateEnum, HostConfig, Mount,
-    MountTypeEnum, RestartPolicy, RestartPolicyNameEnum,
+    ContainerCreateBody, ContainerSummary, ContainerSummaryStateEnum, DeviceRequest, HostConfig,
+    Mount, MountTypeEnum, RestartPolicy, RestartPolicyNameEnum,
 };
 use bollard::query_parameters::{
     CreateContainerOptionsBuilder, CreateImageOptions, DownloadFromContainerOptionsBuilder,
     ListContainersOptionsBuilder, RemoveContainerOptionsBuilder, StopContainerOptionsBuilder,
 };
 use bytes::Bytes;
 use futures::{Stream, StreamExt};
-use openshell_core::config::DEFAULT_STOP_TIMEOUT_SECS;
+use openshell_core::config::{CDI_GPU_DEVICE_ALL, DEFAULT_STOP_TIMEOUT_SECS};
 use openshell_core::proto::compute::v1::{
     CreateSandboxRequest, CreateSandboxResponse, DeleteSandboxRequest, DeleteSandboxResponse,
     DriverCondition, DriverSandbox, DriverSandboxStatus, DriverSandboxTemplate,
@@ -159,6 +159,7 @@ struct DockerDriverRuntimeConfig {
     supervisor_bin: PathBuf,
     guest_tls: Option<DockerGuestTlsPaths>,
     daemon_version: String,
+    supports_gpu: bool,
 }
 
 #[derive(Clone)]
@@ -195,6 +196,12 @@ impl DockerComputeDriver {
         let version = docker.version().await.map_err(|err| {
             Error::execution(format!("failed to query Docker daemon version: {err}"))
         })?;
+        let supports_gpu = docker
+            .info()
+            .await
+            .ok()
+            .and_then(|info| info.cdi_spec_dirs)
+            .is_some_and(|dirs| !dirs.is_empty());
         let daemon_arch = normalize_docker_arch(version.arch.as_deref().unwrap_or_default());
         let supervisor_bin = resolve_supervisor_bin(&docker, docker_config, &daemon_arch).await?;
         let guest_tls = docker_guest_tls_paths(config, docker_config)?;
@@ -212,6 +219,7 @@ impl DockerComputeDriver {
                 supervisor_bin,
                 guest_tls,
                 daemon_version: version.version.unwrap_or_else(|| "unknown".to_string()),
+                supports_gpu,
             },
             events: broadcast::channel(WATCH_BUFFER).0,
             supervisor_readiness,
@@ -230,12 +238,15 @@ impl DockerComputeDriver {
             driver_name: "docker".to_string(),
             driver_version: self.config.daemon_version.clone(),
             default_image: self.config.default_image.clone(),
-            supports_gpu: false,
+            supports_gpu: self.config.supports_gpu,
             gpu_count: 0,
         }
     }
 
-    fn validate_sandbox(sandbox: &DriverSandbox) -> Result<(), Status> {
+    fn validate_sandbox(
+        sandbox: &DriverSandbox,
+        config: &DockerDriverRuntimeConfig,
+    ) -> Result<(), Status> {
         let spec = sandbox
             .spec
             .as_ref()
@@ -250,9 +261,9 @@ impl DockerComputeDriver {
                 "docker sandboxes require a template image",
             ));
         }
-        if spec.gpu {
+        if spec.gpu && !config.supports_gpu {
             return Err(Status::failed_precondition(
-                "docker compute driver does not support gpu sandboxes",
+                "docker GPU sandboxes require Docker CDI support. Enable CDI on the Docker daemon, then restart the OpenShell gateway/server so GPU capability is detected.",
             ));
         }
         if !template.agent_socket_path.trim().is_empty() {
@@ -300,7 +311,7 @@ impl DockerComputeDriver {
     }
 
     async fn create_sandbox_inner(&self, sandbox: &DriverSandbox) -> Result<(), Status> {
-        Self::validate_sandbox(sandbox)?;
+        Self::validate_sandbox(sandbox, &self.config)?;
 
         if self
             .find_managed_container_summary(&sandbox.id, &sandbox.name)
@@ -674,7 +685,7 @@ impl ComputeDriver for DockerComputeDriver {
             .into_inner()
             .sandbox
             .ok_or_else(|| Status::invalid_argument("sandbox is required"))?;
-        Self::validate_sandbox(&sandbox)?;
+        Self::validate_sandbox(&sandbox, &self.config)?;
         Ok(Response::new(ValidateSandboxCreateResponse {}))
     }
 
@@ -876,6 +887,16 @@ fn build_environment(sandbox: &DriverSandbox, config: &DockerDriverRuntimeConfig
         .collect()
 }
 
+fn docker_gpu_device_requests(gpu: bool) -> Option<Vec<DeviceRequest>> {
+    gpu.then(|| {
+        vec![DeviceRequest {
+            driver: Some("cdi".to_string()),
+            device_ids: Some(vec![CDI_GPU_DEVICE_ALL.to_string()]),
+            ..Default::default()
+        }]
+    })
+}
+
 fn build_container_create_body(
     sandbox: &DriverSandbox,
     config: &DockerDriverRuntimeConfig,
@@ -917,6 +938,7 @@ fn build_container_create_body(
         host_config: Some(HostConfig {
             nano_cpus: resource_limits.nano_cpus,
             memory: resource_limits.memory_bytes,
+            device_requests: docker_gpu_device_requests(spec.gpu),
             mounts: Some(build_mounts(config)),
             restart_policy: Some(RestartPolicy {
                 name: Some(RestartPolicyNameEnum::UNLESS_STOPPED),

crates/openshell-driver-docker/src/tests.rs

@@ -52,6 +52,7 @@ fn runtime_config() -> DockerDriverRuntimeConfig {
             key: PathBuf::from("/tmp/tls.key"),
         }),
         daemon_version: "28.0.0".to_string(),
+        supports_gpu: false,
     }
 }
 
@@ -170,6 +171,48 @@ fn build_container_create_body_clears_inherited_cmd() {
             .and_then(|labels| labels.get(SANDBOX_NAMESPACE_LABEL_KEY)),
         Some(&"default".to_string())
     );
+    assert!(
+        create_body
+            .host_config
+            .as_ref()
+            .and_then(|host_config| host_config.device_requests.as_ref())
+            .is_none(),
+        "non-GPU containers should not request Docker devices"
+    );
+}
+
+#[test]
+fn validate_sandbox_rejects_gpu_when_cdi_unavailable() {
+    let config = runtime_config();
+    let mut sandbox = test_sandbox();
+    sandbox.spec.as_mut().unwrap().gpu = true;
+
+    let err = DockerComputeDriver::validate_sandbox(&sandbox, &config).unwrap_err();
+
+    assert_eq!(err.code(), tonic::Code::FailedPrecondition);
+    assert!(err.message().contains("Docker CDI"));
+}
+
+#[test]
+fn build_container_create_body_maps_gpu_to_all_cdi_device() {
+    let mut config = runtime_config();
+    config.supports_gpu = true;
+    let mut sandbox = test_sandbox();
+    sandbox.spec.as_mut().unwrap().gpu = true;
+
+    let create_body = build_container_create_body(&sandbox, &config).unwrap();
+    let request = create_body
+        .host_config
+        .as_ref()
+        .and_then(|host_config| host_config.device_requests.as_ref())
+        .and_then(|requests| requests.first())
+        .expect("GPU request should add a Docker device request");
+
+    assert_eq!(request.driver.as_deref(), Some("cdi"));
+    assert_eq!(
+        request.device_ids.as_ref().unwrap(),
+        &vec![CDI_GPU_DEVICE_ALL.to_string()]
+    );
 }
 
 #[test]

docs/sandboxes/manage-sandboxes.mdx

@@ -39,6 +39,10 @@ To request GPU resources, add `--gpu`:
 openshell sandbox create --gpu -- claude
 ```
 
+For Docker-backed sandboxes, GPU injection uses Docker CDI. If you enable Docker
+CDI after the gateway starts, restart the gateway so OpenShell can detect the
+updated Docker daemon capability.
+
 ### Custom Containers
 
 Use `--from` to create a sandbox from a pre-built community package, a local directory, or a container image:

e2e/rust/e2e-docker.sh

@@ -2,7 +2,7 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-# Run the Rust e2e smoke test against a standalone gateway running the
+# Run a Rust e2e test against a standalone gateway running the
 # bundled Docker compute driver.
 #
 # Unlike the Kubernetes driver (which deploys a k3s cluster) or the VM
@@ -20,10 +20,12 @@
 #   4. Starts openshell-gateway with --drivers=docker, binding to a
 #      random free host port.
 #   5. Installs the client cert into the CLI gateway config dir and
-#      runs the Rust smoke test.
+#      runs the selected Rust e2e test.
 #   6. Tears the gateway process down on exit.
 #
-# Usage: mise run e2e:docker
+# Usage:
+#   mise run e2e:docker
+#   mise run e2e:docker:gpu
 
 set -euo pipefail
 
@@ -35,6 +37,8 @@ STATE_DIR=""
 GATEWAY_CONFIG_DIR=""
 GATEWAY_PID=""
 GATEWAY_LOG="${WORKDIR}/gateway.log"
+E2E_TEST="${OPENSHELL_E2E_DOCKER_TEST:-smoke}"
+GPU_MODE="${OPENSHELL_E2E_DOCKER_GPU:-0}"
 # Unique sandbox namespace for this test run. Set just before the gateway
 # is started so cleanup can filter Docker containers strictly to ones
 # this run created, even when other OpenShell sandboxes are present on
@@ -119,6 +123,17 @@ if ! command -v openssl >/dev/null 2>&1; then
   echo "ERROR: openssl is required to generate ephemeral PKI" >&2
   exit 2
 fi
+if [ "${GPU_MODE}" = "1" ]; then
+  DOCKER_CDI_SPEC_DIRS="$(docker info --format '{{json .CDISpecDirs}}' 2>/dev/null || true)"
+  if [ -z "${DOCKER_CDI_SPEC_DIRS}" ] \
+     || [ "${DOCKER_CDI_SPEC_DIRS}" = "null" ] \
+     || [ "${DOCKER_CDI_SPEC_DIRS}" = "[]" ] \
+     || [ "${DOCKER_CDI_SPEC_DIRS}" = "<no value>" ]; then
+    echo "ERROR: e2e:docker:gpu requires Docker CDI support." >&2
+    echo "       Generate CDI specs and restart Docker, then verify docker info reports CDISpecDirs." >&2
+    exit 2
+  fi
+fi
 
 normalize_arch() {
   case "$1" in
@@ -186,8 +201,10 @@ chmod +x "${SUPERVISOR_BIN}"
 # in the image. Use the community sandbox base image (also what real
 # deployments default to). Callers can override with
 # OPENSHELL_E2E_DOCKER_SANDBOX_IMAGE if they have a smaller local image
-# with the required 'sandbox' user.
-SANDBOX_IMAGE="${OPENSHELL_E2E_DOCKER_SANDBOX_IMAGE:-ghcr.io/nvidia/openshell-community/sandboxes/base:latest}"
+# with the required 'sandbox' user. CDI injects the NVIDIA userspace
+# stack at runtime, so the GPU lane uses the same base image.
+DEFAULT_SANDBOX_IMAGE="ghcr.io/nvidia/openshell-community/sandboxes/base:latest"
+SANDBOX_IMAGE="${OPENSHELL_E2E_DOCKER_SANDBOX_IMAGE:-${DEFAULT_SANDBOX_IMAGE}}"
 if ! docker image inspect "${SANDBOX_IMAGE}" >/dev/null 2>&1; then
   echo "Pulling ${SANDBOX_IMAGE}..."
   docker pull "${SANDBOX_IMAGE}"
@@ -313,8 +330,8 @@ if [ "${elapsed}" -ge "${timeout}" ]; then
   exit 1
 fi
 
-# ── Run the smoke test ───────────────────────────────────────────────
-echo "Running e2e smoke test (gateway: ${OPENSHELL_GATEWAY}, endpoint: ${CLI_GATEWAY_ENDPOINT})..."
-cargo test --manifest-path e2e/rust/Cargo.toml --features e2e --test smoke -- --nocapture
+# ── Run the selected test ────────────────────────────────────────────
+echo "Running e2e ${E2E_TEST} test (gateway: ${OPENSHELL_GATEWAY}, endpoint: ${CLI_GATEWAY_ENDPOINT})..."
+cargo test --manifest-path e2e/rust/Cargo.toml --features e2e --test "${E2E_TEST}" -- --nocapture
 
-echo "Smoke test passed."
+echo "${E2E_TEST} test passed."

e2e/rust/tests/docker_gpu.rs

@@ -0,0 +1,36 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+#![cfg(feature = "e2e")]
+
+//! Docker GPU e2e test.
+//!
+//! Requires a Docker-backed gateway started with Docker CDI support. The
+//! `e2e:docker:gpu` mise task starts that gateway with the default sandbox image
+//! unless OPENSHELL_E2E_DOCKER_SANDBOX_IMAGE is set.
+
+use openshell_e2e::harness::output::strip_ansi;
+use openshell_e2e::harness::sandbox::SandboxGuard;
+
+#[tokio::test]
+async fn docker_gpu_sandbox_runs_nvidia_smi() {
+    let mut guard = SandboxGuard::create(&[
+        "--gpu",
+        "--",
+        "sh",
+        "-lc",
+        "gpu_name=$(nvidia-smi --query-gpu=name --format=csv,noheader | head -n 1); \
+         test -n \"$gpu_name\"; \
+         printf 'gpu-ok:%s\n' \"$gpu_name\"",
+    ])
+    .await
+    .expect("GPU sandbox create should succeed");
+
+    let output = strip_ansi(&guard.create_output);
+    assert!(
+        output.contains("gpu-ok:"),
+        "expected GPU smoke marker in sandbox output:\n{output}"
+    );
+
+    guard.cleanup().await;
+}

tasks/test.toml

@@ -60,3 +60,8 @@ run = "e2e/rust/e2e-vm.sh"
 ["e2e:docker"]
 description = "Run smoke e2e against a standalone gateway with the Docker compute driver"
 run = "e2e/rust/e2e-docker.sh"
+
+["e2e:docker:gpu"]
+description = "Run GPU e2e against a standalone gateway with the Docker compute driver"
+env = { OPENSHELL_E2E_DOCKER_GPU = "1", OPENSHELL_E2E_DOCKER_TEST = "docker_gpu" }
+run = "e2e/rust/e2e-docker.sh"