fix(onboard): authorize managed loopback vLLM endpoints

[laitingsheng]

Summary

The managed host-local vLLM runtime always publishes on 127.0.0.1, and the shared SSRF preflight admits an explicit loopback host without minting a trusted-private capability, so onboarding's unconditional capability demand could never pass and every managed vLLM install exited before creating a sandbox. A loopback managed endpoint now satisfies the check on its own, while any other host still requires a provenance-checked capability.

Related Issue

Fixes #8539

Changes

• managedVllmValidationOptions in src/lib/onboard/setup-nim-vllm.ts splits one condition into two. A preflight rejection still fails closed. The trusted-private capability is now demanded only when the endpoint host is not loopback, because assertEndpointResolvesPublic returns early for an explicit loopback host and issues no capability for it — a capability records which private addresses may appear in a curl --resolve pin, and loopback needs no pin. The truthiness test is replaced by isTrustedPrivateEndpointCapability, so a forged object no longer satisfies the check.
• pinnedAddresses keeps passing preflight.addresses ?? []. The empty array is load-bearing: src/lib/adapters/http/probe.ts treats a defined value, including [], as proof that the preflight ran and strips every proxy environment variable, so the credentialed loopback probe is not routed through an ambient proxy.
• Two tests in src/lib/onboard/setup-nim-vllm.test.ts. The first drives a loopback managed binding through the handler and asserts the validation options it forwards; it fails against the unfixed code. The second holds the other side of the gate by asserting that a managed endpoint which is neither loopback nor operator-trusted private still fails closed. Neither test resolves DNS.
• The gate is scoped to loopback rather than to the preflight's trustedPrivateEndpoint flag. Gating on that flag would also have admitted a managed endpoint on a public address, which the previous code rejected. There are three managed-binding producers, and the managed-cluster one derives its base URL from a discovered fabric interface address that is not constrained to private space, so that widening would have been a real behaviour change rather than a theoretical one. Scoping to loopback fixes this defect and widens nothing.
• No production behaviour changes for the DGX Station or managed-cluster endpoints, which resolve to routed private addresses and still mint and require a capability. That path is covered by the pre-existing test using 10.40.0.1.

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: no flag, prompt, configuration key, default, or success-path output changes. The fix restores the onboarding flow the documentation already describes.
• 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 maintainer security review passed with no findings.
• 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: no documentation paths changed. The review checked the "When to Update Docs" triggers in docs/CONTRIBUTING.md and found none met: no flag is added, removed, or renamed, no default or configuration changes, and the pages describe the flow this fix restores rather than describing it incorrectly. It found the error string absent from docs/, with the only near hit in docs/reference/troubleshooting.mdx being an unrelated WSL message, and no vLLM onboarding-failure entry to stay consistent with. It confirmed that the managed-endpoint address statements in docs/inference/choose-local-inference-server.mdx and docs/inference/set-up-vllm.mdx describe where the server is published rather than an authorization rule, and that the trusted-private posture in docs/inference/custom-endpoint-security.mdx is scoped to custom endpoints and disclaims managed provider defaults, so no published claim is contradicted. It also checked docs/reference/commands.mdx, the remaining docs/inference/ vLLM pages, all pages under docs/security/, and docs/get-started/, and confirmed that neither CONTRIBUTING.md nor AGENTS.md documents the preflight capability pattern, so nothing there is stale. The review additionally rejected an earlier version of this change that gated on trustedPrivateEndpoint, and its finding produced the loopback-scoped gate in this commit.
• Agent: Codex Desktop Documentation Writer

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: npx vitest run --project cli src/lib/onboard/setup-nim-vllm.test.ts — 34 passed. npx vitest run --project cli across the eight further suites reaching this handler, including setup-nim-flow, vllm-menu, provider-selection, inference-providers/vllm-local, both provider-inference handlers, and rebuild-local-provider-recreate — 123 passed. npx vitest run --project integration test/onboard-selection-vllm.test.ts — 7 passed. npx vitest run --project installer-integration test/install-express-prompt.test.ts — 84 passed. npm run typecheck:cli and npm run build:cli — clean. test/vllm-docker-storage.test.ts skips without Docker and was not run.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: not applicable. This changes one private function in a single onboarding module and adds no harness mechanics — no Vitest config, setup file, project glob, or registration topology. npm run checks:repository passed, including the layer import boundary, source architecture budget with zero cycles, and Vitest project membership.
• 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: Tinson Lai tinsonl@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Improved authorization handling for managed vLLM endpoints.
  • Local loopback endpoints can proceed without additional private-endpoint permissions.
  • Non-loopback private endpoints remain protected and are rejected when authorization requirements are not met.
  • Authorization errors are now reported before endpoint validation.

[coderabbitai]

📝 Walkthrough

Walkthrough

