feat(providers): anthropic subscription oauth by cjfit · Pull Request #2285 · NVIDIA/OpenShell

cjfit · 2026-07-15T01:18:04Z

Summary

Adds an anthropic-oauth provider type (alias: claude-subscription) that lets sandboxed agents run Claude Code against an Anthropic Pro/Max subscription instead of an API key. The OAuth access token is held gateway-side and injected only at the egress boundary (inference.local) and it never enters the sandbox environment, filesystem, or logs.

Related Issue

Closes #1925

Human Notes

Claude Fable 5 was used to help prepare the changes and PR, but all changes were prompted and reviewed by a human.
I chose to edit existing GCP provider functions because they already implemented functionality that would otherwise need to be duplicated for Anthropic OAuth (e.g. ensuring env vars have real values at sandbox initialization).
I used providers v2 as it seems this is the path that the project is standardizing on, and it handles OAuth refreshes well.
I chose not to make this fully "magic" (i.e. doing auto-discovery and initialization of the provider without the user explicitly opting in). I'm open to thoughts here, but this seems a bit intrusive due to the fact that the Claude OAuth token is read from the user's Keychain on macOS. Incorporating into the main README in a future PR with instructions could help users do the setup (currently 3 lines).

These screenshots show how the new provider works in a new sandbox. osl is an alias for my locally-compiled OpenShell executable. Providers v2 must be enabled first: osl settings set --global --key providers_v2_enabled --value true --yes.

Changes

