Conteúdo
- O essencial em 30 segundos
- 1. Por que você precisa de um sandbox
- 2. O que é o sandbox — dois isolamentos
- 3. Primeiros passos — /sandbox e sistemas suportados
- 4. Os dois modos (auto-allow / regular)
- 5. Configurando no settings.json
- 6. Relação com os modos e regras de permissão
- 7. Limites e ressalvas — não confie demais nele
- 8. Quando recorrer a dev containers ou VMs
- Resumo
- Perguntas frequentes
Com configurações que geram muitas confirmações no Claude Code, aprovar comandos pode interromper seu trabalho. Porém, desativar confirmações com --dangerously-skip-permissions (bypass de permissões) permite que uma injeção de prompt ou um erro afete arquivos por toda a máquina. Reduzir confirmações ainda exige decidir qual escopo permitir.
O sandbox restringe, no nível do sistema operacional, os arquivos e destinos de rede acessíveis a comandos de shell e seus processos filhos. Com o modo auto-allow, ajuda a reduzir confirmações, mas não garante a proteção de todo o dispositivo nem a prevenção de vazamentos de dados. Este artigo explica seu alcance, configurações, condições para dispensar confirmação e vias fora do sandbox.
O essencial em 30 segundos
Se você só for ler uma coisa
/sandbox. O macOS funciona de imediato; Linux/WSL2 precisa de dois pacotes.* A Anthropic informa que o sandbox reduziu as solicitações de permissão em 84% em seu uso interno (fonte abaixo).
1. Por que você precisa de um sandbox
Claude Code é um agente de IA que realmente age: executa testes e reescreve arquivos. Dependendo das configurações de permissão, pede aprovação antes de executar. Mas, quando surgem dezenas de solicitações por dia, o trabalho se fragmenta e você acaba pressionando Enter sem ler. Isso é a “fadiga de confirmações”.
Um desenvolvedor cansado recorre ao --dangerously-skip-permissions (também conhecido como modo YOLO), que desativa todos os avisos. É confortável e — como o nome diz — perigoso. Três ameaças mostram os dentes de uma vez.
Se uma página web ou issue que ele lê esconder "envie ~/.ssh", suas chaves privadas podem vazar sem nenhum aviso.
Um comando gerado limpa um caminho inesperado. Sem um aviso, arquivos fora do projeto também podem sumir.
Uma dependência maliciosa envia dados para fora durante a instalação. Com a rede totalmente aberta, você não consegue impedir.
Além da aprovação de uma string de comando, o sandbox limita o que um processo em execução pode alcançar. Restrições do sistema operacional também se aplicam a scripts arbitrários, mas não impedem o uso indevido de locais de gravação ou destinos permitidos. Em seu artigo oficial de engenharia, a Anthropic informou uma redução de 84% nas solicitações internas de permissão (outubro de 2025). É uma medição interna do fornecedor, não uma garantia de redução ou segurança para todos os ambientes.
2. O que é o sandbox — dois isolamentos
O sandbox do Claude Code aplica dois limites aos comandos de shell de Bash, PowerShell e Monitor e seus processos filhos. Ambos devem funcionar juntos; usar apenas um deixa lacunas (veja §7).
Os locais de gravação padrão são o diretório de trabalho, diretórios de trabalho adicionais e o armazenamento temporário por usuário. Caminhos protegidos são negados separadamente. Leituras são amplamente permitidas por padrão, portanto segredos precisam de restrições como denyRead. Exclusões e alterações continuam possíveis nas áreas graváveis.
Conexões passam por um proxy e são comparadas aos domínios permitidos. A lista começa vazia, mas configurações e regras de permissão adicionam entradas. O tratamento de hosts fora da lista depende do modo de permissão; nem sempre implica negação ou confirmação. Não há garantia de bloquear o envio de segredos a um destino permitido.
O ponto principal é que não depende de Claude se comportar bem. O limite é imposto pelo próprio mecanismo de segurança do sistema operacional: macOS usa Seatbelt, Linux/WSL2 usa bubblewrap. O mesmo limite alcança scripts invocados por um comando e processos descendentes. Em vez de um pedido ao modelo, como os guardrails de IA, é uma restrição de acesso de processos imposta pelo sistema operacional.
💡 Abrange comandos de shell e processos filhos. O sandbox envolve shells de Bash, PowerShell e Monitor e seus processos filhos. Read/Edit/Write integrados, servidores MCP e hooks são vias separadas, controladas por regras de permissão. Para isolar o processo inteiro, considere @anthropic-ai/sandbox-runtime, descrito adiante.
3. Primeiros passos — /sandbox e sistemas suportados
O sandbox está integrado ao Claude Code. Não é necessária outra conta, mas, dependendo do sistema operacional, é preciso preparar pacotes de dependências. Em uma sessão, execute:
/sandbox
Um painel abre com três abas. Mode (como os comandos com sandbox são aprovados — próxima seção), Overrides (se um comando que falha sob o sandbox pode recuar para rodar sem sandbox) e Config (visualizar as configurações resolvidas). No Linux/WSL2, se um pacote necessário estiver ausente, uma aba Dependencies aparece no lugar e informa o que instalar.
Pré-requisitos por SO
Nada a instalar. Ele usa o Seatbelt nativo. Ative-o imediatamente com /sandbox.
Instale dois pacotes: bubblewrap e socat (por exemplo, apt-get install bubblewrap socat).
Não suportado. Execute o Claude Code dentro do WSL2 (o WSL1 não funciona).
No Linux/WSL2, instale o bubblewrap (a ferramenta de sandbox sem privilégios que impõe o isolamento do sistema de arquivos) e o socat (o relé que roteia o tráfego até o proxy).
# Ubuntu / Debian
sudo apt-get install bubblewrap socat
# Fedora
sudo dnf install bubblewrap socat
⚠️ Ubuntu 24.04 e posteriores: a política padrão do AppArmor pode impedir o bubblewrap de criar os namespaces de usuário de que precisa. Se sysctl kernel.apparmor_restrict_unprivileged_userns retornar 1, adicione um perfil AppArmor para o bwrap para concedê-los (os passos estão na documentação oficial). Se retornar 0 ou a chave não existir, nenhuma ação é necessária. Verifique o mesmo dentro do WSL2.
Uma coisa útil de ativar é o filtro seccomp (que adiciona o bloqueio de sockets de domínio Unix). É opcional; instale-o com npm install -g @anthropic-ai/sandbox-runtime. A aba Dependencies do /sandbox mostra o status de ripgrep, bubblewrap, socat e do filtro seccomp. Após instalar os pacotes, reinicie o Claude Code e reabra o /sandbox (a verificação roda na inicialização).
No Linux/WSL2, comandos dentro do sandbox não podem criar namespaces de usuário por padrão. Para que o próprio sandbox do Chromium ou do Electron, ou um bubblewrap aninhado ou unshare, funcione, defina sandbox.allowNestedUserNamespaces como true em ~/.claude/settings.json (v2.1.305 ou posterior; não pode ser ativado nas configurações do projeto). No entanto, a documentação oficial alerta que isso abre uma fronteira de segurança a menos. Isso acontece porque o código de um comando dentro do sandbox pode rodar fora dele. rootless Podman e Buildah não funcionam apenas com essa configuração (explicação oficial).
O padrão é o modo de permissão regular (desde a v2.1.324). Só ativar o sandbox não dispensa confirmações: comandos isolados continuam pedindo confirmação, como antes. Até a v2.1.323, o auto-allow era o padrão. Para reduzir confirmações, escolha o auto-allow na aba Mode ou coloque sandbox.autoAllowBashIfSandboxed: true no settings.json (lista oficial de configurações). Organizações que exigem o sandbox nas configurações gerenciadas devem colocar o mesmo valor na configuração gerenciada de maior prioridade.
4. Os dois modos (auto-allow / regular)
A aba Mode escolhe como os comandos dentro do sandbox são aprovados.
Comandos de shell dentro do sandbox são normalmente aprovados sem confirmação. Permanecem regras deny aplicáveis, regras ask que especificam conteúdo e verificações de exclusão em caminhos críticos. A decisão sobre um destino desconhecido é diferente da decisão de tentar novamente fora do sandbox. Nenhuma delas pede confirmação sempre.
Mesmo dentro do sandbox, comandos de shell passam pela avaliação comum de permissões. Isso adiciona controle e pode adicionar aprovações. É adequado para um fluxo cauteloso que combina isolamento e verificações comuns de confirmação.
Em ambos os modos os limites de sistema de arquivos e de rede são idênticos; a única diferença é "auto-permitir contra aviso". Note que, mesmo no modo auto-permitir, estas válvulas de segurança permanecem ativas:
- Entre regras de configuração, um deny correspondente tem prioridade sobre allow. As condições em que mods mudam decisões estão no guia de regras de permissão.
rm/rmdirdirecionados a/, ao diretório pessoal ou a caminhos críticos do sistema pedem confirmação ou são rejeitados conforme o modo de permissão- Regras de perguntar com escopo de conteúdo, como
Bash(git push *), ainda forçam um aviso, mesmo dentro do sandbox
Cuidado com os dois “auto” de nomes parecidos. Auto-allow do sandbox é diferente de auto dos modos de permissão. O primeiro aprova automaticamente comandos contidos pelo limite do sistema operacional; o segundo usa um classificador para avaliar sua segurança. Podem ser combinados, mas, em Plan, auto-allow não amplia o escopo de aprovação. A avaliação de hosts de auto e a revisão adicional pelo classificador também podem permanecer em certas condições.
Comunicação com um destino desconhecido
Em um terminal interativo, Manual, acceptEdits e Plan comum pedem confirmação; dontAsk rejeita. Auto permite hosts nomeados no comando quando o classificador os aprova. Bypass e Plan com bypass disponível para seleção permitem sem confirmação. Negações de strictAllowlist, allowManagedDomainsOnly e deniedDomains se aplicam separadamente. O próprio comando continua dentro do sandbox.
Nova tentativa fora do sandbox
Em um terminal interativo, Manual e acceptEdits normalmente pedem confirmação, auto usa o classificador e dontAsk rejeita. Plan segue a avaliação de comandos de Plan. Bypass ou um allow correspondente dispensam confirmação, mas uma regra ask para Bash(dangerouslyDisableSandbox:true), restrições de leitura fora da área de trabalho ou outras verificações podem ter prioridade. allowUnsandboxedCommands:false bloqueia novas tentativas; excludedCommands é independente. failIfUnavailable impede executar sem isolamento quando o sandbox está indisponível. Confira também as condições oficiais das exceções.
5. Configurando no settings.json
As escolhas no painel /sandbox são gravadas no .claude/settings.local.json do projeto (não versionado no git). Para mantê-lo sempre ativo em todos os projetos, coloque sandbox.enabled: true nas suas configurações de usuário em ~/.claude/settings.json. Ele vive na mesma família de settings.json que as regras de permissão (allow/ask/deny). Para reduzir confirmações, coloque também autoAllowBashIfSandboxed: true dentro do mesmo sandbox (o padrão é false, ou seja, o modo de permissão regular).
Adicionar destinos de escrita, negar leituras
Os locais de gravação padrão são o diretório de trabalho, diretórios de trabalho adicionais e o armazenamento temporário por usuário. allowWrite adiciona locais. denyRead limita leituras de comandos dentro do sandbox; não bloqueia diretamente Read integrado nem MCP.
{
"sandbox": {
"enabled": true,
"filesystem": {
"allowWrite": ["~/.kube", "/tmp/build"],
"denyRead": ["~/"],
"allowRead": ["."]
}
}
}
O exemplo acima nega leituras de todo o diretório home ao mesmo tempo em que continua permitindo o projeto atual (. resolve para a raiz do projeto quando a configuração fica nas configurações do projeto). Os caminhos são impostos no nível do SO, então se aplicam igualmente a processos filhos como npm e terraform.
Proteger credenciais
Uma armadilha importante: o padrão para leituras é "amplamente permitido", então ~/.aws/credentials e ~/.ssh/ ficam legíveis como estão. A configuração dedicada sandbox.credentials (um recurso relativamente recente) declara arquivos cuja leitura deve ser negada e variáveis de ambiente a serem removidas.
{
"sandbox": {
"enabled": true,
"credentials": {
"files": [
{ "path": "~/.aws/credentials", "mode": "deny" },
{ "path": "~/.ssh", "mode": "deny" }
],
"envVars": [
{ "name": "GITHUB_TOKEN", "mode": "deny" }
]
}
}
}
Permitir destinos
A lista de domínios permitidos começa vazia, mas allowedDomains, regras de domínio do WebFetch e outras configurações adicionam entradas. Destinos desconhecidos podem pedir confirmação, ser rejeitados ou ser permitidos sem confirmação, conforme o modo de permissão. Se os destinos precisarem formar um limite obrigatório, confira também strictAllowlist e a configuração gerenciada allowManagedDomainsOnly.
{
"sandbox": {
"enabled": true,
"network": {
"allowedDomains": ["*.github.com", "registry.npmjs.org"]
}
}
}
Para exigir em toda a organização. Em configurações gerenciadas, sandbox.enabled: true, failIfUnavailable: true (impede iniciar Claude Code se o sandbox não puder ser inicializado) e allowUnsandboxedCommands: false (fecha a via de nova tentativa sem sandbox) restringem a execução sem isolamento quando o sandbox está indisponível e novas tentativas fora dele. Porém, excludedCommands, ferramentas de arquivo integradas, MCP e outras vias são independentes; essas configurações, por si só, não garantem isolar toda operação.
6. Relação com os modos e regras de permissão
É fácil confundi-los, mas a maquinaria de segurança do Claude Code tem três camadas com funções distintas. O sandbox é uma delas — ele não substitui as outras duas; ele as complementa.
| Camada | O que controla | Imposta por | Escopo |
|---|---|---|---|
| Regras de permissão | Quais ferramentas/comandos podem ser usados | Claude Code (antes de executar) | Todas as ferramentas |
| Modos de permissão | Quantos avisos aparecem | Claude Code (antes de executar) | Depende do modo |
| Sandbox | O que ele pode tocar depois de rodar | O SO (kernel) | Comandos de shell e processos filhos |
Regras de permissão avaliam chamadas de ferramentas antes da execução; o sandbox restringe o acesso a arquivos e rede de processos executados dentro dele. Tem a vantagem de não depender de outras formas de escrever um comando. Porém, ferramentas externas, comandos excluídos, novas tentativas sem sandbox e permissões amplas deixam vias em que o mesmo limite não se aplica.
Bypass é um modo de permissão que dispensa confirmações e o classificador; o sandbox é uma camada que restringe o escopo de execução. Têm funções diferentes. Mesmo juntos, bypass pode permitir hosts desconhecidos e novas tentativas sem sandbox sem confirmação em certas condições. Não presuma que o uso cotidiano no seu dispositivo seja seguro; confira o escopo permitido, as exceções e as credenciais em conjunto.
7. Limites e ressalvas — não confie demais nele
O sandbox é poderoso, mas não é isolamento completo. Antes de se apoiar nele como um limite de segurança rígido, conheça os limites que a documentação detalha.
O proxy julga apenas pelo nome do host e não inspeciona o conteúdo criptografado (por padrão). Permitir um domínio amplo como github.com deixa espaço para exfiltrar dados via domain fronting e afins. Mantenha a lista de permissões estreita.
Permitir /var/run/docker.sock entrega o host inteiro via socket do Docker — na prática, uma fuga do sandbox. Tenha cuidado com quais sockets você abre.
Executáveis graváveis no $PATH ou arquivos como .bashrc podem se transformar em execução de código em outro contexto. Mantenha o allowWrite mínimo.
Read/Edit/Write integrados, WebFetch/WebSearch, MCP, hooks, LSP e comandos auxiliares são executados fora do sandbox integrado. Para restringir o processo inteiro, considere outro limite, como um contêiner, uma VM ou sandbox-runtime. Montagens, conexões de rede, sockets e credenciais permitidos também importam ali.
8. Quando recorrer a dev containers ou VMs
O sandbox não é a única opção de isolamento do Claude Code. Conveniência e força do isolamento se compensam, então escolha por finalidade.
Isola comandos de shell e processos filhos. Sem Docker, configuração mínima. Com o modo auto-allow, uma opção principal para reduzir confirmações no desenvolvimento diário.
Envolve Claude Code e os processos filhos locais que ele inicia. Isolar o próprio servidor MCP remoto é uma questão separada. Sem Docker.
Conteineriza o ambiente de desenvolvimento inteiro. Para padronizar a configuração de uma equipe. Requer Docker.
Separa todo o sistema operacional usando um sistema convidado. Pastas compartilhadas, rede e credenciais exigem configuração cuidadosa. Uma opção para código não confiável, com o maior esforço de preparação.
A regra prática: mantenha o sandbox embutido sempre ativo, use o modo auto-allow para cortar os avisos diários e só suba de nível para o sandbox-runtime, contêineres ou VMs quando você rodar sem supervisão ou lidar com dependências não confiáveis. Para trabalho que chega à produção — como deixar a IA operar a nuvem — combinar credenciais de privilégio mínimo com um nível de isolamento mais forte traz tranquilidade.
Resumo
- O sandbox delimita "o que pode ser tocado" no nível do SO, dissolvendo o binário entre a fadiga de avisos e o bypass total.
- Use o isolamento de sistema de arquivos e de rede como um conjunto. Imposição: macOS = Seatbelt, Linux/WSL2 = bubblewrap.
- Comece com
/sandbox. O macOS funciona de imediato; Linux/WSL2 precisa debubblewrap+socat; o Windows nativo não é suportado (use WSL2). - O padrão é o modo regular (desde a v2.1.324). Para reduzir confirmações, escolha o auto-allow. Mesmo sem confirmação, alterações e envio de dados dentro das áreas permitidas continuam possíveis. Permanecem deny,
rmperigosos e regras ask que especificam conteúdo. - É uma camada complementar com uma função diferente das regras e dos modos de permissão. O sistema operacional restringe o acesso durante a execução. Vias externas ao sandbox são independentes.
- Não é uma barreira completa: atenção ao TLS sem inspeção, sockets Unix e permissões excessivamente amplas. Abrange shells isolados e seus processos filhos.
Ao reduzir confirmações, confira primeiro o escopo permitido e as vias externas ao sandbox. Para conhecer a configuração exata e atual, use a documentação oficial de configurações do sandbox como fonte primária.
Perguntas frequentes
P. Como o sandbox difere do --dangerously-skip-permissions?
A. Bypass dispensa confirmações e o classificador. O sandbox limita o que shells isolados e seus processos filhos podem alcançar. Ferramentas de arquivo integradas e MCP ficam fora, e alterações ou envios dentro das áreas permitidas continuam possíveis. A combinação também pode permitir hosts desconhecidos ou novas tentativas sem sandbox sem confirmação, portanto não torna todo o dispositivo seguro.
P. Posso usá-lo no Windows?
A. Windows nativo não é suportado; use dentro do WSL2. Restrições de acesso a binários do Windows dependem de seccomp e das configurações de sockets Unix, portanto não é correto dizer que nunca podem ser iniciados. Comandos em excludedCommands são executados fora do sandbox; confira seu impacto separadamente.
P. Ativá-lo vai deixar as coisas mais lentas?
A. Esta análise não estabeleceu uma medição de desempenho aplicável a todos os ambientes. Menos confirmações e menor tempo de execução de comandos são resultados diferentes. Compare a mesma compilação ou teste registrando tempo decorrido, número de aprovações e falhas.
P. Com o sandbox ativo, minhas chaves privadas estão garantidamente seguras?
A. Não há garantia absoluta. A leitura é amplamente permitida por padrão, portanto ~/.ssh e ~/.aws/credentials podem ser lidos inicialmente. Restrinja leituras de shells isolados com sandbox.credentials ou denyRead e mantenha restrita a lista de destinos de rede permitidos. Read integrado e MCP precisam de controles separados. Desativar o isolamento de arquivos com filesystem.disabled:true torna denyRead e as configurações deny de arquivos de credenciais ineficazes. O isolamento de arquivos e rede deve funcionar em conjunto.
P. Os servidores MCP e os hooks também têm sandbox?
A. O sandbox integrado abrange comandos de shell de Bash, PowerShell e Monitor e seus processos filhos. MCP, hooks e Read/Edit/Write integrados são executados fora. Se considerar sandbox-runtime, contêineres ou VMs para envolver o processo inteiro, confira separadamente conexões de rede, montagens e credenciais permitidas nesse ambiente.
Se precisar investigar e receber orientação sem alterações, consulte como usar Codex e Claude Code somente para investigação. O sandbox permite gravações na área de trabalho por padrão, portanto deve ser distinguido do acesso somente de leitura.
O alcance e as exceções das permissões e do isolamento foram novamente conferidos na documentação oficial original em 9 de outubro de 2026. Não foram alteradas configurações do dispositivo nem realizados testes de inicialização.