Skip to content

fix(onboard): relaunch Windows Ollama after install#3330

Merged
ericksoa merged 3 commits into
NVIDIA:mainfrom
yimoj:fix/3262-wsl-ollama-install-start
May 11, 2026
Merged

fix(onboard): relaunch Windows Ollama after install#3330
ericksoa merged 3 commits into
NVIDIA:mainfrom
yimoj:fix/3262-wsl-ollama-install-start

Conversation

@yimoj

@yimoj yimoj commented May 11, 2026

Copy link
Copy Markdown
Contributor

Summary

Make the WSL Windows-host Ollama install path explicitly relaunch Ollama when the installer does not leave a reachable daemon. This prevents onboarding from returning to the provider menu after a successful Windows-host install whose auto-start side effect failed.

Related Issue

Fixes #3262

Changes

  • Pass the verified Windows ollama.exe path into the robust Windows-host restart helper after install readiness fails.
  • Persist OLLAMA_HOST=0.0.0.0:11434, stop stale Windows Ollama watcher/daemon processes in the existing safe order, and launch either the watcher path or verified install path.
  • Add Windows-side timeout diagnostics for Get-Process, Get-NetTCPConnection, and host.docker.internal curl probes.
  • Add focused onboarding coverage for the install branch fallback when initial readiness fails.

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)

Verification

  • npx prek run --all-files passes
  • npm test passes
  • Tests added or updated for new or changed behavior
  • No secrets, API keys, or credentials committed
  • Docs updated for user-facing behavior changes
  • make 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)

Additional verification performed:

  • npm run build:cli passes.
  • npx vitest run test/onboard-selection.test.ts -t "restarts Windows-host Ollama" passes.
  • npx vitest run test/onboard-selection.test.ts passes.
  • npm run typecheck:cli passes.
  • npm run lint passes.
  • npm test was run but does not pass in this worktree due unrelated failures in test/install-preflight.test.ts and test/fetch-guard-patch-regression.test.ts; the fetch-guard failure was reproduced independently as a non-root permission error removing /usr/local/lib/node_modules/openclaw.
  • npx prek run --all-files was run after installing local hadolint; it fails only in the CLI coverage hook on the same unrelated test/fetch-guard-patch-regression.test.ts failure.

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

Summary by CodeRabbit

  • New Features

    • Added Windows startup timeout diagnostics to help probe and diagnose Ollama launch issues.
  • Bug Fixes

    • Improved retry/restart logic for Windows Ollama startup, including using a discovered installed executable, killing stale processes and retrying readiness probes.
    • Clears cached host info when falling back to provider selection to force fresh probing.
  • Tests

    • Added tests covering Windows installation/restart and helper behavior.

Review Change Stack

Signed-off-by: Yimo Jiang <yimoj@nvidia.com>
@yimoj yimoj self-assigned this May 11, 2026
@coderabbitai

coderabbitai Bot commented May 11, 2026

Copy link
Copy Markdown
Contributor

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: 82c9b330-5524-4dd2-a68a-1fdbb9181b37

📥 Commits

Reviewing files that changed from the base of the PR and between 1e31ac4 and 8cfc92b.

📒 Files selected for processing (2)
  • src/lib/inference/ollama/windows.test.ts
  • src/lib/inference/ollama/windows.ts
🚧 Files skipped from review as they are similar to previous changes (1)
  • src/lib/inference/ollama/windows.ts

📝 Walkthrough

Walkthrough

This PR adds a PowerShell-safe quoting helper, refactors Windows Ollama relaunch to accept an installed binary path, retries launch using the installer-discovered path on readiness failure, centralizes timeout diagnostics, and updates onboarding to clear cached host state on fallback.

Changes

Windows Ollama Installation & Startup Retry

Layer / File(s) Summary
PowerShell Quoting Utility
src/lib/inference/ollama/windows.ts
Added psSingleQuote(value) helper to safely escape single quotes for embedding file paths into PowerShell Start-Process commands.
Ollama Launch Function Refactor
src/lib/inference/ollama/windows.ts
launchAndAwaitWindowsOllama now accepts options object and conditionally launches via watcher path, explicit installedPath with -ArgumentList 'serve', or default ollama.exe serve, killing stale processes and probing readiness between attempts.
Setup Function Option Threading
src/lib/inference/ollama/windows.ts
setupWindowsOllamaWith0000Binding extended to accept installedPath option and pass it to the relaunch logic for post-install retry flows.
Diagnostics Helper & Export
src/lib/inference/ollama/windows.ts
Added printWindowsOllamaTimeoutDiagnostics() function emitting PowerShell process and TCP listening checks plus a curl probe for host.docker.internal:<port>; exported for reuse in onboarding.
Onboard Retry & Diagnostics Integration
src/lib/onboard.ts
Imported diagnostics helper; on install readiness failure, retry setupWindowsOllamaWith0000Binding with discovered installer path; print diagnostics on retry failure and either exit (non-interactive) or continue provider selection (interactive); clear Ollama host cache before returning to provider selection.
Test Coverage for Restart Behavior
test/onboard-selection.test.ts, src/lib/inference/ollama/windows.test.ts
Added non-interactive test verifying install → readiness failure → retry with installed path flow and unit tests for Windows helper behavior, mocking runner and spawnSync to assert PowerShell argument composition and process stop commands.

