Skip to content

feat(vllm): auto-prepare trusted dual DGX Stations - #7030

Open
ericksoa wants to merge 105 commits into
mainfrom
feat/dual-dgx-station-inference
Open

feat(vllm): auto-prepare trusted dual DGX Stations#7030
ericksoa wants to merge 105 commits into
mainfrom
feat/dual-dgx-station-inference

Conversation

@ericksoa

@ericksoa ericksoa commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

Summary

Station Express now detects one pretrusted DGX Station GB300 peer across two direct private /30 rails and prepares the qualified pair for distributed Nemotron 3 Ultra inference. Without a qualified pair, Express keeps the existing single-Station Ultra path. The dual-Station path remains Deferred and does not change the single-Station support status. Operators still own rail configuration, network isolation, SSH trust, firewall policy, and reboots.

Changes

  • Derive only the mathematical peer on each of two active private /30, 400 Gb/s, MTU-9000 CX-8 rails. The installer does not scan subnets or enroll SSH trust.
  • Require a pretrusted reciprocal peer and validate its rail addresses, MACs, routes, neighbors, jumbo reachability, Station identity, and distinct GB300 GPU UUID before selecting distributed inference.
  • Keep NEMOCLAW_DGX_STATION_PEER, NEMOCLAW_VLLM_MODEL, and --station-deepseek authoritative and fail closed on conflicting intent.
  • Reuse scripts/prepare-dgx-station-host.sh on both hosts with exact-byte hashing and strict noninteractive SSH execution.
  • Preserve owner-only resume state across operator-managed reboots, bound to the revision, helper digest, SSH host-key identity, GPU UUIDs, and reciprocal rail identity.
  • Run the distributed Ultra path with the pinned vLLM image, Ray 2.56.0, PP=2/TP=1, FP8 KV cache, prefix caching, and served alias nemotron-ultra. Single-Station Ultra continues to serve nvidia/nemotron-3-ultra-550b-a55b.
  • Bind distributed serving to the direct trusted rails, retain bearer authentication and lifecycle ownership, and fail closed on unhealthy or ambiguously owned local-provider state.
  • Harden managed recovery so empty or non-200 health probes fail, API-key creation requires O_NOFOLLOW, and only explicit managed bindings enter managed lifecycle handling.
  • Complete fresh peer preparation by permitting noninteractive --check to use sudo only for read-only Docker inventory, reopening SSH after peer login-required status, and binding both controller UIDs after pair qualification.
  • Normalize every guarded installer and Local vLLM continuation state path when HOME has a trailing slash and accept physical iproute2 route JSON that omits redundant filtered fields while retaining exact direct-route, device, scope, MAC, neighbor-state, and jumbo-frame checks.
  • Add focused installer, peer-selection, model-staging, SSH-binding, authentication, lifecycle, rollback, ownership, and documentation-contract coverage.
  • Update Station preparation, vLLM, command-reference, and pinned prompt documentation for topology selection and its security 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: Aaron accepted the documented trusted two-host boundary for v0.0.91. Exact-head security review and confirmation that the same Deferred /30 scope applies to the current release remain pending before approval.
  • 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: At PR SHA c8998d6f7, the final correction records the already documented qualified dual-Station nemotron-ultra served alias in the sealed Station Express intent. Current docs already define that alias and route behavior. The updated behavior-oriented test titles follow WRITING.md; no user-facing page or changelog change is required. The previously reviewed dual-Station documentation remains unchanged.
  • Agent: Codex Desktop

