Configurar a ferramenta Bash em sandbox

Aprenda como a ferramenta Bash em sandbox do Claude Code fornece isolamento de sistema de arquivos e rede para execução de agentes mais segura e autônoma.

O sandbox Bash permite que Claude execute a maioria dos comandos shell sem parar para pedir permissão. Em vez de aprovar cada comando, você define quais arquivos e domínios de rede os comandos podem acessar, e o sistema operacional impõe esse limite para cada comando Bash e seus processos filhos.

Esta página aborda como:

Habilitar o sandbox e escolher como os comandos em sandbox são aprovados
Configurar quais caminhos e domínios de rede os comandos podem alcançar
Combinar sandboxing com regras de permissão e modos de permissão
Impor sandboxing em toda uma organização com configurações gerenciadas

Get started

O sandbox é integrado ao Claude Code e é executado em macOS, Linux e WSL2. Windows nativo não é suportado. No Windows, execute Claude Code dentro de uma distribuição WSL2.

No macOS, não há nada para instalar: o sandboxing usa o framework Seatbelt integrado. No Linux e WSL2, o sandbox depende de dois pacotes, abordados em Set up Linux and WSL2. Mesmo que você ainda não os tenha instalado, você pode começar com /sandbox, porque seu painel mostra se algo está faltando.

Run /sandbox

Inicie uma sessão do Claude Code e execute o comando /sandbox:

/sandbox

Isso abre o painel de sandbox com três abas:

Mode: escolha como os comandos em sandbox são aprovados, abordado na próxima etapa
Overrides: escolha se os comandos que falham sob o sandbox podem voltar a ser executados sem sandbox. Esta é a configuração allowUnsandboxedCommands
Config: visualize as configurações de sandbox resolvidas

Se o painel mostrar apenas uma aba Dependencies, um pacote necessário está faltando. Instale-o conforme descrito em Set up Linux and WSL2, reinicie Claude Code e execute /sandbox novamente.

Choose a mode

Na aba Mode, selecione auto-allow ou regular permissions. Auto-allow executa comandos em sandbox sem avisar, e regular permissions mantém os prompts de permissão regulares mesmo quando os comandos estão em sandbox. Consulte Sandbox modes para saber quais comandos ainda solicitam no modo auto-allow.

Run a Bash command

Peça ao Claude para executar um comando, como uma compilação ou um conjunto de testes. Por padrão, os comandos dentro do sandbox podem escrever apenas no diretório de trabalho e no diretório temporário da sessão. Na primeira vez que um comando precisa de um novo domínio de rede, Claude Code solicita aprovação.

Comandos que não podem ser executados em sandbox voltam ao fluxo de permissão regular. Para ampliar ou estreitar esses limites, consulte Configure sandboxing.

Selecionar um modo no painel escreve nas configurações locais do seu projeto em .claude/settings.local.json, que se aplicam ao projeto atual e não são verificadas no git. Para habilitar o sandbox em todos os seus projetos, defina sandbox.enabled como true em suas configurações de usuário em ~/.claude/settings.json. Para impor sandboxing para cada desenvolvedor em uma organização, use managed settings.

Set up Linux and WSL2

No Linux e WSL2, o sandbox depende de dois pacotes:

bubblewrap: a ferramenta de sandboxing sem privilégios que impõe isolamento de sistema de arquivos
socat: o relay usado para rotear tráfego de rede através do proxy de sandbox

Instale-os com o gerenciador de pacotes da sua distribuição:

sudo apt-get install bubblewrap socat

sudo dnf install bubblewrap socat

Após a instalação, a aba Dependencies em /sandbox mostra se ripgrep, bubblewrap, socat e o filtro seccomp estão disponíveis em sua plataforma. Ripgrep é incluído no binário nativo do Claude Code. O filtro seccomp é opcional e adiciona bloqueio de socket de domínio Unix. Instale-o com npm install -g @anthropic-ai/sandbox-runtime se estiver faltando.

Quando uma dependência necessária está faltando, a aba Dependencies é a única aba mostrada até que você a instale. A verificação de dependência é executada na inicialização, portanto reinicie Claude Code após instalar pacotes para que /sandbox os detecte.

No Ubuntu 24.04 e posterior, a política padrão do AppArmor impede que bubblewrap crie os namespaces de usuário que precisa para isolamento.

Para verificar se seu ambiente impõe essa restrição, incluindo dentro do WSL2, execute `sysctl kernel.apparmor_restrict_unprivileged_userns`. Se a chave não existir ou retornar `0`, pule esta etapa. Se retornar `1`, adicione um perfil AppArmor que conceda a `bwrap` essa capacidade:

```bash theme={null}
sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF
```

O perfil se aplica apenas a `bwrap` em si, não aos comandos executados dentro do sandbox. Recarregue AppArmor para aplicá-lo:

```bash theme={null}
sudo systemctl reload apparmor
```

Notas do WSL2

Verifique sua versão do WSL com wsl -l -v do PowerShell. Se você vir Sandboxing requires WSL2, sua distribuição está executando WSL1. Atualize-a para WSL2 ou execute Claude Code sem sandboxing.

No WSL2, comandos em sandbox não podem iniciar binários do Windows como cmd.exe, powershell.exe ou qualquer coisa em /mnt/c/. WSL entrega esses para o host do Windows através de um socket Unix, que o sandbox bloqueia. Se um comando precisar invocar um binário do Windows, adicione-o a excludedCommands para que seja executado fora do sandbox.

Sandbox modes

Claude Code oferece dois modos de sandbox:

Modo auto-allow: Comandos Bash tentarão ser executados dentro do sandbox e são automaticamente permitidos sem exigir permissão. Comandos que não podem ser colocados em sandbox, como aqueles que precisam de acesso à rede para hosts não permitidos, voltam ao fluxo de permissão regular, onde Claude Code verifica suas permission rules e solicita sua aprovação para qualquer comando que essas regras não permitam.

