fix(installer): fall back to WSL-local Ollama on native Docker in WSL

[rluo8]

Summary

Express install on WSL auto-selected the Windows-host Ollama provider (install-windows-ollama) regardless of the container runtime. With native Docker Engine inside WSL (no Docker Desktop integration), that provider is rejected at onboarding step [3/8] and, in express's non-interactive mode, aborts with no fallback — leaving a half-completed onboard. Express now probes the runtime and falls back to WSL-local Ollama (install-ollama) when the runtime is not Docker Desktop, so onboarding completes on native-Docker-Engine WSL.

Related Issue

Fixes #7318

Changes

• Add express_wsl_can_use_windows_host_ollama in scripts/install.sh — true only when the container runtime reports Docker Desktop.
• Probe via express_wsl_docker_operating_system = timeout 10 docker info --format '{{.OperatingSystem}}'. The hard timeout keeps a wedged / misconfigured / dead-DOCKER_HOST daemon from hanging the interactive express prompt (this runs through describe_express_install, before ensure_docker, which WSL skips); timeout or any error yields empty output and falls back to WSL-local Ollama.
• activate_express_install "Windows WSL" now selects install-windows-ollama under Docker Desktop and install-ollama (WSL-local Ollama) otherwise. Any indeterminate result (docker unavailable, unknown runtime) also falls back to the WSL-local path, which is the safe default because native Docker-in-WSL cannot reach the Windows host's Ollama ([WSL2][Onboard] Ollama option 8 binds 127.0.0.1, sandbox cannot reach host #3695).
• describe_express_install mirrors the choice in the express summary text, so the disclosure matches the provider that is actually selected.
• docs/get-started/windows-preparation.mdx: document the runtime-based express selection (native Docker Engine now configures WSL-local Ollama instead of aborting).
• Tests: parametrize the existing express-WSL prompt test for Docker Desktop, add a native-Docker-Engine express test, and add cross-platform activate_express_install unit tests (Docker Desktop → install-windows-ollama; native engine → install-ollama; probe failure/timeout → install-ollama).

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 — PASS review: fix(installer): fall back to WSL-local Ollama on native Docker in WSL #7365 (comment)
• 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: The full final diff and docs/get-started/windows-preparation.mdx were reviewed against the implementation and repository docs style. The page now documents the WSL Express boundary: local Docker Desktop WSL integration selects Windows-host Ollama; native Docker Engine, an unavailable or unprobeable runtime, a remote or non-default context, or unreadable or unparseable context fails closed to WSL-local Ollama; the Express prompt remains; and onboarding uses the sandbox auth proxy when containers cannot reach host loopback. It retains the NEMOCLAW_NO_EXPRESS=1 manual-provider escape hatch. The exact-head toppers only make tests host-independent and synchronize current main (f0f23ade57d7d4fb0bc8644f88b6d9525901d7c0); the signed/DCO E2E-retry commit is empty and changes no source tree. The complete effective PR patch is identical to the independently reviewed patch after normalizing only blob-ID index lines and hunk line coordinates (normalized SHA-256 40e0b1eba6753f27696ed74558bb08620d58c10b36e8604888fd0050f6a64836) and changes no additional documented behavior.
• Changed docs: docs/get-started/windows-preparation.mdx
• 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 check:diff passed 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:
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• 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: Rui Luo ruluo@nvidia.com

Summary by CodeRabbit

• New Features

  • Windows WSL express install now auto-selects the right Ollama setup based on Docker Desktop WSL integration vs native Docker Engine availability.
  • The express-install prompt now matches the selected option (Windows-host via host.docker.internal vs WSL-local Ollama).
  • Windows-host Ollama is only chosen for local Docker Desktop targets; remote Docker targets now safely fall back to WSL-local Ollama.
  • You can still decline express setup (or use NEMOCLAW_NO_EXPRESS=1) to choose manually.

• Documentation

  • Updated the Windows WSL guide to clarify selection and fallback behavior.

• Tests

  • Expanded prompt/provider selection coverage with deterministic Docker probing scenarios.

