fix(cli): preserve healthy Docker authority

[prekshivyas]

Summary

NemoClaw now preserves a reachable Docker CLI default, including a custom DOCKER_CONFIG, when DOCKER_HOST is unset instead of replacing it with the first existing socket.
If the default is unreachable, the CLI probes only its bounded local-socket candidates and selects a fallback only when server-version evidence identifies one runtime.

Related Issue

Fixes #8816

Changes

• Preserve an explicit DOCKER_HOST without probing or replacing its authority.
• Probe the Docker CLI default before local fallbacks so a reachable Docker Engine remains selected when Docker and Podman sockets coexist.
• Validate each allowlisted fallback for reachability and Docker or Podman identity. Mixed or unknown fallback identities produce no automatic override.
• Reuse the existing Docker-compatible server-version classifier from host preflight instead of creating a second runtime identity rule.
• Preserve a reachable configured DOCKER_CONTEXT and its DOCKER_CONFIG directory for Docker commands, and clear the context only when a verified socket fallback must take precedence.
• Add regression coverage for explicit endpoints, coexistence, Podman-only hosts, stale sockets, mixed runtimes, unknown engines, and probe environment filtering.
• Update the system-readiness reference with the default and fallback authority order.

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:
• Docs updated for user-facing behavior changes
• Docs 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: Maintainer review covered endpoint validation, credential filtering, failure handling, and runtime authority. The read-only default probe and Docker runner preserve DOCKER_CONTEXT and its DOCKER_CONFIG path; fallback probes and host overrides omit both; selecting a verified fallback clears the conflicting context; and non-Docker commands receive neither value. Regression coverage confirms NVIDIA_INFERENCE_API_KEY remains filtered at both boundaries. The maintainer explicitly approved this Docker-only configuration boundary.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: docs/reference/system-readiness.mdx documents Docker default-authority selection with DOCKER_CONTEXT and DOCKER_CONFIG, verified local socket fallback, and conflicting context removal.
• Agent: Codex Desktop

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: 10 focused regression and security files passed 308 tests on the refreshed head; CLI and plugin builds and type checks passed; the full pre-commit, commit-message, and pre-push sequence passed against upstream/main.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Not required for this focused CLI change.
• 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) — result: the build passed; Fern reported two baseline warnings that it suppresses unless run with --warnings.
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Prekshi Vyas prekshiv@nvidia.com

Summary by CodeRabbit

• Enhancements

  • Improved Docker runtime detection using configured hosts, Docker CLI defaults, and eligible local sockets.
  • Verifies runtime identity before selecting an endpoint, distinguishing Docker from Podman and rejecting unknown or conflicting results.
  • Improved readiness and profile selection when multiple container runtimes are available.
  • Applies Docker context settings appropriately, clearing them for selected socket fallbacks while preserving explicit configurations.

• Documentation

  • Updated system readiness guidance to explain Docker fallback detection and runtime compatibility behavior.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

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: 9ce097ea-6fe2-4cfe-a213-2fc0d94266df

📥 Commits

Reviewing files that changed from the base of the PR and between af062ea and 982a17d.

📒 Files selected for processing (5)

• docs/reference/system-readiness.mdx
• src/lib/platform.ts
• src/lib/runner.ts
• test/platform.test.ts
• test/runner.test.ts

🚧 Files skipped from review as they are similar to previous changes (5)

• docs/reference/system-readiness.mdx
• src/lib/runner.ts
• test/runner.test.ts
• src/lib/platform.ts
• test/platform.test.ts

---

📝 Walkthrough

Walkthrough

Docker host detection now probes the CLI default authority and validates Docker or Podman identity before selecting socket fallbacks. Runner environments preserve or clear Docker context settings by command type. Tests cover mixed runtimes, explicit hosts, unknown identities, readiness, profile compatibility, and probe filtering.

Changes

Docker authority detection