New provider plugin (openshell-providers): anthropic-oauth with claude-subscription alias. Seeds sandbox env with ANTHROPIC_BASE_URL=https://inference.local and an ANTHROPIC_AUTH_TOKEN placeholder. Deliberately does not inject ANTHROPIC_API_KEY — Claude Code interrupts startup to confirm env API keys, but accepts ANTHROPIC_AUTH_TOKEN silently; the router strips both headers at egress anyway and injects the real subscription Bearer token plus the oauth-2025-04-20 beta header, so the two are wire-identical.
Static-config env resolution (openshell-core): the credential pipeline placeholderizes all provider env values, but SDKs must parse ANTHROPIC_BASE_URL at process startup. child_env_with_gcp_resolved is generalized to child_env_with_static_config_resolved and now resolves non-secret Anthropic config keys back to real values in the sandbox env, following the existing GCP pattern. Auth tokens stay egress-time placeholders. (Call sites and a doc-comment in google_cloud_metadata.rs updated for the rename.)
CLI setup flow (openshell-cli): openshell provider create --from-claude-login harvests the subscription OAuth material from the host keychain; --name/--type now default to claude-subscription/anthropic-oauth when that flag is set, a default inference route is configured if none exists, and the missing-provider message during sandbox create points at the correct setup command (the credentials can't be configured from inside a sandbox).
Token refresh (openshell-server): the refresh worker rotates the access token ahead of expiry and persists rotated refresh tokens. When the token endpoint rejects the refresh grant with HTTP 4xx (revoked login, lapsed plan), the stored error now carries recovery guidance (claude login on the host, recreate the provider); transient network errors and 5xx are excluded.
Docs: provider guide (docs/providers/anthropic-subscription.mdx) covering setup, the env preset, why Claude Code's "API Usage Billing" banner is cosmetic (billing goes to the subscription), and refresh-failure recovery; architecture/gateway.md updated for the env projection behavior.

Testing

Unit suites green: provider plugin, provider_credentials static-config resolution, gRPC resolve_provider_environment (asserts the access token is never injected into sandbox env), and provider refresh (re-login hint applies only to anthropic-oauth 4xx grant rejections).
Manual golden path on a locally built gateway: provider create --from-claude-login → sandbox create --provider claude-subscription → bare claude inside the sandbox authenticates without prompts and answers requests; Console API usage stays flat (billing hits the subscription).
mise run pre-commit green.

Local test checklist

Prereqs: Docker running, a Claude Pro/Max subscription with claude login completed on the host.

One caveat for macOS reviewers: a pre-existing bash 3.2 empty-array bug in e2e/mcp-conformance.sh (unrelated to this PR)

Checklist

Conventional Commits, DCO sign-off
Architecture and published docs updated
e2e run on final revision

copy-pr-bot · 2026-07-15T01:18:08Z

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

github-actions · 2026-07-15T01:20:23Z

All contributors have signed the DCO ✍️ ✅
_{Posted by the DCO Assistant Lite bot.}

cjfit · 2026-07-15T01:23:22Z

I have read the DCO document and I hereby sign the DCO.

cjfit · 2026-07-15T01:25:42Z

recheck

purp · 2026-07-15T03:57:22Z

Personally super excited that you're tackling this! It was on my list of annoyances to fix once I had a bit more understanding of the provider system.

Note that CLAUDE_CODE_OAUTH_TOKEN is also an environment variable which Claude will recognize for a long-lived (1 year) token as noted in their authentication documentation.

As noted in #620 you can create a provider based on it which is recognized by claude ... CLI commands in a sandbox, but starting a claude type sandbox still forces a copy-paste web login. To give that (also broken) flow a try:

openshell provider create --name anthropic --type claude --credential CLAUDE_CODE_OAUTH_TOKEN
openshell sandbox create --name claude-is-sad --provider anthropic -- claude 
# ... and then ignore the Claude setup screen which will want you to pick a login method
# instead, in another shell:
openshell sandbox exec --name claude-is-sad -- bash -lc 'echo $(claude auth status)'
# returns: { "loggedIn": true, "authMethod": "oauth_token", "apiProvider": "firstParty" }

Looking forward to this!

cjfit · 2026-07-15T12:52:04Z

Personally super excited that you're tackling this! It was on my list of annoyances to fix once I had a bit more understanding of the provider system.

Note that CLAUDE_CODE_OAUTH_TOKEN is also an environment variable which Claude will recognize for a long-lived (1 year) token as noted in their authentication documentation.

As noted in #620 you can create a provider based on it which is recognized by claude ... CLI commands in a sandbox, but starting a claude type sandbox still forces a copy-paste web login. To give that (also broken) flow a try:
openshell provider create --name anthropic --type claude --credential CLAUDE_CODE_OAUTH_TOKEN

openshell sandbox create --name claude-is-sad --provider anthropic -- claude 

# ... and then ignore the Claude setup screen which will want you to pick a login method

# instead, in another shell:

openshell sandbox exec --name claude-is-sad -- bash -lc 'echo $(claude auth status)'

# returns: { "loggedIn": true, "authMethod": "oauth_token", "apiProvider": "firstParty" }
Looking forward to this!

Thanks @purp! Will play around with this secret. Ideally if it works it could shrink this PR by removing some redundant code for configuring the provider.

cjfit · 2026-07-15T15:07:20Z

I've investigated #620 and my findings were consistent trying to use CLAUDE_CODE_OAUTH_TOKEN. I'm not sure that's a path worth going down further

johntmyers · 2026-07-17T17:48:38Z

gator-agent

Blocked

Gator is blocked because PR #2285 currently has merge conflicts with main (mergeable: CONFLICTING, mergeStateStatus: DIRTY).

Head SHA: 195c591c44a920c545fdd8d2dee1d27f48bb3c2d

Next action: @cjfit, please update the branch from main, resolve the conflicts, and push the resolution. Gator will run the independent code review on the new head and use one batched review for any actionable diff-anchorable findings.

johntmyers · 2026-07-17T17:49:57Z

New provider plugin (openshell-providers): anthropic-oauth with claude-subscription alias. Seeds sandbox env with ANTHROPIC_BASE_URL=https://inference.local/ and an ANTHROPIC_AUTH_TOKEN placeholder. Deliberately does not inject ANTHROPIC_API_KEY

Is this necessary? The future of inference.local is up in the air, so curious if we could just map to the actual Anthropic endpoints instead.

Add an `anthropic-oauth` provider type (alias `claude-plan`) so sandboxes can run Claude Code on an Anthropic Pro/Max subscription. The OAuth token is harvested, stored, and refreshed entirely outside the sandbox and injected only at the egress boundary; it is never written into the sandbox environment, filesystem, or logs. - inference: new anthropic-oauth profile (Authorization: Bearer plus a mandatory anthropic-beta: oauth-2025-04-20 default header) - router: merge the mandatory anthropic-beta flag with any client-sent value so the sandbox cannot drop it - server: mark ANTHROPIC_OAUTH_TOKEN non-injectable (proxy-only) - cli: add `provider create --from-claude-login` to read the local Claude Code login (macOS Keychain or ~/.claude/.credentials.json) and wire the gateway's OAuth2 background refresh - docs: add the Anthropic Subscription provider page and update gateway architecture and provider tables The macOS path (Keychain) is validated end-to-end. Linux reads the same ~/.claude/.credentials.json file and should work unchanged, but has not yet been validated on Linux. Signed-off-by: Cedric Fitzgerald <soulcedric2@gmail.com>

Project ANTHROPIC_BASE_URL and a placeholder ANTHROPIC_AUTH_TOKEN into sandboxes bound to an anthropic-oauth provider so agent CLIs reach the gateway inference endpoint without manual configuration, login flows, or API-key confirmation prompts. The auth token is a non-secret constant; inference.local replaces caller auth with the real subscription token at the egress boundary. Resolve ANTHROPIC_BASE_URL to its real value in the sandbox env: the credential pipeline placeholderizes all provider env values, and a placeholderized URL cannot be parsed by SDKs at process startup. Auth values stay egress-time placeholders. Renames child_env_with_gcp_resolved to child_env_with_static_config_resolved since it now covers non-GCP static config. Signed-off-by: Cedric Fitzgerald <soulcedric2@gmail.com>

Make --name and --type optional for provider create with --from-claude-login, defaulting to claude-subscription/anthropic-oauth. After creating the provider, configure the user inference route automatically when none is set (best-effort, unverified), removing the separate inference set step. When sandbox create hits a missing anthropic-oauth provider, stop offering env-credential discovery (subscription login material lives in the host keychain and cannot be configured from inside a sandbox) and point at provider create --from-claude-login instead. Signed-off-by: Cedric Fitzgerald <soulcedric2@gmail.com>

When the anthropic-oauth token endpoint rejects the refresh grant with HTTP 4xx (revoked login, lapsed plan), append recovery guidance to the stored refresh error so provider refresh status tells the operator to re-authenticate on the host and recreate the provider. Transient network errors and 5xx responses are excluded. Signed-off-by: Cedric Fitzgerald <soulcedric2@gmail.com>

…d recovery Describe the ANTHROPIC_AUTH_TOKEN env preset and why an API key is not injected, note that the API-usage billing banner in Claude Code is cosmetic while billing goes to the subscription, and add recovery steps for a rejected refresh token. Update the gateway architecture doc to match the env projection behavior. Signed-off-by: Cedric Fitzgerald <soulcedric2@gmail.com>

johntmyers

gator-agent

PR Review Status

Validation: This providers-v2 contribution implements the maintainer-welcomed capability in #1925 while preserving the intended gateway-side credential boundary.
Head SHA: c2d3218e2bbd220eb4a55195e8bec60305e1e814

Review findings: Seven actionable findings are attached inline. The main blockers are cluster-wide subscription authorization and ownership of Claude Code's rotating refresh token. Integration coverage is also needed for the import/refresh/rollback path and for route authorization.

Docs: The new provider guide and gateway architecture update cover the user-facing flow, and docs/index.yml already includes the provider folder. Two accuracy fixes are requested inline.

Thanks @johntmyers. I checked your question about avoiding inference.local: the current implementation needs that route because the real token is excluded from sandbox environment injection and added by the egress router. Mapping directly to Anthropic would require a different endpoint-bound authentication mechanism. Because this PR bakes inference.local into provider injection, automatic cluster routing, architecture, and published UX, its future is a maintainer design decision that should be resolved before merge.

Next state: gator:in-review

johntmyers · 2026-07-17T18:21:51Z

+            "client_id".to_string(),
+            ANTHROPIC_OAUTH_CLIENT_ID.to_string(),
+        );
+        material.insert("refresh_token".to_string(), creds.refresh_token);


