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

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

1. 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

1. 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)

1. ARM64 workaround:

```bash
# 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

1. Known issues:

• ARM64 OAuth flow generates truncated scope parameters
• Native installer doesn't support ARM64 (#20490)
• Workaround: copy credentials from working machine

1. Related GitHub issues:

• #22992 - Device-code auth for headless
• #20490 - ARM64 installer issues
• #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