fix(inference): allow keyless localhost endpoints

[sandl99]

Summary

OpenAI-compatible endpoints on exact loopback hosts now offer an explicit no-auth mode.
Real loopback API keys still work, non-loopback endpoints still require credentials, and no fabricated Authorization value reaches a no-auth upstream.

Related Issue

Fixes #7424

Changes

• Keep the API key prompt and accept Enter as no authentication for supported loopback endpoints.
• Require NEMOCLAW_COMPATIBLE_AUTH_MODE=none for non-interactive no-auth onboarding.
• Reuse the protected local proxy because OpenShell OpenAI routes require an internal credential and otherwise inject Bearer auth. The proxy authenticates inference.local traffic and strips its internal Authorization header before forwarding.
• Preserve real loopback credentials and reject no-auth mode for non-loopback endpoints.
• Restore the last committed proxy token, backend, and process credential when replacement setup fails or returns to provider selection.
• Document both modes and cover prompting, provider routing, rollback, and the upstream header 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: Exact-loopback matching, explicit mode selection, real-key preservation, fail-closed non-loopback handling, internal proxy authentication, upstream header stripping, and rollback to committed proxy state were reviewed and covered by focused tests.
• 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: PR SHA 6b067f4b4: the documentation writer confirmed that the final change is test-only and needs no additional documentation; the three changed pages continue to cover the loopback no-auth contract. The final focused integration test, Biome, diff checks, normal hooks, and CLI type-check passed.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit: not applicable
• 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 — normal hooks passed for PR SHA 6b067f4b4.
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — 31 focused proxy/provider tests and all 300 tests selected by npm run test:changed passed for the final source change at PR SHA 25c595d1e; the stabilized process-level rollback test passed again at final PR SHA 6b067f4b4. Coverage proves failed and abandoned replacement setup relaunches the committed token and backend. The preceding reporter change also records 28 focused integration tests, 24 E2E invocation-support tests, and an actual Vitest CLI selector reproduction with passed=1, skipped=0.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: not run; the change is covered by focused tests, changed tests, and type-checking.
• 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 two 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: San Dang sdang@nvidia.com

Summary by CodeRabbit

• New Features
  • Added no-auth support for OpenAI-compatible compatible endpoints only for exact loopback URLs (e.g., localhost, 127.0.0.1, [::1])—with interactive selection and non-interactive NEMOCLAW_COMPATIBLE_AUTH_MODE=none.
  • Enhanced local proxy routing with configurable loopback upstream origin.
• Bug Fixes
  • Improved onboarding/probing to correctly handle missing credentials for supported loopback URLs and avoid embedding COMPATIBLE_API_KEY when not needed.
• Documentation
  • Updated quickstart, endpoint setup, and command reference to reflect the new no-auth mode rules.
• Tests
  • Expanded coverage for loopback URL/auth-mode behavior and no-auth proxy flows.

