Claude Code em um dev container: a configuração segura e reproduzível
Instale a extensão Dev Containers, mantenha o Docker rodando, adicione o feature oficial claude-code, reabra no contêiner, faça login pelo terminal e mantenha a autenticação viva entre rebuilds — cada passo verificado contra a documentação de dev containers da Anthropic.
A versão curta
- Instale a extensão Dev Containers, deixe o Docker rodando e dê Reopen in Container em qualquer repositório com .devcontainer/ — o Claude Code e todo comando que ele executa rodam dentro do contêiner, não na sua máquina.
- O feature oficial — "ghcr.io/anthropics/devcontainer-features/claude-code:1.0" no bloco features — instala a CLI em qualquer devcontainer; o VS Code também ganha a extensão, e ambos compartilham o mesmo ~/.claude.
- Faça login pelo terminal do contêiner; se o callback do navegador não alcançar, cole o código no prompt. Faça a autenticação sobreviver a rebuilds com um volume em ~/.claude mais containerEnv.CLAUDE_CONFIG_DIR.
- Um dev container substitui o ambiente (o /sandbox, em vez disso, confina comandos individuais no seu host). Eles se compõem — contêiner para o ambiente, sandbox e prompts de permissão para o comportamento.
Run Your AI Coding Agent in Dev Containers - Complete Beginner's Guide
Canal: Visual Studio Code15:39
Step-by-Step: Run Claude Code SAFELY in a Dev Container
Canal: Fuzz Puppy6:56
Development containers — official documentation
Documentação oficial: code.claude.com/docs
Cada passo de configuração, nome de feature e caminho de credencial desta página foi verificado contra a documentação oficial de development containers; os vídeos acima são as fontes visuais e factuais.
As capturas de tela pertencem aos seus criadores, com links diretos para os timestamps exatos. Nenhum quadro com rosto é usado.
Rodar o Claude Code num dev container, passo a passo
Parte 1 — Pré-requisitos: VS Code encontra Docker
- 1
Instale a extensão Dev Containers
Abra a visualização de extensões no VS Code e instale o Dev Containers da Microsoft. A extensão adiciona o indicador remoto na barra de status, o comando Reopen in Container e o Remote Explorer — todo o fluxo abaixo passa por ela. Docker ainda não é necessário.
A extensão Dev Containers é o que adiciona o Reopen in Container ao VS Code — instale primeiro pela visualização de extensões.Ver em 2:00 - 2
Instale o Docker Desktop e deixe-o ligado
Dev containers são contêineres de verdade, então um motor de contêineres precisa estar rodando antes de qualquer coisa abrir. O Docker Desktop é a escolha usual no macOS e Windows; o Docker Engine serve no Linux. Ligue e deixe ligado — um motor parado é a causa número um de um "Opening Remote" travado na primeira tentativa.
O Docker Desktop só precisa estar rodando; uma lista de Containers vazia é exatamente a cara de um setup saudável pré-contêiner.Ver em 2:12 - 3
Entenda o que muda para o Claude Code
Depois do Reopen in Container, o VS Code roda seu servidor dentro do contêiner — e todo comando que o Claude Code executa também. Instalações, testes e edições de arquivo ficam dentro do contêiner, enquanto a pasta do workspace é montada de volta no seu repositório. Sua máquina só precisa de VS Code e Docker; toolchains e dependências moram na imagem, e um experimento fugaz do agente não toca em nada lá fora.
Parte 2 — Um contêiner funcionando, de ponta a ponta
- 4
Abra um dev container pronto
O caminho mais rápido para ver a maquinaria funcionar: no Remote Explorer, escolha uma amostra como o dev container de Go. O VS Code clona github.com/microsoft/vscode-remote-try-go e abre dentro de um volume de contêiner — nenhuma configuração escrita por você ainda.
O Remote Explorer traz amostras prontas — escolha uma e o VS Code clona o repositório direto para um volume de contêiner.Ver em 2:30 - 5
Deixe o VS Code construir e conectar
A primeira conexão clona o repositório, puxa a imagem do contêiner camada por camada e inicia o contêiner — a barra de status anuncia "Connecting to Dev Container". Numa conexão lenta, esta é a espera mais longa do setup; toda abertura seguinte reusa a imagem e leva segundos.
A primeira build baixa a imagem do contêiner camada por camada; a barra de status acompanha a conexão ao dev container.Ver em 2:52 - 6
Confirme que o terminal está dentro do contêiner
Abra um terminal novo e imprima a versão da toolchain (go version aqui). A saída nomeia o sistema e a arquitetura do contêiner, não os do seu notebook. Este terminal é exatamente onde você abriria o claude — e tudo que ele executar fica dentro do contêiner.
go version imprime a toolchain do contêiner, não a do notebook — rode claude neste terminal e ele também fica dentro.Ver em 3:50 - 7
Leia o devcontainer.json
O arquivo .devcontainer/devcontainer.json define o ambiente inteiro: a imagem base (ou um Dockerfile), as extensões de VS Code a instalar no contêiner, portas redirecionadas, passos de postCreateCommand e o remoteUser. Para o Claude Code, é também onde entram o feature oficial e o volume de credenciais — cobertos nos passos 9 e 13.
Tudo de que o contêiner é feito mora em .devcontainer/devcontainer.json: imagem, extensões, portas redirecionadas, comandos pós-criação.Ver em 4:40 - 8
Aponte o agente para o workspace
Anexe @workspace no painel do agente e peça uma explicação do projeto. A explicação e cada comando por trás dela executam dentro do contêiner. O Claude Code funciona do mesmo jeito depois que a CLI entra na imagem: contexto estilo @workspace mais comandos que nunca saem do contêiner.
Pedindo ao agente para explicar o projeto via @workspace — cada comando executado roda dentro do contêiner.Ver em 5:20 - 9
Troque pelo feature oficial do Claude Code
Sem instalações manuais: adicione "ghcr.io/anthropics/devcontainer-features/claude-code:1.0" ao bloco features do devcontainer.json e reconstrua. O feature instala a CLI — e, quando o contêiner abre no VS Code, a extensão do Claude Code também, compartilhando o mesmo ~/.claude do terminal. Se a imagem base não tem Node.js, você verá "Failed to install Node.js and npm": adicione o feature do Node acima dele. Configurações de ambiente como CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC ou DISABLE_AUTOUPDATER vão em containerEnv, e mounts pode trazer seus outros repositórios locais para dentro do contêiner.
- 10
Rode o app e use a porta redirecionada
Inicie o app de dentro do contêiner (painel de debug, npm run dev, go run — o que a stack pedir) e o VS Code detecta a porta em escuta: uma notificação oferece abri-la no seu navegador local. O servidor nunca sai do contêiner; o redirecionamento só faz o localhost se comportar como sempre.
O app roda na porta 9000 dentro do contêiner; o VS Code a redireciona para o localhost funcionar exatamente como de costume.Ver em 6:08
Parte 3 — Seu repositório e o login
- 11
Adicione um dev container ao seu projeto
Em qualquer repositório, rode Dev Containers: Add Dev Container Configuration Files pela paleta de comandos ou pelo indicador remoto, e escolha "Add configuration to workspace folder". Commitada junto com o código, a config dá aos colegas — e aos Codespaces — o ambiente idêntico de graça.
Sem devcontainer.json ainda? O VS Code gera um a partir de um template — mantenha no workspace para o git compartilhar.Ver em 9:00 - 12
Escolha o template e os features
O VS Code sugere um template compatível com sua stack (Node.js, Python, Go…) e mostra a lista de features — instaladores reutilizáveis como Git LFS ou GitHub CLI. É nessa lista que o feature claude-code do passo 9 se encaixa. Aceite os padrões (ou peça ao agente para refinar o arquivo gerado) e reabra no contêiner.
A lista de features é onde uma linha de feature do Claude Code se encaixa ao lado do que o template sugere.Ver em 9:48 - 13
Faça login dentro do contêiner
Rode claude no terminal integrado e escolha seu login (assinatura Claude ou Anthropic Console). O navegador abre no seu host; se o callback não alcançar o contêiner, copie o código do navegador e cole no prompt "Paste code here if prompted". Para sobreviver a rebuilds, monte um volume em ~/.claude e aponte containerEnv.CLAUDE_CONFIG_DIR para o mesmo caminho — o arquivo de conta ~/.claude.json mora fora dessa pasta, e é por isso que as duas metades importam. Para execuções headless ou Codespaces, gere um token com claude setup-token e passe ANTHROPIC_API_KEY ou CLAUDE_CODE_OAUTH_TOKEN.
Dev container vs /sandbox: qual isolamento você precisa?
O Claude Code traz duas respostas de isolamento, e elas resolvem problemas diferentes. Um dev container substitui o ambiente em que o agente trabalha; o sandboxing embutido confina os comandos que ele roda na sua máquina atual. Os docs oficiais os posicionam como complementares — o devcontainer de referência até embute um script de restrição de egress.
- 1Escopo. Um dev container troca o ambiente inteiro — SO, toolchain, dependências — pelo definido no devcontainer.json. O sandboxing mantém sua máquina e restringe o que cada comando bash pode ler, escrever e alcançar na rede.
- 2Requisitos. Dev containers pedem Docker (Desktop ou Engine) mais a extensão Dev Containers; o sandboxing é embutido no Claude Code e não precisa de nenhum dos dois.
- 3Mecânica de time. O devcontainer.json é commitado, então cada colega e cada Codespace constrói o ambiente idêntico; a política do sandbox mora nas configurações do Claude Code e segue o usuário, não o repositório.
- 4Raio de explosão. Num contêiner, um rm -rf desastrado ou uma instalação desgovernada atinge um sistema de arquivos descartável e seu host fica intacto. O sandbox mira o mesmo resultado por comando — sem a fronteira do contêiner.
- 5Escolha um dev container quando o próprio projeto precisa de um ambiente: múltiplos runtimes, onboarding limpo, desenvolvimento em nuvem. Escolha o sandbox como a proteção do dia a dia para sessões no seu host. Eles se compõem — rode o Claude Code dentro de um dev container e mantenha sandboxing e prompts de permissão ligados.
Mais uma linha os diferencia: o /sandbox é uma política por sessão que você ajusta no meio da conversa, enquanto um dev container é decidido antes da sessão começar — mudar significa rebuild. Execuções em lote não assistidas apoiam-se nos dois ao mesmo tempo: usuário de contêiner sem root, egress restrito e --dangerously-skip-permissions somente dentro do contêiner.
Algo fora do comportamento? Comece aqui
A maior parte do atrito de dev containers com o Claude Code cai em meia dúzia de padrões conhecidos. Cada correção abaixo vem direto da documentação oficial de development containers.
- 1"Failed to install Node.js and npm" na instalação do feature: a imagem base não tem Node.js. Adicione o feature do Node (ghcr.io/devcontainers/features/node:1) acima do feature claude-code no bloco features e reconstrua.
- 2O login se completa no navegador mas o contêiner segue deslogado: o callback OAuth não alcança o contêiner. Copie o código mostrado no navegador e cole no prompt "Paste code here if prompted" no terminal.
- 3Login e configurações somem a cada rebuild: nada persiste o ~/.claude. Monte um volume nomeado nesse caminho e aponte containerEnv.CLAUDE_CONFIG_DIR para ele — inclua a variável devcontainerId no nome do volume para os projetos seguirem isolados. Nos Codespaces a pasta sobrevive a stop/start mas é limpa num rebuild completo, então forneça ANTHROPIC_API_KEY ou um CLAUDE_CODE_OAUTH_TOKEN do claude setup-token como secret.
- 4Surpresas de versão do Claude Code: a tag claude-code:1.0 fixa o script de instalação, não a CLI — a versão mais recente é instalada e se autoatualiza dentro do contêiner. Para congelar uma versão, instale-a no Dockerfile com npm install -g @anthropic-ai/claude-code@X.Y.Z.
- 5"Is Docker running?" ou um "Opening remote" travado: o motor não está acessível — inicie o Docker Desktop (ou o daemon) e tente de novo. Se o --dangerously-skip-permissions se recusa a iniciar, o contêiner está rodando como root; defina remoteUser como um usuário sem root, como "vscode". Organizações podem desativar o modo bypass por completo via managed-settings.json em /etc/claude-code.
Reconstruir é a retentativa universal: paleta de comandos → "Dev Containers: Rebuild Container" relê o devcontainer.json e reexecuta os features após qualquer edição. Se um rebuild se comporta diferente de um clone fresco, apague o contêiner e reabra — imagens e volumes nomeados sobrevivem à exclusão.