fix(onboard): validate Windows Ollama from Docker

[cjagwani]

Summary

Windows-host Ollama validation on WSL ran from the WSL host, where Docker Desktop does not define host.docker.internal. This change runs the credential-free validation request from Docker Desktop's network context and restricts that path to the configured Windows-host Ollama endpoint.

Related Issue

Fixes #8127

Changes

• Add a Docker-context curl adapter that preserves validated curl arguments, rejects credential config files, and binds only the probe response directory under the operating-system temporary directory.
• Use the adapter only for the configured http://host.docker.internal:<ollama-port>/v1 route with no API key, extra headers, query, fragment, or embedded URL credentials.
• Keep the direct host probe for every other inference endpoint.
• Add source tests for strict and compatibility validation paths, credential and route rejection, temp-directory mount boundaries, and Windows-host Ollama option selection.

The adapter is required because Docker Desktop defines host.docker.internal in the container network context, not in the WSL host resolver. src/lib/inference/onboard-host-docker-internal.test.ts protects the current Windows-host Ollama consumer and verifies that both validation modes execute through Docker.

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: docs/inference/set-up-ollama.mdx already documents Windows-host Ollama from WSL, Docker Desktop integration, host.docker.internal:11434, validation, and the unauthenticated-port warning. This change restores that documented path.
• 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: Codex Desktop reviewed command injection, authentication, credential handling, cryptography, network exposure, input parsing, dependencies, filesystem access, and logic. The path uses argv-based process execution, accepts only the configured credential-free Windows-host Ollama route, rejects curl credential configs, and limits the bind mount to the probe response directory under the operating-system temporary directory.
• 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: no-docs-needed
• Evidence: Existing docs/inference/set-up-ollama.mdx and docs/reference/troubleshooting.mdx already cover the restored Windows-host Ollama behavior, validation, security warning, detection, and restart remediation. No documentation paths changed.
• 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: npm exec vitest run -- --project cli src/lib/adapters/http/container-curl-probe.test.ts src/lib/inference/onboard-host-docker-internal.test.ts src/lib/inference/local.test.ts src/lib/onboard/inference-selection-validation.test.ts passed 112 tests in 4 files. npm run typecheck:cli 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 run; this change is limited to the Windows-host Ollama validation path and has focused source-test coverage.
• 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: Charan Jagwani cjagwani@nvidia.com

Summary by CodeRabbit

• New Features

  • Added container-based connectivity checks for supported local AI endpoints.
  • Added validation for Docker-hosted Ollama endpoints, including port, route, credential, and output-path checks.
  • Added support for injecting and reusing custom probe processes during endpoint validation.

• Bug Fixes

  • Improved Docker-context detection and fallback behavior when container probing is unavailable.
  • Prevented invalid or unsafe curl requests from being executed.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds a Docker-based curl probe, validates restricted Windows-host Ollama URLs, and propagates injectable process spawners through inference probing and retry paths.

Changes

Docker-context Ollama probing

Layer / File(s)	Summary
Container curl probe src/lib/adapters/http/container-curl-probe.ts, src/lib/adapters/http/container-curl-probe.test.ts, src/lib/inference/onboard-host-docker-internal.ts	Adds Docker curl execution with temporary-directory output restrictions, credential-file rejection, UID/GID matching, and validation tests.
Docker-context selection validation src/lib/inference/local.ts, src/lib/inference/local.test.ts, src/lib/onboard/inference-selection-validation.ts, src/lib/inference/onboard-host-docker-internal.test.ts	Adds probeFromDocker options and enables them for host.docker.internal with the expected Ollama port. Tests cover host resolution, Docker invocation, credentials, headers, and URL variants.
Probe spawner propagation and routing src/lib/inference/onboard-probes.ts	Propagates spawnSyncImpl through standard, tool-calling, timeout, retry, and fallback probes. Docker requests use the container probe and bypass optimized validation-session probing.

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

Sequence Diagram(s)

