Repository navigation
feat(gpu): support runtime-owned Docker GPU compatibility for WSL and Jetson #4837
Description
User Story
We use OpenShell as the sandbox runtime for NemoClaw. While qualifying the OpenShell 0.1.3 upgrade in NVIDIA/NemoClaw#12603, we encountered two failing Docker GPU compatibility scenarios.
NemoClaw retains compatibility routes for Docker Desktop WSL and Jetson/Tegra. These routes can require Docker GPU injection or the NVIDIA runtime and supplementary groups when usable NVIDIA CDI devices are unavailable. We need an OpenShell-owned path that preserves those requirements.
Problem Statement
The inspected Docker driver exposes GPU selection through CDI. It does not expose an equivalent supported path for the existing compatibility requirements.
NemoClaw's older compatibility code recreates a workload container externally. That approach does not carry forward to the split supervisor/workload runtime: OpenShell owns bootstrap staging, launch credentials, workload networking, and restart identity.
The first observed failure is also a NemoClaw defect: its compatibility cutover expects one Docker container, while OpenShell creates a supervisor and workload. Correcting that selector alone does not supply the missing runtime contract.
This issue requests a supported runtime workflow. It does not assert that OpenShell has already promised support for every affected host.
Impact / Why This Matters
The upgrade cannot qualify the retained GPU compatibility behavior. The previous full NemoClaw run failed both scenarios:
Those CI results establish the compatibility-path failure on Linux. They are not physical WSL or Jetson validation.
Proposed Design
A caller should request a GPU sandbox through OpenShell's managed creation workflow. OpenShell should select and validate the supported GPU mechanism for that host, create the workload, and retain lifecycle ownership.
The workflow must preserve the required devices, libraries, and supplementary groups together with supervisor/workload identity, bootstrap credentials, networking, restart, rollback, and cleanup.
Please establish the supported host requirements and configuration contract before implementation. This proposal does not require a particular new CLI flag or internal replacement mechanism.
Acceptance Criteria
- Establish a supported OpenShell workflow for the existing Docker GPU compatibility requirements, including hosts without usable NVIDIA CDI devices, or demonstrate an equivalent CDI path on those exact host configurations.
- Demonstrate real CUDA initialization through that workflow on Docker Desktop WSL and Jetson/Tegra. Record runtime versions, host profiles, tested commits, commands, and results.
- Preserve the selected GPU devices, required libraries, supplementary groups, and inference behavior through sandbox stop/start and gateway restart.
- Keep workload networking isolated and keep launch credentials under runtime ownership. Callers must not copy bootstrap private keys or externally clone the workload to obtain GPU access.
- On creation or transition failure, preserve existing workload data and rollback authority. Reject foreign or ambiguous workload identities.
- Qualify both NemoClaw compatibility-only and native-rejection/fallback scenarios using the published runtime artifact. Preserve the existing assertions.
Alternatives Considered
- CDI requirements: #4204, assessed at revision
33350a881f55011286e7c3a68d8007e43e50e0bf, addresses CDI-derived devices, mounts, sockets, and groups. That revision still requires CDI and lacks complete hardware qualification. It does not establish the required behavior on hosts without usable CDI. - Existing design: #1606 covers CDI-derived sandbox access. This issue records the remaining compatibility requirement rather than duplicating that resolver work.
- External container recreation: fixing role selection leaves bootstrap staging, network isolation, and restart admission unresolved.
- Middleware or inference providers: these extension points do not own Docker GPU device injection or workload creation.
- Disable GPU support: that does not preserve NemoClaw's retained support requirements.
Agent Investigation
Source inspection used OpenShell 0.1.3 revision e1f3c82caa3ed3b65de22889ae7ef32a774878ef and the latest release tag, v0.1.5.
In the v0.1.5 Docker driver, DockerSandboxDriverConfig exposes cdi_devices and mounts, and GPU DeviceRequest uses driver cdi. Source inspection does not establish a live failure on v0.1.5.
The 0.1.3 driver stages runtime/bootstrap files after workload creation and requires workload network mode none. Restart selection cannot target an externally created replacement by immutable Docker ID while an original with the same sandbox labels remains retained.
No physical WSL or Jetson reproduction is claimed here.
Checklist
- Reviewed relevant existing issues, PRs, runtime source, and repository issue templates.
- This is a workflow proposal with observable acceptance criteria.
Activity
rsliter commentedon Oct 22, 2026
We have a local prototype extending #4204 with OpenShell-owned NVIDIA GPU injection for Docker Desktop WSL, tested on real ARM64 N1X hardware. This provides a path to unblock the most critical flow in this issue for the upgrade to OpenShell 0.1.x.
What it does
--gpu --driver-config-json '{"docker":{"nvidia_wsl_gpus":"all"}}'. The gateway operator must enable driver configuration.What we tested
On an NVIDIA RTX Spark N1X running Ubuntu 24.04 under WSL2, Docker Desktop 4.96.0 / Engine 29.9.1, and NVIDIA driver 620.66:
The Docker driver suite passed 165 tests on both macOS and ARM64 Linux, with two existing tests ignored. Strict Clippy and formatting checks also passed.
Scope and remaining work
This is an unpublished prototype based on #4204 at
33350a881f55011286e7c3a68d8007e43e50e0bf. It demonstrates the explicit all-GPU path on this ARM64 WSL host. It does not yet qualify Jetson, x86 WSL, individual GPU selection on multi-GPU hosts, model inference, or NemoClaw’s two compatibility scenarios against a published runtime artifact.The hardware test used an isolated development gateway configuration, so production gateway transport/authentication is also outside this evidence.
This supports a focused Docker Desktop WSL implementation slice; it does not establish completion of all #4837 acceptance criteria.
Feedback or Approval Requested
We'd love feedback on this approach, or approval to proceed.
purp commentedon Nov 5, 2026
Thanks for the detailed write-up. The problem is clear: OpenShell's Docker driver does not support the Docker Desktop WSL and Jetson/Tegra configurations that NemoClaw needs. A few specifics are needed before a maintainer can decide.
What the current code does. On
main, the Docker driver treats CDI as supported whendocker inforeports non-emptyCDISpecDirs. It builds its GPU inventory only fromDiscoveredDevicesentries with sourcecdi. The only injection path is aDeviceRequestwith drivercdi. If no NVIDIA CDI devices are discovered,--gpufails with "no NVIDIA CDI GPU devices were discovered". If the daemon reports no CDI spec dirs, it fails with "docker GPU sandboxes require Docker CDI support".The existing WSL2
nvidia.com/gpu=allfallback applies only when the daemon already listsnvidia.com/gpu=allas a discovered device. It does not help when discovery returns nothing. This is consistent with the issue's premise, but the code alone cannot show what Docker Desktop WSL and Jetson hosts actually report.Information needed
docker infoCDI fields (CDISpecDirs,DiscoveredDevices), plus the exact error fromopenshell sandbox create --gpuon currentmainor the latest release.Scope. This issue combines two host families, hardware qualification, rollback guarantees, and cross-repo NemoClaw qualification. Please split it into separately deliverable issues, each with its own acceptance criteria:
Then narrow or retitle this issue to what remains. Related: #4204 (CDI base, currently open and stale), #1606 (closed), #4327.
Next human decision: a maintainer decides whether to accept the split work once the above is provided.
elezar commentedon Nov 5, 2026
@prekshivyas could you please update the issue description to make the distinction betwen the OpenShell Runtime and the NVIDIA Container Runtime (which I assume is referred to as the "NVIDIA runtime") more clear.
If I understand that ask, what you are asking for is a mechanism to switch between our current CDI-only-based injection to at least the following alternatives:
docker run --gpus={{ .Request }}docker run --gpus={{ .Request }} --runtime=nvidiaIs this correct?
In general, I don't think pushing the compatibility behaviour into OpenShell is the right approach here (or at least not without further motivation). The existing work in #4204 and #2846 attempts to address platform-specific inconsistencies and should remove the need for most of the workarounds that are being put in place on these systems.
One thing to note: Injecting a GPU into the sandbox using an alternative mechansim does not guarantee that the injected paths (device nodes, libraries, etc.) are accessible in a sandbox. These may still be restricted by the landlocked policies that we're applying. The intent of #4204 is to ensure that we also use the CDI specification to populate the required sandbox policies.