DGX Station Hardware Evidence

  • Tested on DGX Station
  • Tested commit: 546e67b9ea0277b755095dfc14151cb0d5a73dfb
  • Station profile/scenario: two physical DGX Station GB300 systems running the NVIDIA AI Developer Tools image, connected by two direct 400 Gb/s /30 rails. Exact-head preparation, relogin continuation, reciprocal pair qualification, controller binding, worker preparation, CDI validation, and exact-source/OpenShell installation passed.
  • Evidence: qualification plan and preserved fabric results; earlier partial E2E result
  • Result: Partial. The physical DGX Station pair was exercised at 546e67b9 through exact-head preparation and continuation. That revision incorrectly classified the public Nemotron Ultra repository as gated and stopped before model or vLLM image download. Current candidate 950cb3a59 restores the base branch's public-model contract; live Hugging Face metadata reports private=false, gated=false, and the same pinned revision. Exact-head model staging, two-node Ray/vLLM readiness, authenticated routing, agent smoke, restart/reboot recovery, and rollback remain pending.

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 — justification: current refreshed head passed 187 focused model and dual-Station CLI tests, CLI typecheck, and all diff-scoped pre-commit, commit-msg, and pre-push hooks against current upstream/main. The preceding exact-head feature evidence includes 542 CLI tests, 139 installer-integration tests, 105 integration and documentation-contract tests, exact Vitest membership across 1,876 files, and docs validation with 0 errors and 2 existing Fern warnings.
  • Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — npm test: 1,177 passed and 2 intentional skips before the non-overlapping main refresh.
  • 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) — build passed with 0 errors and 2 existing Fern warnings.
  • Doc pages follow the style guide (doc changes only)
  • New doc pages include SPDX header and frontmatter (new pages only)

Signed-off-by: Aaron Erickson aerickson@nvidia.com
Signed-off-by: Senthil Ravichandran senthilr@nvidia.com

ericksoa and others added 15 commits July 15, 2026 20:50
Signed-off-by: Aaron Erickson <aerickson@nvidia.com>
Signed-off-by: Aaron Erickson <aerickson@nvidia.com>
Signed-off-by: Aaron Erickson <aerickson@nvidia.com>
Signed-off-by: Aaron Erickson <aerickson@nvidia.com>
Signed-off-by: Aaron Erickson <aerickson@nvidia.com>
Signed-off-by: Aaron Erickson <aerickson@nvidia.com>
Signed-off-by: Aaron Erickson <aerickson@nvidia.com>
Signed-off-by: Aaron Erickson <aerickson@nvidia.com>
Signed-off-by: Aaron Erickson <aerickson@nvidia.com>
Signed-off-by: Aaron Erickson <aerickson@nvidia.com>
Signed-off-by: Aaron Erickson <aerickson@nvidia.com>
Signed-off-by: Aaron Erickson <aerickson@nvidia.com>
Signed-off-by: Aaron Erickson <aerickson@nvidia.com>
Signed-off-by: Senthil Kumar Ravichandran <senthilr@nvidia.com>
Signed-off-by: Aaron Erickson <aerickson@nvidia.com>
@copy-pr-bot

copy-pr-bot Bot commented Jul 16, 2026

Copy link
Copy Markdown

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

@coderabbitai

coderabbitai Bot commented Jul 16, 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

This PR adds DGX Station dual-peer qualification, secure SSH and resume state, managed two-node vLLM lifecycle orchestration, onboarding integration, updated documentation, and a guarded fixture-backed simulator with extensive tests.

Changes

Dual-Station installer and preparation