Sequence Diagram(s)

sequenceDiagram
  participant OnboardCLI
  participant WindowsInstaller
  participant PowerShell
  participant HostProbe as host.docker.internal:11434

  OnboardCLI->>WindowsInstaller: install Ollama (returns installedPath)
  WindowsInstaller-->>OnboardCLI: installedPath
  OnboardCLI->>PowerShell: Start-Process (OLLAMA_HOST=0.0.0.0:11434)
  PowerShell->>HostProbe: awaitWindowsOllamaReady probe (curl)
  alt probe fails
    OnboardCLI->>PowerShell: Start-Process with installedPath (-ArgumentList 'serve')
    PowerShell->>HostProbe: awaitWindowsOllamaReady probe (retry)
    alt retry fails
      OnboardCLI->>OnboardCLI: printWindowsOllamaTimeoutDiagnostics()
      OnboardCLI->>OnboardCLI: resetOllamaHostCache() and fallback/exit
    end
  end
Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

A rabbit hops with glee,
Paths safe for PowerShell cheer,
Installer restarts Ollama near,
Diagnostics whisper clear—
Host binds, logs smile, all deer! 🐰✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 22.22% 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 'fix(onboard): relaunch Windows Ollama after install' directly and clearly describes the main change—relaunching Windows Ollama after installation to address the onboarding timeout issue.
Linked Issues check ✅ Passed The PR implements all coding requirements from #3262: relaunching Ollama with OLLAMA_HOST binding, handling stale processes, adding diagnostics, and updating the onboarding flow with retry logic and cache clearing.
Out of Scope Changes check ✅ Passed All changes are directly aligned with the linked issue objective—Windows Ollama startup reliability improvements, onboarding retry logic, and diagnostic helpers are all within scope.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

  • Generate code and open pull requests
  • Plan features and break down work
  • Investigate incidents and troubleshoot customer tickets together
  • Automate recurring tasks and respond to alerts with triggers
  • Summarize progress and report instantly

Built for teams:

  • Shared memory across your entire org—no repeating context
  • Per-thread sandboxes to safely plan and execute work
  • Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started


Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
src/lib/inference/ollama/windows.ts (1)

203-207: ⚡ Quick win

Harden printed diagnostics to avoid hanging during triage.

The timeout diagnostics should print a bounded curl command so troubleshooting output remains fast and deterministic.

Suggested diff
-  console.error('    powershell.exe -Command "Get-Process ollama*"');
+  console.error('    powershell.exe -Command "Get-Process ollama* -ErrorAction SilentlyContinue"');
   console.error(
-    '    powershell.exe -Command "Get-NetTCPConnection -LocalPort 11434 -State Listen"',
+    '    powershell.exe -Command "Get-NetTCPConnection -LocalPort 11434 -State Listen -ErrorAction SilentlyContinue"',
   );
-  console.error(`    curl http://host.docker.internal:${OLLAMA_PORT}/api/tags`);
+  console.error(
+    `    curl -sS --connect-timeout 2 --max-time 5 http://host.docker.internal:${OLLAMA_PORT}/api/tags`,
+  );
🤖 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/ollama/windows.ts` around lines 203 - 207, The printed curl
diagnostic currently can hang; update the console.error that prints the curl
command (the one using OLLAMA_PORT) to include bounded timeout flags (e.g.
--max-time and --connect-timeout, and optionally --fail and -sS) so the
troubleshooting curl is fast and deterministic; locate the console.error that
outputs `curl http://host.docker.internal:${OLLAMA_PORT}/api/tags` in
src/lib/inference/ollama/windows.ts and replace the unbounded example with a
bounded curl invocation.
🤖 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/ollama/windows.ts`:
- Around line 203-207: The printed curl diagnostic currently can hang; update
the console.error that prints the curl command (the one using OLLAMA_PORT) to
include bounded timeout flags (e.g. --max-time and --connect-timeout, and
optionally --fail and -sS) so the troubleshooting curl is fast and
deterministic; locate the console.error that outputs `curl
http://host.docker.internal:${OLLAMA_PORT}/api/tags` in
src/lib/inference/ollama/windows.ts and replace the unbounded example with a
bounded curl invocation.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 27daadcc-282b-4622-a932-af9621317bcd

