Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Um contêiner de desenvolvimento, ou dev container, permite que você defina um ambiente idêntico e isolado que cada engenheiro da sua equipe possa executar. Com Claude Code instalado nesse contêiner, os comandos que Claude executa funcionam dentro dele em vez de na máquina host, enquanto as edições nos arquivos do seu projeto aparecem no seu repositório local conforme você trabalha. Esta página aborda instalar Claude Code em um dev container e os tópicos de configuração que se seguem. Cada tópico é independente, então pule para os que correspondem ao que você precisa configurar:
Embora o dev container forneça proteções substanciais, nenhum sistema é completamente imune a todos os ataques. Quando executado com --dangerously-skip-permissions, dev containers não impedem que um projeto malicioso exfiltre qualquer coisa acessível dentro do contêiner, incluindo as credenciais do Claude Code armazenadas em ~/.claude. Use dev containers apenas ao desenvolver com repositórios confiáveis e monitore as atividades do Claude. Evite montar segredos do host como ~/.ssh ou arquivos de credenciais de nuvem no contêiner; prefira tokens com escopo de repositório ou de curta duração.
Diagrama mostrando um editor no host conectando a um contêiner dev Docker. Claude Code, o terminal e ferramentas de compilação executam dentro do contêiner. O repositório do host é bind-mounted no contêiner como o workspace.Um dev container é executado como um contêiner Docker, seja na sua máquina ou em um host de nuvem como GitHub Codespaces. Um editor que suporta a especificação Dev Containers, como VS Code, GitHub Codespaces, um IDE JetBrains ou Cursor, se conecta a esse contêiner: você navega e edita arquivos no editor como de costume, mas o terminal integrado, servidores de linguagem e ferramentas de compilação todos executam dentro do contêiner em vez de no seu host. Editores sem suporte a dev container, como Vim simples, não fazem parte deste fluxo de trabalho.Claude Code é executado dentro do contêiner, então ele vê os mesmos arquivos, dependências e ferramentas que o resto da cadeia de ferramentas do seu projeto. No VS Code você pode usar o painel de extensão Claude Code ou executar claude no terminal integrado; ambos executam dentro do contêiner e compartilham a mesma configuração ~/.claude.

​
Adicionar Claude Code ao seu dev container

Claude Code é instalado em qualquer dev container através do Claude Code Dev Container Feature. As configurações funcionam com qualquer ferramenta que suporte a especificação Dev Containers, como VS Code, GitHub Codespaces ou IDEs JetBrains. Os passos abaixo usam VS Code como exemplo. Quando você abre o contêiner no VS Code ou Codespaces, o feature também adiciona a extensão Claude Code VS Code; outros editores ignoram essa parte.
Novo em dev containers? O tutorial Dev Containers do VS Code orienta você na instalação do Docker, da extensão e na abertura do seu primeiro contêiner. Para um exemplo mais completo e endurecido com firewall e volumes persistentes, veja Experimente o contêiner de referência.
1

Criar ou atualizar devcontainer.json

Salve o seguinte como .devcontainer/devcontainer.json no seu repositório, ou adicione o bloco features ao seu arquivo existente.A tag de versão no final, como :1.0, fixa o script de instalação do feature, não a versão do Claude Code. O feature instala o Claude Code mais recente, e Claude Code se atualiza automaticamente dentro do contêiner por padrão.Para fixar a versão da CLI ou desabilitar auto-atualização, veja Aplicar política organizacional.
.devcontainer/devcontainer.json
{
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}
  }
}
Substitua a linha image pela imagem base do seu projeto ou remova-a se seu arquivo existente usar um Dockerfile.
2

Reconstruir o contêiner

Abra a Paleta de Comandos do VS Code com Cmd+Shift+P no Mac ou Ctrl+Shift+P no Windows e Linux, e execute Dev Containers: Rebuild Container.Para outras ferramentas, siga a ação de reconstrução dessa ferramenta: veja reconstruindo no GitHub Codespaces, a CLI Dev Containers, ou a documentação de dev container do seu IDE.
3

Entrar no Claude Code

