feat(gpu): support runtime-owned Docker GPU compatibility for WSL and Jetson #4837

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:

• Native GPU rejection followed by compatibility fallback.
• Compatibility-only GPU startup.

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.