fix(onboard): pre-pull sandbox GPU image

[laitingsheng]

Summary

On Docker Desktop WSL, managed bootstrap now inspects and explicitly pulls the exact managed sandbox image before GPU mode selection. Docker mode probes then use --pull never, so their 30-second capability timeout no longer includes first-install registry latency.

Related Issue

Fixes #10105

Changes

• Inspect the exact-digest managed sandbox image and pull it with progress reporting and a 30-minute maximum when it is absent locally.
• Prevent Docker Desktop WSL GPU mode probes from starting implicit image pulls while retaining existing probe behavior on other Docker hosts.
• Cover cold and warm image caches, pull timeout handling, both compatibility mode candidates, and unchanged non-WSL selection.
• Docker Desktop WSL currently requires NemoClaw's compatibility GPU route. Raising the 30-second probe timeout would still conflate image transfer with capability detection; docker-runtime.test.ts protects the separate pull and probe sequence.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: Pending maintainer review.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run validate:pr passed after refreshing origin/main when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: npx vitest run --project cli on four GPU onboarding files passed 4 files and 90 tests; CLI build, strict CLI typecheck, formatting, targeted Oxlint, and repository checks also passed.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Not applicable; scope is limited to Docker Desktop WSL managed-bootstrap image preparation and its targeted test seams.
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Tinson Lai tinsonl@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Improved GPU-enabled Docker setup on Docker Desktop with WSL.
  • Automatically checks for required images and pulls missing images before setup when needed.
  • Avoids unnecessary image downloads when the required image is already available locally.
  • Added clearer handling for image-pull timeouts, startup failures, and unsuccessful Docker operations.
  • Improved GPU compatibility checks by preventing unintended image pulls during probing.

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall line coverage in commit 5cf14e7 in the fix/gpu-probe-image-... branch remains at 96%, unchanged from commit 645b459 in the main branch.

---

_{Updated August 24, 2026 20:32 UTC}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: ccf68e06-1961-464f-9523-5e31e208a69b

📥 Commits

Reviewing files that changed from the base of the PR and between 5a56a77 and 717974c.

📒 Files selected for processing (4)

• src/lib/onboard/docker-gpu-patch-mode-selection.test.ts
• src/lib/onboard/docker-gpu-patch-mode.ts
• src/lib/onboard/managed-bootstrap/docker-runtime.test.ts
• src/lib/onboard/managed-bootstrap/docker-runtime.ts

Included review availability: Your plan provides up to 12 included reviews per hour; 10 remain after this review.

---

📝 Walkthrough

Walkthrough

Docker Desktop WSL managed bootstrap now prepares the sandbox image before GPU probing. GPU probes can disable image pulls after preparation. Tests cover cached and uncached images, non-WSL behavior, probe execution, and pull failures.

Changes

Docker GPU bootstrap

Layer / File(s)	Summary
GPU probe pull policy src/lib/onboard/docker-gpu-patch-mode.ts, src/lib/onboard/docker-gpu-patch-mode-selection.test.ts	GPU mode selection accepts an optional "never" pull policy. Probes add --pull never when configured and retain the default "missing" behavior.
WSL image preparation src/lib/onboard/managed-bootstrap/docker-runtime.ts	Docker Desktop WSL inspects and pulls the managed image before deferred GPU mode selection. Pull timeouts, startup failures, and nonzero exit statuses produce specific errors. Replacement options are created after preparation.
Bootstrap flow validation src/lib/onboard/managed-bootstrap/docker-runtime.test.ts	Tests cover uncached and cached WSL images, non-WSL implicit pulls, bounded GPU probes, and pull-timeout behavior.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: 🟡 Moderate · up to 71797

This change separates managed GPU image preparation from capability probing on Docker Desktop WSL, which should avoid first-install registry latency during mode detection. Targeted validation is reported as passing, but the required sensitive-path maintainer review or waiver and related quality-gate completion are still pending, so the PR is not merge-ready until they are recorded.

Suggested reviewers: ericksoa, prekshivyas, apurvvkumaria

Sequence Diagram(s)

sequenceDiagram
  participant runCreate
  participant DockerImageInspection
  participant DockerWatchdogPull
  participant selectDockerGpuPatchMode
  runCreate->>DockerImageInspection: Inspect managed sandbox image
  DockerImageInspection-->>runCreate: Report image availability
  runCreate->>DockerWatchdogPull: Pull image when unavailable
  DockerWatchdogPull-->>runCreate: Return pull result or error
  runCreate->>selectDockerGpuPatchMode: Select GPU mode with pullPolicy "never"
  selectDockerGpuPatchMode-->>runCreate: Return selected GPU mode

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the primary change: pre-pulling the sandbox GPU image during onboarding.
Linked Issues check	✅ Passed	The changes address issue #10105 by pre-pulling the WSL sandbox image and preventing GPU probes from pulling it.
Out of Scope Changes check	✅ Passed	The implementation and tests remain within the linked issue scope of Docker Desktop WSL image preparation and GPU probe behavior.
Docstring Coverage	✅ Passed	Docstring check was indeterminate for this PR — some files could not be analyzed in time. Not blocking.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/gpu-probe-image-pull

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Synthesis status: Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite for the commit under review.

Recommended E2E: managed-image-protected-runtime

Manual-only E2E: managed-image-multiarch-startup, onboard-repair, onboard-resume, cloud-onboard
The manual PR workflow does not run these selectors for the commit under review. Run them from reviewed code on main.

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.