[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

📝 Walkthrough

Walkthrough

The installer now detects Docker Desktop availability and target locality in WSL before selecting Windows-host or WSL-local Ollama. Tests cover runtime and fallback paths, and Windows setup documentation describes the revised express-install behavior.

Changes

WSL Ollama selection

Layer / File(s)	Summary
Detect runtime and select provider scripts/install.sh	Docker operating-system and target-locality detection now selects Windows-host Ollama for local Docker Desktop and WSL-local Ollama for native, unavailable, or remote Docker targets.
Document and test WSL behavior test/install-express-prompt.test.ts, docs/get-started/windows-preparation.mdx	Tests cover Docker Desktop, native Docker Engine, probe failures, and remote targets; Windows setup documentation reflects the updated express-install behavior.

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

Sequence Diagram(s)

sequenceDiagram
  participant ExpressInstall
  participant DockerCLI
  participant OllamaProvider
  ExpressInstall->>DockerCLI: Query local Docker operating system and target
  DockerCLI-->>ExpressInstall: Return Docker Desktop, native engine, or probe failure
  ExpressInstall->>OllamaProvider: Select Windows-host or WSL-local Ollama

Loading

Suggested labels: area: docs, v0.0.92

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.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
Linked Issues check	✅ Passed	The PR addresses #7318 by detecting native Docker in WSL and selecting a compatible Ollama provider so onboarding can complete.
Out of Scope Changes check	✅ Passed	The documentation, prompt text, and tests all support the same installer fallback behavior and do not introduce unrelated scope.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: switching WSL express install to WSL-local Ollama when native Docker is detected.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/7318-wsl-express-native-docker

---

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

[github-actions]

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 5ce658c in the fix/7318-wsl-express... branch remains at 96%, unchanged from commit 3370e93 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 5ce658c in the fix/7318-wsl-express... branch remains at 80%, unchanged from commit f0f23ad in the main branch.

Show a code coverage summary of the most impacted files.

File	main f0f23ad	fix/7318-wsl-express... 5ce658c	+/-
src/lib/domain/.../connect-env.ts	97%	89%	-8%
src/lib/state/m...-acquisition.ts	89%	84%	-5%
src/lib/inferen...ollama/proxy.ts	29%	26%	-3%
src/lib/onboard.ts	31%	31%	0%
src/lib/onboard...p-nim-ollama.ts	90%	90%	0%
src/lib/sandbox...rce-identity.ts	87%	87%	0%
src/lib/state/m...ock-identity.ts	95%	95%	0%
src/lib/state/m...lock-storage.ts	97%	97%	0%
src/lib/onboard...iders/remote.ts	93%	98%	+5%
src/lib/onboard...l-navigation.ts	32%	46%	+14%

---

_{Updated July 25, 2026 16:21 UTC}

[coderabbitai]

Actionable comments posted: 1

🤖 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.

Inline comments:
In `@scripts/install.sh`:
- Around line 3795-3799: Remove the native-Docker detection claim from the
fallback in express install inference-summary logic, using a generic WSL-local
Ollama label for all non-host-probe-success cases. Update
docs/get-started/windows-preparation.mdx to document unavailable runtimes and
probe failures as WSL-local Ollama fallbacks, and extend
test/install-express-prompt.test.ts to exercise the failed-probe prompt path and
assert it does not show a native-Docker-detected summary.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: d28b88f3-1a7c-432e-ae73-cb79e6f28a39

📥 Commits

Reviewing files that changed from the base of the PR and between fdad045 and 243d4fa.

📒 Files selected for processing (3)

• docs/get-started/windows-preparation.mdx
• scripts/install.sh
• test/install-express-prompt.test.ts

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions
Status: Canonical ledger: 0 blocker(s), 1 warning(s), 0 suggestion(s).

Model lanes

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

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

E2E guidance

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

Recommended E2E: cloud-onboard, credential-sanitization, security-posture

1 optional E2E recommendation

• ollama-auth-proxy

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Cover a remote context selected through DOCKER_CONFIG

• Location: test/install-express-wsl-ollama.test.ts:244
• Category: tests
• Problem: The tests cover the default Docker configuration directory but do not cover the supported DOCKER_CONFIG override. A remote currentContext in that directory can select the Windows-host Ollama path if the override is not read correctly.
• Impact: A regression in DOCKER_CONFIG handling could route a remote Docker Desktop target to Windows-host Ollama. Its containers cannot reliably reach the local Windows-host daemon.
• Recommendation: Add a sourced-installer test that sets DOCKER_CONFIG to a temporary directory containing config.json with currentContext remote-prod. Stub Docker Desktop and assert NEMOCLAW_PROVIDER=install-ollama.
• Verification: Inspect express_wsl_docker_active_context in scripts/install.sh and the sourced installer cases in test/install-express-wsl-ollama.test.ts.
• Test coverage: A sourced-installer test with DOCKER_CONFIG pointing to config.json containing {"currentContext":"remote-prod"} must select install-ollama despite a Docker Desktop operating-system result.
• Evidence: scripts/install.sh reads ${DOCKER_CONFIG:-${HOME:-}/.docker}/config.json. test/install-express-wsl-ollama.test.ts covers $HOME/.docker/config.json but has no DOCKER_CONFIG case.

Workflow run details

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

[coderabbitai]

Actionable comments posted: 1

🤖 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.

Inline comments:
In `@scripts/install.sh`:
- Around line 3592-3604: Update express_wsl_docker_target_is_local to resolve
Docker’s effective context, including the persisted currentContext from
~/.docker/config.json when DOCKER_CONTEXT and DOCKER_HOST are unset, and return
false unless that active context is default with no remote host override. Add a
regression test using a temporary Docker config whose currentContext is a remote
context, verifying the guard fails closed.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: f16bc372-c942-4dac-bc36-ba9522f5f5f1

📥 Commits

Reviewing files that changed from the base of the PR and between b00f3f3 and e2c81cb.

📒 Files selected for processing (2)

• scripts/install.sh
• test/install-express-prompt.test.ts

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

• test/install-express-prompt.test.ts

[ericksoa]

Maintainer security review for exact PR SHA 86dff116395b3c9c0158eb9e2de2d0d24cf511b2 against base SHA 2f6298ee165f4821f635be962fedff5e165701ee.

Verdict: PASS. I found no blocking correctness or security issue in the seven-file effective diff.

Category	Verdict	Evidence
1. Secrets and credentials	PASS	The diff adds no credential material and does not print Docker config contents or paths.
2. Input validation and sanitization	PASS	Docker context data is parsed as JSON, compared to the exact local default context, passed as a quoted file argument, and fails closed on malformed, unreadable, remote, or unavailable state.
3. Authentication and authorization	PASS	No authentication or authorization surface changes.
4. Dependencies and third-party libraries	PASS	No dependency or registry changes.
5. Error handling and logging	PASS	Docker probe errors and timeouts select WSL-local Ollama without exposing internal config or credentials.
6. Cryptography and data protection	PASS	No cryptographic or protected-data behavior changes.
7. Configuration and security headers	PASS	Windows-host Ollama is selected only for a local default Docker target that reports Docker Desktop; remote and unknown targets select the local WSL path.
8. Security testing	PASS	Tests cover Docker Desktop, native Docker Engine, probe failure/timeout, DOCKER_HOST, DOCKER_CONTEXT, persisted remote/default contexts, malformed/unreadable config, Node absence, and proxy endpoint state.
9. System security	PASS	The change preserves least-privilege provider selection and does not weaken sandbox, policy, network, or installer trust controls.

Local exact-tree evidence: 94 installer tests passed with one intentional skip; 14 Ollama handler tests passed; npm run docs, normal commit hooks, and pre-push checks passed. scripts/prepare-dgx-station-host.sh is not changed, so the DGX Station hardware-evidence rule does not apply.

Advisory evidence gap: the PR does not attach a reviewer-linked run on a real Windows WSL2 host with native Docker Engine. Deterministic regression coverage is present, and exact-head CI/E2E is still running.

[ericksoa]

Maintainer sensitive-path review refresh for exact PR SHA f2b724d79ef487bbc56f8c4d5f697a71fd72010d against base SHA 9171d797f4d258a28d48bf5e5961d2116e30b4e7.

Verdict: PASS. No blocking correctness or security findings.

The effective seven-file PR diff is byte-for-byte identical to the previously reviewed 86dff1163 / 2f6298ee1 diff (SHA-256 f08449943a74d2f4f5f4c93a69ffb1bb982b63904eb09002551477823e353014). The only new commit merges current main; its two main-side files are outside the effective PR diff. The prior nine-category findings therefore carry forward unchanged: secrets/credentials, input validation, authorization boundaries, dependency/supply chain, error handling/logging, cryptography, configuration/defaults, security tests, and system interaction all PASS.

Fresh exact-tree evidence:

• WSL/Express installer integration: 94 passed, 1 intentional skip.
• onboarding unit suite: 14 passed.
• current-main Perl contract: 4 passed.
• npm run docs: passed; generated variants and guarded routes are current (0 errors, 2 existing Fern warnings).

Detailed prior review: #7365 (comment)

The remaining advisory is unchanged: there is no reviewer-linked real native-Docker WSL2 hardware run. Deterministic coverage exercises the decision boundary, and this path has no repository-required hardware evidence rule.

[ericksoa]

Maintainer sensitive-path review refresh for exact PR SHA 45f8e3b98e5cda43de3e41b3dfc1b0759ac5e24c against base SHA 6e8d21af09e724c1d6ddd3c6d8124d3578ebe291.

Verdict: PASS. No blocking correctness or security findings.

The current-main merge was conflict-free. Because current main also changed scripts/install.sh, raw patch blob IDs and hunk offsets moved; after removing those non-semantic anchors, the complete seven-file effective PR patch is identical to the fully reviewed prior patch (normalized SHA-256 40e0b1eba6753f27696ed74558bb08620d58c10b36e8604888fd0050f6a64836). The prior nine-category findings therefore remain unchanged: secrets/credentials, input validation, authorization boundaries, dependency/supply chain, error handling/logging, cryptography, configuration/defaults, security tests, and system interaction all PASS.

Fresh exact-tree evidence:

• WSL/Express installer integration: 94 passed, 1 intentional skip.
• onboarding unit suite: 14 passed.
• npm run docs: passed; generated variants and guarded routes are current (0 errors, 2 existing Fern warnings).
• normal merge hooks and pre-push CLI typecheck/tag synchronization passed.

Detailed reviews: #7365 (comment) and #7365 (comment)

The remaining advisory is unchanged: there is no reviewer-linked real native-Docker WSL2 hardware run. Deterministic coverage exercises the decision boundary, and this path has no repository-required hardware evidence rule.

[ericksoa]

Maintainer sensitive-path review refresh for exact PR SHA 5a4f57ec265aa627ec9cbb5df79dcc4b58d1f550 against base SHA 6e8d21af09e724c1d6ddd3c6d8124d3578ebe291.

Verdict: PASS. No blocking correctness or security findings.

This head adds only a signed and DCO-compliant empty commit to recover from the terminal E2E controller-authorization publication race in runs 30160718543 and 30160733837; no selected E2E job or secret ran in that failed attempt. Its Git tree is byte-identical to reviewed head 45f8e3b98e5cda43de3e41b3dfc1b0759ac5e24c. The complete seven-file effective PR patch remains identical after normalizing raw blob-ID index lines and hunk coordinates (SHA-256 40e0b1eba6753f27696ed74558bb08620d58c10b36e8604888fd0050f6a64836).

The prior nine-category findings therefore remain unchanged: secrets/credentials, input validation, authorization boundaries, dependency/supply chain, error handling/logging, cryptography, configuration/defaults, security tests, and system interaction all PASS.

Exact-tree evidence carried forward unchanged:

• WSL/Express installer integration: 94 passed, 1 intentional skip.
• onboarding unit suite: 14 passed.
• npm run docs: passed; generated variants and guarded routes are current (0 errors, 2 existing Fern warnings).
• normal merge hooks and pre-push CLI typecheck/tag synchronization passed.

Detailed reviews: #7365 (comment) and #7365 (comment)

The remaining advisory is unchanged: there is no reviewer-linked real native-Docker WSL2 hardware run. Deterministic coverage exercises the decision boundary, and this path has no repository-required hardware evidence rule.

[ericksoa]

Maintainer sensitive-path review refresh for exact PR SHA ef25772dd0ac828c74c4408567cbb90d79a76d8d against current base SHA f0f23ade57d7d4fb0bc8644f88b6d9525901d7c0.

Verdict: PASS. No blocking correctness or security findings.

The current-main refresh was conflict-free. The intervening main commit changes sandbox gateway/version-probe code and tests, with no path overlap with this PR. After normalizing raw blob-ID index lines and hunk coordinates, the complete seven-file effective PR patch remains identical to the fully reviewed patch (SHA-256 40e0b1eba6753f27696ed74558bb08620d58c10b36e8604888fd0050f6a64836). The prior nine-category findings therefore remain unchanged: secrets/credentials, input validation, authorization boundaries, dependency/supply chain, error handling/logging, cryptography, configuration/defaults, security tests, and system interaction all PASS.

Fresh exact-tree evidence:

• WSL/Express installer integration: 94 passed, 1 intentional skip.
• onboarding unit suite: 14 passed.
• npm run docs: passed; generated variants and guarded routes are current (0 errors, 2 existing Fern warnings).
• merge hooks and non-force push prechecks passed; the merge commit is signed, DCO-compliant, and GitHub Verified.

Detailed reviews: #7365 (comment) and #7365 (comment)

The remaining advisory is unchanged: there is no reviewer-linked real native-Docker WSL2 hardware run. Deterministic coverage exercises the decision boundary, and this path has no repository-required hardware evidence rule.