Claude Code em um devcontainer

Um ambiente de desenvolvimento isolado (sandbox) para executar o Claude Code com bypassPermissions ativado com segurança. Criado na Trail of Bits para fluxos de trabalho de auditoria de segurança.

Por que usar isso?

Executar o Claude com bypassPermissions na sua máquina host é arriscado — ele pode executar qualquer comando sem confirmação. Este devcontainer fornece isolamento de sistema de arquivos para que você obtenha os benefícios de produtividade do Claude irrestrito sem arriscar seu sistema host.

Projetado para:

• Auditorias de segurança: Revise o código do cliente sem arriscar seu host
• Repositórios não confiáveis: Explore bases de código desconhecidas com segurança
• Trabalho experimental: Deixe o Claude modificar código livremente em isolamento
• Engajamentos multi-repositório: Trabalhe em vários repositórios relacionados

Pré-requisitos

• Runtime Docker (um de):

  • Docker Desktop - certifique-se de que está em execução
  • OrbStack
  • Colima: brew install colima docker && colima start

• Para fluxos de trabalho em terminal (instalação única):

  root@kitploit:~

  npm install -g @devcontainers/cli
  git clone https://github.com/trailofbits/claude-code-devcontainer ~/.claude-devcontainer
  ~/.claude-devcontainer/install.sh self-install
  

# Stop and delete current VM (removes containers/images)
colima stop && colima delete

# Start with optimized settings
colima start \
  --cpu 4 \
  --memory 8 \
  --disk 100 \
  --vm-type vz \
  --vz-rosetta \
  --mount-type virtiofs

Início Rápido

Escolha o padrão que se adequa ao seu fluxo de trabalho:

Padrão A: Contêiner por Projeto (Isolado)

Cada projeto tem seu próprio contêiner com volumes independentes. Melhor para revisões pontuais, repositórios não confiáveis, ou quando você precisa de isolamento entre projetos.

Terminal:

git clone <untrusted-repo>
cd untrusted-repo
devc .          # Installs template + starts container
devc shell      # Opens shell in container

VS Code / Cursor:

1. Instale a extensão Dev Containers:

   • VS Code: ms-vscode-remote.remote-containers
   • Cursor: anysphere.remote-containers

2. Configure o devcontainer (escolha um):

   root@kitploit:~

   # Option A: Use devc (recommended)
   devc .
   
   # Option B: Clone manually
   git clone https://github.com/trailofbits/claude-code-devcontainer .devcontainer/
   

3. Abra a pasta do seu projeto no VS Code, então:

   • Pressione Cmd+Shift+P (Mac) ou Ctrl+Shift+P (Windows/Linux)
   • Digite "Reopen in Container" e selecione Dev Containers: Reopen in Container

Padrão B: Contêiner de Workspace Compartilhado (Agrupado)

Um diretório pai contém a configuração do devcontainer, e você clona vários repositórios dentro. Volumes compartilhados entre todos os repositórios. Melhor para engajamentos de clientes, repositórios relacionados, ou trabalho contínuo.

# Create workspace for a client engagement
mkdir -p ~/sandbox/client-name
cd ~/sandbox/client-name
devc .          # Install template + start container
devc shell      # Opens shell in container

# Inside container:
git clone <client-repo-1>
git clone <client-repo-2>
cd client-repo-1
claude          # Ready to work

Autenticação Baseada em Token (Headless)

Para servidores headless ou para pular o assistente de login interativo:

claude setup-token                          # run on host, one-time
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
devc rebuild                                # rebuilds with token

O token é encaminhado para o contêiner. Em cada criação de contêiner, post_install.py executa um handshake de autenticação único para que o claude inicie sem o assistente de login.