Mesmo no modo auto-allow, o seguinte ainda se aplica:

Deny rules explícitas são sempre respeitadas
Comandos rm ou rmdir que visam /, seu diretório home ou outros caminhos críticos do sistema ainda acionam um prompt de permissão
Ask rules com escopo de conteúdo como Bash(git push *) ainda forçam um prompt mesmo para comandos em sandbox
Uma regra ask Bash simples, ou o formulário equivalente Bash(*), é ignorada para comandos executados em sandbox; ainda se aplica a comandos que voltam ao fluxo de permissão regular

Modo regular permissions: Todos os comandos Bash passam pelo fluxo de permissão regular, mesmo quando em sandbox. Isso fornece mais controle, mas requer mais aprovações.

Em ambos os modos, o sandbox impõe as mesmas restrições de sistema de arquivos e rede. A diferença é apenas se os comandos em sandbox são aprovados automaticamente ou requerem permissão explícita.

O diretório temporário da sessão é gravável dentro do sandbox por padrão, junto com o diretório de trabalho. Claude Code define $TMPDIR para este diretório para comandos em sandbox, portanto ferramentas que escrevem arquivos temporários funcionam sem configuração extra. Comandos não em sandbox herdam o $TMPDIR do seu shell inalterado, o que significa que comandos em sandbox e não em sandbox resolvem $TMPDIR para diretórios diferentes. Para passar arquivos temporários entre os dois, escreva-os no diretório de trabalho em vez disso.

Alguns comandos não podem ser executados dentro do sandbox, como ferramentas que são incompatíveis com ele ou que precisam de um host que você não permitiu. Em vez de falhar na tarefa ou exigir que você desative o sandboxing, Claude Code inclui um escape hatch: quando um comando falha por causa de restrições de sandbox, Claude analisa a falha e pode tentar novamente o comando com o parâmetro dangerouslyDisableSandbox. O comando retentado é executado fora do sandbox, portanto passa pelo fluxo de permissão regular e requer sua aprovação.

Você pode desabilitar esse escape hatch definindo "allowUnsandboxedCommands": false em suas sandbox settings. Quando desabilitado, que a aba Overrides do /sandbox mostra como Strict sandbox mode, o parâmetro dangerouslyDisableSandbox é completamente ignorado e todos os comandos devem ser executados em sandbox ou estar explicitamente listados em excludedCommands.

Configure sandboxing

Personalize o comportamento do sandbox através de seu arquivo settings.json. Consulte Settings para a referência de configuração completa.

Por padrão, comandos em sandbox podem escrever apenas no diretório de trabalho atual e no diretório temporário da sessão. Se comandos de subprocesso como kubectl, terraform ou npm precisarem escrever fora desses diretórios, use sandbox.filesystem.allowWrite para conceder acesso a caminhos específicos:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

Esses caminhos são impostos no nível do SO, portanto todos os comandos executados dentro do sandbox, incluindo seus processos filhos, os respeitam. Esta é a abordagem recomendada quando uma ferramenta precisa de acesso de escrita a um local específico, em vez de excluir a ferramenta do sandbox inteiramente com excludedCommands.

Quando o mesmo array de sistema de arquivos é definido em múltiplos settings scopes, os arrays são mesclados: caminhos de cada escopo são combinados, não substituídos.

Prefixos de caminho controlam como os caminhos são resolvidos:

Prefixo	Significado	Exemplo
`/`	Caminho absoluto da raiz do sistema de arquivos	`/tmp/build` permanece `/tmp/build`
`~/`	Relativo ao diretório home	`~/.kube` torna-se `$HOME/.kube`
`./` ou sem prefixo	Relativo à raiz do projeto para configurações de projeto, ou a `~/.claude` para configurações de usuário	`./output` em `.claude/settings.json` resolve para `<project-root>/output`

Esta sintaxe difere das Read and Edit permission rules, que usam //path para absoluto e /path para relativo ao projeto. Os caminhos do sistema de arquivos do sandbox usam convenções padrão: /tmp/build é absoluto.

Você também pode negar acesso de escrita ou leitura usando sandbox.filesystem.denyWrite e sandbox.filesystem.denyRead, e permitir novamente caminhos específicos dentro de uma região negada usando sandbox.filesystem.allowRead.

O exemplo abaixo bloqueia a leitura de todo o diretório home enquanto ainda permite leituras do projeto atual. Coloque-o no .claude/settings.json do seu projeto, porque o caminho relativo . resolve para a raiz do projeto apenas quando a configuração reside em configurações de projeto:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

O . em allowRead resolve para a raiz do projeto porque esta configuração reside em configurações de projeto. Se você colocasse a mesma configuração em ~/.claude/settings.json, . resolveria para ~/.claude em vez disso, e arquivos do projeto permaneceriam bloqueados pela regra denyRead.

Como o sandboxing funciona

Isolamento do sistema de arquivos

A ferramenta Bash em sandbox restringe o acesso ao sistema de arquivos a diretórios específicos:

Comportamento padrão de escrita: acesso de leitura e escrita ao diretório de trabalho atual e seus subdiretórios, além do diretório temporário da sessão para o qual $TMPDIR aponta
Comportamento padrão de leitura: acesso de leitura a todo o computador, exceto certos diretórios negados. Observe que esse padrão ainda permite ler arquivos de credenciais como ~/.aws/credentials e ~/.ssh/. Adicione-os a denyRead para bloqueá-los.
Acesso bloqueado: não é possível modificar arquivos fora do diretório de trabalho atual e do diretório temporário da sessão sem permissão explícita, incluindo arquivos de configuração de shell como ~/.bashrc e binários do sistema em /bin/
Git worktrees: quando o diretório de trabalho é um git worktree vinculado, o sandbox também permite escritas no diretório .git compartilhado do repositório principal para que comandos como git commit possam atualizar refs e o índice. As escritas em hooks/ e config dentro desse diretório permanecem negadas.
Configurável: defina caminhos permitidos e negados personalizados através de configurações