sequenceDiagram
  participant Onboarding
  participant OpenAILikeValidation
  participant ContainerCurlProbe
  participant Docker
  participant Ollama
  Onboarding->>OpenAILikeValidation: validate OpenAI-like selection
  OpenAILikeValidation->>ContainerCurlProbe: request Docker-context probe
  ContainerCurlProbe->>Docker: run curl container
  Docker->>Ollama: request host.docker.internal:11434
  Ollama-->>Docker: return endpoint response
  Docker-->>ContainerCurlProbe: return curl result
  ContainerCurlProbe-->>OpenAILikeValidation: return probe result

Loading

Possibly related PRs

• NVIDIA/NemoClaw#5418: Modifies the same OpenAI-like selection validation flow.
• NVIDIA/NemoClaw#5432: Modifies overlapping Ollama onboarding and probing logic.
• NVIDIA/NemoClaw#5887: Relates to curl-based provider reachability validation.

Suggested labels: platform: container, area: security

Suggested reviewers: ericksoa, 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 identifies the onboarding fix for validating Windows-hosted Ollama from Docker.
Linked Issues check	✅ Passed	The changes address issue #8127 by validating credential-free Windows-hosted Ollama endpoints through Docker context.
Out of Scope Changes check	✅ Passed	The changes remain focused on Docker-based Ollama reachability validation, argument safety, and related tests.

✨ 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 codex/fix-8127-wsl-ollama-probe

---

