fix(onboard): reject macOS Podman compat socket before gateway launch (#7320)

[yimoj]

Summary

On Apple Silicon macOS, onboarding forces the OpenShell Docker-driver gateway path. When the Docker CLI is routed to a Podman machine's Docker compatibility socket, preflight failed to recognize Podman and let onboarding start the Docker-driver gateway, which then bound Podman's VM-only bridge address (10.89.1.1:8080) and exited EADDRNOTAVAIL. This change detects Podman behind the compatibility socket in preflight and fails closed early with the existing unsupported-runtime guidance, before any gateway launch. Podman remains unsupported per ci/platform-matrix.json; no Podman support is added.

Related Issue

Fixes #7320

Changes

• src/lib/onboard/preflight.ts: assessHost() now reclassifies a Docker CLI fronting Podman's docker-compat socket as runtime: "podman". Podman's /info mimics Docker and carries no "podman" marker (observed: ServerVersion "5.6.2", OperatingSystem "fedora"), so detection uses two observed docker-compat signals: the explicit docker version --format '{{json .}}' "Podman Engine" server component (primary), and the /info ProductLicense: "Apache-2.0" (backstop when the version probe is unavailable). The docker version probe runs only when the daemon is reachable. No false positives on Docker Engine, Docker Desktop, or Colima.
• src/lib/onboard/preflight-messages.ts: the unsupported-runtime recovery message now names Docker Engine, Docker Desktop, and Colima (macOS reporters use Docker Desktop/Colima, not native Docker Engine).
• Regression tests: preflight-podman-compat.test.ts (real docker-compat info+version metadata drives runtime: "podman"; real Docker stays supported) and fatal-runtime-preflight.test.ts (the rejection path); message-guidance assertions in preflight-messages.test.ts.

The existing preflight gate (rejectUnsupportedContainerRuntime) already runs on both the fresh and resume paths before the gateway state; correcting runtime detection is what makes it fire. No new abstraction, config, or fallback path is introduced.

Type of Change

• Code change (feature, bug fix, or refactor)

Quality Gates

• Tests added or updated for changed behavior
• Docs not applicable — justification: docs/reference/platform-support.mdx and troubleshooting.mdx already document Podman as unsupported and direct users to Docker Engine/Docker Desktop/Colima; this fix makes that already-documented rejection actually fire for the macOS docker-compat case.
• 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: preflight/onboarding path; local code-review (high) surfaced only two low-severity, non-blocking design notes (ProductLicense backstop scope; one extra docker version subprocess per reachable-Docker assessHost), both acceptable; awaiting maintainer sensitive-path review.

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 check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set — command/result: npx vitest run src/lib/onboard/preflight-podman-compat.test.ts src/lib/onboard/fatal-runtime-preflight.test.ts src/lib/onboard/preflight-messages.test.ts src/lib/onboard/preflight.test.ts → 143 passed; full --project cli → 9593 passed / 1 skipped.
• No secrets, API keys, or credentials committed

Real-CLI E2E (Apple Silicon macOS, Podman docker-compat socket)

Reproduced the exact reporter command ./bin/nemoclaw.js onboard --fresh on an Apple Silicon macOS host (macOS 26.5.2, arm64) with a running podman machine whose Docker compatibility socket forwards to /var/run/docker.sock, Docker CLI 29.3.1 routed to it (ServerVersion 5.6.2, ProductLicense Apache-2.0, DefaultRuntime crun).

• Pre-fix: preflight misclassified the runtime (✓ Container runtime: docker) and advanced to [2/8] Starting OpenShell gateway → Starting OpenShell Docker-driver gateway — the forced Docker-driver path the reporter hits.
• Post-fix: onboarding fails closed at [1/8] Preflight checks with ✗ … Podman is not supported for this NemoClaw integration path. Switch to Docker Engine, Docker Desktop, or Colima, then rerun onboarding. and exits non-zero (1), before any gateway launch. assessHost() against the live socket now reports runtime: "podman", isUnsupportedRuntime: true.

---

Signed-off-by: Yimo Jiang yimoj@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Improved host runtime detection to correctly identify Podman when it fronts Docker-compatible interfaces.
  • Unsupported Podman environments are now blocked earlier in onboarding, with clearer “switch to Docker Engine, Docker Desktop, or Colima” guidance.
• Tests
  • Added targeted test coverage for runtime rejection behavior and Podman/docker-compat detection scenarios.
  • Expanded assertions to validate macOS-oriented error message guidance.

[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: 7cc508bd-3f1d-4948-ae89-5715fb5d49fd

📥 Commits

Reviewing files that changed from the base of the PR and between a58a9bf and 67cf46d.

📒 Files selected for processing (1)

• src/lib/onboard/fatal-runtime-preflight.test.ts

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

• src/lib/onboard/fatal-runtime-preflight.test.ts

---

📝 Walkthrough

Walkthrough

Podman Docker-compatibility detection was added to onboarding preflight. The runtime is reclassified before gateway setup, unsupported-runtime rejection is covered by tests, and error guidance now includes Docker Engine, Docker Desktop, and Colima.

Changes

Podman preflight handling

Layer / File(s)	Summary
Podman compatibility detection src/lib/onboard/preflight.ts, src/lib/onboard/preflight-podman-compat.test.ts	Parses Docker version and info output to detect Podman behind the Docker compatibility socket, with injectable version output and fixtures.
Preflight runtime reclassification src/lib/onboard/preflight.ts, src/lib/onboard/preflight-podman-compat.test.ts	Captures docker version output and reclassifies compatible Podman before gateway bindings; tests cover Podman and real Docker.
Unsupported runtime rejection and messaging src/lib/onboard/fatal-runtime-preflight.test.ts, src/lib/onboard/preflight-messages.ts, src/lib/onboard/preflight-messages.test.ts, src/lib/onboard/preflight-podman-compat.test.ts	Tests Podman rejection and supported Docker behavior, while expanding unsupported-runtime guidance for Docker Engine, Docker Desktop, and Colima.

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

Sequence Diagram(s)

sequenceDiagram
  participant Onboarding
  participant assessHost
  participant DockerCLI
  participant RuntimeGate
  Onboarding->>assessHost: assess container runtime
  assessHost->>DockerCLI: query docker version and info
  DockerCLI-->>assessHost: compatibility metadata
  assessHost->>RuntimeGate: classify runtime as podman or docker
  RuntimeGate-->>Onboarding: reject unsupported Podman or continue Docker flow

Loading

Possibly related PRs

• NVIDIA/NemoClaw#7350: Contains overlapping Podman Docker-compatibility detection, injectable version output, and unsupported-runtime coverage.

Suggested labels: area: onboarding, bug-fix

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.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 matches the main change: rejecting Podman-compatible macOS onboarding before gateway launch.
Linked Issues check	✅ Passed	The code and tests implement the requested pre-launch rejection for macOS Podman compatibility sockets, preventing the gateway crash in #7320.
Out of Scope Changes check	✅ Passed	The added runtime-detection logic, tests, and updated guidance all support the issue scope and do not introduce unrelated changes.

✨ 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/7320-macos-podman-preflight

---

_{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 67cf46d in the fix/7320-macos-podma... branch remains at 96%, unchanged from commit 33f210e in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 67cf46d in the fix/7320-macos-podma... branch remains at 80%, unchanged from commit 7be1bad in the main branch.

Show a code coverage summary of the most impacted files.

File	main 7be1bad	fix/7320-macos-podma... 67cf46d	+/-
src/lib/state/m...-acquisition.ts	89%	87%	-2%
src/lib/sandbox...rce-identity.ts	87%	87%	0%
src/lib/tunnel/services.ts	73%	73%	0%
src/lib/onboard/preflight.ts	81%	82%	+1%
src/lib/inferen...er-lifecycle.ts	65%	71%	+6%
src/lib/onboard...me-preflight.ts	32%	50%	+18%
src/lib/inferen...lama/process.ts	50%	100%	+50%

---

_{Updated July 22, 2026 04:10 UTC}

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / medium confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: No actionable findings remain in the canonical review ledger.

Model lanes

• GPT-5.6 Terra (primary): Completed · medium confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized E2E selections match; severity counts match.

Nemotron output stays in workflow artifacts and does not change the assessment above.

Since last review: 0 prior items resolved · 0 still apply · 0 new items found

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: onboard-repair, onboard-resume, cloud-onboard

1 optional E2E recommendation

• onboard-negative-paths

Workflow run details

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

[coderabbitai]

🧹 Nitpick comments (1)

src/lib/onboard/fatal-runtime-preflight.test.ts (1)

9-30: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

hostWithRuntime uses as HostAssessment to paper over missing fields.

The literal omits several HostAssessment fields (packageManager, systemctlAvailable, dockerServiceActive/dockerServiceEnabled, dockerInfoSummary, dockerCgroupVersion, dockerDefaultCgroupnsMode, dockerStorageDriver, dockerUsesContainerdSnapshotter, dockerCpus, dockerMemTotalBytes) and relies on as HostAssessment to suppress the resulting type error. This defeats the compiler's missing-required-property check, so a future required field added to HostAssessment won't be caught here.

♻️ Proposed fix: fill in the remaining fields (or type as Partial and merge)

 function hostWithRuntime(runtime: HostAssessment["runtime"]): HostAssessment {
   return {
     platform: process.platform,
     isWsl: false,
     runtime,
+    packageManager: "unknown",
+    systemctlAvailable: false,
+    dockerServiceActive: null,
+    dockerServiceEnabled: null,
     dockerInstalled: true,
     dockerRunning: true,
     dockerReachable: true,
     nodeInstalled: true,
     openshellInstalled: true,
+    dockerInfoSummary: undefined,
+    dockerCgroupVersion: "unknown",
+    dockerDefaultCgroupnsMode: undefined,
+    dockerStorageDriver: undefined,
+    dockerUsesContainerdSnapshotter: false,
+    dockerCpus: undefined,
+    dockerMemTotalBytes: undefined,
     isContainerRuntimeUnderProvisioned: false,
     hasNestedOverlayConflict: false,
     requiresHostCgroupnsFix: false,
     isUnsupportedRuntime: runtime === "podman",
     isHeadlessLikely: false,
     hasNvidiaGpu: false,
     dockerCdiSpecDirs: [],
     cdiNvidiaGpuSpecMissing: false,
     nvidiaContainerToolkitInstalled: false,
     notes: [],
-  } as HostAssessment;
+  };
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/onboard/fatal-runtime-preflight.test.ts` around lines 9 - 30, Update
hostWithRuntime to provide values for every required HostAssessment field,
including packageManager, systemctlAvailable, Docker service/status details,
resource metadata, and containerd snapshotter state. Remove the as
HostAssessment assertion so the object literal is checked directly and future
required fields remain compiler-enforced.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/lib/onboard/fatal-runtime-preflight.test.ts`:
- Around line 9-30: Update hostWithRuntime to provide values for every required
HostAssessment field, including packageManager, systemctlAvailable, Docker
service/status details, resource metadata, and containerd snapshotter state.
Remove the as HostAssessment assertion so the object literal is checked directly
and future required fields remain compiler-enforced.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: cd628443-7be2-41f1-b899-415c3134b320

📥 Commits

Reviewing files that changed from the base of the PR and between 5087eb4 and a58a9bf.

📒 Files selected for processing (5)

• src/lib/onboard/fatal-runtime-preflight.test.ts
• src/lib/onboard/preflight-messages.test.ts
• src/lib/onboard/preflight-messages.ts
• src/lib/onboard/preflight-podman-compat.test.ts
• src/lib/onboard/preflight.ts