Managed vLLM authorization now permits loopback endpoints without trusted-private capability. Non-loopback endpoints still require trusted-private capability. Authorization runs before model discovery and validation.

Changes

Managed vLLM authorization

Layer / File(s)	Summary
Authorization logic and coverage src/lib/onboard/setup-nim-vllm.ts, src/lib/onboard/setup-nim-vllm.test.ts	Managed endpoints use loopback hostname detection during preflight. Authorization runs before model discovery. Loopback endpoints proceed without trusted-private capability. Unauthorized non-loopback endpoints fail closed before discovery and OpenAI validation. Tests cover both paths.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes fix issue #8539 by allowing authorized loopback vLLM endpoints and preserving fail-closed behavior for untrusted endpoints.
Out of Scope Changes check	✅ Passed	The implementation and tests remain within the linked issue scope of managed vLLM endpoint authorization during onboarding.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: authorizing managed loopback vLLM endpoints during onboarding.

✨ 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/managed-vllm-loopback-authorization

---

_{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 57bc91b in the fix/managed-vllm-loo... branch remains at 96%, unchanged from commit c31724f in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 57bc91b in the fix/managed-vllm-loo... branch remains at 81%, unchanged from commit d8fbb6e in the main branch.

Show a code coverage summary of the most impacted files.

File	main d8fbb6e	fix/managed-vllm-loo... 57bc91b	+/-
src/lib/inferen...board-probes.ts	95%	94%	-1%
src/lib/shields...sive-runtime.ts	86%	85%	-1%
src/lib/onboard...-transaction.ts	93%	93%	0%
src/lib/inferen...ompatibility.ts	90%	90%	0%
src/lib/actions.../status-text.ts	41%	41%	0%
src/lib/actions...-route-probe.ts	100%	100%	0%
src/lib/shields/index.ts	82%	83%	+1%
src/lib/onboard...tup-nim-vllm.ts	86%	88%	+2%
src/lib/adapter...command-argv.ts	0%	50%	+50%
src/lib/shields...-convergence.ts	0%	75%	+75%

---

_{Updated August 07, 2026 11:13 UTC}

[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 82-88: In src/lib/onboard/setup-nim-vllm.ts:82-88, move the
managed endpoint authorization using preflight and managedVllmValidationOptions
before queryVllmModels, and exit immediately when authorization fails so no
API-key-bearing request occurs. In
src/lib/onboard/setup-nim-vllm.test.ts:169-185, spy on queryVllmModels and
assert it is not called when authorization fails.

🪄 Autofix

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: c12f7381-b556-4731-ae16-015f27ff2620

📥 Commits

Reviewing files that changed from the base of the PR and between 19b096b and f2b89e3.

📒 Files selected for processing (2)

• src/lib/onboard/setup-nim-vllm.test.ts
• src/lib/onboard/setup-nim-vllm.ts

[github-actions]

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): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized terminology decisions differ; normalized E2E selections match; severity counts match.

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

2 semantic terminology decisions

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

• justified — managed loopback endpoint at src/lib/onboard/setup-nim-vllm.test.ts:137: Keep “managed loopback endpoint”; the modifier identifies the narrow authorization condition.
• established — operator-trusted private at src/lib/onboard/setup-nim-vllm.test.ts:169: Keep the established term; it accurately describes the non-loopback authorization branch.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite against this exact revision.

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.

[apurvvkumaria]

Maintainer follow-up is complete on branch revision 57bc91b2d.

• Addressed the valid security review finding by running managed-endpoint authorization before model discovery. An unauthorized endpoint can no longer receive the API-key-bearing inventory request. The denial regression now asserts that queryVllmModels is never called.
• Refreshed from current main with normal signed merge commits. The contributor commit remains intact and attributed to Tinson Lai.
• Classified the earlier shard 3 failure as transient test load: it timed out in a pure-mock setup-nim-flow case that does not invoke this PR's changed handler. The same suite passed locally as part of 146 onboarding tests, and all other CI shards passed.
• Validation passed: 34 focused handler tests, 146 related onboarding tests, 7 integration tests, 76 endpoint-security tests, 2 recovery tests, CLI build and type-check, Biome, repository integrity gates, pre-commit hooks, secret scan, and pre-push hooks.
• Documentation writer result: no-docs-needed. Existing pages already describe the authenticated managed-loopback workflow and routed-private endpoint boundary; this change restores that behavior and adds no user-facing command, configuration, default, or lifecycle contract. Receipt: branch revision 57bc91b2d, AGENTS.md blob c69aad4d5.
• Sensitive-path security review: PASS across secrets, input validation, authentication and authorization, dependencies, error handling and logging, cryptography, configuration, security tests, and holistic posture. The change narrows credential exposure, keeps explicit loopback admission, preserves provenance checks for every non-loopback managed endpoint, adds no dependency or privilege, and exercises both allowed and denied paths.

Fresh required checks and independent human review are still pending. No gate is waived.