docs(gpu): document counted CDI defaults

Signed-off-by: Evan Lezar <elezar@nvidia.com>

Author: elezar

architecture/compute-runtimes.md

@@ -55,11 +55,12 @@ through the driver configuration. The Helm chart defaults sandbox agents to
 `Unconfined` so runtime/default AppArmor profiles do not block supervisor
 network namespace setup on AppArmor-enabled nodes.
 
-GPU requests enter the driver layer through `SandboxSpec.gpu` and
-`SandboxSpec.gpu_device`. Docker and Podman map default GPU requests to one
-concrete NVIDIA CDI device when individual CDI devices are available, use
-`nvidia.com/gpu=all` only for WSL2/all-only compatibility, and pass explicit
-driver-native device IDs through.
+GPU requests enter the driver layer through `SandboxSpec.resource_requirements`.
+An omitted GPU count is interpreted as one GPU. Docker and Podman pass explicit
+`driver_config.cdi_devices` values through as opaque CDI IDs; otherwise they
+refresh their CDI inventory and select the requested number of default NVIDIA
+CDI devices in round-robin order. The `nvidia.com/gpu=all` fallback is used only
+for WSL2/all-only compatibility and counts as one selectable device.
 
 VM runtime state paths are derived only from driver-validated sandbox IDs
 matching `[A-Za-z0-9._-]{1,128}`. The gateway-owned VM driver socket uses a

crates/openshell-driver-docker/README.md

@@ -32,7 +32,7 @@ contract:
 | `apparmor=unconfined` | Avoids Docker's default profile blocking required mount operations. |
 | `restart_policy = unless-stopped` | Keeps managed sandboxes resumable across daemon or gateway restarts. |
 | `PidsLimit` | Enforces the sandbox PID budget at the Docker cgroup layer. Set `[openshell.drivers.docker].sandbox_pids_limit = 0` to inherit the Docker/runtime default. |
-| CDI GPU request | Uses `driver_config.cdi_devices` when set; otherwise selects one concrete NVIDIA CDI GPU when the sandbox resource requirements ask for GPU support and daemon CDI support is detected. Docker daemon `/info` can permit `nvidia.com/gpu=all` as a WSL2 all-only compatibility fallback. Count-only GPU requests are rejected; exact CDI device lists with more than one entry require an explicit GPU count matching the device list length. |
+| CDI GPU request | Uses opaque `driver_config.cdi_devices` values when set; otherwise selects the requested count of NVIDIA CDI GPUs in round-robin order when daemon CDI support is detected. Docker daemon `/info` can permit `nvidia.com/gpu=all` as a WSL2 all-only compatibility fallback, where it counts as one selectable device. Exact CDI device lists must not contain duplicates and must match the effective GPU count. |
 
 The agent child process does not retain these supervisor privileges.
 

crates/openshell-driver-podman/README.md

@@ -46,7 +46,7 @@ The container spec in `container.rs` sets these security-critical fields:
 | `no_new_privileges` | `true` | Prevents privilege escalation after exec. |
 | `seccomp_profile_path` | `unconfined` | The supervisor installs its own policy-aware BPF filter. A container-level profile can block Landlock/seccomp syscalls during setup. |
 | `mounts` | Private tmpfs at `/run/netns` | Lets the supervisor create named network namespaces in rootless Podman. |
-| CDI GPU devices | `driver_config.cdi_devices` when set, otherwise one concrete NVIDIA CDI GPU. Local `/dev/dxg` permits `nvidia.com/gpu=all` as a WSL2 all-only compatibility fallback. | Exposes requested GPUs to GPU-enabled sandbox containers. Count-only GPU requests are rejected; exact CDI device lists with more than one entry require an explicit GPU count matching the device list length. |
+| CDI GPU devices | Opaque `driver_config.cdi_devices` values when set, otherwise the requested count of NVIDIA CDI GPUs selected in round-robin order. Local `/dev/dxg` permits `nvidia.com/gpu=all` as a WSL2 all-only compatibility fallback, where it counts as one selectable device. | Exposes requested GPUs to GPU-enabled sandbox containers. Exact CDI device lists must not contain duplicates and must match the effective GPU count. |
 
 The restricted agent child does not retain these supervisor privileges.
 

docs/reference/sandbox-compute-drivers.mdx

@@ -53,19 +53,29 @@ openshell sandbox create \
 ```
 
 Driver config is for fields without a stable public flag. Prefer `--cpu`,
-`--memory`, and `--gpu` for supported resource intent. Pass a count to `--gpu`
-when the active driver supports counted allocation. Docker and Podman reject
-count-only GPU selection. If `driver_config` lists more than one exact CDI
-device, pass `--gpu COUNT`; the count must match the number of listed devices.
-A single exact CDI device is compatible with the default `--gpu` request.
+`--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`; replace the top-level `docker` key with
-`podman` when using the Podman driver, for example
-`{"docker":{"cdi_devices":["nvidia.com/gpu=0"]}}`. 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.
+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,

docs/sandboxes/manage-sandboxes.mdx

@@ -76,25 +76,27 @@ Request a specific number of GPUs by passing a count to `--gpu`:
 openshell sandbox create --gpu 2 -- claude
 ```
 
-Support for counted GPU requests is driver-dependent. Kubernetes honors a
-counted `--gpu` request by setting the `nvidia.com/gpu` limit. Docker and Podman
-reject count-only selection. If `driver_config` lists more than one exact CDI
-device, pass `--gpu COUNT`; the count must match the number of listed devices.
-A single exact CDI device is compatible with the default `--gpu` request. VM
-gateways accept only one GPU, either through `--gpu` or `--gpu 1`; a single
-`gpu_device_ids` entry works with either form.
+When you omit the count, OpenShell treats the request as `--gpu 1`.
+Kubernetes honors counted `--gpu` requests by setting the `nvidia.com/gpu`
+limit. Docker and Podman select the requested number of default NVIDIA CDI
+devices in round-robin order. VM gateways accept only one GPU, either through
+`--gpu` or `--gpu 1`; a single `gpu_device_ids` entry works with either form.
 
 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.
 
-Docker and Podman gateways map a default `--gpu` request to one concrete
-NVIDIA CDI device when individual CDI devices are available. On WSL2 all-only
-runtimes, the default can fall back to `nvidia.com/gpu=all`.
+Docker and Podman refresh the CDI inventory before validating or creating a
+default GPU request, so CDI devices added or removed after the driver starts can
+be reflected in later sandbox creates. On WSL2 all-only runtimes, the default
+can fall back to `nvidia.com/gpu=all`; that fallback counts as one selectable
+device.
 
 Exact GPU device selection is driver-specific and still requires `--gpu`. For
 Docker or Podman, pass CDI IDs through `cdi_devices`. The top-level key must
-match the active driver; replace `docker` with `podman` when using Podman:
+match the active driver; replace `docker` with `podman` when using Podman. CDI
+IDs are treated as opaque strings. The list must not contain duplicate IDs, and
+its length must match the effective GPU count:
 
 ```shell
 openshell sandbox create \