Claude Code em devcontainer: ambiente isolado para a equipe

Claude Code em devcontainer: ambiente isolado para a equipe

Rodar o Claude Code em um devcontainer significa colocar o agente dentro de um contêiner definido no próprio repositório, com usuário sem privilégios, apenas o código do projeto montado, segredos fora da imagem e saída de rede limitada a uma lista de destinos. Assim, toda a equipe trabalha no mesmo ambiente e, se o agente errar ou for induzido a errar, o estrago fica contido. O contêiner não substitui permissões nem revisão humana, mas reduz bastante o que um erro consegue alcançar.

Principais pontos

• O devcontainer padroniza versões, ferramentas e configuração, e deixa o ambiente do agente versionado junto com o código.
• O isolamento útil vem de três limites: o que o agente enxerga em disco, para onde ele consegue conectar e quais credenciais existem lá dentro.
• Contêiner não é uma fronteira absoluta: ele compartilha o kernel do host, e a pasta do projeto montada continua gravável.
• A pasta .devcontainer precisa de revisão como qualquer código sensível, porque o agente pode tentar alterá-la.
• Comece com um repositório e um fluxo, teste tentativas que devem falhar e só então expanda para o resto da equipe.

O que é um devcontainer e por que usá-lo com o Claude Code?

Um devcontainer é um ambiente de desenvolvimento descrito em arquivos do repositório, normalmente o devcontainer.json e, quando necessário, um Dockerfile. Editores compatíveis e ferramentas de linha de comando leem essa descrição, constroem o contêiner e abrem o projeto dentro dele. Quem clona o repositório recebe o mesmo sistema, as mesmas versões de linguagem e as mesmas extensões.

Para o Claude Code, isso resolve dois problemas de uma vez. O primeiro é operacional: o agente deixa de depender da máquina de cada pessoa, e o famoso funciona no meu computador perde força. O segundo é de risco: um agente que lê arquivos, executa comandos e instala pacotes tem muito mais alcance quando roda direto no notebook do desenvolvedor, onde existem chaves SSH, arquivos pessoais e sessões abertas. Dentro de um contêiner, esse alcance é decidido por você.

A documentação do Claude Code traz uma configuração de referência de devcontainer, incluindo a ideia de um firewall com lista de destinos permitidos. Vale partir dela e conferir a versão atual, porque os detalhes mudam. O restante deste texto é implementação que recomendamos adaptar ao seu caso, e não uma regra oficial.

O que o contêiner protege e o que ele não protege?

Separar o que é fato do que é expectativa evita falsa sensação de segurança.

O que o contêiner ajuda a proteger:

• Arquivos pessoais e de outros projetos no computador, que simplesmente não estão montados.
• Credenciais do usuário, como chaves SSH e tokens de nuvem guardados no diretório pessoal.
• Consistência: o agente usa as ferramentas que você escolheu, nas versões que você fixou.
• Rede, se você aplicar uma política de saída restritiva.

O que ele não resolve sozinho:

• O código montado é gravável. O agente pode apagar, reescrever ou corromper arquivos do projeto, inclusive os de configuração do próprio contêiner.
• Contêineres compartilham o kernel do host. Para código hostil ou cargas de maior risco, uma máquina virtual separada é um limite mais forte.
• Dados dentro do projeto podem ser lidos pelo agente. Se houver dados pessoais reais no repositório, a LGPD continua valendo, e o isolamento não muda isso.
• Injeção de prompt: um texto malicioso em uma página, issue ou dependência pode tentar induzir o agente a agir. O guia da OWASP sobre prevenção de injeção de prompt descreve esse risco e ajuda a pensar nas defesas em camadas.

O devcontainer é uma camada. Ele funciona melhor combinado com as permissões e o sandbox descritos em Segurança no Claude Code para empresas.

Como montar o devcontainer, passo a passo

Este é um plano enxuto para um primeiro repositório. Cada passo é uma decisão, e não apenas um arquivo.

