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):

  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):

   # 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