_{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 add8bf0 in the codex/fix-8127-wsl-o... branch remains at 96%, unchanged from commit 8c542b2 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit add8bf0 in the codex/fix-8127-wsl-o... branch remains at 81%, unchanged from commit 8c542b2 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 8c542b2	codex/fix-8127-wsl-o... add8bf0	+/-
src/lib/inferen...board-probes.ts	93%	91%	-2%
src/lib/inferen...ompatibility.ts	95%	94%	-1%
src/lib/inferen...ker-internal.ts	100%	100%	0%
src/lib/sandbox...rce-identity.ts	88%	88%	0%
src/lib/state/g...way-registry.ts	94%	94%	0%
src/lib/tunnel/services.ts	76%	76%	0%
src/lib/inference/local.ts	79%	80%	+1%
src/lib/onboard...shboard-port.ts	90%	96%	+6%
src/lib/adapter...r-curl-probe.ts	0%	85%	+85%

---

_{Updated August 03, 2026 17:11 UTC}

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / low confidence
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions
Status: Partial review preserved 1 canonical finding(s) and 3 terminology decision(s) before the advisor stopped.

Model lanes

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

Second-opinion terminology and E2E selections are advisory. They do not change the primary assessment or E2E / PR Gate.

3 semantic terminology decisions

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

• justified — Docker-context validation at src/lib/inference/onboard-probes.ts:709: Keep this term for the restricted Docker Desktop probe path and contrast it with host-side validation when both paths are discussed.
• established — Windows-host Ollama at src/lib/inference/onboard-host-docker-internal.test.ts:50: Keep the established term for this WSL and Docker Desktop route.
• established — credential-free at src/lib/adapters/http/container-curl-probe.ts:33: Keep the controlled term for the Docker probe restriction.

E2E guidance

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

Recommended E2E: inference-routing, network-policy, onboard-repair, onboard-resume, cloud-onboard

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Pin the Docker probe image by digest

• Location: src/lib/adapters/http/container-curl-probe.ts:12
• Category: security
• Problem: The Docker-context probe executes curlimages/curl:8.10.1 by mutable tag.
• Impact: If the tag is retargeted, onboarding can execute an image that was not reviewed with this change.
• Recommendation: Replace the mutable tag with the verified curlimages/curl digest and keep the image reference in the probe tests.
• Verification: Inspect CONTAINER_REACHABILITY_IMAGE and the docker run argv in container-curl-probe.ts to confirm that the reference includes an immutable sha256 digest.
• Test coverage: Assert that the Docker probe argv contains the approved digest-pinned image reference.
• Evidence: src/lib/adapters/http/container-curl-probe.ts:12 defines CONTAINER_REACHABILITY_IMAGE as curlimages/curl:8.10.1. The wrapper passes CONTAINER_REACHABILITY_IMAGE directly to docker run at src/lib/adapters/http/container-curl-probe.ts:58-64.

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/inference/onboard-probes.ts (1)

811-850: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Thread spawnSyncImpl through the responsesProbe branches too.

Every other curl-executing site in this function (calibration, tool-calling probe, standard chat-completions probe, both doubled-timeout retry branches) now passes spawnSyncImpl: options.spawnSyncImpl. The two responsesProbe branches at Line 817-823 and Line 828-849 do not.

Today this gap is inert: options.probeFromDocker requires options.skipResponsesProbe === true (Line 700-706), and responsesProbe is only included in the probes array when !options.skipResponsesProbe (Line 881-883). So responsesProbe.execute cannot run while Docker-context probing is active.

If a future change relaxes that coupling, responsesProbe would silently fall back to the default host spawnSync instead of the container-mediated one, reintroducing the exact WSL/host.docker.internal unreachability regression this PR fixes, without any test catching it. Thread spawnSyncImpl through both branches now so the invariant is enforced structurally rather than by an implicit skip-flag coupling.

♻️ Proposed fix to thread spawnSyncImpl through the Responses probe branches

     const responsesProbe =
       options.requireResponsesToolCalling === true
         ? {
             name: "Responses API with tool calling",
             api: "openai-responses",
             execute: () =>
               probeResponsesToolCalling(endpointUrl, model, apiKey, {
                 authMode: options.authMode,
                 extraHeaders: options.extraHeaders,
                 pinnedAddresses,
                 trustedPrivateCapability: options.trustedPrivateCapability,
                 validationTiming,
+                spawnSyncImpl: options.spawnSyncImpl,
               }),
           }
         : {
             name: "Responses API",
             api: "openai-responses",
             execute: () =>
               runCurlProbe(
                 [...],
                 {
                   trustedConfigFiles: authConfig.trustedConfigFiles,
                   pinnedAddresses,
                   trustedPrivateCapability: options.trustedPrivateCapability,
+                  spawnSyncImpl: options.spawnSyncImpl,
                 },
               ),
           };

🤖 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/inference/onboard-probes.ts` around lines 811 - 850, Update both
`responsesProbe` branches to pass `spawnSyncImpl: options.spawnSyncImpl` into
their curl-execution paths: the `probeResponsesToolCalling` options in the
required-tool-calling branch and the `runCurlProbe` options in the standard
Responses API branch. Preserve all existing probe arguments and behavior while
ensuring both branches use the configured process-spawn implementation.

🤖 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/inference/onboard-probes.ts`:
- Around line 811-850: Update both `responsesProbe` branches to pass
`spawnSyncImpl: options.spawnSyncImpl` into their curl-execution paths: the
`probeResponsesToolCalling` options in the required-tool-calling branch and the
`runCurlProbe` options in the standard Responses API branch. Preserve all
existing probe arguments and behavior while ensuring both branches use the
configured process-spawn implementation.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 68d39bbb-0c46-4cc3-81fd-d4177ae05282

📥 Commits

Reviewing files that changed from the base of the PR and between 8c542b2 and add8bf0.

📒 Files selected for processing (8)

• src/lib/adapters/http/container-curl-probe.test.ts
• src/lib/adapters/http/container-curl-probe.ts
• src/lib/inference/local.test.ts
• src/lib/inference/local.ts
• src/lib/inference/onboard-host-docker-internal.test.ts
• src/lib/inference/onboard-host-docker-internal.ts
• src/lib/inference/onboard-probes.ts
• src/lib/onboard/inference-selection-validation.ts

[apurvvkumaria]

Approve — reviewed exact head add8bf0. The Docker-context probe is restricted to the canonical credential-free Windows-host Ollama route, uses argv-based execution, rejects curl credential configuration, and mounts only the temporary response directory. Focused coverage exercises strict and compatibility paths plus credential, route, and mount rejection, and the exact-head CI and selected E2E gate pass. I found no blocking correctness, security, compatibility, or regression defect. The existing automated mutable-image warning remains non-blocking and is not duplicated here.