Configuração

Toda a configuração está no arquivo .env na raiz do projeto. Este arquivo está no gitignore — ele nunca é commitado.

Variáveis de Ambiente

Provedor de IA

O container suporta dois modos de autenticação mutuamente exclusivos (em ordem de prioridade):

• Proxy LiteLLM — defina LITELLM_BASE_URL e LITELLM_API_KEY para rotear através de um proxy LiteLLM (veja abaixo).
• Modo OAuth — defina apenas CLAUDE_CODE_OAUTH_TOKEN (veja abaixo).

Não combine os modos — use exatamente um.

Claude Max (OAuth)

Variável	Descrição	Exemplo
CLAUDE_CODE_OAUTH_TOKEN	Token OAuth de uma assinatura Claude Max	sk-ant-oat01-...

Quando definido, o Claude Code autentica diretamente com a Anthropic usando OAuth — sem necessidade de chave de API ou proxy. Obtenha seu token nas configurações do Claude Code ou no console da Anthropic.

Proxy LiteLLM

Se seu proxy LiteLLM (ou outro) já fala a API nativa Anthropic Messages — incluindo web_search, streaming e uso de ferramentas — defina LITELLM_BASE_URL para o domínio do proxy. O container deriva automaticamente as URLs específicas do provedor:

• Endpoint Anthropic → ${LITELLM_BASE_URL}/anthropic (usado pelo Claude Code)
• Endpoint compatível com OpenAI → ${LITELLM_BASE_URL}/openai/v1

Variável	Descrição	Exemplo
LITELLM_BASE_URL	Domínio do seu proxy LiteLLM (sem sufixo de caminho)	https://litellm.example.com
LITELLM_API_KEY	Chave de API para autenticação no proxy	your-api-key ou padrão litellm-proxy

Os usuários só precisam definir o domínio — os sufixos de caminho do provedor são adicionados automaticamente. Em tempo de execução, o entrypoint deriva ANTHROPIC_API_KEY a partir de LITELLM_API_KEY para que o Claude Code possa consumir a credencial do proxy sem exigir uma variável separada voltada ao usuário.

Os nomes dos modelos não são remapeados neste modo. O Claude Code envia seus identificadores de modelo padrão (ex.: claude-sonnet-4-6) e o LiteLLM os roteia para o backend configurado.

Validação de Certificado TLS

Por padrão, o Node.js valida certificados TLS para todas as conexões HTTPS. Se seu provedor de API upstream usa um certificado autoassinado (comum com proxies internos Open WebUI ou LiteLLM), você pode desabilitar a validação adicionando isso ao seu arquivo .env:

NODE_TLS_REJECT_UNAUTHORIZED=0

Isso não é recomendado para uso em produção. Defina isso apenas quando você confia no caminho de rede entre o container e seu endpoint de API.

Agentes de Codificação IA

O container inclui vários agentes de codificação IA além do Claude Code:

Agente	Comando	Provedor
Codex	codex	Compatível com OpenAI
Pi	pi	Multi-provedor (configure em tempo de execução)
Oh-My-Pi	omp	Multi-provedor (configure em tempo de execução)

Pi e Oh-My-Pi são instalados como pacotes npm globais. Codex é um binário independente que se auto-atualiza em tempo de execução.

Display Remoto (noVNC)

O container executa uma pilha de display virtual para visualizar e interagir com navegadores com interface gráfica. Consulte Display Remoto (noVNC) para instruções de conexão e variáveis de ambiente (ENABLE_VNC, VNC_RESOLUTION, DISPLAY, NOVNC_HOST_PORT).

Chrome DevTools MCP

O container inclui um servidor Chrome DevTools MCP pré-configurado para automação de navegador headless. O Claude Code pode navegar em páginas web, tirar capturas de tela e inspecionar o DOM sem nenhuma configuração adicional. Consulte Chrome DevTools MCP para detalhes.

Git

Variável	Descrição	Como Definir
GIT_AUTHOR_NAME	Nome para commits git	git config user.name
GIT_AUTHOR_EMAIL	Email para commits git	git config user.email

Se o git está configurado na sua máquina host, preencha ambos os valores automaticamente:

echo "GIT_AUTHOR_EMAIL=$(git config user.email)" >> .env
echo "GIT_AUTHOR_NAME=\"$(git config user.name)\"" >> .env

SSH

Variável	Descrição	Como Definir
SSH_PRIVATE_KEY	Chave privada codificada em Base64	base64 < ~/.ssh/id_ed25519

GitHub CLI

Variável	Descrição	Como Definir
GH_TOKEN	Token de acesso pessoal do GitHub para o CLI gh e git HTTPS	gh auth token (se o gh está instalado localmente)

Quando GH_TOKEN está definido no .env, o CLI gh autentica automaticamente — sem necessidade de executar gh auth login. O entrypoint também executa gh auth setup-git, que configura o helper de credenciais do git para que git clone e git push via HTTPS funcionem sem chaves SSH.

