Tutorial do sandbox do Claude Code: guia de configuração do /sandbox
Rode /sandbox, escolha auto-allow e ponha cada comando bash dentro de um perímetro imposto pelo sistema operacional — com as chaves de configuração reais, não folclore. 12 passos verificados contra a documentação oficial.
TL;DR
- O comando /sandbox abre um painel com as abas Mode, Overrides e Config. O modo auto-allow roda comandos bash isolados sem pedido de permissão; regular permissions mantém cada confirmação.
- O perímetro é imposto pelo kernel, não por avisos: Seatbelt no macOS, bubblewrap no Linux e no WSL2. Windows nativo e WSL1 não são suportados.
- Comandos isolados só podem escrever no seu diretório de trabalho, num diretório temporário por usuário e nos caminhos do --add-dir. O tráfego de rede passa por um proxy que não pré-permite nenhum domínio.
- Leituras não são bloqueadas por padrão — ~/.ssh e ~/.aws continuam legíveis até você adicionar regras sandbox.credentials. O diálogo Sandbox do VS Code chegou na v2.1.280.
Claude Code Sandbox Explained
Canal:The Art of Vibe Coding4:29
How auto mode works with Claude Code
Canal:Claude5:42
Configure the sandboxed Bash tool (official docs)
Docs:code.claude.com
O primeiro vídeo é uma peça de motion graphics — os quadros dele nesta página são ilustrações estilizadas, não capturas de tela, e algumas afirmações dele são corrigidas nos passos abaixo (credenciais são legíveis por padrão; as chaves de configuração de exemplo do vídeo não batem com as reais). O segundo vídeo é a gravação oficial da Anthropic; só o terminal real e a UI de configurações dele são usados.
Fatos conferidos com code.claude.com/docs/en/sandboxing e o CHANGELOG do anthropics/claude-code (v2.1.280–2.1.283). As capturas citam trechos breves das gravações para comentário.
Configure o sandbox do Claude Code em 12 passos
Entenda o perímetro
- 1
Reconheça o problema da fadiga de aprovação
Sem sandbox, cada comando sugerido para num y/n: npm install, git status, e o próximo. A Anthropic mediu que 97% dos pedidos de permissão do Claude Code são aprovados — e é exatamente por isso que o sandbox tira a checagem de cada comando e a leva para um perímetro que você configura uma vez.
Uma recriação do loop de y/n por comando que o sandbox substitui — apertar Enter 47 vezes e parar de ler.Ver em 0:22 - 2
Inicie o Claude Code numa plataforma suportada
Abra uma sessão no seu projeto. O isolamento vem embutido no macOS, onde o Seatbelt acompanha o sistema e nada precisa ser instalado. No Linux e no WSL2, instale primeiro bubblewrap e socat com o seu gerenciador de pacotes. Windows nativo e WSL1 não são suportados — usuários de Windows rodam o Claude Code dentro de uma distro WSL2.
Uma sessão em ~/Documents/code/acme — esse diretório de trabalho é o que o sandbox tratará como gravável.Ver em 0:35 - 3
Rode /sandbox e leia o painel
Digite /sandbox na sessão. O painel tem três abas: Mode (como comandos isolados são aprovados), Overrides (se comandos que falham podem tentar de novo fora do sandbox — a configuração allowUnsandboxedCommands) e Config (as configurações de sandbox totalmente resolvidas). O Linux acrescenta uma aba Dependencies listando o que faltar, como bubblewrap, socat ou o filtro seccomp opcional. Desde a v2.1.281 dá para trocar de aba com as setas, e o VS Code ganhou um diálogo Sandbox para as mesmas configurações na v2.1.280.
Ligue-o
- 4
Escolha auto-allow ou permissões normais
Na aba Mode, o auto-allow roda comandos isolados sem perguntar, enquanto regular permissions mantém as perguntas mesmo para comandos isolados. A escolha é salva no .claude/settings.local.json do projeto, que o Claude Code gitignora para você. Para cobrir todo projeto, defina "sandbox": undefined em ~/.claude/settings.json; para uma única sessão, passe com --settings.
O quick start de dois passos: /sandbox escolhe o modo, settings.json guarda o que é duradouro.Ver em 4:00 - 5
Saiba o que o auto-allow ainda pergunta
Auto-allow não é um botão de mudo. Regras deny explícitas sempre vencem, rm ou rmdir mirando caminhos críticos ainda pergunta, e regras ask por conteúdo como Bash(git push *) ainda forçam confirmação. Comandos que não podem rodar isolados caem no fluxo normal com um aviso intitulado "Bash command (unsandboxed)". O auto-allow também funciona independente do seu modo de permissão — bash isolado roda sem avisos até no modo Manual.
shift+tab alterna os modos de permissão — um controle separado do auto-allow do sandbox.Ver em 0:28 - 6
Veja como o SO desenha o perímetro
As restrições são impostas pelo kernel, não são sugestões educadas: o macOS usa Seatbelt, o Linux e o WSL2 usam bubblewrap. Um comando com injeção de prompt que tente ler ~/.ssh ou telefonar para casa bate na mesma parede, porque as regras prendem o processo em execução e cada filho que ele criar — o modelo não convence o kernel com conversa.
Checagens de permissão no nível da aplicação podem ser burladas; a camada do kernel não.Ver em 2:07
Sistema de arquivos, credenciais e rede
- 7
Entenda os padrões do sistema de arquivos — e a pegadinha da leitura
Comandos isolados podem escrever no diretório de trabalho e subdiretórios, num diretório temporário por usuário e em pastas adicionadas com --add-dir ou permissions.additionalDirectories. As leituras ficam abertas por padrão: o disco inteiro é legível, incluindo ~/.aws/credentials e ~/.ssh, até você bloquear. Vídeos explicativos costumam dizer que credenciais ficam “invisíveis” — a documentação é direta: protegê-las é trabalho seu, com sandbox.credentials ou regras denyRead.
Escrituras param no muro do sandbox; leituras seguem abertas até você fechá-las no próximo passo.Ver em 1:30 - 8
Proteja credenciais antes de virar autônomo
Adicione um bloco sandbox.credentials: liste arquivos como ~/.ssh ou ~/.aws/credentials com "mode": "deny", e variáveis de ambiente secretas como GITHUB_TOKEN para que sejam limpas dentro de cada comando isolado. O modo mask vai além — o comando vê um valor sentinela e o proxy do sandbox troca pelo real só nos hosts que você permitir. Regras Read do permissions.deny cobrem as ferramentas de arquivo por cima.
Regras deny para curl e leituras de .env — o mesmo arquivo de configurações carrega o seu bloco sandbox.Ver em 4:35 - 9
Permita os domínios de rede que seu stack precisa
Todo tráfego isolado passa por um proxy, e nenhum domínio é pré-permitido. Na primeira vez que um comando precisar de um host, o Claude Code pergunta; responda "Yes, and don't ask again" e ele salva uma regra allow WebFetch(domain:...) para sessões futuras. Pré-permita registros com sandbox.network.allowedDomains, bloqueie hosts específicos com deniedDomains e ative strictAllowlist para transformar a lista num teto duro em vez de uma lista de perguntas.
Downloads do registry passam pelo proxy; um postinstall telefonando para evil.com não passa.Ver em 1:51 - 10
Delimite a configuração: projeto, usuário ou gerenciada
Configurações de projeto em .claude/settings.json podem adicionar caminhos graváveis e domínios, mas não podem desativar o isolamento do sistema de arquivos nem habilitar Apple Events — essas chaves só são honradas a partir de configurações de usuário, configurações gerenciadas ou a flag --settings, então um repositório clonado não pode enfraquecer seu sandbox. Times impõem o sandbox por configurações gerenciadas com enabled, failIfUnavailable e allowUnsandboxedCommands em true/false/false.
Um arquivo de configurações gerenciadas descreve o ambiente confiável da organização — admins configuram, desenvolvedores herdam.Ver em 4:10
Verifique e corrija
- 11
Verifique com uma tarefa real
Peça um build ou uma rodada de testes. Comandos isolados executam sem perguntar, e quando algo é bloqueado, a violação nomeia o caminho ou host no resultado do comando para que Claude se adapte. Abra a aba Config do /sandbox para ler cada regra resolvida, inclusive os caminhos protegidos que nenhuma configuração pode anular. Para uma prova estrita pontual, inicie com: claude --settings 'undefined}'.
Uma tarefa digitada, zero avisos por comando — o perímetro se sustenta sem você.Ver em 0:32 - 12
Resolva as falhas de sempre
jest trava — watchman é incompatível, rode jest --no-watchman. docker falha — não pode rodar isolado, adicione "docker *" ao excludedCommands. open ou osascript falha com erro -600 no macOS — Apple Events está bloqueado a menos que allowAppleEvents seja true. git merge ou checkout falha com "unable to unlink old" — um caminho protegido ou regra denyWrite está no caminho, então aprove a nova tentativa fora do sandbox ou rode o comando você mesmo. bwrap reporta Operation not permitted dentro de um contêiner — ative enableWeakerNestedSandbox. Pipes para a área de transferência falham — use /copy em vez de pbcopy.
As configurações do sandbox que importam
O painel do /sandbox escreve o básico, mas a alavanca real está no settings.json. Estas são as chaves que a referência oficial de sandboxing documenta — todas vivem sob um bloco "sandbox" (a última sob "permissions").
- 1sandbox.enabled — desligado até você ligar. true em ~/.claude/settings.json cobre todos os seus projetos; o painel do /sandbox escreve a cópia local do projeto em .claude/settings.local.json.
- 2sandbox.autoAllowBashIfSandboxed — a chave do auto-allow, true por padrão. Defina false para manter pedidos de permissão mesmo para comandos rodando dentro do sandbox.
- 3sandbox.allowUnsandboxedCommands e sandbox.failIfUnavailable — false na primeira mata a nova tentativa dangerouslyDisableSandbox (mostrada como Strict sandbox mode na aba Overrides); true na segunda transforma dependências ausentes em falha dura de inicialização em vez de aviso.
- 4sandbox.filesystem — allowWrite para caminhos fora do projeto que as ferramentas precisam ("~/.kube", "/tmp/build"), denyRead mais allowRead para lugares secretos, e disabled (v2.1.216+) para remover a camada de sistema de arquivos mantendo o isolamento de rede.
- 5sandbox.network — allowedDomains e deniedDomains, strictAllowlist (v2.1.219+) para proibir tudo que não estiver listado, allowLocalBinding para dev servers poderem vincular portas, e tlsTerminate para mascaramento de credenciais no proxy.
- 6sandbox.credentials — entradas de files e envVars com modos deny ou mask; máscaras exigem tlsTerminate e só são honradas de fontes user, managed ou --settings. Combine com permissions.blockReadsOutsideWorkingDirectories para cortar todas as leituras fora dos seus diretórios de trabalho.
Seatbelt vs bubblewrap: diferenças por plataforma
O macOS usa Seatbelt, embutido no sistema — nada a instalar. As arestas são específicas: CLIs baseados em Go como gh, gcloud e terraform podem falhar verificação TLS sob o Seatbelt, então liste-os no excludedCommands; open, osascript e fluxos de autenticação de navegador falham com erro -600 até você definir allowAppleEvents, o que enfraquece o isolamento e é ignorado nas configurações de projeto.
Linux e WSL2 usam bubblewrap mais socat, instalados com o gerenciador de pacotes. O filtro seccomp opcional (npm install -g @anthropic-ai/sandbox-runtime) adiciona bloqueio de Unix domain sockets e é o que impede o WSL2 de deixar entrar binários do Windows. Ubuntu 24.04 e mais novos trazem uma política AppArmor que impede o bubblewrap de criar user namespaces — adicione o perfil bwrap da documentação e recarregue o AppArmor. Dentro de um contêiner sem privilégios, defina enableWeakerNestedSandbox para o bubblewrap fazer bind-mount do /proc existente.
WSL1 não é suportado de forma alguma — o bubblewrap precisa de recursos de kernel que só o WSL2 tem. A sobrecarga de desempenho é mínima, embora algumas operações de sistema de arquivos rodem um pouco mais devagar. Subagents rodam no mesmo processo da sessão pai e herdam a configuração de sandbox dele, então bash em segundo plano dentro de um agente também fica isolado.
O tratamento do sandbox ainda se move entre versões: a v2.1.280 adicionou o diálogo Sandbox do VS Code, a v2.1.281 melhorou a navegação de abas do /sandbox e a dica de allowLocalBinding para dev servers, e a v2.1.282–2.1.283 corrigiu o casamento de excludedCommands, escrituras em TMPDIR e o parsing de configurações gerenciadas. Folheie o CHANGELOG antes de confiar em comportamento de caso-limite.