Missing documentation: How to authenticate Claude Code on ARM64/Raspberry Pi and headless servers

[davidbicho]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/authentication

Section/Topic

ARM64/Raspberry Pi authentication and ~/.claude/.credentials.json location

Current Documentation

The docs currently say:

• "Run claude /login to authenticate"
• No mention of where credentials are stored
• No mention of ARM64-specific issues
• No workaround for headless servers with Max subscription

But it doesn't explain that:

• On ARM64, /login generates broken OAuth URLs (truncated scope:
  "user:inferenc")
• Credentials are stored in ~/.claude/.credentials.json on Linux
• The workaround is to copy credentials from a working machine

What's Wrong or Missing?

The documentation doesn't explain:

1. WHERE credentials are actually stored:

   • Linux: ~/.claude/.credentials.json
   • macOS: Keychain
   • This is never documented anywhere

2. ARM64/Raspberry Pi authentication is BROKEN:

   • OAuth URL has truncated scope: "user:inferenc" instead of "user:inference"
   • Browser shows "Invalid OAuth Request: Unknown scope: user:inferenc"
   • Makes authentication impossible on ARM64

3. No workaround documented for:

   • Headless servers with Max subscription
   • ARM64 systems
   • How to copy credentials between machines

Users waste hours trying solutions that don't work:

• SSH port forwarding (still broken OAuth URL on ARM64)
• claude setup-token (doesn't work on ARM64)
• Copying oauthAccount from .claude.json (doesn't include actual tokens)

Suggested Improvement

Add a new documentation section: "Authentication on ARM64 and Headless Servers"

Include:

1. Credential storage locations:

   • Linux: ~/.claude/.credentials.json
   • macOS: Keychain (accessed via security command)

2. ARM64 workaround:

   # Step 1: Authenticate on x86_64 Linux or macOS
   claude /login
   
   # Step 2: Copy credentials to ARM64 device
   scp ~/.claude/.credentials.json pi@raspberry-pi:~/.claude/.credentials.json
   
   # Step 3: Ensure onboarding is complete
   ssh pi@raspberry-pi
   # Edit ~/.claude.json and set "hasCompletedOnboarding": true
   

3. Known issues:
   - ARM64 OAuth flow generates truncated scope parameters
   - Native installer doesn't support ARM64 ([BUG] Native installer reports success but fails to install binary on Raspberry Pi (ARM64) #20490)
   - Workaround: copy credentials from working machine

4. Related GitHub issues:
   - Support device-code authentication flow (RFC 8628) for Pro/Max subscription users in headless environments #22992 - Device-code auth for headless
   - [BUG] Native installer reports success but fails to install binary on Raspberry Pi (ARM64) #20490 - ARM64 installer issues
   - Native Installer Incorrectly Rejects aarch64 as "Unsupported architecture: arm" #3569 - aarch64 rejection

Impact

High - Prevents users from using a feature

Additional Context

This affects ALL Raspberry Pi and ARM64 users with Claude Max subscription.

Tested and confirmed on:

• Raspberry Pi 4 (ARM64, Debian 13)
• Ubuntu ARM64 servers
• Credentials successfully copied from x86_64 Ubuntu and macOS

The workaround is reliable and credentials persist across reboots.

Related issues: #20490, #3569, #22992, #21678

[github-actions]

Found 3 possible duplicate issues:

1. [BUG] install-github app OAuth error #22622
2. [BUG] Invalid OAuth Request - Unknown scope: user:sessions% #26874
3. [BUG] Invalid OAuth Request: Unknown scope: org%3Acreate_api_key #20325

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

[github-actions]

This issue has been automatically closed as a duplicate of #22622.

If this is incorrect, please re-open this issue or create a new one.

🤖 Generated with Claude Code

[fieldse]

This is not a duplicate of #29947; should be reopened.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.