[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

This change adds explicit no-auth support for exact loopback OpenAI-compatible endpoints, routes them through a protected configurable Ollama proxy, updates nullable-credential onboarding flows, expands validation coverage, and revises setup and command documentation.

Changes

Loopback compatible endpoint onboarding

Layer / File(s)	Summary
Loopback authentication policy src/lib/onboard/inference-providers/compatible-endpoint-gateway-route.ts, src/lib/onboard/inference-providers/compatible-endpoint-gateway-route.test.ts, docs/...	Exact loopback URLs support explicit api-key or none authentication; non-loopback endpoints continue requiring credentials.
Protected loopback proxy routing src/lib/inference/ollama/proxy.ts, scripts/ollama-auth-proxy.mts, test/ollama-auth-proxy-handler*	The proxy forwards to validated loopback HTTP(S) origins, persists and restores the backend origin, and provides proxy credentials for no-auth upstreams.
Nullable credential provider flow src/lib/onboard.ts, src/lib/onboard/inference-providers/*, src/lib/onboard/setup-*.ts	Remote provider setup accepts missing compatible credentials, invokes the no-auth proxy when eligible, and preserves required credential validation for other providers.
Proxy and onboarding validation test/onboard-inference-gateway-scope.test.ts, test/support/*, src/lib/onboard/inference-providers/remote-openai-surface.test.ts	Integration harnesses and tests verify proxy credential injection, omission of COMPATIBLE_API_KEY, and nullable-credential setup paths.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related issues

• #7209 — The changes implement the related custom endpoint and local Ollama verification behavior.

Suggested labels: feature, security

Suggested reviewers: laitingsheng, ericksoa, apurvvkumaria, jyaunches, chengjiew

Sequence Diagram(s)

sequenceDiagram
  participant Operator
  participant Onboarding
  participant compatibleEndpointGatewayRoute
  participant RemoteProvider
  participant OllamaAuthProxy
  participant LoopbackEndpoint
  Operator->>Onboarding: select compatible endpoint
  Onboarding->>compatibleEndpointGatewayRoute: select authentication mode
  compatibleEndpointGatewayRoute-->>Onboarding: return none for exact loopback
  Onboarding->>RemoteProvider: setup with nullable upstream credential
  RemoteProvider->>OllamaAuthProxy: prepare endpoint proxy
  OllamaAuthProxy->>LoopbackEndpoint: forward request without upstream API key
  LoopbackEndpoint-->>OllamaAuthProxy: return response
  OllamaAuthProxy-->>RemoteProvider: return protected proxy credentials

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 23.53% 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	The code and tests cover loopback no-auth onboarding, preserve authenticated loopback use, keep non-loopback credentials required, and preserve sandbox proxy routing.
Out of Scope Changes check	✅ Passed	The docs, tests, and proxy wiring all directly support the loopback no-auth onboarding and proxy behavior.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: explicit no-auth support for localhost-compatible inference endpoints.

✨ 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/7424-no-auth-loopback

---

_{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 6b067f4 in the fix/7424-no-auth-loo... branch remains at 96%, unchanged from commit cd87ccc in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 6b067f4 in the fix/7424-no-auth-loo... branch remains at 80%, unchanged from commit d399e58 in the main branch.

Show a code coverage summary of the most impacted files.

File	main d399e58	fix/7424-no-auth-loo... 6b067f4	+/-
src/lib/inferen...ollama/proxy.ts	30%	25%	-5%
src/lib/platform.ts	89%	84%	-5%
src/lib/onboard.ts	31%	31%	0%
src/lib/messagi...nnels/policy.ts	100%	100%	0%
src/lib/sandbox...rce-identity.ts	87%	87%	0%
src/lib/securit...ntial-filter.ts	93%	93%	0%
src/lib/trace.ts	94%	94%	0%
src/lib/tunnel/services.ts	73%	73%	0%
src/lib/onboard...iders/remote.ts	93%	98%	+5%
src/lib/onboard...l-navigation.ts	32%	46%	+14%

---

_{Updated July 24, 2026 22:28 UTC}

[github-actions]

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

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions
Status: Canonical ledger: 0 blocker(s), 1 warning(s), 0 suggestion(s).

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 1 warning · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 8 warnings · 4 suggestions
• Model comparison: normalized findings differ; normalized E2E selections match; Nemotron reported the same number of blockers, 7 more warnings, 4 more 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

• ollama-auth-proxy

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Cover specification-specific risk-signal selection

• Location: test/e2e/risk-signal-reporter.ts:67
• Category: tests
• Problem: The reporter now selects its name pattern from TestSpecification entries, but the new test covers only an undefined entry that falls back to the global CLI pattern.
• Impact: A regression in specification-specific pattern precedence or conflicting-pattern rejection could count unselected tests or write passing evidence for an ambiguous multi-specification run.
• Recommendation: Add reporter tests for a specification-specific pattern that overrides a different global pattern and for two different specification patterns that reject before evidence is written.
• Verification: Inspect test/e2e-risk-signal-reporter.test.ts and confirm it exercises both a defined TestSpecification.testNamePattern and conflicting patterns.
• Test coverage: Instantiate E2eRiskSignalReporter with a global pattern and a distinct specification pattern, then assert the risk signal counts only specification-selected tests; add a conflicting-specification case that throws without writing risk-signal.json.
• Evidence: test/e2e/risk-signal-reporter.ts adds testNamePatternForRun(), which derives a pattern from each TestSpecification and throws when patterns differ. test/e2e-risk-signal-reporter.test.ts tests only testNamePattern: undefined with a global pattern. The changed reporter determines which test results become E2E risk-signal evidence.

Workflow run details

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

[coderabbitai]

Caution

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

⚠️ Outside diff range comments (1)

src/lib/onboard.ts (1)

3462-3472: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Skip non-interactive credential validation for optional loopback keys.

When compatibleApiKeyOptional is true, this code skips recovery and prompting, but Line 3478 still unconditionally calls validateNonInteractiveCredential. With no credential, that validator receives "" and exits, so non-interactive onboarding for a no-auth custom loopback endpoint still fails. Skip that validation when the predicate is true (or pass the predicate into the validator), and add a regression test for non-interactive http://localhost onboarding without a key.

🤖 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/onboard.ts` around lines 3462 - 3472, The non-interactive onboarding
flow still validates credentials when compatibleApiKeyOptional is true, causing
no-auth loopback endpoints to fail. Update the validation call near the
recovery/prompt branching in onboard so validateNonInteractiveCredential is
skipped for optional loopback keys, while preserving validation for required
credentials, and add a regression test covering non-interactive http://localhost
onboarding without a key.

🤖 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/onboard.ts`:
- Around line 3462-3472: The non-interactive onboarding flow still validates
credentials when compatibleApiKeyOptional is true, causing no-auth loopback
endpoints to fail. Update the validation call near the recovery/prompt branching
in onboard so validateNonInteractiveCredential is skipped for optional loopback
keys, while preserving validation for required credentials, and add a regression
test covering non-interactive http://localhost onboarding without a key.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 6185042c-0401-45a9-b583-66ce42644c24

📥 Commits

Reviewing files that changed from the base of the PR and between d41a167 and c0f5742.

📒 Files selected for processing (2)

• src/lib/onboard.ts
• src/lib/onboard/openrouter-selection.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.ts`:
- Around line 3467-3469: Update the interactive credential prompt in the
onboarding flow around ensureNamedCredential to explicitly state that pressing
Enter selects no authentication, while preserving the existing credential
validation and optional-key behavior. Add or update the onboarding boundary
coverage to assert the revised prompt text, including the no-auth choice.

🪄 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: 63b2e463-0024-4e37-96d7-c429f3c2c666

📥 Commits

Reviewing files that changed from the base of the PR and between c0f5742 and ef99a83.

📒 Files selected for processing (4)

• docs/inference/set-up-openai-compatible-endpoint.mdx
• src/lib/onboard.ts
• src/lib/onboard/credential-navigation.test.ts
• src/lib/onboard/credential-navigation.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/inference/set-up-openai-compatible-endpoint.mdx

[coderabbitai]

Actionable comments posted: 2

Caution

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

⚠️ Outside diff range comments (1)

src/lib/onboard/inference-selection-validation.ts (1)

334-345: 🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

Allow exact loopback endpoints through both preflight gates.

The new no-auth route is unreachable in production: both validation and setup apply assertEndpointResolvesPublic, which rejects localhost, 127.0.0.1, and [::1] before prepareCompatibleEndpointNoAuthProxy can run. The test passes because its harness resolves localhost to 93.184.216.34.

• src/lib/onboard/inference-selection-validation.ts#L334-L345: exempt only the approved exact loopback hosts from the generic public-endpoint preflight.
• src/lib/onboard/setup-inference.ts#L427-L427: apply the same exact-loopback exception before forwarding to remote setup.
• test/onboard-inference-gateway-scope.test.ts#L113-L152: override DNS resolution to return 127.0.0.1 and prove the proxy route still succeeds.

🤖 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/onboard/inference-selection-validation.ts` around lines 334 - 345,
Allow only exact loopback hosts (localhost, 127.0.0.1, and [::1]) to bypass the
generic public-endpoint preflight in the validation flow around
preflightCustomEndpointOrFail, and apply the identical exception in
setup-inference before remote forwarding. Update
test/onboard-inference-gateway-scope.test.ts lines 113-152 to override DNS
resolution to 127.0.0.1 and verify the no-auth proxy route succeeds; no other
private or non-approved hosts should be exempted.

🤖 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.ts`:
- Around line 3310-3334: Update the auth-mode selection in the selected.key ===
"custom" branch to hydrate the configured credential using fill-only-if-missing
semantics before computing credentialAvailable. Preserve any explicit
process.env credential value, use the stored or legacy credential only when the
environment value is absent, and pass the resulting availability into
selectCompatibleEndpointAuthMode without changing later state assignment
behavior.

In `@src/lib/onboard/inference-providers/compatible-endpoint-gateway-route.ts`:
- Around line 57-65: Update the compatible endpoint route logic to reject
missing credentials for every non-interactive endpoint; allow the
COMPATIBLE_ENDPOINT_AUTH_MODE_ENV=none alternative only when
compatibleEndpointAllowsMissingApiKey identifies a loopback URL. In
src/lib/onboard/inference-providers/compatible-endpoint-gateway-route.ts lines
57-65, preserve the api-key return for endpoints with credentials. In
src/lib/onboard/inference-providers/compatible-endpoint-gateway-route.test.ts
lines 84-95, add coverage asserting that a non-loopback endpoint with
credentialAvailable: false rejects.

---

Outside diff comments:
In `@src/lib/onboard/inference-selection-validation.ts`:
- Around line 334-345: Allow only exact loopback hosts (localhost, 127.0.0.1,
and [::1]) to bypass the generic public-endpoint preflight in the validation
flow around preflightCustomEndpointOrFail, and apply the identical exception in
setup-inference before remote forwarding. Update
test/onboard-inference-gateway-scope.test.ts lines 113-152 to override DNS
resolution to 127.0.0.1 and verify the no-auth proxy route succeeds; no other
private or non-approved hosts should be exempted.

🪄 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: 205453a2-d222-4ae2-a182-5ebb414e1cb7

📥 Commits

Reviewing files that changed from the base of the PR and between ef99a83 and 3ea59fb.

📒 Files selected for processing (18)

• docs/get-started/quickstart.mdx
• docs/inference/set-up-openai-compatible-endpoint.mdx
• docs/reference/commands.mdx
• scripts/ollama-auth-proxy.mts
• src/lib/inference/ollama/proxy.ts
• src/lib/onboard.ts
• src/lib/onboard/inference-providers/compatible-endpoint-gateway-route.test.ts
• src/lib/onboard/inference-providers/compatible-endpoint-gateway-route.ts
• src/lib/onboard/inference-providers/remote-openai-surface.test.ts
• src/lib/onboard/inference-providers/remote.ts
• src/lib/onboard/inference-providers/types.ts
• src/lib/onboard/inference-selection-validation.ts
• src/lib/onboard/setup-inference.ts
• src/lib/onboard/setup-nim-selection.ts
• test/ollama-auth-proxy-handler-helpers.ts
• test/ollama-auth-proxy-handler.test.ts
• test/onboard-inference-gateway-scope.test.ts
• test/support/setup-inference-test-harness.ts

🚧 Files skipped from review as they are similar to previous changes (3)

• docs/get-started/quickstart.mdx
• docs/inference/set-up-openai-compatible-endpoint.mdx
• src/lib/onboard/inference-providers/remote.ts