Se o gh está instalado e autenticado na sua máquina host, extraia o token diretamente:

echo "GH_TOKEN=$(gh auth token)" >> .env

Caso contrário, crie um token de acesso pessoal e adicione-o manualmente. Tanto tokens refinados (recomendado) quanto tokens clássicos funcionam. Tokens refinados permitem que você defina o escopo de acesso a repositórios específicos. Tokens clássicos requerem o escopo repo para acesso a repositórios privados.

Para verificar a autenticação dentro do container:

gh auth status

Como as Ferramentas São Instaladas

Cada runtime de linguagem, CLI e ferramenta é instalado diretamente no Dockerfile no momento do build da imagem. A imagem pré-construída é publicada em ghcr.io/f5-sales-demo/devcontainer:latest a cada push para main, então a maioria dos usuários nunca precisa construir localmente.

Docker

Executar docker compose up -d puxa a imagem pré-construída automaticamente. Para construir localmente após personalizar o Dockerfile, passe o arquivo de build explicitamente:

docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

Consulte Desenvolvimento Local para detalhes.

Podman

Executar podman-compose up -d puxa a imagem pré-construída automaticamente. Para construir localmente após personalizar o Dockerfile, passe o arquivo de build explicitamente:

podman-compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

Consulte Desenvolvimento Local para detalhes.

O Dockerfile usa um build de dois estágios otimizado para cache de camadas do Docker. Consulte Desenvolvimento Local — Arquitetura de Build em Dois Estágios para o detalhamento completo das camadas e detalhes do cache de build.

Consciência de Ferramentas do Claude Code

O container inclui configuração integrada que impede o Claude Code de confundir nomes de ferramentas. A consciência de ferramentas é instalada em dois níveis de memória para defesa em profundidade:

• Política gerenciada (/etc/claude-code/CLAUDE.md) — instalada no momento do build do Docker. Este é o nível de mais alta prioridade na hierarquia de memória do Claude Code e é sempre carregado, mesmo quando um CLAUDE.md grande de projeto existe no diretório de trabalho.
• Memória do usuário (~/.claude/CLAUDE.md) — semeada pelo entrypoint na primeira inicialização. Fornece uma camada de backup e uma cópia visível e personalizável para os usuários.

Prioridade dos Níveis de Memória

O Claude Code carrega instruções de múltiplos níveis de memória (da mais alta para a mais baixa prioridade):

1. Política gerenciada (/etc/claude-code/) — Sempre carregada, não pode ser excluída
2. Memória do projeto (./CLAUDE.md) — Carregada por diretório de projeto
3. Memória do usuário (~/.claude/CLAUDE.md) — Carregada globalmente para todas as sessões
4. Memória local (./CLAUDE.local.md) — Sobrescritas pessoais por projeto

Sem o nível de Política gerenciada, a consciência de ferramentas na Memória do usuário pode ser desprioritizada ao competir com um CLAUDE.md grande no nível do projeto, fazendo com que o Claude perca a consciência dos nomes de ferramentas em PascalCase. O nível Gerenciado garante que a consciência de ferramentas seja sempre carregada com a mais alta prioridade.

Autoteste

Execute o autoteste integrado para verificar a configuração:

claude-self-test

Isso verifica se todos os arquivos de configuração estão no lugar e contêm as referências de ferramentas esperadas.

Adicionando Ferramentas

Para adicionar ferramentas à imagem, edite o Dockerfile e reconstrua localmente. Consulte Desenvolvimento Local — Adicionando Ferramentas para instruções sobre como adicionar pacotes APT, ferramentas npm, ferramentas pip e downloads de binários.

Extensões do VS Code

As extensões são configuradas em .devcontainer/devcontainer.json sob customizations.vscode.extensions e instaladas automaticamente ao abrir no VS Code.

Persistência de Dados

Todos os dados residem em volumes nomeados — nenhum diretório do host é montado:

Volume	Ponto de Montagem	Conteúdo
workspace	/workspace	Seus repositórios clonados e arquivos de projeto
home	/home/vscode	Histórico do shell, configurações de ferramentas, caches, chaves SSH

Docker

Ambos persistem entre reinicializações e reconstruções do container. Execute docker compose pull para buscar a imagem pré-construída mais recente antes de reiniciar.

Ação	Dados
docker compose down	Preservados
docker compose down -v	Deletados

Podman

Ambos persistem entre reinicializações e reconstruções do container. Execute podman-compose pull para buscar a imagem pré-construída mais recente antes de reiniciar.

Ação	Dados
podman-compose down	Preservados
podman-compose down -v	Deletados

Mapeamento de Portas

Host	Container	Serviço
127.0.0.1:${NOVNC_HOST_PORT:-6080}	6080	Display remoto noVNC (apenas localhost, sobrescreva com NOVNC_HOST_PORT)

As portas são vinculadas a 127.0.0.1 para que sejam acessíveis apenas a partir da sua máquina, não da rede.