Você pode conceder acesso de escrita a caminhos adicionais usando sandbox.filesystem.allowWrite em suas configurações. Essas restrições são impostas no nível do SO, portanto se aplicam a todos os comandos de subprocesso, incluindo ferramentas como kubectl, terraform e npm, não apenas às ferramentas de arquivo do Claude.

Isolamento de rede

O acesso à rede é controlado através de um servidor proxy executado fora do sandbox:

Restrições de domínio: nenhum domínio é pré-permitido. Na primeira vez que um comando precisa de um novo domínio, Claude Code solicita aprovação. Pré-permita domínios com allowedDomains para evitar o prompt.
Managed lockdown: se allowManagedDomainsOnly estiver definido em configurações gerenciadas, domínios não permitidos são bloqueados automaticamente em vez de solicitar, e apenas allowedDomains de configurações gerenciadas são honrados.
Suporte a proxy personalizado: usuários avançados podem implementar regras personalizadas no tráfego de saída
Cobertura abrangente: as restrições se aplicam a todos os scripts, programas e subprocessos gerados por comandos

Imposição no nível do SO

A ferramenta Bash em sandbox aproveita primitivos de segurança do sistema operacional:

macOS: usa Seatbelt para imposição de sandbox
Linux: usa bubblewrap para isolamento
WSL2: usa bubblewrap, igual ao Linux

WSL1 não é suportado porque bubblewrap requer recursos de kernel disponíveis apenas no WSL2. Essas restrições no nível do SO garantem que todos os processos filhos gerados pelos comandos do Claude Code herdem os mesmos limites de segurança.

Esses mesmos primitivos estão disponíveis como o pacote autônomo @anthropic-ai/sandbox-runtime, que a página Sandbox environments aborda como uma abordagem separada para envolver todo o processo do Claude Code.

Como sandboxing se relaciona com permissões e modos de permissão

Sandboxing, regras de permissão e modos de permissão são camadas complementares. As seções abaixo abrangem como o sandbox interage com cada uma.

Regras de permissão

Regras de permissão e sandboxing controlam coisas diferentes:

Regras de permissão controlam quais ferramentas Claude Code pode usar e são avaliadas antes de qualquer ferramenta ser executada. Elas se aplicam a todas as ferramentas: Bash, Read, Edit, WebFetch, MCP e outras.
Sandboxing fornece imposição no nível do SO que restringe o que comandos Bash podem acessar no nível de sistema de arquivos e rede. Aplica-se apenas a comandos Bash e seus processos filhos.

As duas camadas também diferem em como são impostas. Claude Code avalia decisões de permissão antes de um comando ser executado, com base na string do comando e, no modo auto, no julgamento de um classificador separado sobre se o comando é seguro. O sistema operacional impõe o limite do sandbox no processo em execução, portanto se mantém independentemente do que o modelo escolheu executar e mesmo se um comando permitido faz mais do que seu nome sugere.

Restrições de sistema de arquivos e rede são configuradas através de configurações de sandbox e regras de permissão:

Configuração ou regra	O que faz
`sandbox.filesystem.allowWrite`	Concede acesso de escrita de subprocesso a caminhos fora do diretório de trabalho
`sandbox.filesystem.denyWrite` e `sandbox.filesystem.denyRead`	Bloqueiam acesso de subprocesso a caminhos específicos
`sandbox.filesystem.allowRead`	Permite novamente a leitura de caminhos específicos dentro de uma região `denyRead`
Regras de permissão `Edit`	Concedem acesso de escrita a caminhos específicos, da mesma forma que `sandbox.filesystem.allowWrite` faz
Regras de negação `Read` e `Edit`	Bloqueiam acesso a arquivos ou diretórios específicos
Regras de permissão e negação `WebFetch`	Controlam acesso a domínios
`allowedDomains` de sandbox	Controla quais domínios comandos Bash podem alcançar
`deniedDomains` de sandbox	Bloqueia domínios específicos mesmo quando um wildcard `allowedDomains` mais amplo permitiria de outra forma

Caminhos de ambas as configurações sandbox.filesystem e regras de permissão são mesclados juntos na configuração final do sandbox.

O diretório de exemplos do repositório claude-code inclui configurações de configurações iniciais para cenários de implantação comuns, incluindo exemplos específicos de sandbox. Use-os como pontos de partida e ajuste-os para suas necessidades.

Modos de permissão

/sandbox não é um modo de permissão. Modos de permissão decidem se uma chamada de ferramenta é executada e se você é solicitado primeiro, enquanto o sandbox restringe o que um comando Bash pode acessar uma vez que é executado. Eles diferem no que controlam e o que substitui o prompt por ação:

	O que controla	O que substitui o prompt
`/sandbox`	O que um comando Bash pode acessar uma vez que é executado	O limite do sandbox em si, no modo auto-allow
Modo auto	Se cada chamada de ferramenta é executada	Um classificador que revisa ações
`--dangerously-skip-permissions`	Se cada chamada de ferramenta é executada	Nada. Verificações de caminho protegido também são ignoradas; apenas remover `/` ou seu diretório home ainda solicita

O modo auto-allow do sandbox é separado do modo auto: auto-allow aprova comandos Bash porque o limite do sandbox os contém, enquanto modo auto usa um classificador para revisar ações. Os dois funcionam independentemente e podem ser combinados. Para escolher um limite de isolamento para execuções autônomas, consulte Ambientes de sandbox.

Configure the sandbox for your organization