gator-agent

High: This copies Claude Code's rotating refresh token into a second independent consumer. The background worker will eventually rotate it, leaving Claude Code's stored copy stale; if Claude Code rotates first, OpenShell becomes stale instead. Acquire a distinct OAuth grant for OpenShell, or make this an explicit ownership-transfer flow rather than duplicating one rotating token.

Valid callout. Anthropic doesn't expose public OAuth client registration for subscription auth. This would be the ideal.

I'll update this to use the claude setup-token flow instead.

johntmyers · 2026-07-17T18:21:51Z

        None
    };

+    if from_claude_login && provider_type != ANTHROPIC_OAUTH_PROVIDER_TYPE {


gator-agent

Low: The advertised claude-subscription provider-type alias is rejected by --from-claude-login because this compares the raw type to the canonical spelling. Validate through normalize_inference_provider_type and consistently pass or store the canonical type.

cjfit-agent

The type is normalized before the check: run.rs:4886 calls normalize_provider_type, which delegates to normalize_inference_provider_type (openshell-core/src/inference.rs:265) where "claude-subscription" → "anthropic-oauth". So by line 4943, provider_type is already canonical and the guard passes. The bot appears to have missed the normalization at the top of provider_create.

…efresh

cjfit · 2026-07-21T00:09:03Z

New provider plugin (openshell-providers): anthropic-oauth with claude-subscription alias. Seeds sandbox env with ANTHROPIC_BASE_URL=https://inference.local/ and an ANTHROPIC_AUTH_TOKEN placeholder. Deliberately does not inject ANTHROPIC_API_KEY

Is this necessary? The future of inference.local is up in the air, so curious if we could just map to the actual Anthropic endpoints instead.

Traffic to api.anthropic.com is TLS end to end, so the proxy can't inject auth in it. The router also adds a required header that subscription tokens require. We'd have to do TLS interception to do this which adds a ton of complexity and security pitfalls. Traffic wouldn't be TLS encrypted to the proxy, plus even if we went that route it'd fail open and not closed creating a debugging nightmare.

it's a pretty thin coupling to inference.local so if were ever renamed or reworked later it's a one-line change.

pierzchalski · 2026-07-21T06:58:51Z

HTTPS MITM rewriting proxies exist (e.g. hudsucker) so it might not be too difficult to support keeping ANTHROPIC_BASE_URL unchanged and just setting HTTPS_PROXY, right?

But also that's something you could do after merging this inference.local version anyways.

johntmyers

gator-agent

PR Review Status

Validation: This providers-v2 contribution implements the maintainer-welcomed capability in #1925 and has a clear user path, security-boundary goal, and published docs.
Head SHA: 664b0a147c21fee2542ff359e71207e55478ca9e

Review findings: Six actionable diff-anchored findings are attached inline. Two additional high-severity general findings remain:

GetInferenceBundle authorizes only that the caller is some sandbox, then returns the gateway-wide route and personal subscription credential without checking that the provider is attached to that sandbox (CWE-862/CWE-269). Load the caller's sandbox and scope the user route to its provider attachments, with allow/deny coverage.
Inference bundle resolution ignores credential_expires_at_ms, so an expired subscription token can remain distributed and cached after refresh enters reauth_required (CWE-613). Omit expired routes and publish a changed bundle so supervisors clear stale cached credentials.

Thanks @cjfit. I checked your current-head fixes and replies: the missing-provider path now aborts, terminal refresh failures stop automatic retries, alias normalization was already correct, and the token-storage and upstream-revocation docs are corrected. The current head still imports Claude Code's rotating refresh token despite your planned claude setup-token change, and documenting gateway-wide subscription access does not enforce sandbox authorization.

Docs: The Fern provider page, provider-management link, architecture update, and folder-based navigation cover the direct UX. Two documentation corrections are attached inline.

Process blocker: this head also conflicts with main (mergeable: CONFLICTING, mergeStateStatus: DIRTY).

Next state: gator:blocked until the merge conflict is resolved; the code-review findings also require author changes before pipeline watch.

johntmyers · 2026-07-21T14:47:52Z

+            "client_id".to_string(),
+            ANTHROPIC_OAUTH_CLIENT_ID.to_string(),
+        );
+        material.insert("refresh_token".to_string(), creds.refresh_token);