📥 Commits

Reviewing files that changed from the base of the PR and between 118541a and f7911b0.

📒 Files selected for processing (3)
  • src/lib/inference/ollama/windows.ts
  • src/lib/onboard.ts
  • test/onboard-selection.test.ts

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
src/lib/inference/ollama/windows.ts (1)

149-172: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Watcher launch failure should fall back to installedPath before failing

When both paths exist, Line 149 gives watcher priority; if that launch fails (Lines 166-172), the function returns false immediately and never attempts the verified installedPath. This can still bounce onboarding back to provider selection on stale watcher-path systems.

Suggested fix
 function launchAndAwaitWindowsOllama(
   opts: { watcherPath?: string; installedPath?: string } = {},
 ): boolean {
   console.log("  Starting Ollama on Windows host via WSL interop...");
   const watcherPath = typeof opts.watcherPath === "string" ? opts.watcherPath.trim() : "";
   const installedPath = typeof opts.installedPath === "string" ? opts.installedPath.trim() : "";
-  let launchScript: string;
-  if (watcherPath) {
-    launchScript =
-      `$env:OLLAMA_HOST='0.0.0.0:11434'; Start-Process -FilePath ${psSingleQuote(watcherPath)} ` +
-      "-WindowStyle Hidden";
-  } else if (installedPath) {
-    launchScript =
-      `$env:OLLAMA_HOST='0.0.0.0:11434'; Start-Process -FilePath ${psSingleQuote(installedPath)} ` +
-      "-ArgumentList 'serve' -WindowStyle Hidden";
-  } else {
-    launchScript =
-      "$env:PATH = [Environment]::GetEnvironmentVariable('PATH','Machine') + ';' + [Environment]::GetEnvironmentVariable('PATH','User'); " +
-      "$env:OLLAMA_HOST='0.0.0.0:11434'; Start-Process -FilePath ollama.exe -ArgumentList serve -WindowStyle Hidden";
-  }
-  const result = run(["powershell.exe", "-Command", launchScript], {
-    ignoreError: true,
-    suppressOutput: true,
-  });
-  if (result.status !== 0) {
-    const stderr = String(result.stderr || "").trim();
-    console.error(
-      `  PowerShell launch failed (exit ${result.status})${stderr ? `: ${stderr}` : ""}`,
-    );
-    return false;
-  }
-  return awaitWindowsOllamaReady();
+  const launchScripts: string[] = [];
+  if (watcherPath) {
+    launchScripts.push(
+      `$env:OLLAMA_HOST='0.0.0.0:11434'; Start-Process -FilePath ${psSingleQuote(watcherPath)} -WindowStyle Hidden`,
+    );
+  }
+  if (installedPath) {
+    launchScripts.push(
+      `$env:OLLAMA_HOST='0.0.0.0:11434'; Start-Process -FilePath ${psSingleQuote(installedPath)} -ArgumentList 'serve' -WindowStyle Hidden`,
+    );
+  }
+  if (launchScripts.length === 0) {
+    launchScripts.push(
+      "$env:PATH = [Environment]::GetEnvironmentVariable('PATH','Machine') + ';' + [Environment]::GetEnvironmentVariable('PATH','User'); " +
+        "$env:OLLAMA_HOST='0.0.0.0:11434'; Start-Process -FilePath ollama.exe -ArgumentList serve -WindowStyle Hidden",
+    );
+  }
+
+  for (const launchScript of launchScripts) {
+    const result = run(["powershell.exe", "-Command", launchScript], {
+      ignoreError: true,
+      suppressOutput: true,
+    });
+    if (result.status === 0 && awaitWindowsOllamaReady()) {
+      return true;
+    }
+  }
+  return false;
 }