Administradores podem exigir sandboxing para cada usuário, impedir que desenvolvedores ampliem a política e rotear tráfego de sandbox através de um proxy corporativo.

Enforce sandboxing with managed settings

Para exigir o sandbox para cada desenvolvedor, entregue as chaves sandbox através de managed settings, seja como um arquivo gerenciado pelo seu MDM ou através de server-managed settings no Claude.ai.

A seguinte configuração de managed settings habilita o sandbox, recusa iniciar Claude Code se o sandbox não conseguir inicializar e impede que o modelo tente novamente comandos fora do sandbox:

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

As duas chaves além de enabled controlam o que acontece quando o sandbox não consegue executar um comando:

failIfUnavailable: uma dependência faltante como bubblewrap no Linux bloqueia Claude Code de iniciar em vez de mostrar um aviso e voltar a execução sem sandbox
allowUnsandboxedCommands: false: o escape hatch dangerouslyDisableSandbox é ignorado, portanto comandos que falham sob o sandbox não podem ser retentados fora dele

Duas adições valem a pena considerar junto com elas. Adicione excludedCommands para qualquer ferramenta aprovada pela organização que deve ser executada sem isolamento. Adicione entradas denyRead para diretórios de credenciais como ~/.aws e ~/.ssh, que a política de leitura padrão ainda permite.

O sandbox não é executado no Windows nativo, portanto se sua frota inclui hosts Windows, escope esta configuração para macOS e Linux ou tenha esses usuários executarem Claude Code dentro do WSL2 ou um container.

Keep developers from widening the policy

Para chaves booleanas como enabled e failIfUnavailable, Claude Code usa o valor gerenciado e ignora qualquer coisa que um desenvolvedor defina localmente. Para chaves de array como excludedCommands e allowRead, Claude Code mescla entradas de cada escopo, portanto um desenvolvedor pode anexar entradas que ampliem a política.

Defina allowManagedReadPathsOnly como true em configurações gerenciadas para que apenas entradas allowRead de configurações gerenciadas sejam honradas. Entradas allowRead de usuário, projeto e local são ignoradas. Isso impede que desenvolvedores ampliem o acesso de leitura além dos caminhos aprovados pela organização. Para bloquear domínios de rede para os valores gerenciados da mesma forma, defina allowManagedDomainsOnly.

excludedCommands não tem um equivalente de lockdown apenas gerenciado, portanto um desenvolvedor sempre pode anexar entradas que executem comandos adicionais fora do sandbox. Mantenha a lista gerenciada estreita.

Custom proxy configuration

Para organizações que exigem segurança de rede avançada, você pode implementar um proxy personalizado para:

Descriptografar e inspecionar tráfego HTTPS
Aplicar regras de filtragem personalizadas
Registrar todas as solicitações de rede
Integrar com infraestrutura de segurança existente

Para apontar Claude Code para seu proxy, defina as portas de proxy em sandbox settings:

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

Troubleshooting

Alguns comandos falham dentro do sandbox mesmo que funcionem fora dele. As correções abaixo abrangem os casos mais comuns.

Comandos falham com um erro host-not-allowed: muitas ferramentas CLI precisam alcançar hosts específicos. Conceder permissão quando solicitado adiciona o host à sua lista de permitidos para que a ferramenta seja executada dentro do sandbox no futuro.
jest trava ou falha: watchman é incompatível com o sandbox. Execute jest --no-watchman em vez disso.
CLIs baseadas em Go falham na verificação TLS no macOS: ferramentas como gh, gcloud e terraform podem falhar na verificação TLS sob Seatbelt. Liste essas ferramentas em excludedCommands para executá-las fora do sandbox. Se você estiver usando httpProxyPort com um proxy MITM e CA personalizado, defina enableWeakerNetworkIsolation como true em vez disso.
Comandos docker falham: docker é incompatível com o sandbox. Adicione docker * a excludedCommands para executá-lo fora do sandbox.
Bubblewrap falha ao iniciar dentro de um container: em um container sem privilégios, bubblewrap não consegue montar um sistema de arquivos /proc fresco. Defina enableWeakerNestedSandbox como true para que o sandbox interno faça bind-mount do /proc existente do container em vez disso. Use esta configuração apenas quando o container externo já fornece o limite de isolamento que você precisa, pois expõe informações de processo a comandos em sandbox que uma montagem /proc fresca ocultaria.
Filtro seccomp no Linux: o filtro seccomp é necessário para bloquear sockets de domínio Unix. A aba Dependencies em /sandbox mostra se está disponível. Se estiver faltando, execute npm install -g @anthropic-ai/sandbox-runtime para instalar o helper.
--dangerously-skip-permissions falha como root: este sinalizador é bloqueado ao executar como root ou via sudo no Linux e macOS, porque acesso root combinado com nenhum prompt de permissão pode modificar qualquer arquivo ou serviço no sistema. A verificação é ignorada automaticamente dentro de um sandbox reconhecido. Para executar autonomamente em um container, use a configuração dev container, que executa Claude Code como um usuário não-root.

Limitações

Sandboxing reduz risco, mas não é um limite de isolamento completo. Revise as limitações abaixo antes de confiar nele como um controle de segurança difícil.

Limitações de segurança

Filtragem de rede: o sistema de filtragem de rede funciona restringindo os domínios aos quais os processos podem se conectar. O proxy integrado não termina ou realiza inspeção TLS no tráfego de saída, portanto o conteúdo de conexões criptografadas não é examinado. Você é responsável por garantir que apenas domínios confiáveis sejam permitidos em sua política.