gator-agent

High: This gives Claude Code and the gateway shared ownership of one rotating refresh token. When either consumer refreshes, the other copy becomes stale; delaying the first gateway refresh only postpones the failure. Please use the dedicated claude setup-token or another separate credential flow and do not copy Claude Code's live login refresh token.

johntmyers · 2026-07-21T14:47:52Z

-            state.next_refresh_at_ms =
-                now_ms.saturating_add(REFRESH_ERROR_RETRY_SECONDS.saturating_mul(1000));
-            persist_refresh_state_if_current(store, &state, expected_version).await?;
+            put_refresh_state(store, &state).await?;


gator-agent

High: This must remain a version-matched update. An unconditional put can resurrect refresh secret material deleted during the HTTP call or overwrite a newer reconfiguration. Use persist_refresh_state_if_current(..., expected_version), abort on None, and retain the delete/supersede race tests.

johntmyers · 2026-07-21T14:47:52Z

+    openshell_core::inference::normalize_inference_provider_type(&provider.r#type)
+        == Some("anthropic-oauth")
+        && err.code() == tonic::Code::FailedPrecondition
+        && err.message().contains("token endpoint returned HTTP 4")


gator-agent

Warning: This also makes 408, 429, and every other 4xx permanently terminal. Parse the OAuth error and reserve reauth_required for terminal grant failures such as invalid_grant; rate limits and timeouts should be rescheduled with bounded backoff.

johntmyers · 2026-07-21T14:47:52Z

        );
    }

-    #[test]


gator-agent

Warning: This replacement removes extensive unrelated AWS STS, additional-output, collision, session-token, and refresh-race regression coverage. Please restore those tests and add the Anthropic terminal-state test alongside them.