Isso contorna o assistente de integração interativo do Claude Code que sempre aparece em contêineres, mesmo com credenciais válidas (#8938).

Se você não definir um token, o fluxo de login interativo funciona como antes.

Comandos Auxiliares da CLI

devc .              Instala o template + inicia o contêiner no diretório atual
devc up             Inicia o devcontainer
devc rebuild        Reconstrói o contêiner (preserva volumes persistentes)
devc destroy [-f]   Remove contêiner, volumes e imagem para o projeto atual
devc down           Para o contêiner
devc shell          Abre shell zsh no contêiner
devc exec CMD       Executa comando dentro do contêiner
devc upgrade        Atualiza o Claude Code no contêiner
devc mount SRC DST  Adiciona um bind mount (host → contêiner)
devc sync [NAME]    Sincroniza sessões do Claude Code de devcontainers para o host
devc template DIR   Copia arquivos do devcontainer para o diretório
devc self-install   Instala devc em ~/.local/bin

Nota: Use devc destroy para limpar os recursos Docker de um projeto. Remover contêineres manualmente (ex.: docker rm) deixará volumes e imagens órfãos que devc destroy não conseguirá encontrar.

Sincronização de Sessão para /insights

O comando /insights do Claude Code analisa seu histórico de sessão, mas ele lê apenas de ~/.claude/projects/ no host. Sessões dentro de volumes do devcontainer são invisíveis para ele.

devc sync copia logs de sessão de todos os devcontainers (em execução e parados) para o host para que /insights possa incluí-los:

devc sync              # Sync all devcontainers
devc sync crypto       # Filter by project name (substring match)

Devcontainers são descobertos automaticamente via labels Docker — não é necessário saber nomes ou IDs de contêineres. A sincronização é incremental, então é seguro executar repetidamente.

Compartilhamento de Arquivos

VS Code / Cursor

Arraste arquivos do seu host para o painel Explorer do VS Code — eles são copiados para /workspace/ automaticamente. Nenhuma configuração necessária.

Terminal: devc mount

Para disponibilizar um diretório do host dentro do contêiner:

devc mount ~/drop /drop           # Read-write
devc mount ~/secrets /secrets --readonly

Isso adiciona um bind mount ao devcontainer.json e recria o contêiner. Montagens existentes são preservadas em atualizações do devc template.

Dica: Uma "pasta de transferência" compartilhada é útil para passar arquivos sem montar todo o diretório home.

Nota de segurança: Evite montar grandes diretórios do host (ex.: $HOME). Cada caminho montado é gravável de dentro do contêiner a menos que --readonly seja especificado, o que compromete o isolamento de sistema de arquivos que este projeto fornece.

Isolamento de Rede

Por padrão, os contêineres têm acesso total à rede de saída. Para maior segurança, use iptables para restringir o acesso à rede.

Quando Ativar o Isolamento de Rede

• Revisar código que pode conter dependências maliciosas
• Auditar software com telemetria ou comportamento de phone-home
• Isolamento máximo para revisões altamente sensíveis

Exemplo: Claude + GitHub + Registros de Pacotes

sudo iptables -A OUTPUT -d api.anthropic.com -j ACCEPT
sudo iptables -A OUTPUT -d github.com -j ACCEPT
sudo iptables -A OUTPUT -d raw.githubusercontent.com -j ACCEPT
sudo iptables -A OUTPUT -d registry.npmjs.org -j ACCEPT
sudo iptables -A OUTPUT -d pypi.org -j ACCEPT
sudo iptables -A OUTPUT -d files.pythonhosted.org -j ACCEPT
sudo iptables -A OUTPUT -o lo -j ACCEPT
sudo iptables -A OUTPUT -j DROP

Trade-offs

• Bloqueia gerenciadores de pacotes a menos que você coloque registros na lista de permissões
• Pode quebrar ferramentas que exigem acesso à rede
• A resolução de DNS ainda funciona (considere bloquear se for paranoico)

Modelo de Ameaça

A principal ameaça que este projeto aborda é Claude Code executando comandos arbitrários na sua máquina host. Quando bypassPermissions está ativado, o Claude executa comandos de shell, instala pacotes e modifica arquivos sem confirmação. Em uma máquina host, isso significa que ele pode modificar sua configuração de shell, rm -rf fora do diretório do projeto, ou abusar de credenciais armazenadas localmente. O devcontainer confina tudo isso a um contêiner descartável onde o raio de explosão é limitado a /workspace.

O contêiner inclui ferramentas de desenvolvimento comuns para que você possa fazer todo o trabalho de desenvolvimento dentro dele - não apenas executar o Claude. O fluxo de trabalho pretendido é: clonar um repositório, iniciar o devcontainer e trabalhar inteiramente dentro dele. Se o seu projeto precisar de runtimes ou ferramentas adicionais além do que está incluído, adicione-os ao Dockerfile para uso repetido ou instale-os ad-hoc com devc exec.

Para os limites específicos do que é e não é isolado, veja Modelo de Segurança abaixo. Uma nuance que vale a pena destacar: o runtime do devcontainer encaminha automaticamente o socket do agente SSH do seu host (SSH_AUTH_SOCK) para o contêiner. Isso permite que o código dentro do contêiner autentique como você via SSH (ex.: git push), mas o material da chave privada real permanece no host e nunca é exposto ao contêiner.

Modelo de Segurança

Este devcontainer fornece isolamento de sistema de arquivos mas não um sandbox completo.

Em sandbox: Sistema de arquivos (arquivos do host inacessíveis), processos (isolados do host), instalações de pacotes (permanecem no contêiner)

Não em sandbox: Rede (saída completa por padrão — veja Isolamento de Rede), identidade git (~/.gitconfig montado somente leitura), agente SSH (socket encaminhado, chaves permanecem no host), socket Docker (não montado por padrão)

O contêiner configura automaticamente o modo bypassPermissions — o Claude executa comandos sem confirmação. Isso seria arriscado em uma máquina host, mas o próprio contêiner é o sandbox.

Detalhes do Contêiner

Os volumes são armazenados fora do contêiner, então seu histórico de shell, configurações do Claude e login gh persistem mesmo após devc rebuild. O ~/.gitconfig do host é montado como somente leitura para identidade git.

Solução de Problemas

"devcontainer CLI não encontrado"

npm install -g @devcontainers/cli

Contêiner não inicia

1. Verifique se o Docker está em execução
2. Tente reconstruir: devc rebuild
3. Verifique os logs: docker logs $(docker ps -lq)

Autenticação do GitHub CLI não persiste

O volume gh pode precisar de correção de propriedade:

sudo chown -R $(id -u):$(id -g) ~/.config/gh

Python/uv não funcionando

Python é gerenciado via uv:

uv run script.py              # Run a script
uv add package                # Add project dependency
uv run --with requests py.py  # Ad-hoc dependency

Desenvolvimento

Construa a imagem manualmente:

devcontainer build --workspace-folder .

Teste o contêiner:

devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . zsh