Escalação de privilégio via Unix sockets: a configuração allowUnixSockets pode inadvertidamente conceder acesso a serviços poderosos do sistema que poderiam levar a bypasses de sandbox. Por exemplo, permitir acesso a /var/run/docker.sock efetivamente concede acesso ao sistema host através do socket Docker. Considere cuidadosamente quaisquer Unix sockets que você permita através do sandbox.
Escalação de permissão de sistema de arquivos: permissões de escrita de sistema de arquivos excessivamente amplas podem habilitar ataques de escalação de privilégio. Permitir escritas em diretórios contendo executáveis em $PATH, diretórios de configuração do sistema ou arquivos de configuração de shell do usuário como .bashrc ou .zshrc pode levar a execução de código em diferentes contextos de segurança quando outros usuários ou processos do sistema acessam esses arquivos.
Força do sandbox Linux: a implementação Linux fornece isolamento forte de sistema de arquivos e rede, mas inclui um modo enableWeakerNestedSandbox que o habilita a funcionar dentro de ambientes Docker sem namespaces privilegiados, ou em hosts Linux onde namespaces de usuário sem privilégios são desabilitados por sysctl. Esta opção enfraquece consideravelmente a segurança e deve ser usada apenas quando isolamento adicional é de outra forma imposto.
Arquivos de configurações protegidos: o sandbox automaticamente nega acesso de escrita aos arquivos settings.json do Claude Code em cada escopo e ao diretório de configurações gerenciadas, portanto um comando em sandbox não pode modificar sua própria política.

Compatibilidade de plataforma e ferramentas

Suporte de plataforma: suporta macOS, Linux e WSL2. WSL1 e Windows nativo não são suportados.
Overhead de desempenho: mínimo, mas algumas operações de sistema de arquivos podem ser ligeiramente mais lentas.
Compatibilidade de ferramentas: algumas ferramentas que exigem padrões de acesso específicos do sistema podem precisar de ajustes de configuração, ou podem precisar ser executadas fora do sandbox.

Escopo

O sandbox isola subprocessos Bash. Outras ferramentas operam sob limites diferentes:

Ferramentas de arquivo integradas: Read, Edit e Write usam o sistema de permissão diretamente em vez de serem executadas através do sandbox. Consulte permissions.
Computer use: quando Claude abre aplicativos e controla sua tela, ele é executado em seu desktop real em vez de em um ambiente isolado. Prompts de permissão por aplicativo controlam cada aplicativo. Consulte computer use in the CLI ou computer use in Desktop.
Variáveis de ambiente: comandos Bash em sandbox herdam o ambiente do processo pai por padrão, incluindo quaisquer credenciais definidas lá. Para remover credenciais do Anthropic e do provedor de nuvem de subprocessos, defina CLAUDE_CODE_SUBPROCESS_ENV_SCRUB.
Subagents: subagents são executados no mesmo processo que a sessão pai e usam a mesma configuração de sandbox. Comandos Bash dentro de um subagent são colocados em sandbox quando sandboxing está habilitado na sessão pai.

Veja também

Sandbox environments: compare o sandbox integrado com dev containers, containers e VMs
Security: recursos de segurança abrangentes e melhores práticas
Permissions: configuração de permissão e controle de acesso
Settings: referência de configuração completa
CLI reference: opções de linha de comando

sandboxing.md +23 −20

49 </Step>49 </Step>

50 50

51 <Step title="Run a Bash command">51 <Step title="Run a Bash command">

52 Peça ao Claude para executar um comando, como uma compilação ou um conjunto de testes. Por padrão, os comandos dentro do sandbox podem escrever apenas no diretório de trabalho. Na primeira vez que um comando precisa de um novo domínio de rede, Claude Code solicita aprovação.52 Peça ao Claude para executar um comando, como uma compilação ou um conjunto de testes. Por padrão, os comandos dentro do sandbox podem escrever apenas no diretório de trabalho e no diretório temporário da sessão. Na primeira vez que um comando precisa de um novo domínio de rede, Claude Code solicita aprovação.

53 53