Layer / File(s)	Summary
Probe contracts and engine classification src/lib/platform.ts	Added constrained docker version probing and classification for Docker, Podman, and unknown identities.
Validated host selection and readiness wiring src/lib/platform.ts, src/lib/onboard/preflight.ts, docs/reference/system-readiness.mdx	The default Docker authority is checked before socket candidates. Unreachable, unknown, or conflicting runtimes are rejected. The documentation describes these rules.
Docker context environment propagation src/lib/runner.ts	Docker subprocesses preserve Docker context and configuration only when no explicit Docker host is configured. Socket fallbacks clear DOCKER_CONTEXT.
Runtime, profile, and command regression coverage test/platform.test.ts, test/docker-authority-profile.test.ts, test/runner.test.ts, test/ollama-gpu-cleanup.test.ts, src/lib/shields/index.test.ts	Added runtime and profile tests. Updated mocks and command assertions to account for Docker authority probes.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant NemoClaw
  participant DockerCLI
  participant SocketCandidates
  participant Readiness
  NemoClaw->>DockerCLI: Probe default docker version authority
  DockerCLI-->>NemoClaw: Return reachability and server identity
  NemoClaw->>SocketCandidates: Probe fallback sockets when required
  SocketCandidates-->>NemoClaw: Return validated endpoint identity
  NemoClaw->>Readiness: Project selected runtime
  Readiness-->>NemoClaw: Resolve Docker-only profile compatibility

Loading

Possibly related PRs

• NVIDIA/NemoClaw#8732: Related Docker/Podman runtime detection and onboarding environment handling.

Suggested labels: platform: container, area: networking

Suggested reviewers: senthilr-nv, cv

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 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: preserving a healthy Docker authority during CLI detection.
Linked Issues check	✅ Passed	The changes address issue #8816 by preserving explicit and healthy Docker authorities, validating fallback identity, rejecting ambiguity, and adding regression and integration coverage.
Out of Scope Changes check	✅ Passed	The implementation, documentation, mocks, and test updates all support Docker authority detection, runtime classification, or regression coverage for issue #8816.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/preserve-docker-authority

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 982a17d in the agent/preserve-docke... branch remains at 96%, unchanged from commit 9642eb0 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 982a17d in the agent/preserve-docke... branch remains at 82%, unchanged from commit 9642eb0 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 9642eb0	agent/preserve-docke... 982a17d	+/-
src/lib/cua/bounded-file.ts	94%	84%	-10%
src/lib/cua/run...ime-manifest.ts	91%	84%	-7%
src/lib/cua/contract.ts	87%	80%	-7%
src/lib/trace.ts	94%	90%	-4%
src/lib/state/o...d-checkpoint.ts	90%	87%	-3%
src/lib/onboard/preflight.ts	82%	83%	+1%
src/lib/onboard...press-resume.ts	78%	81%	+3%
src/lib/securit...ntial-filter.ts	91%	95%	+4%
src/lib/onboard...der/snapshot.ts	75%	83%	+8%
src/lib/platform.ts	84%	95%	+11%

---

_{Updated August 12, 2026 01:21 UTC}

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-8823.docs.buildwithfern.com/nemoclaw

[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

Model lanes

• GPT-5.6 Terra (primary): Completed · medium confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Failed after a partial review · low confidence · 0 blockers · 0 warnings · 0 suggestions

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

3 semantic terminology decisions

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• established — Docker authority at test/docker-authority-profile.test.ts:48: Keep `Docker authority`; repository lifecycle and receipt documentation already use this term consistently.
• established — server-version evidence at docs/reference/system-readiness.mdx:104: Keep `server-version evidence`; existing readiness documentation and Docker-host validation use this term.
• justified — selected authority at docs/reference/system-readiness.mdx:103: Keep `selected authority`; the modifier distinguishes Docker CLI selection from a socket fallback.

E2E guidance

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

Recommended E2E: None

Manual-only E2E: cloud-onboard, onboard-repair, onboard-resume
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.

[senthilr-nv]

Approved: #8816 remains in scope; Docker authority now preserves DOCKER_CONTEXT and DOCKER_CONFIG without exposing them to non-Docker commands, focused validation and required checks pass on 982a17d, and automated review has no findings.