• Escolha uma imagem base mínima e fixe a versão. Evite imagens genéricas enormes, porque cada ferramenta extra é superfície a mais.
• Crie um usuário sem root e configure o devcontainer.json para usá-lo (o campo remoteUser serve para isso). O agente não precisa de administrador para editar código e rodar testes.
• Instale só o necessário: runtime da linguagem, gerenciador de pacotes, git, o próprio Claude Code e as ferramentas de teste. Use o postCreateCommand ou o Dockerfile para isso, de forma reproduzível.
• Monte apenas a pasta do projeto. Não monte o diretório pessoal, a pasta de chaves SSH nem o socket do Docker. Montar o socket do Docker equivale a dar controle do host.
• Guarde a configuração do Claude Code em um volume nomeado do contêiner, para não perder histórico e preferências a cada reconstrução e sem expor o diretório do host.
• Injete segredos em tempo de execução, e não no arquivo versionado. Use variáveis vindas de um gerenciador de segredos ou do ambiente da pessoa, com credenciais de teste e escopo mínimo.
• Aplique a política de rede (próxima seção).
• Versione tudo e proteja a pasta .devcontainer com revisão obrigatória, por exemplo via CODEOWNERS.
• Escreva testes de recusa: tentativas que devem falhar, listadas mais adiante.

Se a equipe já usa padrões compartilhados, vale empacotar instruções e comandos comuns. Veja como em Plugins do Claude Code para equipes.

Como restringir a rede do contêiner?

Por padrão, um contêiner sai para a internet inteira. Para um agente que lê conteúdo externo e executa comandos, essa é a porta mais perigosa: dados do projeto podem sair por ela, e instruções maliciosas podem entrar por ela.

A abordagem recomendada é negar por padrão e liberar uma lista curta de destinos. Em geral, essa lista inclui:

• O endereço da API do modelo que o Claude Code usa.
• Os registros de pacotes que o projeto realmente utiliza, como npm ou PyPI.
• O host do repositório de código, se o agente precisar de git remoto.
• Serviços internos de teste, quando indispensáveis.

Tudo fora da lista é bloqueado. A configuração de referência mencionada pela documentação aplica regras de firewall dentro do contêiner, o que costuma exigir capacidades de rede extras para o próprio contêiner. Isso é uma troca real: quem tem esse privilégio dentro do contêiner pode, em tese, alterar as regras. Por isso, se o seu ambiente permitir, uma alternativa mais robusta é aplicar a política fora do contêiner, em um proxy de saída ou em regras da rede do host, onde o agente não consegue mexer.

Qualquer que seja o caminho, registre quais destinos foram liberados e por quê. Cada exceção deve ter um motivo escrito. Servidores MCP também abrem conexões, então revise-os antes: veja Configurar MCP no Claude Code e, para a análise de segurança, o texto sobre como auditar um servidor MCP antes de instalar.

Como restringir arquivos e segredos?

A regra é simples: o agente só enxerga o que precisa para a tarefa.

• Monte apenas a raiz do projeto. Se o repositório for grande, considere montar só o subdiretório do serviço em que a pessoa trabalha.
• Mantenha arquivos de ambiente reais fora da pasta montada. Forneça um exemplo com valores falsos e deixe os valores verdadeiros para quem executa o sistema em outro lugar.
• Use tokens de curta duração e escopo mínimo para git e para qualquer API. Prefira credenciais que só leiam, quando a tarefa não exige escrita.
• Trabalhe em um branch próprio. Ninguém deve dar ao agente permissão de publicar direto em produção.
• Evite dados reais de clientes no repositório e nos testes. Dados anonimizados ou sintéticos reduzem o risco de privacidade e simplificam a conversa com o jurídico.
• Trate a pasta .devcontainer, os arquivos de configuração do Claude Code do projeto e os scripts de CI como áreas sensíveis, com revisão humana.

O guia da OWASP sobre riscos em aplicações com LLM lista problemas como excesso de autonomia e vazamento de informações sensíveis. Os limites acima atacam justamente esses dois pontos: menos acesso e menos credenciais disponíveis.

Posso rodar o agente sem pedir confirmação dentro do contêiner?

É uma pergunta comum, porque pedir confirmação a cada comando cansa. O Claude Code possui modos que reduzem ou removem as confirmações. Nossa leitura, que é julgamento de implementação e não regra oficial, é a seguinte:

• Só considere reduzir confirmações quando a rede estiver restrita, não houver segredos úteis dentro do contêiner e o projeto estiver em um branch descartável.
• Mesmo assim, o conteúdo do projeto continua legível pelo agente. Se a rede permitir algum destino, algo pode sair por ele.
• Para repositórios com código sensível ou dados pessoais, mantenha as confirmações e use listas de comandos permitidos.
• Qualquer ação irreversível, como apagar dados, publicar ou enviar mensagem a cliente, continua exigindo aprovação humana.

