headless-claude-code

# Headless Claude Code Running Claude Code outside a desktop terminal — in Docker containers, CI runners, cloud VMs, or orchestrated by another process — is full of undocumented friction. This guide covers everything we've learned getting CC to work reliably in these environments. --- ## 1. Authentication CC tries multiple auth strategies in a fixed priority order. Understanding this chain is the key to headless auth. ### Priority Order (highest → lowest) 1. **Cloud provider ambient credentials** — AWS Bedrock, GCP Vertex (auto-detected) 2. **`ANTHROPIC_AUTH_TOKEN`** — raw bearer token for Anthropic's API 3. **`ANTHROPIC_API_KEY`** — direct API key (pay-per-token, no Pro subscription features) 4. **`apiKeyHelper`** — executable that prints a token to stdout (set via `--settings`) 5. **`CLAUDE_CODE_OAUTH_TOKEN`** — OAuth token (Pro/Team subscription) 6. **`/login`** — interactive browser OAuth dance (unusable in headless) ### Recommended: `apiKeyHelper` The most flexible headless strategy. Point CC at a script that returns a valid token: ```json { "apiKeyHelper": "/path/to/your-auth-script" } ``` Pass it via `--settings /path/to/settings.json` on launch. CC calls this script whenever it needs a token, so it handles rotation naturally. **Example helper** (reads from a credential vault): ```bash #!/bin/bash # Prints the OAuth token to stdout. CC calls this on demand. your-vault-cli get anthropic-oauth-token ``` The script MUST: - Print exactly one token to stdout...