Skip to content

fix(onboard): auto-select managed vLLM non-interactively on DGX Spark (#7293)#7296

Merged
senthilr-nv merged 11 commits into
mainfrom
fix/7293-spark-noninteractive-vllm-default
Jul 23, 2026
Merged

fix(onboard): auto-select managed vLLM non-interactively on DGX Spark (#7293)#7296
senthilr-nv merged 11 commits into
mainfrom
fix/7293-spark-noninteractive-vllm-default

Conversation

@yanyunl1991

@yanyunl1991 yanyunl1991 commented Jul 21, 2026

Copy link
Copy Markdown
Contributor

Summary

Non-interactive onboarding on DGX Spark now chooses a running local vLLM instance, then the managed vLLM install path, before falling back to NVIDIA Endpoints when no provider was requested or previously recorded. DGX Station and other hosts retain their existing unset-provider behavior.

Related Issue

Closes #7293

Product Scope Verdict

In scope as a correction to the existing supported DGX Spark managed-vLLM onboarding behavior documented by the issue and current product documentation. This does not add a new integration, solution recipe, custom image, or third-party stack. This evidence-based scope verdict is separate from GitHub merge state and is not a claim of human approval.

Changes

  • Pass a Spark-only managed-vLLM preference from the onboarding flow to provider selection.
  • Prefer a running vLLM instance, then managed installation, while preserving the existing NVIDIA Endpoints fallback.
  • Keep the provider resolver platform-agnostic by making the caller's preference explicit.
  • Add tests for the Spark running/install paths and the Station, unsupported-platform, and missing-registry boundaries.
  • Document the Spark non-interactive default and fallback order in the quickstart and vLLM setup guides.

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: Automated Codex nine-category security review found no findings; independent human sensitive-path review remains required.
  • 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/get-started/quickstart.mdx; docs/inference/set-up-vllm.mdx. The writer found the Spark-only behavior, fallback order, and unchanged Station/other-host behavior accurate and found no writing or documentation issue.
  • Agent: Codex Desktop

DGX Station Hardware Evidence

  • Tested on DGX Station
  • Tested commit: Not applicable; scripts/prepare-dgx-station-host.sh is not in the PR diff.
  • Station profile/scenario: Not applicable.
  • Result: Not applicable.
  • Supporting evidence: Not applicable.

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
    • Exact canonical-base fallback passed: npx prek run --from-ref upstream/main --to-ref HEAD --stage pre-commit, npx commitlint --from upstream/main --to HEAD, and npx prek run --from-ref upstream/main --to-ref HEAD --stage pre-push. The fallback used upstream/main explicitly because the local origin/main was not the canonical base.
  • Targeted behavior tests pass for the current change set, or tests are marked not applicable above — npx vitest run --project cli src/lib/onboard/provider-selection.test.ts src/lib/onboard/setup-nim-flow.test.ts src/lib/onboard/vllm-menu.test.ts passed 47 tests; npx vitest run test/changelog-docs.test.ts passed 6 tests.
  • Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — not applicable to this narrow onboarding and documentation 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) — passed with 0 errors and 2 non-fatal Fern warnings; no warning waiver is claimed.
  • Doc pages follow the style guide (doc changes only)
  • New doc pages include SPDX header and frontmatter (new pages only) — no new doc pages.

Contributor-provided DGX Spark evidence: #7296 (comment)


Signed-off-by: Yanyun Liao yanyunl@nvidia.com

…/Station (#7293)

On a DGX Spark, `nemoclaw onboard --non-interactive` with no NEMOCLAW_PROVIDER
(and no cloud key) fell back to cloud NVIDIA Endpoints (`build` → nvidia-prod)
instead of the managed local vLLM (`install-vllm`) that the interactive menu
already offers for the platform. The GB10 GPU is detected and the
`Install vLLM (DGX Spark)` entry is present in the non-interactive options, but
the default-selection logic in resolveRequestedProviderSelection unconditionally
chose `build` and never looked at it.

Fix: when a non-interactive onboard has no requested/recorded provider and the
host is a DGX managed-vLLM-default platform (Spark/Station) whose `install-vllm`
entry is present, default to `install-vllm` instead of `build`. The Spark/Station
predicate is exported from vllm-menu as `isManagedVllmDefaultPlatform` and reused
by both the interactive menu and this non-interactive default so they stay in
lock-step. Generic-Linux/experimental hosts and non-DGX platforms keep the cloud
`build` default (the entry is either absent or the platform is not a default
platform), so no non-Spark regression.

Verified live on a DGX Spark (GB10, aarch64): `[3/8]` now prints
`[non-interactive] Provider: install-vllm` and selects the Qwen3.6-35B-A3B NVFP4
checkpoint instead of falling back to NVIDIA Endpoints.

Signed-off-by: Yanyun Liao <yanyunl@nvidia.com>
@coderabbitai

coderabbitai Bot commented Jul 21, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

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 onboarding flow detects managed-vLLM default platforms, passes that preference to provider resolution, and selects an available local vLLM option before falling back to build. Tests cover platform detection, fallback behavior, and non-interactive DGX Spark setup.

Changes

Managed vLLM provider selection

Layer / File(s) Summary
Platform detection and vLLM menu
src/lib/onboard/vllm-menu.ts, src/lib/onboard/vllm-menu.test.ts
Adds isManagedVllmDefaultPlatform for Spark and Station and reuses it for menu labeling and install-vllm eligibility.
Provider default resolution
src/lib/onboard/provider-selection.ts, src/lib/onboard/provider-selection.test.ts
Adds preferManagedVllmDefault and selects vllm first, then install-vllm, when preferred and available; otherwise retains build.
Onboarding preference wiring
src/lib/onboard/setup-nim-flow.ts, src/lib/onboard/setup-nim-flow.test.ts
Derives the preference from the detected GPU platform and verifies non-interactive managed vLLM selection.

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

Sequence Diagram(s)

sequenceDiagram
  participant SetupNimFlow
  participant isManagedVllmDefaultPlatform
  participant ProviderResolver
  SetupNimFlow->>isManagedVllmDefaultPlatform: Check gpu?.platform
  isManagedVllmDefaultPlatform-->>SetupNimFlow: Return managed-vLLM preference
  SetupNimFlow->>ProviderResolver: Resolve provider with preference
  ProviderResolver-->>SetupNimFlow: Select vllm, install-vllm, or build
Loading

Possibly related issues

Suggested labels: bug-fix, area: onboarding, area: providers, provider: vllm, platform: dgx-station

Suggested reviewers: cv, senthilr-nv, apurvvkumaria

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 20.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 Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately summarizes the main change: non-interactive managed vLLM auto-selection on DGX Spark.
✨ 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/7293-spark-noninteractive-vllm-default

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

@github-code-quality

github-code-quality Bot commented Jul 21, 2026

Copy link
Copy Markdown
Contributor

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit a43dcd7 in the fix/7293-spark-nonin... branch remains at 96%, unchanged from commit fe56943 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit a43dcd7 in the fix/7293-spark-nonin... branch remains at 80%, unchanged from commit fe56943 in the main branch.

Show a code coverage summary of the most impacted files.
File main fe56943 fix/7293-spark-nonin... a43dcd7 +/-
src/lib/onboard...ndbox-create.ts 83% 33% -50%
src/lib/onboard...-create-plan.ts 88% 75% -13%
src/lib/onboard...-desktop-gpu.ts 89% 77% -12%
src/lib/onboard...ndbox-create.ts 91% 83% -8%
src/lib/agent/r...ime-manifest.ts 100% 100% 0%
src/lib/onboard...er-selection.ts 100% 100% 0%
src/lib/onboard/vllm-menu.ts 100% 100% 0%
src/lib/shields/index.ts 71% 72% +1%
src/lib/state/m...-acquisition.ts 84% 89% +5%
src/lib/domain/.../connect-env.ts 89% 97% +8%

Updated July 23, 2026 18:30 UTC

…7293)

The new #7293 cases used `if (result.kind === "selected")` narrowing, which
tripped the changed-test-file conditionals guardrail (no added if statements).
Replace with a ternary `selectedKey()` accessor so the if-count stays at base.

Signed-off-by: Yanyun Liao <yanyunl@nvidia.com>
@github-actions

github-actions Bot commented Jul 21, 2026

Copy link
Copy Markdown
Contributor

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 · 4 warnings · 0 suggestions
  • Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 4 more warnings, the same number of 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: onboard-repair, onboard-resume, cloud-onboard

1 optional E2E recommendation
  • spark-install

Workflow run details

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

…hrough the flow (#7293)

Address PR Review Advisor PRA-1: the resolver/predicate unit tests exercise the
default in isolation, and the existing managed-vLLM flow cases return an explicit
getNonInteractiveProvider()=install-vllm, so nothing verified the call-site
wiring (preferManagedVllmDefault from gpu?.platform) that makes a DGX Spark
non-interactive run with NO requested provider enter the managed-install branch.

Add a createSetupNim regression: isNonInteractive true, getNonInteractiveProvider
returns null, gpu.platform=spark, install-vllm menu entry present -> asserts
installVllm + handleVllmSelection run and the cloud handler is never reached
(handleRemoteProviderSelection stays 'unexpected', so a build fallback throws).

Signed-off-by: Yanyun Liao <yanyunl@nvidia.com>
… Spark default (#7293)

Address PR Review Advisor PRA-1 (blocker): the managed-vLLM default only looked
for the `install-vllm` entry. When vLLM is already running the menu can instead
expose only `vllm`, so the branch would fall through to cloud `build`.

Select the available local vLLM option in priority order — running `vllm` first,
otherwise `install-vllm` — before the cloud fallback, via
resolveManagedVllmDefaultKey(). Adds a resolver case for the sole-`vllm` running
entry on a managed-vLLM platform.

Signed-off-by: Yanyun Liao <yanyunl@nvidia.com>
@yanyunl1991

Copy link
Copy Markdown
Contributor Author

Re: PRA-1 (running-vLLM) — addressed in 0b5e0fa02. The managed-vLLM default now selects in priority order running vllminstall-vllm → cloud build (resolveManagedVllmDefaultKey), so a sole vllm menu entry is honored instead of falling through to build.

A note on the observed flow: in the non-interactive, no-NEMOCLAW_PROVIDER path the vLLM probe is off (probeVllm: false), so vllmRunning is false in the host state and buildVllmMenuEntries emits install-vllm even when a server is already up — and the install-vllm handler then reuses the running instance. So the vllm-only menu state the blocker describes does not arise in this exact path today; the priority change is a correctness hardening for any path where the probe is on.

Verified live on a DGX Spark (GB10, aarch64), both states:

  • vLLM not running → Provider: install-vllm → installs → route vllm-local / nvidia/Qwen3.6-35B-A3B-NVFP4, onboard completes.
  • vLLM already running → Provider: install-vllmreuses the running server (✓ Updated provider vllm-local, no reinstall) → same route, onboard completes.

In both cases the non-interactive DGX Spark onboard selects managed local vLLM and never falls back to cloud NVIDIA Endpoints.

…7293)

Address PR Review Advisor PRA-1 (warning): the running-vLLM priority had a
resolver unit test, but the only running-vLLM flow case used an explicit
getNonInteractiveProvider()=vllm. Add a createSetupNim regression: non-interactive
Spark, no requested provider, vllmRunning true with only a `vllm` menu entry —
asserts handleVllmSelection runs with managedInstall:false, installVllm is never
called (no reinstall), and the cloud handler is never reached.

Signed-off-by: Yanyun Liao <yanyunl@nvidia.com>
@wscurran wscurran added area: local-models Local model providers, downloads, launch, or connectivity area: onboarding Onboarding FSM, provider setup, sandbox launch, or first-run flow area: providers Inference provider integrations and provider behavior bug-fix PR fixes a bug or regression platform: dgx-spark Affects DGX Spark hardware or workflows platform: dgx-station Affects DGX Station hardware or workflows labels Jul 21, 2026
@senthilr-nv senthilr-nv self-assigned this Jul 21, 2026
Signed-off-by: Charan Jagwani <cjagwani@nvidia.com>
@cjagwani cjagwani changed the title fix(onboard): auto-select managed vLLM non-interactively on DGX Spark/Station (#7293) fix(onboard): auto-select managed vLLM non-interactively on DGX Spark (#7293) Jul 22, 2026
@github-actions

Copy link
Copy Markdown
Contributor

@senthilr-nv senthilr-nv left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Approved after the maintainer merge gate passed for head a43dcd7 against base fe56943. Product scope is an existing supported-behavior correction linked to #7293. Required CI and exact-pair E2E gates passed, contributor verification passed, and no actionable correctness or security finding remains.

@senthilr-nv
senthilr-nv merged commit f95a685 into main Jul 23, 2026
81 checks passed
@senthilr-nv
senthilr-nv deleted the fix/7293-spark-noninteractive-vllm-default branch July 23, 2026 18:52
@cv cv mentioned this pull request Jul 23, 2026
23 tasks
cv added a commit that referenced this pull request Jul 23, 2026
<!-- markdownlint-disable MD041 -->
## Summary

Adds the canonical dated `## v0.0.93` release entry to
`docs/changelog/2026-07-23.mdx`.
The entry records user-visible behavior, release validation, and
documentation controls merged after `v0.0.92`, while preserving the
pending DGX OS `7.6.x` Station Express qualification caveat.

## Changes

- Adds the parser-safe dated release entry with a summary, grouped
details, and published-route links.
- Reconciles the `v0.0.92..origin/main` commit range with merged
`v0.0.93` PRs.
- Records that no-OTA DGX OS `7.6.x` passed bounded host preflight,
while full Station Express end-to-end qualification remains pending.
- Leaves existing product pages unchanged because the source PRs already
document their supported behavior.

### Source summary

- #7285 -> `docs/changelog/2026-07-23.mdx`: Records the existing-vLLM
ownership choice and resumable Station handoff.
- #7419 -> `docs/changelog/2026-07-23.mdx`: Records bounded no-OTA DGX
OS `7.6.x` recognition and its pending end-to-end qualification.
- #7268 -> `docs/changelog/2026-07-23.mdx`: Records optional Hugging
Face authentication, output sanitization, and resumable HTTP `429`
recovery.
- #7442 -> `docs/changelog/2026-07-23.mdx`: Records clean SIGINT
handling at hidden credential prompts.
- #7299 -> `docs/changelog/2026-07-23.mdx`: Records Intel macOS
rejection before ref resolution or network work.
- #7296 -> `docs/changelog/2026-07-23.mdx`: Records the DGX Spark
non-interactive local-vLLM selection order.
- #7342 -> `docs/changelog/2026-07-23.mdx`: Records delegated protected
E2E approvals in the grouped release-validation bullet.
- #7373 -> `docs/changelog/2026-07-23.mdx`: Records base-image
publication gating before final-main fanout.
- #7388 -> `docs/changelog/2026-07-23.mdx`: Records semantic phase
runtime summaries.
- #7397 -> `docs/changelog/2026-07-23.mdx`: Records progress coverage
hardening.
- #7391 -> `docs/changelog/2026-07-23.mdx`: Records centralized
larger-runner routing.
- #7423 -> `docs/changelog/2026-07-23.mdx`: Records one retry for
confirmed hosted-runner loss.
- #7399 -> `docs/changelog/2026-07-23.mdx`: Records runner-comparison
telemetry.
- #7270 -> `docs/changelog/2026-07-23.mdx`: Records staging Brev
Launchable validation.
- #7426 -> `docs/changelog/2026-07-23.mdx`: Records filtering of
irrelevant base-image run history.
- #7333 -> `docs/changelog/2026-07-23.mdx`: Records aligned Quickstart
platform guidance.
- #7343 -> `docs/changelog/2026-07-23.mdx`: Records documentation-writer
receipt collection.
- #7400 -> `docs/changelog/2026-07-23.mdx`: Records the
documentation-writer receipt requirement for docs-only PRs.
- #7413 -> `docs/changelog/2026-07-23.mdx`: Records removal of redundant
receipt PR metadata.
- #7405 -> `docs/changelog/2026-07-23.mdx`: Records corrected inference
CLI references.
- #7389 -> `docs/changelog/2026-07-23.mdx`: Records completion of the
v0.0.91 documentation audit.

`#7384` is an internal refactor with no intended runtime behavior
change.
`#7401` updates internal CodeQL Actions dependencies.
`#7376` is already contained in `v0.0.92`, so it is outside the
release-entry scan range despite its retained planning label.

## Type of Change

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

## Quality Gates

- [ ] Tests added or updated for changed behavior
- [x] Existing tests cover changed behavior — justification:
`test/changelog-docs.test.ts` validates dated changelog structure, SPDX
syntax, and version headings.
- [ ] Tests not applicable — justification:
- [x] 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:
- [ ] Non-success, skipped, or missing CI check accepted by maintainer —
check name, approval link, and follow-up issue:

## Documentation Writer Review

- [x] Documentation writer subagent reviewed the completed changes
- Result: `docs-updated`
- Evidence: Reviewed `docs/changelog/2026-07-23.mdx` against
`WRITING.md`, `docs/CONTRIBUTING.md`, `docs/.docs-skip`,
`docs/index.yml`, the six user-visible source PRs, and the remaining
grouped release commits. The review corrected an ambiguous qualification
claim, confirmed all published routes, preserved the DGX OS `7.6.x`
caveat, and found no remaining action.
- Agent: Codex Desktop
<!-- docs-review-head-sha: ec0a866 -->
<!-- docs-review-agents-blob-sha: 9c9b36d -->

## DGX Station Hardware Evidence

- [ ] Tested on DGX Station
- Tested commit: Not applicable. This PR does not change
`scripts/prepare-dgx-station-host.sh`.
- Station profile/scenario: Not applicable.
- Result: Not applicable.
- Supporting evidence: Not applicable.

## Verification

- [x] PR description includes a `Signed-off-by:` line and every commit
appears as `Verified` in GitHub
- [x] Normal `pre-commit`, `commit-msg`, and `pre-push` hooks passed, or
`npm run check:diff` passed when hooks were skipped or unavailable
- [x] Targeted behavior tests pass for the current change set, or tests
are marked not applicable above — `npx vitest run
test/changelog-docs.test.ts`: 1 file and 6 tests passed.
- [ ] Applicable broad gate passed — Not applicable to one native
changelog file.
- [x] Quality Gates section completed with required justifications or
waivers
- [x] No secrets, API keys, or credentials committed
- [ ] `npm run docs` builds without warnings (doc changes only) —
completed with 0 errors and 2 existing Fern warnings.
- [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)
— not applicable because native changelog entries use a parser-safe MDX
SPDX comment without frontmatter.

---
Signed-off-by: Carlos Villela <cvillela@nvidia.com>


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

## Summary by CodeRabbit

* **Documentation**
* Added the v0.0.93 changelog covering onboarding and validation
improvements.
* Documented support for additional DGX Station Express workstation
releases and clearer handling of existing vLLM workloads.
* Added guidance for optional Hugging Face authentication, resumable
rate-limit recovery, and DGX Spark provider selection.
* Clarified installer behavior on Intel macOS, release validation
requirements, hosted-runner retries, documentation checks, and supported
CLI quickstart paths.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: local-models Local model providers, downloads, launch, or connectivity area: onboarding Onboarding FSM, provider setup, sandbox launch, or first-run flow area: providers Inference provider integrations and provider behavior bug-fix PR fixes a bug or regression platform: dgx-spark Affects DGX Spark hardware or workflows platform: dgx-station Affects DGX Station hardware or workflows

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[DGX Spark][Onboard] nemoclaw onboard --non-interactive does not auto-select managed local vLLM on DGX Spark

4 participants