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:

{
  "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):

#!/bin/bash
# Prints the OAuth token to stdout. CC calls this on demand.