Layer / File(s) Summary
Peer qualification and resume flow
scripts/install.sh, scripts/lib/dgx-station-peer.mts, scripts/prepare-dual-dgx-station.mts, scripts/prepare-dgx-station-host.sh
Discovers reciprocal trusted Station peers, validates rails and connectivity, persists revision-bound resume state, supports reboot-required status 10, and runs host preparation in explicit modes.
Managed vLLM runtime
src/lib/inference/vllm-station-cluster.ts, src/lib/inference/vllm-station-cluster-lifecycle.ts, src/lib/inference/vllm-station-model-staging.ts, src/lib/inference/vllm.ts
Builds validated dual-node plans, stages pinned model snapshots, performs GPU/runtime preflight, starts worker/head containers, verifies readiness and authentication, and rolls back exact owned resources.
SSH binding and Docker transport
src/lib/inference/vllm-station-ssh-binding.ts, src/lib/inference/vllm-docker-env.ts, src/lib/inference/vllm-api-key.ts
Persists immutable host-key bindings, validates filesystem metadata, creates sanitized local/remote Docker environments, and manages a protected shared API key.
Inference and onboarding integration
src/lib/inference/local.ts, src/lib/inference/context-window.ts, src/lib/onboard/*, src/lib/inference/vllm-models.ts
Routes local vLLM probing through managed endpoints when available, passes explicit managed credentials to validation, and adds the pinned distributed Nemotron command and gated-model handling.
Simulation and tests
scripts/simulate-dual-station.mts, src/lib/inference/*simulator*, test/install-station-pair-preparation.test.ts, vitest.config.ts
Adds a restricted simulator command, in-memory dual-Station lifecycle fixtures, installer project routing, and regression coverage for qualification, lifecycle, authentication, and resume behavior.

Estimated code review effort: 5 (Critical) | ~120 minutes

Possibly related PRs

  • NVIDIA/NemoClaw#5927 — Shares the inference-selection validation boundary and its dependency-injection changes.
  • NVIDIA/NemoClaw#6883 — Overlaps the DGX Station express-install and Nemotron model-selection logic.
  • NVIDIA/NemoClaw#6991 — Extends the same Station host-preparation and controller-binding workflow.

Suggested labels: area: ci, area: e2e, area: install

Suggested reviewers: cv, sandl99, hoyalim

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 10.36% 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 clearly and concisely summarizes the main change: automatic preparation for trusted dual DGX Stations.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/dual-dgx-station-inference

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

@github-code-quality

github-code-quality Bot commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit eada676 in the feat/dual-dgx-statio... branch remains at 96%, unchanged from commit 5e6a821 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit eada676 in the feat/dual-dgx-statio... branch is 80%. The coverage in commit d0a95dc in the main branch is 81%.

Show a code coverage summary of the most impacted files.
File main d0a95dc feat/dual-dgx-statio... eada676 +/-
src/lib/inferen...m-docker-env.ts 100% 85% -15%
src/lib/state/m...-acquisition.ts 89% 75% -14%
src/lib/inference/vllm.ts 90% 89% -1%
src/lib/inferen...odel-staging.ts 0% 65% +65%
src/lib/inferen...er-lifecycle.ts 0% 75% +75%
src/lib/inferen...fecycle-lock.ts 0% 78% +78%
src/lib/inferen...vllm-api-key.ts 0% 80% +80%
src/lib/inferen...tion-cluster.ts 0% 83% +83%
src/lib/inferen...-ssh-binding.ts 0% 87% +87%
src/lib/inferen...test-support.ts 0% 100% +100%

Updated July 27, 2026 18:49 UTC

@github-actions

github-actions Bot commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

  • GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
  • Nemotron 3 Ultra (second opinion): Failed after a partial review · low confidence · 2 blockers · 10 warnings · 0 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, inference-routing, network-policy, onboard-repair, onboard-resume

1 optional E2E recommendation
  • vllm-docker-storage

Workflow run details

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

Comment thread src/lib/inference/vllm-api-key.ts Fixed
Comment thread src/lib/inference/vllm-station-cluster-lifecycle.ts Fixed
Comment thread src/lib/inference/vllm-station-cluster-lifecycle.ts Fixed
@ericksoa ericksoa added the feature PR adds or expands user-visible functionality label Jul 16, 2026
@ericksoa ericksoa self-assigned this Jul 16, 2026
@ericksoa ericksoa added platform: dgx-station Affects DGX Station hardware or workflows provider: vllm vLLM local or hosted provider behavior area: inference Inference routing, serving, model selection, or outputs area: onboarding Onboarding FSM, provider setup, sandbox launch, or first-run flow labels Jul 16, 2026
senthilr-nv and others added 4 commits July 16, 2026 11:22
Signed-off-by: Senthil Kumar Ravichandran <senthilr@nvidia.com>
…st-prereqs

Signed-off-by: Senthil Kumar Ravichandran <senthilr@nvidia.com>
Signed-off-by: Aaron Erickson <aerickson@nvidia.com>
Signed-off-by: Aaron Erickson <aerickson@nvidia.com>
(cherry picked from commit 586a60d)
@senthilr-nv senthilr-nv added the v0.0.96 Release target label Jul 27, 2026
@senthilr-nv

Copy link
Copy Markdown
Collaborator

@ericksoa @apurvvkumaria Before final exact-head qualification, please confirm that the previously accepted Deferred dual-DGX Station boundary applies unchanged to the current v0.0.96 candidate 9d965a291734f2e256ce7005cd5669a1a1d1b57f: two trusted Stations on direct private /30 rails, operator-owned isolation/firewall/SSH/reboots, no shared /24, and no support-status promotion.

Static CI is green and the canonical PR Review Advisor reports no blockers. The exact-head PR E2E observer is waiting, but its automatic control-plane run did not start. After scope confirmation, a repository maintainer can launch E2E / PR Gate Controller with run-control-plane for PR 7030, head 9d965a291734f2e256ce7005cd5669a1a1d1b57f, and base 1bc0283144062b560e7496baa92d3293e4a65089. We will bind the credentialed two-Station model/Ray/vLLM/auth/smoke/recovery/rollback receipt to that exact head.

Copilot AI review requested due to automatic review settings July 27, 2026 16:27

Copilot AI 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.

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.

@senthilr-nv senthilr-nv added v0.0.97 Release target and removed v0.0.96 Release target labels Jul 27, 2026
Copilot AI review requested due to automatic review settings July 27, 2026 17:37

Copilot AI 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.

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.

Signed-off-by: Senthil Ravichandran <senthilr@nvidia.com>
Copilot AI review requested due to automatic review settings July 27, 2026 17:53

Copilot AI 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.

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.

Signed-off-by: Senthil Ravichandran <senthilr@nvidia.com>
Copilot AI review requested due to automatic review settings July 27, 2026 18:03

Copilot AI 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.

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.

Signed-off-by: Senthil Ravichandran <senthilr@nvidia.com>
Copilot AI review requested due to automatic review settings July 27, 2026 18:11

Copilot AI 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.

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.

Factory Station images can provide CDI-backed --gpus support without
registering a named nvidia Docker runtime. Verify the actual no-pull GPU
container contract instead. The qualified RoCE path uses CUDA DMA-BUF/Data
Direct, so it does not require nvidia_peermem.

Signed-off-by: Senthil Ravichandran <senthilr@nvidia.com>
Copilot AI review requested due to automatic review settings July 27, 2026 18:24

Copilot AI 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.

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.

Factory Station iproute2 reports the selected source under the JSON from key
and omits the redundant device field when route show is already filtered by
device. Accept those forms while preserving the direct-route, scope-link,
neighbor identity, and jumbo-frame checks.

Signed-off-by: Senthil Ravichandran <senthilr@nvidia.com>
Copilot AI review requested due to automatic review settings July 27, 2026 18:31

Copilot AI 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.

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.

Factory Station iproute2 omits the redundant device field when neighbor
output is already filtered by device. Accept the omission while still rejecting
any emitted device that does not match the qualified rail.

Signed-off-by: Senthil Ravichandran <senthilr@nvidia.com>
Copilot AI review requested due to automatic review settings July 27, 2026 18:37

Copilot AI 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.

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: inference Inference routing, serving, model selection, or outputs area: onboarding Onboarding FSM, provider setup, sandbox launch, or first-run flow feature PR adds or expands user-visible functionality platform: dgx-station Affects DGX Station hardware or workflows provider: vllm vLLM local or hosted provider behavior v0.0.97 Release target

Projects

None yet

Development

Successfully merging this pull request may close these issues.

9 participants