Um bom critério de decisão é perguntar: se o agente fosse induzido a fazer o pior comando possível aqui dentro, o que perderíamos? Se a resposta for apenas um branch descartável, a autonomia é razoável. Se for algo que não se recupera, não é.

Cenário ilustrativo: uma equipe pequena e um sistema interno

Cenário ilustrativo: uma empresa tem um sistema interno de agendamento, mantido por quatro pessoas. Cada uma usa um computador com configurações diferentes, e uma delas guarda chaves de produção na máquina. A empresa quer usar o Claude Code para refatorar módulos e escrever testes.

Ela cria um devcontainer com imagem fixa, usuário sem root, apenas a pasta do projeto montada e uma lista de saída com a API do modelo, o registro de pacotes e o host do git. As credenciais de produção não entram no contêiner: só um token de teste com permissão de leitura no banco de homologação. A pasta .devcontainer passa a exigir revisão de uma segunda pessoa.

Na primeira semana, a equipe roda os testes de recusa. Uma tentativa de acessar um domínio fora da lista falha. A leitura de um arquivo fora do projeto falha. O pedido de uma variável de produção volta vazio. Só então o restante da equipe adota o ambiente. O ganho não é um número: é que todos trabalham do mesmo jeito e o pior caso ficou menor e mais fácil de explicar.

Testes de recusa antes de liberar para a equipe

Um isolamento que ninguém testou é só uma suposição. Antes de entregar, confirme que estas tentativas falham:

• Conectar a um domínio que não está na lista de destinos.
• Ler arquivos do diretório pessoal do host ou chaves SSH.
• Acessar o socket do Docker ou criar contêineres a partir de dentro.
• Ler variáveis de ambiente de produção.
• Publicar direto em branch protegido.
• Alterar a pasta .devcontainer sem passar por revisão.

Repita os testes quando a imagem ou a política de rede mudar. Para acompanhar o uso sem transformar o ambiente em vigilância individual, veja como medir produtividade com IA sem virar vigilância.

Como o método mapear, limitar, pilotar e transferir se aplica

Na prática de consultoria, o caminho segue quatro etapas. Mapear: levantar quais repositórios, dados, credenciais e destinos de rede o fluxo realmente toca, e como a equipe trabalha hoje. Limitar: reduzir arquivos montados, segredos e saída de rede ao mínimo necessário, e definir o que exige aprovação humana. Pilotar: aplicar o devcontainer em um repositório real, com logs e um critério de sucesso combinado, por exemplo menos tempo para configurar a máquina de uma pessoa nova e nenhum teste de recusa falhando. Transferir: documentar o ambiente, treinar a equipe e decidir junto se expande, ajusta ou interrompe.

Perguntas frequentes

Preciso de Docker para usar o Claude Code em devcontainer? Em geral sim, porque o devcontainer depende de um mecanismo de contêiner, normalmente o Docker ou um equivalente compatível, e de um editor ou ferramenta que leia o devcontainer.json. Confira na documentação atual o que a sua ferramenta suporta. Em máquinas corporativas, valide também as políticas de TI antes de instalar.

O devcontainer substitui as permissões do Claude Code? Não. Ele limita o ambiente, enquanto as permissões controlam o que o agente pode fazer dentro dele. As duas camadas se complementam, e a revisão humana de mudanças continua necessária, principalmente em código que vai para produção.

O contêiner impede vazamento de dados do projeto? Ele reduz o risco, mas não elimina. Se algum destino de rede estiver liberado, dados legíveis pelo agente podem, em tese, sair por ele. Por isso a lista de destinos deve ser curta, o projeto não deve conter dados pessoais reais e os segredos devem ficar fora do contêiner.

Vale a pena para uma equipe pequena? Vale, porque o custo de padronizar é baixo no começo e cresce com o tempo. Um único devcontainer bem revisado evita diferenças entre máquinas e dá um ponto claro para aplicar regras de segurança. Comece por um repositório e expanda depois de validar com os testes de recusa.

Fontes

• OWASP: prevenção de injeção de prompt
• OWASP Top 10 para aplicações com LLM
• Model Context Protocol: introdução