Abra um terminal no contêiner reconstruído e execute claude, depois siga o prompt de autenticação.
O que você vê no prompt de autenticação depende do seu provedor: Para provedores de nuvem, passe credenciais para o contêiner como variáveis de ambiente através de containerEnv, um segredo do Codespaces, ou a identidade de carga de trabalho da sua nuvem em vez de montar arquivos de credenciais do host. Veja Amazon Bedrock, Google Vertex AI ou Microsoft Foundry para a cadeia de credenciais que Claude Code lê. Veja Escolha seu provedor de API para decidir qual caminho se adequa à sua organização.
Se a entrada do navegador for concluída mas o callback nunca chegar ao contêiner, copie o código mostrado no navegador e cole-o no prompt Paste code here if prompted no terminal. Isso pode acontecer quando o encaminhamento de porta do editor não roteia o callback localhost.

​
Persistir autenticação e configurações entre reconstruções

Por padrão, o diretório home do contêiner é descartado na reconstrução, então os engenheiros devem entrar novamente a cada vez. Claude Code armazena seu token de autenticação, configurações do usuário e histórico de sessão em ~/.claude. Monte um volume nomeado nesse caminho para manter esse estado entre reconstruções. O exemplo a seguir monta um volume no diretório home do usuário node:
devcontainer.json
"mounts": [
  "source=claude-code-config,target=/home/node/.claude,type=volume"
]
Substitua /home/node pelo diretório home do remoteUser do seu contêiner. Se você montar o volume em algum lugar diferente de ~/.claude, defina CLAUDE_CONFIG_DIR para o caminho de montagem para que Claude Code leia e escreva lá. Para isolar o estado por projeto em vez de compartilhar um volume em todos os repositórios, inclua a variável ${devcontainerId} no nome da fonte. A configuração de referência usa source=claude-code-config-${devcontainerId} para esse propósito. No GitHub Codespaces, ~/.claude persiste entre parar e iniciar um codespace, mas ainda é limpo quando você reconstrói o contêiner, então a montagem de volume acima se aplica lá também. Para levar autenticação entre codespaces, armazene ANTHROPIC_API_KEY ou um CLAUDE_CODE_OAUTH_TOKEN de claude setup-token como um segredo do Codespaces; Codespaces disponibiliza segredos como variáveis de ambiente dentro do contêiner automaticamente.

​
Aplicar política organizacional

Um dev container é um lugar conveniente para aplicar política organizacional, porque a mesma imagem e configuração executam na máquina de cada engenheiro. Claude Code lê /etc/claude-code/managed-settings.json no Linux e a aplica com a precedência mais alta na hierarquia de configurações, então valores lá substituem qualquer coisa que um engenheiro defina em ~/.claude ou no diretório .claude/ do projeto. Copie o arquivo para o lugar certo a partir do seu Dockerfile:
Dockerfile
RUN mkdir -p /etc/claude-code
COPY managed-settings.json /etc/claude-code/managed-settings.json
Como o Dockerfile fica no repositório, qualquer pessoa com acesso de escrita pode alterar ou remover essa etapa. Para política que engenheiros não possam contornar editando arquivos do repositório, entregue configurações gerenciadas através de configurações gerenciadas pelo servidor ou seu MDM em vez disso. Veja arquivos de configurações gerenciadas para as chaves disponíveis e os outros caminhos de entrega. Para definir variáveis de ambiente que se apliquem a cada sessão do Claude Code no contêiner, adicione-as a containerEnv no seu devcontainer.json. O exemplo a seguir desativa telemetria e relatório de erros e impede que Claude Code se atualize automaticamente após a instalação:
devcontainer.json
"containerEnv": {
  "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
  "DISABLE_AUTOUPDATER": "1"
}
O Dev Container Feature sempre instala a versão mais recente do Claude Code. Para fixar uma versão específica do Claude Code para compilações reproduzíveis, instale-o a partir do seu Dockerfile com npm install -g @anthropic-ai/claude-code@X.Y.Z em vez de usar o feature, e defina DISABLE_AUTOUPDATER como mostrado acima. Para a lista completa de controles de política incluindo regras de permissão, restrições de ferramentas e listas de permissão de servidores MCP, veja Configure Claude Code para sua organização. Para disponibilizar servidores MCP dentro do contêiner, defina-os no escopo do projeto em um arquivo .mcp.json na raiz do repositório para que sejam verificados junto com sua configuração de dev container. Instale quaisquer binários dos quais servidores stdio locais dependem no seu Dockerfile, e adicione domínios de servidor remoto à sua lista de permissão de rede.