johntmyers · 2026-07-21T14:47:52Z

+
+The subscription OAuth token represents your whole plan, so it is shared across every sandbox bound to the provider, and revoking it is provider-wide. Anthropic rotates the refresh token on each refresh; the gateway persists the rotated token so refresh keeps working. The long-lived refresh material lives only in gateway state, never in a sandbox.
+
+To rotate the credential, delete and recreate the provider, or rotate through `openshell provider refresh`. Deleting the provider only removes the gateway's copy of the tokens — it does not revoke the OAuth session at Anthropic. Revocation happens via `claude /logout` or Anthropic's session management.


gator-agent

Low: openshell provider refresh is not executable without a subcommand, provider, and credential key. Please show the exact refresh rotate claude-subscription --credential-key ANTHROPIC_OAUTH_TOKEN and corresponding refresh status commands.

johntmyers · 2026-07-21T14:47:52Z

+
+## Prerequisites
+
+- A local Claude Code login on an Anthropic Pro or Max plan. Run `claude login` (or `/login` inside Claude Code) on the host before creating the provider.


gator-agent

Low: This flow depends on undocumented Claude Code credential storage and Anthropic OAuth details. Please identify the integration as experimental, warn that Claude Code upgrades may break import or refresh, and document the supported recovery path.

cjfit requested review from a team, derekwaynecarr, maxamillion and mrunalp as code owners July 15, 2026 01:18

drew changed the title ~~Feat/anthropic subscription oauth~~ feat(providers): anthropic subscription oauth Jul 16, 2026

johntmyers added the gator:blocked Gator is blocked by process or repository gates label Jul 17, 2026

cjfit added 6 commits July 17, 2026 10:57

change alias claude-plan to claude-subscription

e94c575

johntmyers force-pushed the feat/anthropic-subscription-oauth branch from 195c591 to c2d3218 Compare July 17, 2026 17:58

johntmyers reviewed Jul 17, 2026

View reviewed changes

johntmyers added gator:in-review Gator is reviewing or awaiting PR review feedback and removed gator:blocked Gator is blocked by process or repository gates labels Jul 17, 2026

cjfit added 3 commits July 20, 2026 19:59

update docs to call out shared inference endpoint, sever-side token r…

25988e9

…efresh

handle 4xx grant rejections

19d54fe

exit if missing anthropic-oauth

664b0a1

johntmyers reviewed Jul 21, 2026

View reviewed changes

johntmyers added gator:blocked Gator is blocked by process or repository gates and removed gator:in-review Gator is reviewing or awaiting PR review feedback labels Jul 21, 2026

matthewgrossman mentioned this pull request Jul 21, 2026

fix(dco): Fix mismatched wording that breaks initial DCO checks #2399

Open

9 tasks

                       );
                   }
-                  #[test]


		The subscription OAuth token represents your whole plan, so it is shared across every sandbox bound to the provider, and revoking it is provider-wide. Anthropic rotates the refresh token on each refresh; the gateway persists the rotated token so refresh keeps working. The long-lived refresh material lives only in gateway state, never in a sandbox.

		To rotate the credential, delete and recreate the provider, or rotate through `openshell provider refresh`. Deleting the provider only removes the gateway's copy of the tokens — it does not revoke the OAuth session at Anthropic. Revocation happens via `claude /logout` or Anthropic's session management.


		## Prerequisites

		- A local Claude Code login on an Anthropic Pro or Max plan. Run `claude login` (or `/login` inside Claude Code) on the host before creating the provider.

Uh oh!

Conversation

cjfit commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related Issue

Human Notes

Changes

Testing

Local test checklist

Checklist

Uh oh!

copy-pr-bot Bot commented Jul 15, 2026

Uh oh!

github-actions Bot commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cjfit commented Jul 15, 2026

Uh oh!

cjfit commented Jul 15, 2026

Uh oh!

purp commented Jul 15, 2026

Uh oh!

cjfit commented Jul 15, 2026

Uh oh!

cjfit commented Jul 15, 2026

Uh oh!

johntmyers commented Jul 17, 2026

Blocked

Uh oh!

johntmyers commented Jul 17, 2026

Uh oh!

johntmyers left a comment

Choose a reason for hiding this comment

PR Review Status

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cjfit commented Jul 21, 2026

Uh oh!

pierzchalski commented Jul 21, 2026

Uh oh!

johntmyers left a comment

Choose a reason for hiding this comment

PR Review Status

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

cjfit commented Jul 15, 2026 •

edited

Loading

github-actions Bot commented Jul 15, 2026 •

edited

Loading