🤖 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/ollama/windows.ts` around lines 149 - 172, The current
logic gives watcherPath priority and returns false on its launch failure,
skipping a possible fallback to installedPath; change the sequence in the block
that builds launchScript and calls run so that if watcherPath is present you
attempt launching it first (using the existing watcherPath launchScript and run
call) but if that run returns a non-zero status and installedPath is available,
rebuild launchScript for installedPath and call run again; only return false if
both attempts fail (preserve the same error logging using result.stderr), and
keep the original behavior when only installedPath or neither path exists.
🤖 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.

Outside diff comments:
In `@src/lib/inference/ollama/windows.ts`:
- Around line 149-172: The current logic gives watcherPath priority and returns
false on its launch failure, skipping a possible fallback to installedPath;
change the sequence in the block that builds launchScript and calls run so that
if watcherPath is present you attempt launching it first (using the existing
watcherPath launchScript and run call) but if that run returns a non-zero status
and installedPath is available, rebuild launchScript for installedPath and call
run again; only return false if both attempts fail (preserve the same error
logging using result.stderr), and keep the original behavior when only
installedPath or neither path exists.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 8ecb5b2f-5aa2-4b5b-9584-ca8f148efdbf

📥 Commits

Reviewing files that changed from the base of the PR and between f7911b0 and 1e31ac4.

📒 Files selected for processing (1)
  • src/lib/inference/ollama/windows.ts

Signed-off-by: Yimo Jiang <yimoj@nvidia.com>
@yimoj yimoj added the v0.0.39 label May 11, 2026

@ericksoa ericksoa left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the Windows-host Ollama install fallback path and the focused regression coverage. The change is scoped to WSL/Windows Ollama onboarding, preserves the existing watcher-first restart behavior, falls back to the verified installed ollama.exe path when auto-start is not reachable, and the no-commit merge with current main passed local validation.

@ericksoa ericksoa merged commit f98ad00 into NVIDIA:main May 11, 2026
21 checks passed
@miyoungc miyoungc mentioned this pull request May 12, 2026
12 tasks
miyoungc added a commit that referenced this pull request May 12, 2026
## Summary
Refreshes the release-prep docs for v0.0.39 based on changes merged
since the Friday 4pm doc refresh. Updates the source docs, bumps the
docs version metadata, and regenerates the NemoClaw user skills from the
refreshed docs.

## Changes
- #3314 -> `docs/get-started/prerequisites.md`,
`docs/get-started/quickstart.md`, `docs/reference/troubleshooting.md`:
Documents installer Docker setup, Docker group activation, and retry
guidance.
- #3317 -> `docs/get-started/quickstart.md`,
`docs/reference/commands.md`: Documents the DGX Spark and DGX Station
express install prompt and `NEMOCLAW_NO_EXPRESS`.
- #3328 and #3329 -> `docs/security/best-practices.md`,
`docs/deployment/sandbox-hardening.md`: Updates sandbox capability
hardening docs for the stricter bounding-set and `setpriv` step-down
behavior.
- #3330, #3335, and #3346 -> `docs/inference/use-local-inference.md`:
Documents Windows-host Ollama relaunch behavior, NIM key passthrough,
early health-fail diagnostics, and mixed-GPU preflight detail.
- #2406, #2883, #3001, #3244, #3267, #3318, #3320, and #3354 ->
`docs/about/release-notes.md`: Adds the v0.0.39 release-prep section
while keeping the v0.0.38 release notes intact.
- Advances the release-prep docs metadata from v0.0.38 to v0.0.39.
- Regenerates `.agents/skills/nemoclaw-user-*` from the updated source
docs.

## Type of Change
- [ ] Code change (feature, bug fix, or refactor)
- [ ] Code change with doc updates
- [ ] Doc only (prose changes, no code sample modifications)
- [x] Doc only (includes code sample changes)

## Verification
- [x] `npx prek run --all-files` passes
- [ ] `npm test` passes
- [ ] Tests added or updated for new or changed behavior
- [x] No secrets, API keys, or credentials committed
- [x] Docs updated for user-facing behavior changes
- [x] `make docs` builds without warnings (doc changes only)
- [x] Doc pages follow the [style
guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md)
(doc changes only)
- [ ] New doc pages include SPDX header and frontmatter (new pages only)

---
Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

## Release Notes v0.0.39

* **New Features**
  * Host alias management commands for easier configuration
  * Sandbox GPU control options during onboarding
  * Update command with check and confirmation modes

* **Documentation**
* Enhanced Linux installer guidance with Docker and group membership
handling
  * Expanded troubleshooting for permission and connectivity issues
  * Improved capability-dropping security documentation
  * Updated inference model switching commands
  * Brev environment-specific troubleshooting

* **Improvements**
  * DGX Spark/Station express install flow
  * Windows Ollama relay and health-check enhancements
  * NVIDIA NIM preflight GPU reporting

[![Review Change
Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/NVIDIA/NemoClaw/pull/3375)

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
@wscurran wscurran added the bug-fix PR fixes a bug or regression label Jun 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug-fix PR fixes a bug or regression

Projects

None yet

3 participants