[cv]

Summary

DGX Station express onboarding currently rejects an already-running compatible Ultra model when its custom vLLM served name differs from NemoClaw's canonical route ID.
This change verifies the server-reported model root against the managed-model registry, adopts the compatible served alias, and keeps mismatched models and shared-gateway conflicts fail-closed.

Related Issue

Fixes #7023

Changes

• Match an existing vLLM served alias to the requested model only when /v1/models reports a safe root that exactly identifies the registered checkpoint.
• Keep newly managed vLLM installs on their exact served identity and rerun shared-gateway route containment after adopting an existing-server alias.
• Add unit coverage for compatible, incompatible, and shared-route cases plus a non-interactive DGX Station express regression test for the reported Ultra alias.
• Update the vLLM setup guide to describe existing-server selection and the model-identity checks.

The focused matcher is required because vLLM's --served-model-name is intentionally independent from the underlying checkpoint ID, so direct string equality cannot distinguish a compatible alias from a different model.
The unit and Station provider-selection tests protect that boundary.

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: Nine-category security review completed against exact commit d1bbd909645efd15088949a8b7a6f77f3bd3b19f with no findings. The reported root remains allowlisted and must exactly match the registered checkpoint; exact managed identity and post-discovery shared-route containment remain enforced.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

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 — npx vitest run --project cli --project integration src/lib/onboard/setup-nim-vllm.test.ts test/onboard-selection-vllm.test.ts passed 28 tests; npm run test:changed passed 857 tests.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — not run because this is a focused onboarding selection change with direct unit and integration 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) — passed with 0 errors; Fern reported two pre-existing unprinted warnings.
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only) — not applicable; no new page was added.

---

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

Summary by CodeRabbit

• New Features
  • Reuse already-running vLLM servers instead of starting duplicates, including when port 8000 is already in use.
  • If a vLLM “served” alias can be verified as compatible, NemoClaw can adopt it for the selected model.
• Bug Fixes
  • Tightened model-identity and route-compatibility validation to prevent mismatched or unverifiable server/alias selections, with clearer early error guidance.
• Documentation
  • Updated vLLM “existing server” onboarding guidance.
• Tests
  • Expanded coverage for served-alias adoption, missing root metadata, compatibility conflicts, and resume behavior.

[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

NemoClaw now reuses compatible running vLLM servers by validating served-model aliases against reported roots. It adopts valid aliases, rejects mismatched or missing metadata before route validation, and updates Station express, resume-path tests, and documentation.

Changes

vLLM alias selection

Layer / File(s)	Summary
Model alias matching src/lib/onboard/setup-nim-vllm.ts	Adds registry-based served-alias/root matching and permits compatible managed-install selections.
Alias validation coverage src/lib/onboard/setup-nim-vllm.test.ts	Tests compatible adoption, mismatched or missing roots, and route compatibility checks before validation.
Existing-server onboarding regression test/onboard-selection-vllm.test.ts, docs/inference/set-up-vllm.mdx	Verifies Station express selects an existing nemotron-ultra server and documents the updated existing-server behavior.
Persisted alias resume coverage src/lib/onboard/machine/handlers/provider-inference.test.ts	Verifies inference repair reuses persisted vLLM provider, model, endpoint, and API selection without rerunning provider setup.

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

Sequence Diagram(s)

sequenceDiagram
  participant ExpressOnboarding
  participant RunningVLLM
  participant ModelRegistry
  ExpressOnboarding->>RunningVLLM: probe /v1/models
  RunningVLLM-->>ExpressOnboarding: served id and root
  ExpressOnboarding->>ModelRegistry: resolve requested model and root
  ModelRegistry-->>ExpressOnboarding: compatible alias result
  ExpressOnboarding->>ExpressOnboarding: select running vLLM and validate route

Loading

Possibly related PRs

• NVIDIA/NemoClaw#3417: Updates running-vLLM discovery and provider-selection UX.
• NVIDIA/NemoClaw#6883: Adds Station Ultra served-model identities used by alias/root matching.

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

Suggested reviewers: ericksoa, jyaunches, apurvvkumaria

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and clearly describes adopting compatible vLLM served aliases during onboarding.
Linked Issues check	✅ Passed	The changes implement alias adoption for compatible existing vLLM servers and keep rejecting incompatible or conflicting cases, matching #7023.
Out of Scope Changes check	✅ Passed	The docs and tests stay focused on the vLLM onboarding and alias behavior and do not introduce unrelated changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-7023-vllm-served-model

---

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

[github-actions]

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage remains at 96%, unchanged from the main branch.

TypeScript / code-coverage/cli

The overall coverage in the codex/fix-7023-vllm-... branch remains at 80%, unchanged from the main branch.

Show a code coverage summary of the most impacted files.

File	main a9fac78	codex/fix-7023-vllm-... 00f7dc6	+/-
src/lib/domain/.../connect-env.ts	97%	89%	-8%
src/lib/state/registry.ts	86%	83%	-3%
src/lib/onboard...tup-nim-vllm.ts	88%	88%	0%
src/lib/credentials/store.ts	59%	64%	+5%
src/lib/inferen...er-lifecycle.ts	65%	71%	+6%
src/lib/core/pr...mpt-activity.ts	67%	92%	+25%
src/lib/inferen...lama/process.ts	50%	100%	+50%

---

_{Updated July 17, 2026 03:12 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high 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 · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · medium confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized E2E selections differ; severity counts match.

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

• inference-routing

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 `@src/lib/onboard/setup-nim-vllm.ts`:
- Around line 213-218: Remove the options.managedInstall bypass from the model
compatibility condition in setup-nim-vllm.ts; require detectedModel to match
requiredModel exactly or pass reportedModelMatchesRequest(...). In
src/lib/onboard/setup-nim-vllm.test.ts lines 113-145, run the mismatched-root
fixture with managedInstall: true and preserve the rejection and no-validation
assertions.

🪄 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: aad9853e-7cad-4abb-ae4f-83bf11038bbd

📥 Commits

Reviewing files that changed from the base of the PR and between 24c7334 and d1bbd90.

📒 Files selected for processing (4)

• docs/inference/set-up-vllm.mdx
• src/lib/onboard/setup-nim-vllm.test.ts
• src/lib/onboard/setup-nim-vllm.ts
• test/onboard-selection-vllm.test.ts

[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 `@src/lib/onboard/machine/handlers/provider-inference.test.ts`:
- Around line 504-506: Update the test around createSession and its
setupInference, completion-state, and result assertions to use a distinct
non-canonical served alias instead of “nemotron-ultra” consistently. Keep the
alias compatible with the provider, and ensure the test persists and verifies
that exact alias through resume without substituting the canonical route ID.

🪄 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: 9a3dac95-1a4a-4faa-9853-7d544ac584a2

📥 Commits

Reviewing files that changed from the base of the PR and between 7e0ca37 and 0b06ef1.

📒 Files selected for processing (1)

• src/lib/onboard/machine/handlers/provider-inference.test.ts

[cjagwani]

lgtm

[apurvvkumaria]

Addressed the refreshed Advisor test-depth warning at exact head 00f7dc69303dd6f664d6e0b5551a2d25dffd0f73: the new focused case uses managedInstall: true with a root-compatible differing served alias and proves the handler exits before changing the requested model or calling validation. The targeted file passes 23/23 tests, changed-file hooks pass, and the commit is Verified with Carlos credited as co-author. Fresh exact CI and E2E are running; no retry or merge was performed.