54 Comandos que não podem ser executados em sandbox voltam ao fluxo de permissão regular. Para ampliar ou estreitar esses limites, consulte [Configure sandboxing](#configure-sandboxing).54 Comandos que não podem ser executados em sandbox voltam ao fluxo de permissão regular. Para ampliar ou estreitar esses limites, consulte [Configure sandboxing](#configure-sandboxing).

55 </Step>55 </Step>

134 134

135* [Deny rules](/pt/permissions) explícitas são sempre respeitadas135* [Deny rules](/pt/permissions) explícitas são sempre respeitadas

136* Comandos `rm` ou `rmdir` que visam `/`, seu diretório home ou outros caminhos críticos do sistema ainda acionam um prompt de permissão136* Comandos `rm` ou `rmdir` que visam `/`, seu diretório home ou outros caminhos críticos do sistema ainda acionam um prompt de permissão

137* [Ask rules](/pt/permissions) se aplicam a comandos que voltam ao fluxo de permissão regular137* [Ask rules](/pt/permissions) com escopo de conteúdo como `Bash(git push *)` ainda forçam um prompt mesmo para comandos em sandbox

138* Uma regra ask `Bash` simples, ou o formulário equivalente `Bash(*)`, é ignorada para comandos executados em sandbox; ainda se aplica a comandos que voltam ao fluxo de permissão regular

138 139

139**Modo regular permissions**: Todos os comandos Bash passam pelo fluxo de permissão regular, mesmo quando em sandbox. Isso fornece mais controle, mas requer mais aprovações.140**Modo regular permissions**: Todos os comandos Bash passam pelo fluxo de permissão regular, mesmo quando em sandbox. Isso fornece mais controle, mas requer mais aprovações.

140 141

141Em ambos os modos, o sandbox impõe as mesmas restrições de sistema de arquivos e rede. A diferença é apenas se os comandos em sandbox são aprovados automaticamente ou requerem permissão explícita.142Em ambos os modos, o sandbox impõe as mesmas restrições de sistema de arquivos e rede. A diferença é apenas se os comandos em sandbox são aprovados automaticamente ou requerem permissão explícita.

142 143

144O diretório temporário da sessão é gravável dentro do sandbox por padrão, junto com o diretório de trabalho. Claude Code define `$TMPDIR` para este diretório para comandos em sandbox, portanto ferramentas que escrevem arquivos temporários funcionam sem configuração extra. Comandos não em sandbox herdam o `$TMPDIR` do seu shell inalterado, o que significa que comandos em sandbox e não em sandbox resolvem `$TMPDIR` para diretórios diferentes. Para passar arquivos temporários entre os dois, escreva-os no diretório de trabalho em vez disso.

145

143Alguns comandos não podem ser executados dentro do sandbox, como ferramentas que são incompatíveis com ele ou que precisam de um host que você não permitiu. Em vez de falhar na tarefa ou exigir que você desative o sandboxing, Claude Code inclui um escape hatch: quando um comando falha por causa de restrições de sandbox, Claude analisa a falha e pode tentar novamente o comando com o parâmetro `dangerouslyDisableSandbox`. O comando retentado é executado fora do sandbox, portanto passa pelo fluxo de permissão regular e requer sua aprovação.146Alguns comandos não podem ser executados dentro do sandbox, como ferramentas que são incompatíveis com ele ou que precisam de um host que você não permitiu. Em vez de falhar na tarefa ou exigir que você desative o sandboxing, Claude Code inclui um escape hatch: quando um comando falha por causa de restrições de sandbox, Claude analisa a falha e pode tentar novamente o comando com o parâmetro `dangerouslyDisableSandbox`. O comando retentado é executado fora do sandbox, portanto passa pelo fluxo de permissão regular e requer sua aprovação.

144 147

145Você pode desabilitar esse escape hatch definindo `"allowUnsandboxedCommands": false` em suas [sandbox settings](/pt/settings#sandbox-settings). Quando desabilitado, que a aba Overrides do `/sandbox` mostra como **Strict sandbox mode**, o parâmetro `dangerouslyDisableSandbox` é completamente ignorado e todos os comandos devem ser executados em sandbox ou estar explicitamente listados em `excludedCommands`.148Você pode desabilitar esse escape hatch definindo `"allowUnsandboxedCommands": false` em suas [sandbox settings](/pt/settings#sandbox-settings). Quando desabilitado, que a aba Overrides do `/sandbox` mostra como **Strict sandbox mode**, o parâmetro `dangerouslyDisableSandbox` é completamente ignorado e todos os comandos devem ser executados em sandbox ou estar explicitamente listados em `excludedCommands`.

154 157

155Personalize o comportamento do sandbox através de seu arquivo `settings.json`. Consulte [Settings](/pt/settings#sandbox-settings) para a referência de configuração completa.158Personalize o comportamento do sandbox através de seu arquivo `settings.json`. Consulte [Settings](/pt/settings#sandbox-settings) para a referência de configuração completa.

156 159

157Por padrão, comandos em sandbox podem apenas escrever no diretório de trabalho atual. Se comandos de subprocesso como `kubectl`, `terraform` ou `npm` precisarem escrever fora do diretório do projeto, use `sandbox.filesystem.allowWrite` para conceder acesso a caminhos específicos:160Por padrão, comandos em sandbox podem escrever apenas no diretório de trabalho atual e no diretório temporário da sessão. Se comandos de subprocesso como `kubectl`, `terraform` ou `npm` precisarem escrever fora desses diretórios, use `sandbox.filesystem.allowWrite` para conceder acesso a caminhos específicos:

158 161

159```json theme={null}162```json theme={null}

160{163{

209 212

210A ferramenta Bash em sandbox restringe o acesso ao sistema de arquivos a diretórios específicos:213A ferramenta Bash em sandbox restringe o acesso ao sistema de arquivos a diretórios específicos:

211 214

212* **Comportamento padrão de escrita**: acesso de leitura e escrita ao diretório de trabalho atual e seus subdiretórios215* **Comportamento padrão de escrita**: acesso de leitura e escrita ao diretório de trabalho atual e seus subdiretórios, além do diretório temporário da sessão para o qual `$TMPDIR` aponta

213* **Comportamento padrão de leitura**: acesso de leitura a todo o computador, exceto certos diretórios negados. Observe que esse padrão ainda permite ler arquivos de credenciais como `~/.aws/credentials` e `~/.ssh/`. Adicione-os a `denyRead` para bloqueá-los.216* **Comportamento padrão de leitura**: acesso de leitura a todo o computador, exceto certos diretórios negados. Observe que esse padrão ainda permite ler arquivos de credenciais como `~/.aws/credentials` e `~/.ssh/`. Adicione-os a `denyRead` para bloqueá-los.

214* **Acesso bloqueado**: não é possível modificar arquivos fora do diretório de trabalho atual sem permissão explícita, incluindo arquivos de configuração de shell como `~/.bashrc` e binários do sistema em `/bin/`217* **Acesso bloqueado**: não é possível modificar arquivos fora do diretório de trabalho atual e do diretório temporário da sessão sem permissão explícita, incluindo arquivos de configuração de shell como `~/.bashrc` e binários do sistema em `/bin/`

215* **Git worktrees**: quando o diretório de trabalho é um [git worktree vinculado](/pt/worktrees), o sandbox também permite escritas no diretório `.git` compartilhado do repositório principal para que comandos como `git commit` possam atualizar refs e o índice. As escritas em `hooks/` e `config` dentro desse diretório permanecem negadas.218* **Git worktrees**: quando o diretório de trabalho é um [git worktree vinculado](/pt/worktrees), o sandbox também permite escritas no diretório `.git` compartilhado do repositório principal para que comandos como `git commit` possam atualizar refs e o índice. As escritas em `hooks/` e `config` dentro desse diretório permanecem negadas.

216* **Configurável**: defina caminhos permitidos e negados personalizados através de configurações219* **Configurável**: defina caminhos permitidos e negados personalizados através de configurações

217 220

247Esses mesmos primitivos estão disponíveis como o pacote autônomo [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropic-experimental/sandbox-runtime), que a página [Sandbox environments](/pt/sandbox-environments#sandbox-runtime) aborda como uma abordagem separada para envolver todo o processo do Claude Code.250Esses mesmos primitivos estão disponíveis como o pacote autônomo [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropic-experimental/sandbox-runtime), que a página [Sandbox environments](/pt/sandbox-environments#sandbox-runtime) aborda como uma abordagem separada para envolver todo o processo do Claude Code.

248 251

249<h2 id="how-sandboxing-relates-to-permissions-and-permission-modes">252<h2 id="how-sandboxing-relates-to-permissions-and-permission-modes">

250 How sandboxing relates to permissions and permission modes253 Como sandboxing se relaciona com permissões e modos de permissão

251</h2>254</h2>

252 255

253Sandboxing, [permission rules](/pt/permissions) e [permission modes](/pt/permission-modes) são camadas complementares. As seções abaixo abrangem como o sandbox interage com cada uma.256Sandboxing, [regras de permissão](/pt/permissions) e [modos de permissão](/pt/permission-modes) são camadas complementares. As seções abaixo abrangem como o sandbox interage com cada uma.

254 257

255<h3 id="permission-rules">258<h3 id="permission-rules">

256 Permission rules259 Regras de permissão

257</h3>260</h3>

258 261

259Regras de permissão e sandboxing controlam coisas diferentes:262Regras de permissão e sandboxing controlam coisas diferentes:

281O [diretório de exemplos do repositório claude-code](https://github.com/anthropics/claude-code/tree/main/examples/settings) inclui configurações de configurações iniciais para cenários de implantação comuns, incluindo exemplos específicos de sandbox. Use-os como pontos de partida e ajuste-os para suas necessidades.284O [diretório de exemplos do repositório claude-code](https://github.com/anthropics/claude-code/tree/main/examples/settings) inclui configurações de configurações iniciais para cenários de implantação comuns, incluindo exemplos específicos de sandbox. Use-os como pontos de partida e ajuste-os para suas necessidades.

282 285

283<h3 id="permission-modes">286<h3 id="permission-modes">

284 Permission modes287 Modos de permissão

285</h3>288</h3>

286 289

287`/sandbox` não é um [permission mode](/pt/permission-modes). Modos de permissão decidem se uma chamada de ferramenta é executada e se você é solicitado primeiro, enquanto o sandbox restringe o que um comando Bash pode acessar uma vez que é executado. Eles diferem no que controlam e o que substitui o prompt por ação:290`/sandbox` não é um [modo de permissão](/pt/permission-modes). Modos de permissão decidem se uma chamada de ferramenta é executada e se você é solicitado primeiro, enquanto o sandbox restringe o que um comando Bash pode acessar uma vez que é executado. Eles diferem no que controlam e o que substitui o prompt por ação:

288 291

289| | O que controla | O que substitui o prompt |292| | O que controla | O que substitui o prompt |

290| :----------------------------------------------------------------- | :--------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |293| :----------------------------------------------------------------- | :--------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |

293| `--dangerously-skip-permissions` | Se cada chamada de ferramenta é executada | Nada. Verificações de [protected path](/pt/permission-modes#protected-paths) também são ignoradas; apenas remover `/` ou seu diretório home ainda solicita |296| `--dangerously-skip-permissions` | Se cada chamada de ferramenta é executada | Nada. Verificações de [caminho protegido](/pt/permission-modes#protected-paths) também são ignoradas; apenas remover `/` ou seu diretório home ainda solicita |

294 297

295O [modo auto-allow](#sandbox-modes) do sandbox é separado do [auto mode](/pt/permission-modes#eliminate-prompts-with-auto-mode): auto-allow aprova comandos Bash porque o limite do sandbox os contém, enquanto auto mode usa um classificador para revisar ações. Os dois funcionam independentemente e podem ser combinados. Para escolher um limite de isolamento para execuções autônomas, consulte [Sandbox environments](/pt/sandbox-environments#how-isolation-relates-to-permission-modes).298O [modo auto-allow](#sandbox-modes) do sandbox é separado do [modo auto](/pt/permission-modes#eliminate-prompts-with-auto-mode): auto-allow aprova comandos Bash porque o limite do sandbox os contém, enquanto modo auto usa um classificador para revisar ações. Os dois funcionam independentemente e podem ser combinados. Para escolher um limite de isolamento para execuções autônomas, consulte [Ambientes de sandbox](/pt/sandbox-environments#how-isolation-relates-to-permission-modes).

296 299

297<h2 id="configure-the-sandbox-for-your-organization">300<h2 id="configure-the-sandbox-for-your-organization">

298 Configure the sandbox for your organization301 Configure the sandbox for your organization

376* **`--dangerously-skip-permissions` falha como root**: este sinalizador é bloqueado ao executar como root ou via sudo no Linux e macOS, porque acesso root combinado com nenhum prompt de permissão pode modificar qualquer arquivo ou serviço no sistema. A verificação é ignorada automaticamente dentro de um sandbox reconhecido. Para executar autonomamente em um container, use a configuração [dev container](/pt/devcontainer), que executa Claude Code como um usuário não-root.379* **`--dangerously-skip-permissions` falha como root**: este sinalizador é bloqueado ao executar como root ou via sudo no Linux e macOS, porque acesso root combinado com nenhum prompt de permissão pode modificar qualquer arquivo ou serviço no sistema. A verificação é ignorada automaticamente dentro de um sandbox reconhecido. Para executar autonomamente em um container, use a configuração [dev container](/pt/devcontainer), que executa Claude Code como um usuário não-root.

377 380

378<h2 id="limitations">381<h2 id="limitations">

379 Limitations382 Limitações

380</h2>383</h2>

381 384

382Sandboxing reduz risco, mas não é um limite de isolamento completo. Revise as limitações abaixo antes de confiar nele como um controle de segurança difícil.385Sandboxing reduz risco, mas não é um limite de isolamento completo. Revise as limitações abaixo antes de confiar nele como um controle de segurança difícil.

383 386

384<h3 id="security-limitations">387<h3 id="security-limitations">

385 Security limitations388 Limitações de segurança

386</h3>389</h3>

387 390

388* **Filtragem de rede**: o sistema de filtragem de rede funciona restringindo os domínios aos quais os processos podem se conectar. O proxy integrado não termina ou realiza inspeção TLS no tráfego de saída, portanto o conteúdo de conexões criptografadas não é examinado. Você é responsável por garantir que apenas domínios confiáveis sejam permitidos em sua política.391* **Filtragem de rede**: o sistema de filtragem de rede funciona restringindo os domínios aos quais os processos podem se conectar. O proxy integrado não termina ou realiza inspeção TLS no tráfego de saída, portanto o conteúdo de conexões criptografadas não é examinado. Você é responsável por garantir que apenas domínios confiáveis sejam permitidos em sua política.

397* **Arquivos de configurações protegidos**: o sandbox automaticamente nega acesso de escrita aos arquivos `settings.json` do Claude Code em cada escopo e ao diretório de configurações gerenciadas, portanto um comando em sandbox não pode modificar sua própria política.400* **Arquivos de configurações protegidos**: o sandbox automaticamente nega acesso de escrita aos arquivos `settings.json` do Claude Code em cada escopo e ao diretório de configurações gerenciadas, portanto um comando em sandbox não pode modificar sua própria política.

398 401

399<h3 id="platform-and-tool-compatibility">402<h3 id="platform-and-tool-compatibility">

400 Platform and tool compatibility403 Compatibilidade de plataforma e ferramentas

401</h3>404</h3>

402 405

403* **Suporte de plataforma**: suporta macOS, Linux e WSL2. WSL1 e Windows nativo não são suportados.406* **Suporte de plataforma**: suporta macOS, Linux e WSL2. WSL1 e Windows nativo não são suportados.

405* **Compatibilidade de ferramentas**: algumas ferramentas que exigem padrões de acesso específicos do sistema podem precisar de ajustes de configuração, ou podem precisar ser executadas fora do sandbox.408* **Compatibilidade de ferramentas**: algumas ferramentas que exigem padrões de acesso específicos do sistema podem precisar de ajustes de configuração, ou podem precisar ser executadas fora do sandbox.

406 409

407<h3 id="scope">410<h3 id="scope">

408 Scope411 Escopo

409</h3>412</h3>

410 413

411O sandbox isola subprocessos Bash. Outras ferramentas operam sob limites diferentes:414O sandbox isola subprocessos Bash. Outras ferramentas operam sob limites diferentes:

416* **Subagents**: [subagents](/pt/sub-agents) são executados no mesmo processo que a sessão pai e usam a mesma configuração de sandbox. Comandos Bash dentro de um subagent são colocados em sandbox quando sandboxing está habilitado na sessão pai.419* **Subagents**: [subagents](/pt/sub-agents) são executados no mesmo processo que a sessão pai e usam a mesma configuração de sandbox. Comandos Bash dentro de um subagent são colocados em sandbox quando sandboxing está habilitado na sessão pai.

417 420

418<Warning>421<Warning>

419 Sandboxing eficaz requer isolamento **tanto** de sistema de arquivos quanto de rede. Sem isolamento de rede, um agente comprometido poderia exfiltrar arquivos sensíveis como chaves SSH. Sem isolamento de sistema de arquivos, um agente comprometido poderia fazer backdoor de recursos do sistema para obter acesso à rede. Quando você amplia os padrões, verifique que um caminho `allowWrite`, uma entrada `allowedDomains` ampla ou uma exceção `excludedCommands` não desfaz uma restrição no outro lado.422 Sandboxing eficaz requer isolamento tanto de sistema de arquivos quanto de rede. Sem isolamento de rede, um agente comprometido poderia exfiltrar arquivos sensíveis como chaves SSH. Sem isolamento de sistema de arquivos, um agente comprometido poderia fazer backdoor de recursos do sistema para obter acesso à rede. Quando você amplia os padrões, verifique que um caminho `allowWrite`, uma entrada `allowedDomains` ampla ou uma exceção `excludedCommands` não desfaz uma restrição no outro lado.

420</Warning>423</Warning>

421 424

422<h2 id="see-also">425<h2 id="see-also">

423 See also426 Veja também

424</h2>427</h2>

425 428

426* [Sandbox environments](/pt/sandbox-environments): compare o sandbox integrado com dev containers, containers e VMs429* [Sandbox environments](/pt/sandbox-environments): compare o sandbox integrado com dev containers, containers e VMs

sandboxing.md 2026-06-16 21:57 UTC to 2026-06-17 17:02 UTC

Configurar a ferramenta Bash em sandbox

Get started

Run /sandbox

Choose a mode

Run a Bash command

Set up Linux and WSL2

Sandbox modes

Configure sandboxing

Como o sandboxing funciona

Isolamento do sistema de arquivos

Isolamento de rede

Imposição no nível do SO

Como sandboxing se relaciona com permissões e modos de permissão

Regras de permissão

Modos de permissão

Configure the sandbox for your organization

Enforce sandboxing with managed settings

Keep developers from widening the policy

Custom proxy configuration

Troubleshooting

Limitações

Limitações de segurança

Compatibilidade de plataforma e ferramentas

Escopo

Veja também