Support device-code authentication flow (RFC 8628) for Pro/Max subscription users in headless environments

[rajasuryars]

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

Claude Code's OAuth flow requires a browser redirect back to the machine running Claude Code. This makes it impossible to authenticate on headless environments (VMs, SSH sessions, containers, cloud instances) when using a Pro/Max subscription.

API key users can simply set ANTHROPIC_API_KEY — but subscription users have no equivalent workaround.

Proposed Solution

A device-code auth flow (RFC 8628), where authentication happens entirely on a separate device:

$ claude

/login
No browser detected. Use this code to authenticate from another device:
Open: https://claude.ai/device
Code: XXXX-XXXX
Waiting for authentication...
✓ Authentication complete.

This pattern is well-established in major CLI tools:

• GitHub CLI (gh auth login): device code flow with one-time code at github.com/login/device
• Azure CLI (az login --use-device-code): device code flow
• AWS CLI (aws sso login --use-device-code): device code flow

The key difference from the current OAuth flow is that a device-code flow requires no redirect back to the headless machine — the CLI simply polls for a token after the user completes auth on any browser, anywhere.

Alternative Solutions

Currently I work around this by temporarily installing a minimal GUI + browser on the headless VM, completing OAuth in the browser, then purging the GUI packages. Auth persists after removal.

Steps:

1. sudo apt install -y xfce4 xfce4-session firefox dbus-x11 sddm
2. Reboot, log into desktop, run claude, complete OAuth in Firefox
3. sudo apt purge -y xfce4 xfce4-* sddm firefox dbus-x11 && sudo apt autoremove -y
4. Reboot, SSH back in — Claude Code works headless

This works but takes 15+ minutes, downloads ~2-3GB of packages, and shouldn't be necessary.

Other approaches I tried that did NOT work:

• SSH port forwarding (ssh -L 8765:localhost:8765) — redirect still fails
• Copying ~/.claude/ credentials from host via scp — VM still prompts for login

Priority

Critical - Blocking my work

Feature Category

CLI commands and flags

Use Case Example

1. I run Claude Code inside a headless Ubuntu Server VM for security isolation
2. The VM has no GUI or browser — I access it only via SSH
3. I have a Max subscription, not an API key
4. Running claude shows the OAuth URL but the redirect fails because there's no browser
5. With a device-code flow, I could run /login, get a one-time code, paste the URL in my host browser, and authenticate without needing a GUI on the VM
6. This saves time because the current workaround (installing/removing a full desktop environment) takes 15+ minutes and ~2-3GB of downloads

Additional Context

• Environment: Ubuntu Server 24.04 ARM64 in UTM (macOS, M1 Pro)
• Claude Code (latest at time of testing: v2.1.31), Max subscription
• Affects all headless use cases: VMs, Docker containers, SSH remote dev, cloud instances
• API key users are unaffected since they can set ANTHROPIC_API_KEY

Related issues:

• feat(docs, auth): Document Headless/Remote Authentication and Support CI/CD #7100 — Documents headless auth workarounds, requests CI/CD auth support (12 upvotes)
• [BUG] Claude Code Login Authentication Not Persisting for Subscriber Users on remote SSH in MAC #5225 (closed) — Auth not persisting for subscription users over SSH (9 upvotes)
• Claude not respecting BROWSER= env on login? #1210 (closed) — BROWSER env variable not respected in containers

RFC 8628 (OAuth 2.0 Device Authorization Grant): https://datatracker.ietf.org/doc/html/rfc8628

[github-actions]

Found 3 possible duplicate issues:

1. OAuth refresh token not used when credentials are copied to remote/headless machines #21765
2. [BUG] Claude Code MCP Server OAuth authentication doesn't work in SSH remote sessions #1178
3. [BUG] Authentication fails with 403 error when using Claude extension via SSH remote connection #21914

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[rajasuryars]

This is not a duplicate of the flagged issues. Those are bug reports about existing OAuth failing in remote sessions. This is a feature request for a new authentication method — specifically RFC 8628 (OAuth Device Authorization Grant) — which would eliminate the need for a browser redirect entirely. None of the linked issues propose this.

[LorenzoWynberg]

yes please!

[rajasuryars]

Still relevant — especially with Agent Teams now shipping in Opus 4.6. The docs recommend tmux for split-pane agent workflows, which is the standard setup for headless/SSH environments. But the first barrier for Pro/Max users on headless VMs is still getting authenticated. This needs a proper device-code flow, not workarounds.

[andrewboldi]

Yes this would be much appreciated :)

[VictorioBerra]

Please, I need this is Github Codespace... opens in browser proxy... need device code flow

[fieldse]

This is a high priority issue for Pro/Max plan subscribers. It renders several of the core use cases for Claude Code impossible.

[VictorioBerra]

For my usecase in Codespaces, one workaround I was able to do is capture the redirect URL in my browser, and then run CURL with that in my codespace.

IE: curl 'http://localhost:46037/callback?code=REDACTED&state=gtpH-REDACTED'