​
Restringir saída de rede

Você pode limitar o tráfego de saída do contêiner apenas aos domínios que Claude Code precisa. Veja Requisitos de acesso à rede para os domínios de inferência e autenticação, e Serviços de telemetria para as conexões opcionais de telemetria e relatório de erros e como desabilitá-las. O contêiner de referência inclui um script init-firewall.sh que bloqueia todo o tráfego de saída exceto os domínios que Claude Code e suas ferramentas de desenvolvimento precisam. Executar um firewall dentro de um contêiner requer permissões extras, então a referência adiciona as capacidades NET_ADMIN e NET_RAW através de runArgs. O script de firewall e essas capacidades não são necessários para o próprio Claude Code: você pode deixá-los de fora e confiar em seus próprios controles de rede em vez disso.

​
Executar sem prompts de permissão

Como o contêiner executa Claude Code como um usuário não-root e confina a execução de comandos ao contêiner, você pode passar --dangerously-skip-permissions para operação autônoma. A CLI rejeita essa flag quando lançada como root, então confirme que remoteUser está definido para uma conta não-root. Pular prompts de permissão remove sua oportunidade de revisar chamadas de ferramentas antes de serem executadas. Claude ainda pode modificar qualquer arquivo no workspace bind-mounted, que aparece diretamente no seu host, e alcançar qualquer coisa que a política de rede do contêiner permite. Combine essa flag com as restrições de saída de rede acima para limitar o que uma sessão contornada pode alcançar. Se você quer menos prompts sem desabilitar verificações de segurança, considere modo automático em vez disso, que tem um classificador revisando ações antes de serem executadas. Para impedir que engenheiros usem --dangerously-skip-permissions completamente, defina permissions.disableBypassPermissionsMode para "disable" em configurações gerenciadas.

​
Experimente o contêiner de referência

O repositório anthropics/claude-code inclui um exemplo de dev container que combina a CLI, o firewall de saída, volumes persistentes e um shell baseado em Zsh. É fornecido como um exemplo funcional em vez de uma imagem base mantida; use-o para ver como as peças se encaixam antes de aplicá-las à sua própria configuração.
1

Instalar pré-requisitos

Instale VS Code e a extensão Dev Containers.
2

Clonar a referência

Clone o repositório Claude Code e abra-o no VS Code.
3

Reabrir no contêiner

Quando solicitado, clique em Reopen in Container, ou execute Dev Containers: Reopen in Container na Paleta de Comandos.
4

Iniciar Claude Code

Assim que o contêiner terminar de compilar, abra um terminal com Ctrl+` e execute claude para entrar e iniciar sua primeira sessão.
Para usar essa configuração com seu próprio projeto, copie o diretório .devcontainer/ para seu repositório e ajuste o Dockerfile para sua cadeia de ferramentas, ou retorne a Adicionar Claude Code ao seu dev container para adicionar apenas o feature a uma configuração que você já tem. A configuração de referência consiste em três arquivos. Nenhum deles é necessário quando você adiciona Claude Code ao seu próprio dev container através do feature, mas eles mostram uma maneira de combinar as peças.
ArquivoPropósito
devcontainer.jsonMontagens de volume, capacidades runArgs, extensões VS Code e containerEnv
DockerfileImagem base, ferramentas de desenvolvimento e a instalação do Claude Code
init-firewall.shBloqueia todo o tráfego de rede de saída exceto os domínios permitidos

​
Próximos passos

Assim que Claude Code estiver executando no seu dev container, as páginas abaixo cobrem o resto de um rollout organizacional: escolher um caminho de autenticação, entregar política gerenciada fora do repositório, monitorar uso e entender o que Claude Code armazena e envia.