Headroom + Claude Code em Docker

Estrutura pronta para rodar o Headroom (proxy de compressão de contexto) junto com o Claude Code dentro de um container Docker.

Estrutura de arquivos

headroom-claude-setup/
├── Dockerfile           # imagem com Node + Claude Code + Headroom (Python)
├── docker-compose.yml   # orquestração, volumes e variáveis
├── entrypoint.sh        # script que decide o modo de execução (proxy/wrap/shell)
├── .env.example         # modelo de variáveis de ambiente (copiar para .env)
├── .gitignore
├── workspace/           # seu código-fonte (montado em /workspace no container)
└── data/
    ├── claude/          # config/credenciais persistentes do Claude Code (~/.claude)
    └── headroom/        # config/cache/memória persistentes do Headroom (~/.headroom)

Passo a passo

1. Configure as variáveis de ambiente

cp .env.example .env

Edite o .env — é o único lugar onde você normalmente precisa mexer:

Variável	Para que serve	Onde é usada
ANTHROPIC_API_KEY	Chave real da Anthropic, usada pelo Headroom para autenticar a chamada de fato	repassada pelo docker-compose.yml para o container
ANTHROPIC_AUTH_TOKEN	Alternativa ao API_KEY (gateways corporativos, proxies que usam Bearer token). Deixe vazio se não usar	idem
ANTHROPIC_MODEL	Modelo padrão do Claude Code (ex: claude-sonnet-4-6, claude-opus-4-6)	exportada no entrypoint.sh antes de chamar claude
ANTHROPIC_BASE_URL	URL que o Claude Code chama. Dentro do container deve sempre apontar para o proxy local do Headroom, nunca direto para a Anthropic	definida no docker-compose.yml e reforçada no entrypoint.sh
HEADROOM_ANTHROPIC_API_URL	URL upstream real para onde o Headroom encaminha requisições /v1/messages já comprimidas (padrão https://api.anthropic.com)	flag --anthropic-api-url no entrypoint.sh
HEADROOM_OPENAI_API_URL	URL upstream real para /v1/chat/completions e /v1/responses (padrão https://api.openai.com). Use para apontar para OpenRouter, LiteLLM ou gateway próprio	flag --openai-api-url no entrypoint.sh
HEADROOM_VERTEX_API_URL	URL upstream real para rotas Gemini/Anthropic-on-Vertex (/v1/projects/.../publishers/...). Formato https://<REGIAO>-aiplatform.googleapis.com	flag --vertex-api-url no entrypoint.sh
HEADROOM_PORT	Porta do proxy do Headroom (host e container)	docker-compose.yml, entrypoint.sh

Fluxo de dados: claude (CLI) → ANTHROPIC_BASE_URL (proxy Headroom, porta HEADROOM_PORT) → Headroom comprime o contexto → Headroom encaminha para a URL upstream correspondente (HEADROOM_ANTHROPIC_API_URL / HEADROOM_OPENAI_API_URL / HEADROOM_VERTEX_API_URL) usando ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN ou as credenciais do provedor relevante.

Resumindo as URLs, que são independentes:

• ANTHROPIC_BASE_URL = para onde o cliente (claude) manda as requisições → sempre o proxy local.
• HEADROOM_ANTHROPIC_API_URL / HEADROOM_OPENAI_API_URL / HEADROOM_VERTEX_API_URL = para onde o Headroom encaminha de fato cada tipo de rota → mude qualquer uma delas para apontar para um proxy/gateway próprio (ex: OpenRouter no lugar da OpenAI, um gateway corporativo no lugar da Anthropic, etc).

Exemplo: para trocar o destino da OpenAI por um proxy próprio (como no seu log: https://meuproxy.proxy):

# no .env
HEADROOM_OPENAI_API_URL=https://meuproxy.proxy

Não edite ANTHROPIC_BASE_URL para apontar direto para api.anthropic.com — isso pula o Headroom e você perde a compressão. A única variável que normalmente você troca por sessão é ANTHROPIC_MODEL, ex:

ANTHROPIC_MODEL=claude-opus-4-6 docker compose run --rm headroom-claude shell

2. Construa a imagem

docker compose build

3. Suba apenas o proxy (modo padrão, fica em background)

docker compose up -d

Verifique se está saudável:

curl http://localhost:8787/health
# {"status":"healthy","ready":true,...}

4. Use o Claude Code dentro do container, já apontando para o proxy

Para abrir um shell interativo dentro do container (com o proxy já configurado):

docker compose run --rm headroom-claude shell

Dentro do container, o ANTHROPIC_BASE_URL já está setado, então basta rodar:

claude

5. Ou rode o Claude direto, sem abrir shell manualmente

docker compose run --rm headroom-claude wrap "Liste os arquivos do projeto e resuma a estrutura"

Isso sobe o proxy, espera ficar saudável, e já dispara o claude com a mensagem passada.

6. Trabalhando com seu código

Coloque seu projeto dentro da pasta workspace/ — ela é montada em /workspace no container, então o Claude Code vai ler e editar exatamente esses arquivos no seu host.

7. Persistência

• data/claude/ guarda login/config do Claude Code entre reinícios do container (não precisa re-autenticar toda vez).
• data/headroom/ guarda cache, métricas e a "memória" de aprendizado do Headroom (headroom learn).

8. Checar economia de tokens

Dentro do container (modo shell):

headroom perf

Ou ative logs verbosos do Headroom definindo HEADROOM_LOG_LEVEL=DEBUG no .env antes de subir o container.

Comandos úteis

Ação	Comando
Build da imagem	docker compose build
Subir proxy em background	docker compose up -d
Ver logs do proxy	docker compose logs -f headroom-claude
Shell interativo	docker compose run --rm headroom-claude shell
Rodar Claude direto	docker compose run --rm headroom-claude wrap "<prompt>"
Parar tudo	docker compose down

Notas de segurança

• O .env real nunca deve ser commitado (já está no .gitignore).
• Em CI/Docker, prefira sempre passar a ANTHROPIC_API_KEY explicitamente via variável de ambiente, em vez de depender de keychains do host.
• O container roda com usuário não-root (devuser).