SpyBara
Go Premium

sandboxing.md 2026-10-01 23:59 UTC to 2026-10-02 15:01 UTC

This page contains 601 additions and 302 deletions.

2026
Fri 2 16:01

Configurar a ferramenta Bash em sandbox

Restrinja os arquivos e hosts de rede que os comandos de shell do Claude Code podem acessar com o sandbox integrado. Ative-o, defina o limite e corrija o que ele quebra.

O sandbox do Bash é um limite que o sistema operacional impõe em torno dos comandos de shell que o Claude executa na sua máquina. Você define quais arquivos e domínios de rede esses comandos podem acessar, e os limites se aplicam aos comandos Bash, PowerShell e Monitor e aos processos que eles iniciam. Como o sistema operacional aplica os limites enquanto um comando é executado, o Claude Code pode executar comandos em sandbox sem pedir a você que aprove cada um deles.

O sandbox abrange apenas comandos de shell. As ferramentas de arquivo do Claude, os servidores MCP e os hooks são executados fora dele.

O sandbox funciona no macOS, Linux e WSL2. No Windows nativo, o Claude Code executa comandos sem sandbox. Para usar o sandbox em uma máquina Windows, execute o Claude Code dentro de uma distribuição WSL2.

O que o sandbox restringe

Enquanto o sandbox está ativado, os comandos de shell que o Claude executa começam dentro do seu limite, assim como os processos que eles iniciam. O sandbox fica desativado por padrão. Para ativá-lo, execute /sandbox em uma sessão, como mostra Começar, ou defina sandbox.enabled como true em um arquivo de configurações como ~/.claude/settings.json.

A tabela mostra o que um comando em sandbox pode acessar por padrão e as configurações que alteram cada padrão.

Acesso Padrão Altere com
Escritas O diretório de trabalho, um diretório temporário por usuário e diretórios que você adicionou. Caminhos protegidos permanecem com escrita negada filesystem.allowWrite, filesystem.denyWrite
Leituras A maior parte da máquina, incluindo arquivos de credenciais como ~/.ssh e ~/.aws/credentials filesystem.denyRead, credentials
Rede Nenhuma rota direta para fora. As conexões passam por um proxy na sua máquina que verifica cada host em relação aos seus domínios permitidos, que começam vazios. Seu modo de permissão decide o que acontece com outros hosts network.allowedDomains, network.deniedDomains
Variáveis de ambiente Herdadas do Claude Code, incluindo quaisquer segredos em seu ambiente credentials, CLAUDE_CODE_SUBPROCESS_ENV_SCRUB

O Claude Code constrói o sandbox sobre o pacote de código aberto @anthropic-ai/sandbox-runtime.

O que é executado fora do sandbox

O sandbox envolve comandos de shell. Estas ferramentas e processos são executados fora dele:

  • Ferramentas integradas de arquivos e web: ferramentas como Read, Edit, Write, WebFetch e WebSearch seguem regras de permissão em vez disso. Uma entrada denyRead não impede a ferramenta Read, e allowedDomains não limita a WebFetch
  • Outros processos que o Claude Code inicia: hooks de comando, servidores MCP locais, monitores de plugins, servidores LSP e comandos auxiliares como o comando da sua linha de status e apiKeyHelper são executados com seu acesso completo

Alguns comandos de shell também são executados fora do sandbox, dependendo das suas configurações:

Para colocar as ferramentas, processos e comandos desta seção atrás de um único limite, execute o próprio processo do Claude Code em um contêiner, máquina virtual ou no sandbox runtime.

Primeiros passos

O sandbox é integrado ao Claude Code. O que você instala depende da sua plataforma:

  • macOS: o sandboxing usa o framework Seatbelt integrado, então você pode ir direto para os passos
  • Linux e WSL2: o sandbox depende de bubblewrap e socat, abordados em Configurar Linux e WSL2. Mesmo que você ainda não os tenha instalado, pode começar com /sandbox, porque o painel mostra se algo está faltando
1

Execute /sandbox

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

/sandbox

Isso abre o painel do sandbox com três abas, além de uma aba Dependencies no Linux quando o filtro seccomp opcional está ausente:

  • Mode: escolha como os comandos em sandbox são aprovados, abordado no próximo passo
  • Overrides: escolha se os comandos que falham no sandbox podem recorrer à execução fora do sandbox. Esta é a configuração allowUnsandboxedCommands
  • Config: visualize as configurações resolvidas do sandbox

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

2

Escolha um modo

Na aba Mode, selecione auto-allow ou permissões regulares. O auto-allow executa comandos em sandbox sem solicitar confirmação, e as permissões regulares mantêm os prompts de permissão regulares mesmo quando os comandos estão em sandbox. Consulte Modos do sandbox para saber quais comandos ainda solicitam confirmação no modo auto-allow.

3

Execute um comando Bash

Peça ao Claude para executar um comando, como um build ou uma suíte de testes. Por padrão, os comandos dentro do sandbox podem gravar no diretório de trabalho, em um diretório temporário por usuário e em quaisquer diretórios que você adicionou com --add-dir, /add-dir ou permissions.additionalDirectories.

Na primeira vez que um comando precisa de um novo domínio de rede, o Claude Code solicita aprovação; no modo auto, o Claude, em vez disso, nomeia os hosts de que um comando precisa no próprio comando para que o classificador os revise junto com ele.

Para ampliar ou restringir o que o sandbox permite, consulte Configurar o sandboxing.

Se os comandos em sandbox falharem com Operation not permitted dentro de um contêiner, consulte O Bubblewrap não inicia dentro de um contêiner.

Quando você seleciona um modo no painel, o Claude Code o salva nas configurações locais do seu projeto em .claude/settings.local.json, que se aplicam ao projeto atual. O Claude Code adiciona esse arquivo ao seu gitignore global quando salva uma configuração nele. Para ativar o sandbox em todos os seus projetos, defina sandbox.enabled como true nas suas configurações de usuário em ~/.claude/settings.json. Para impor o sandboxing a todos os desenvolvedores de uma organização, use configurações gerenciadas.

Para alterar o sandbox em uma sessão sem gravar em um arquivo de configurações, inicie o Claude Code com --settings. Por exemplo, este comando inicia uma sessão em sandbox na qual o Claude não pode tentar novamente um comando bloqueado fora do sandbox:

claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'

Confirmar que os comandos são executados dentro do sandbox

Para verificar se o sandbox está funcionando, peça ao Claude para executar cada linha da tabela. O que você digita no prompt ! geralmente é executado fora do sandbox, então digitar uma linha você mesmo não o testa.

Comando Resultado dentro do sandbox
touch ~/sandbox-probe Falha com Operation not permitted no macOS, ou Read-only file system no Linux e WSL2
curl --noproxy '*' https://example.com Falha com Could not resolve host, porque o comando não tem rota para contornar o proxy do sandbox

Se o Claude pedir para tentar novamente um comando que falhou fora do sandbox, recuse a nova tentativa. Se touch for bem-sucedido e seu diretório pessoal não for um dos diretórios em que o sandbox permite que os comandos gravem, exclua ~/sandbox-probe. Em seguida, execute /sandbox para verificar se o sandbox está ativado e se suas dependências estão instaladas.

Configurar Linux e WSL2

No Linux e no WSL2, o sandbox depende destes pacotes:

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

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

sudo apt-get install bubblewrap socat

Quando uma dependência está ausente, a aba Dependencies em /sandbox lista quais dentre ripgrep, bubblewrap, socat e o filtro seccomp estão faltando na sua plataforma. Se você não vir a aba após instalar e reiniciar o Claude Code, todas as dependências estão presentes.

O ripgrep vem incluído no binário nativo do Claude Code. O filtro seccomp é opcional e adiciona o bloqueio de sockets de domínio Unix. Instale-o com npm install -g @anthropic-ai/sandbox-runtime se estiver ausente.

Quando uma dependência obrigatória está ausente, a aba Dependencies é a única exibida até que você a instale. Quando apenas o filtro seccomp opcional está ausente, a aba Dependencies aparece junto com as outras abas. A verificação de dependências é executada na inicialização, então reinicie o Claude Code após instalar pacotes para que /sandbox os detecte.

No Ubuntu 24.04 e posteriores, a política padrão do AppArmor impede que o bubblewrap crie os user namespaces de que precisa para o isolamento. 
Para verificar se o seu ambiente impõe essa restrição, inclusive dentro do WSL2, execute `sysctl kernel.apparmor_restrict_unprivileged_userns`. Se o comando retornar `0`, pule este passo. Se ele exibir um erro `No such file or directory`, a chave não existe e você pode pular este passo. Se retornar `1`, adicione um perfil do AppArmor que conceda essa capacidade ao `bwrap`:

```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 ao próprio `bwrap`, não aos comandos que ele executa dentro do sandbox. Recarregue o AppArmor para aplicá-lo:

```bash theme={null}
sudo systemctl reload apparmor
```
Observações sobre o WSL2

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

No WSL2, o WSL repassa a inicialização de um binário do Windows, como cmd.exe, powershell.exe ou qualquer coisa em /mnt/c/, ao host Windows por meio de um socket Unix, então a possibilidade de um comando em sandbox iniciar um deles segue as configurações de socket Unix do sandbox: o filtro seccomp opcional precisa estar instalado para que o socket seja bloqueado. Para permitir essas inicializações, defina allowAllUnixSockets, que abre todos os sockets Unix para os comandos em sandbox.

Modos do sandbox

O Claude Code oferece dois modos de sandbox. Em ambos, o sandbox impõe as mesmas restrições de sistema de arquivos e de rede; a diferença está apenas em se os comandos em sandbox são aprovados automaticamente ou exigem permissão explícita.

Modo auto-allow

O Claude Code aprova um comando automaticamente, sem prompt, quando o comando é executado dentro do sandbox. Um comando passa pelo fluxo de permissão regular quando é executado fora do sandbox porque corresponde a excludedCommands ou porque o Claude o tenta novamente fora do sandbox.

Um comando em sandbox que se conecta a um host que você não permitiu permanece no sandbox. Hosts fora dos seus domínios permitidos explica quem decide se a conexão é realizada.

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

  • Regras de negação explícitas são sempre respeitadas
  • Comandos rm ou rmdir que têm como alvo um caminho crítico ainda passam pelo fluxo de permissão regular
  • Regras de solicitação com escopo de conteúdo, como Bash(git push *), ainda forçam um prompt mesmo para comandos em sandbox
  • Uma regra de solicitação Bash simples, ou a forma equivalente Bash(*), é ignorada para comandos executados em sandbox; ela ainda se aplica a comandos que recorrem ao fluxo de permissão regular. No modo de planejamento, a regra não é ignorada: ela solicita confirmação também para comandos em sandbox, incluindo os somente leitura

Modo de permissões regulares

Todos os comandos Bash passam pelo fluxo de permissão regular, mesmo quando em sandbox. Isso oferece mais controle, mas exige mais aprovações.

A válvula de escape de nova tentativa fora do sandbox

A nova tentativa fora do sandbox é uma válvula de escape para comandos que falham dentro do sandbox, como ferramentas incompatíveis com ele. Quando o sandbox bloqueia uma conexão de rede, o Claude Code nomeia o host negado no resultado do comando, para que o Claude veja o que foi bloqueado. O Claude analisa a falha e pode tentar novamente o comando com o parâmetro dangerouslyDisableSandbox.

O comando tentado novamente é executado fora do sandbox. Em uma sessão interativa de terminal, quem o aprova depende do seu modo de permissão:

  • Modo bypassPermissions: a nova tentativa é executada sem prompt
  • Modo Manual e modo acceptEdits: você recebe um prompt intitulado "Bash command (unsandboxed)"
  • Modo auto: um modelo classificador separado avalia o comando subjacente
  • Modo dontAsk: o Claude Code nega a nova tentativa
  • Modo de planejamento: consulte como o Claude Code controla os comandos enquanto você planeja

Estas regras e configurações mudam quem aprova a nova tentativa:

  • Uma regra de permissão correspondente: se uma regra de permissão como Bash(curl *) corresponder ao comando, ela também aprova a nova tentativa, então o comando é executado fora do sandbox sem prompt
  • Uma regra de solicitação para o parâmetro: adicione uma regra de solicitação para Bash(dangerouslyDisableSandbox:true) para receber um prompt nas novas tentativas do Bash. Você recebe o prompt também no modo auto e no modo bypassPermissions, e a regra tem precedência sobre uma regra de permissão correspondente
  • permissions.blockReadsOutsideWorkingDirectories: Ações que nenhum modo aprova automaticamente abrange as novas tentativas que solicitam confirmação enquanto ela está ativada

Desativar a nova tentativa com o modo de sandbox estrito

Você pode desativar a nova tentativa fora do sandbox definindo "allowUnsandboxedCommands": false nas suas configurações do sandbox. Com a nova tentativa desativada, o Claude Code ignora o parâmetro dangerouslyDisableSandbox. Enquanto o sandbox estiver em execução, os comandos que o Claude executa passam então a ser executados em sandbox, a menos que correspondam a uma entrada de excludedCommands. Para impedir que o Claude Code execute comandos fora do sandbox quando o sandbox não puder ser iniciado, defina também failIfUnavailable. A aba Overrides de /sandbox mostra essa configuração como Strict sandbox mode.

Um false nas suas configurações de usuário, em --settings ou nas configurações gerenciadas prevalece mesmo quando as configurações de um projeto definem true. Um false nas suas configurações de usuário não torna o sandbox exigido pelo administrador, então as outras configurações do sandbox de um projeto ainda se aplicam. Antes da v2.1.285, um true de um projeto sobrescrevia um false nas suas configurações de usuário.

Se você ou seu administrador desativarem a nova tentativa nas configurações gerenciadas ou com a flag --settings, o sandbox passa a ser exigido pelo administrador. O Claude Code então ignora as configurações nos arquivos de um repositório que afrouxam o sandbox, incluindo as entradas de excludedCommands. Configurações do repositório sob um sandbox exigido pelo administrador as lista.

O modo de sandbox estrito se aplica aos comandos que o Claude executa. Os comandos que você mesmo digita no prompt do modo shell ! são executados fora do sandbox, a menos que a sessão seja uma destas:

Antes da v2.1.260, o modo de sandbox estrito executava em sandbox os comandos do modo shell em todas as sessões.

Diretórios temporários

Um diretório temporário por usuário é gravável dentro do sandbox por padrão, junto com o diretório de trabalho. A menos que você desative o isolamento do sistema de arquivos, o Claude Code define $TMPDIR como esse diretório para os comandos em sandbox, para que as ferramentas que gravam arquivos temporários funcionem sem configuração extra.

Os comandos fora do sandbox herdam o $TMPDIR do seu shell quando ele está definido, então, enquanto o isolamento do sistema de arquivos estiver ativado, os comandos em sandbox e fora do sandbox resolvem $TMPDIR para diretórios diferentes. Se o seu shell deixar $TMPDIR indefinido ou vazio, um comando fora do sandbox que referencia $TMPDIR recebe o valor que você definiu em CLAUDE_CODE_TMPDIR para sobrescrevê-lo, ou o diretório temporário do sistema operacional quando você não definiu um ou quando esse valor é um caminho longo, para que a variável não se expanda para uma string vazia. Para passar arquivos temporários entre os dois, grave-os no diretório de trabalho.

Configurar o sandboxing

Personalize o comportamento do sandbox por meio do seu arquivo settings.json. Consulte Configurações para a referência completa de configuração.

Por padrão, os comandos em sandbox podem gravar no diretório de trabalho atual, no diretório temporário por usuário e em quaisquer diretórios que você adicionou com --add-dir, /add-dir ou permissions.additionalDirectories. Se comandos de subprocesso como kubectl, terraform ou npm precisarem gravar 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 aplicados no nível do sistema operacional, portanto todos os comandos executados dentro do sandbox, incluindo seus processos filhos, os respeitam. Essa é a abordagem recomendada quando uma ferramenta precisa de acesso de gravação a um local específico, em vez de excluir a ferramenta do sandbox inteiramente com excludedCommands.

Quando você define o mesmo array de sistema de arquivos em vários escopos de configurações, o Claude Code os mescla, combinando os caminhos em vez de substituir o array de um escopo pelo de outro. O Claude Code deixa uma entrada fora da mesclagem quando um bloqueio descrito em Impedir que os desenvolvedores ampliem a política a cobre.

Se você excluir uma origem com --setting-sources na CLI ou settingSources no Agent SDK, o Claude Code ignora suas entradas sandbox.filesystem, suas regras de permissão Edit e suas regras de negação Read ao montar a configuração do sandbox. Requer o Claude Code v2.1.246 ou posterior.

Quando você edita essas listas de sistema de arquivos durante uma sessão, o Claude Code aplica a alteração à sessão em execução, de modo que o próximo comando em sandbox é executado com os novos caminhos.

Os caminhos de sistema de arquivos do sandbox usam convenções padrão: /tmp/build é absoluto e ~/.kube é relativo ao seu diretório pessoal. Isso difere das regras de permissão Read e Edit, que usam //path para caminhos absolutos e /path para caminhos relativos ao projeto. Para caminhos relativos, barras finais e curingas, consulte Prefixos de caminho do sandbox.

Você também pode negar acesso de gravação ou leitura usando sandbox.filesystem.denyWrite e sandbox.filesystem.denyRead, e voltar a permitir caminhos específicos dentro de uma região negada usando sandbox.filesystem.allowRead. Quando regras de leitura se sobrepõem, aplica-se a regra com o caminho mais restrito:

Regras de exemplo Resultado
"denyRead": ["~/"] com "allowRead": ["~/projects"] ~/projects pode ser lido e o restante do diretório pessoal permanece bloqueado. A permissão mais restrita reabre essa parte da região negada
"allowRead": ["~/"] com "denyRead": ["~/.env"] ~/.env permanece bloqueado e o restante do diretório pessoal pode ser lido. A negação se mantém dentro de uma permissão mais ampla, de modo que uma permissão ampla não pode reexpor silenciosamente um segredo
"allowRead": ["~/"] com "denyRead": ["~/**/.env"] Todo .env sob o diretório pessoal permanece bloqueado e o restante pode ser lido. Uma negação com curinga se mantém dentro de uma permissão mais ampla da mesma forma que um caminho exato

O exemplo abaixo bloqueia a leitura de todo o diretório pessoal, mas ainda permite leituras do projeto atual. Coloque-o no .claude/settings.json do seu projeto, pois o caminho relativo . é resolvido para a raiz do projeto quando a configuração está nas configurações de projeto:

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

Se você colocasse a mesma configuração em ~/.claude/settings.json, . seria resolvido para ~/.claude, e os arquivos do projeto permaneceriam bloqueados pela regra denyRead.

Para negar aos comandos em sandbox acesso de leitura a diretórios pessoais e volumes montados, mantendo os diretórios de trabalho legíveis, defina permissions.blockReadsOutsideWorkingDirectories em vez de escrever regras de caminho.

Executar comandos fora do sandbox com `excludedCommands`

Liste um padrão de comando em sandbox.excludedCommands para executar os comandos correspondentes fora do sandbox, o que significa sem restrições de sistema de arquivos e sem proxy de rede. Use-o para uma ferramenta que não funciona dentro do sandbox e à qual você confia seu acesso completo. Uma ferramenta que precisa de mais um diretório ou mais um host pode funcionar com allowWrite ou allowedDomains, que mantêm o comando no sandbox.

Este exemplo tira comandos docker compose do sandbox. Salve-o em ~/.claude/settings.json para aplicá-lo a todos os seus projetos:

{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["docker compose *"]
  }
}

O Claude Code verifica suas entradas em cada chamada de Bash e Monitor. Uma chamada é a linha de comando inteira que o Claude envia, que pode encadear vários comandos. As regras a seguir decidem se uma chamada sai do sandbox:

  • Termine o padrão com *: as entradas usam a mesma sintaxe de uma regra de permissão Bash(...), em que um padrão sem curinga é uma correspondência exata. docker corresponde apenas a docker sem argumentos. docker * corresponde a docker com ou sem argumentos
  • Todo comando na chamada precisa corresponder: npm ci && docker compose build permanece no sandbox, a menos que outra entrada cubra npm ci
  • O Claude Code compara o texto da chamada: um script ou alvo do make que chama docker internamente não corresponde, nem /usr/local/bin/docker
  • Algumas chamadas permanecem no sandbox: um redirecionamento para um arquivo, um cd ou uma substituição de comando como $(...) mantém a chamada inteira no sandbox. A entrada de referência lista mais chamadas que permanecem no sandbox
  • O local onde você salva a entrada pode importar: enquanto o sandbox é exigido pelo administrador, o Claude Code ignora entradas em .claude/settings.json e .claude/settings.local.json

Um comando excluído passa pelo fluxo normal de permissões:

  • Comandos somente leitura e comandos cobertos pelas suas regras de permissão são executados sem prompt
  • No modo auto, o classificador revisa os demais comandos excluídos
  • No modo bypassPermissions, um comando excluído é executado sem prompt, a menos que uma regra ask corresponda a ele

Para confirmar que uma entrada corresponde, mude para o modo Manual e peça ao Claude para executar um comando correspondente que altere algo, como docker compose up -d. O prompt de permissão tem o título "Bash command (unsandboxed)".

Desativar o isolamento do sistema de arquivos

Defina sandbox.filesystem.disabled como true para ignorar o isolamento do sistema de arquivos, mantendo o isolamento de rede. O exemplo abaixo desativa o isolamento do sistema de arquivos, mantendo uma allowlist de domínios de rede:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "disabled": true
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

O sandbox tem duas camadas independentes: o isolamento do sistema de arquivos controla quais caminhos os comandos em sandbox podem ler e gravar, e o isolamento de rede controla quais domínios eles podem alcançar. Com a camada de sistema de arquivos desativada, os comandos em sandbox obtêm acesso irrestrito de leitura e gravação ao sistema de arquivos do host, enquanto seu tráfego de saída de rede permanece restrito aos seus domínios permitidos. Desative a camada quando você usa o sandbox para controlar onde os comandos se conectam, e não o que eles gravam.

sandbox.filesystem.disabled tem false como padrão. Requer o Claude Code v2.1.216 ou posterior.

Quais configurações podem desativá-lo

Como desativar o isolamento do sistema de arquivos amplia o que os comandos em sandbox podem fazer, o Claude Code respeita filesystem.disabled somente a partir destas origens de configurações:

  • Configurações de usuário, configurações gerenciadas e a flag de CLI --settings podem defini-la. Configurações de projeto em .claude/settings.json e .claude/settings.local.json não podem, de modo que um projeto baixado não pode desativar o isolamento do sistema de arquivos.
  • Quando as configurações gerenciadas configuram sandbox.filesystem de qualquer forma, ou listam qualquer entrada sandbox.credentials.files com "mode": "deny", somente as configurações gerenciadas podem definir a chave. Isso mantém em vigor as restrições de sistema de arquivos implantadas pelo administrador; para relaxar tal implantação, defina "disabled": true nas configurações gerenciadas.
  • Quando CLAUDE_CODE_SUBPROCESS_ENV_SCRUB está definida, o Claude Code ignora filesystem.disabled de todas as origens, incluindo as configurações gerenciadas, e mantém o isolamento do sistema de arquivos ativado.

Uma entrada mask válida não trava a chave, mesmo quando o Claude Code recorre ao fallback deny para ela na inicialização. Liste um caminho que não pode ser mascarado, como um diretório de credenciais, como uma entrada deny explícita nas configurações gerenciadas, o que trava a chave.

O que muda quando o isolamento do sistema de arquivos está desativado

Definir filesystem.disabled remove as proteções que a própria camada de sistema de arquivos aplica. As proteções que outras camadas aplicam continuam valendo:

Proteção Com o isolamento do sistema de arquivos desativado
Bloqueios de leitura filesystem.denyRead e deny de credentials.files Não aplicados. A camada de sistema de arquivos aplica ambos
Entradas deny e mask de credentials.envVars Aplicadas. A limpeza de variáveis de ambiente é independente da camada de sistema de arquivos
Entradas mask de credentials.files aplicadas como máscaras Aplicadas: o mascaramento é independente da camada de sistema de arquivos. Uma entrada que recorreu ao fallback deny não é aplicada, como qualquer entrada deny

Duas outras coisas mudam:

  • Os comandos em sandbox herdam o $TMPDIR do seu shell em vez do diretório temporário por usuário, pois todo diretório temporário é gravável e o Claude Code não redireciona mais os comandos para o diretório por usuário.

    No Linux, a variável muitas vezes não está definida no shell pai. A orientação da ferramenta Bash instrui o Claude a criar diretórios de rascunho com mktemp -d em vez de depender de $TMPDIR.

  • autoAllowBashIfSandboxed ainda tem true como padrão, de modo que os comandos em sandbox continuam sendo executados sem prompts. Defina-o como false para solicitar confirmação para comandos em sandbox.

Proteger credenciais

A configuração sandbox.credentials declara arquivos de credenciais e variáveis de ambiente a serem protegidos dos comandos em sandbox. Cada entrada nomeia um caminho de arquivo ou uma variável de ambiente e um mode. O bloco dedicado credentials mantém as regras de credenciais agrupadas e separadas das regras gerais de sistema de arquivos.

Para entradas com "mode": "deny", os caminhos de arquivo têm a leitura negada dentro do sandbox, a mesma restrição que filesystem.denyRead aplica, e as variáveis de ambiente são removidas antes da execução de cada comando em sandbox. A proteção de arquivos faz parte da camada de sistema de arquivos, portanto não se aplica se você desativar o isolamento do sistema de arquivos; a proteção de variáveis de ambiente continua se aplicando.

O exemplo abaixo bloqueia a leitura do arquivo de credenciais da AWS e do diretório SSH e remove GITHUB_TOKEN e NPM_TOKEN do ambiente dos comandos em sandbox:

{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" },
        { "name": "NPM_TOKEN", "mode": "deny" }
      ]
    }
  }
}

Entradas de variáveis de ambiente e entradas de arquivo também aceitam "mode": "mask", descrito em Mascarar credenciais.

Os caminhos de arquivo seguem as mesmas regras de prefixo das configurações sandbox.filesystem.*.

O Claude Code mescla as entradas deny de todos os escopos de configurações que a sessão carrega. Uma entrada deny apenas restringe o acesso, então qualquer escopo pode adicionar uma, mas nenhum escopo pode remover uma que outro escopo adicionou.

Quando você exclui uma origem de configurações:

  • Configurações de projeto ou locais: o Claude Code não aplica nenhuma de suas entradas credentials. Requer o Claude Code v2.1.246 ou posterior.
  • Configurações de usuário: o Claude Code ainda aplica as entradas deny em ~/.claude/settings.json e mantém suas entradas mask de arquivo como restrições que deixam de autorizar o proxy a substituir o valor real, mas descarta suas entradas mask de variáveis de ambiente.

Não há uma lista de negação de credenciais integrada, então somente os arquivos e variáveis que você listar são restringidos.

sandbox.credentials afeta apenas comandos Bash em sandbox. Para remover credenciais de todos os subprocessos independentemente do sandboxing, defina CLAUDE_CODE_SUBPROCESS_ENV_SCRUB.

Mascarar credenciais

Quando você mascara uma credencial, o Claude Code mostra aos comandos em sandbox um valor substituto por sessão chamado sentinela, e o proxy do sandbox substitui o valor real nas requisições de saída para hosts que você permite. Uma entrada deny em Proteger credenciais bloqueia a credencial em vez disso. Para arquivos no macOS, o Claude Code bloqueia o arquivo em vez de mascará-lo.

Mascarar variáveis de ambiente requer o Claude Code v2.1.199 ou posterior. A referência de sandbox.credentials lista todos os campos.

O mascaramento requer o seguinte:

  • Terminação de TLS: o proxy substitui o valor real dentro do conteúdo da requisição, então precisa enxergá-lo. Defina network.tlsTerminate para que o proxy termine o TLS por conta própria. Sem isso, o mascaramento falha sem expor nada: o comando ainda vê apenas o sentinela, mas o sentinela chega ao servidor inalterado e a autenticação falha. O Claude Code relata essa configuração incorreta na inicialização.
  • Um destino permitido: cada entrada mask pode listar injectHosts, os hosts que o valor real tem permissão para alcançar. O proxy injeta apenas em conexões que a allowlist de domínios admite, então cada host de injectHosts também precisa estar acessível por meio de network.allowedDomains. Para uma entrada mask sem injectHosts, o proxy substitui o valor real em requisições para todos os hosts em network.allowedDomains.
  • Um escopo de configurações confiável: o mascaramento autoriza o proxy a enviar sua credencial real para algum lugar, então o Claude Code respeita entradas mask, network.tlsTerminate, credentials.allowPlaintextInject, awsPairs e sigv4 somente a partir de configurações de usuário, configurações gerenciadas e da flag --settings. Ele os ignora no .claude/settings.json ou .claude/settings.local.json de um repositório. Quando seu administrador fornece entradas mask, network.tlsTerminate ou credentials.allowPlaintextInject por meio de configurações gerenciadas pelo servidor, elas contam como configurações que precisam de aprovação.

Mascarar variáveis de ambiente

Para mascarar uma variável de ambiente, defina "mode": "mask" em sua entrada credentials.envVars. O comando e tudo o que ele registra em log nunca contêm a credencial real, mas suas requisições ainda se autenticam. Quando a mesma variável é listada com deny em qualquer escopo, deny tem precedência.

Este exemplo mascara dois tokens. GH_TOKEN é substituído apenas em requisições para api.github.com, enquanto NPM_TOKEN não tem injectHosts e é substituído em requisições para todos os hosts em network.allowedDomains:

{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com", "registry.npmjs.org"]
    },
    "credentials": {
      "envVars": [
        { "name": "GH_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] },
        { "name": "NPM_TOKEN", "mode": "mask" }
      ]
    }
  }
}

O mascaramento substitui o valor inteiro por padrão. Para um valor com estrutura, como uma string de conexão DATABASE_URL ou um JWT, use os campos extract, decode, maskClaims e onExtractNoMatch para que as ferramentas que analisam o valor continuem funcionando.

Para um destino IPv6, escreva o endereço de forma diferente nas duas listas:

  • network.allowedDomains: a forma entre colchetes, como "[::1]"
  • injectHosts: o endereço puro em sua forma canônica comprimida, como "::1"

O proxy compara cada entrada injectHosts com o endereço de destino puro da conexão, ignorando portas, então uma grafia entre colchetes, com ID de zona ou comprimida de outra forma nunca corresponde. claude doctor sinaliza entradas que nunca podem corresponder com o aviso Sandbox credential injectHosts entries can never match their destination. Essa verificação requer o Claude Code v2.1.229 ou posterior.

Reassinar requisições da AWS

As requisições da AWS carregam assinaturas SigV4 sobre o conteúdo da requisição, então mascare AWS_ACCESS_KEY_ID e AWS_SECRET_ACCESS_KEY juntos. O proxy detecta uma requisição SigV4 pelo sentinela da chave de acesso e reassina a requisição com os valores reais, o que requer o Claude Code v2.1.221 ou posterior. Se você mascarar apenas o segredo, as requisições são assinadas com um valor substituto que o proxy não consegue detectar, então elas falham na AWS.

O Claude Code vincula automaticamente as variáveis convencionais AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY e AWS_SESSION_TOKEN em uma única credencial quando você mascara seus valores inteiros. Se sua credencial da AWS estiver em variáveis com outros nomes, agrupe-as com credentials.awsPairs, que requer o Claude Code v2.1.224 ou posterior.

Uploads por streaming, URLs pré-assinadas e requisições SigV4A carregam assinaturas que o proxy não consegue recalcular. Quando uma dessas requisições é assinada com o valor substituto de um par mascarado, o proxy a faz falhar em vez de encaminhar uma assinatura quebrada. Requisições assinadas com credenciais não mascaradas não são afetadas. Use credentials.sigv4, que requer o Claude Code v2.1.224 ou posterior, para encaminhar uma dessas formas de requisição em vez disso. A AWS ainda rejeita a requisição, então a ferramenta chamadora recebe a própria resposta de rejeição da AWS em vez de um erro de proxy.

Mascarar arquivos de credenciais

Para mascarar um arquivo de credenciais, defina "mode": "mask" em sua entrada credentials.files. Mascarar arquivos requer o Claude Code v2.1.221 ou posterior. O que um comando em sandbox vê depende da plataforma:

  • Linux e WSL2: os comandos em sandbox leem uma cópia sentinela do arquivo, e o proxy substitui o valor real nas requisições de saída.
  • macOS: os comandos em sandbox não conseguem ler o arquivo de forma alguma. O Claude Code não cria cópia sentinela, então as ferramentas que se autenticam com o arquivo não funcionam dentro do sandbox, o mesmo efeito de deny. O bloqueio de leitura se mantém mesmo quando você desativa o isolamento do sistema de arquivos.

Este exemplo mascara um token do GitHub armazenado em ~/.config/gh/hosts.yml. O padrão extract marca qual parte do arquivo é o segredo, de modo que, no Linux e no WSL2, o gh ainda analisa o restante de sua configuração:

{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com"]
    },
    "credentials": {
      "files": [
        {
          "path": "~/.config/gh/hosts.yml",
          "mode": "mask",
          "extract": "oauth_token:\\s*(\\S+)",
          "injectHosts": ["api.github.com"]
        }
      ]
    }
  }
}

Para confirmar que a máscara está ativa, peça ao Claude para executar cat ~/.config/gh/hosts.yml em um comando em sandbox. No Linux e no WSL2, a saída mostra um sentinela no lugar do token, e no macOS a leitura falha.

Sem extract ou decode, o Claude Code substitui o arquivo inteiro por um único sentinela, o que é adequado para um arquivo que contém um único segredo simples. Use os campos extract, decode, maskClaims, onExtractNoMatch e maskDuplicates para controlar o mascaramento parcial e o que acontece quando o padrão não corresponde a nada.

mask se aplica a um único arquivo, então liste cada arquivo de credenciais individualmente. O Claude Code recorre a deny como fallback para uma entrada mask que não consegue mascarar com segurança: um caminho de diretório, um padrão glob, um arquivo maior que 8 MiB ou um arquivo que não é texto UTF-8.

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, a quaisquer diretórios que você tenha adicionado com --add-dir, /add-dir ou permissions.additionalDirectories, além do diretório temporário por usuário para o qual $TMPDIR aponta
  • Comportamento padrão de leitura: acesso de leitura a todo o computador, exceto a certos diretórios negados. Esse padrão ainda permite a leitura de arquivos de credenciais, então proteja as credenciais que você não quer que os comandos leiam.
  • Bloqueio de leitura: com permissions.blockReadsOutsideWorkingDirectories ativado, os comandos em sandbox também perdem o acesso de leitura ao seu diretório pessoal e aos outros diretórios que contêm arquivos do usuário, exceto os caminhos listados em Comandos em sandbox sob o bloqueio. Essa seção também informa quando essa parte do bloqueio não se aplica.
  • Git worktrees: quando o diretório de trabalho é um worktree git 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. Escritas em hooks/ e config dentro desse diretório continuam negadas.

Para ignorar completamente o isolamento do sistema de arquivos mantendo o isolamento de rede, defina sandbox.filesystem.disabled.

Caminhos protegidos

Dentro dos diretórios nos quais os comandos em sandbox podem escrever, o sandbox ainda nega escritas nos arquivos dos quais o Claude Code carrega configuração e código. Um comando que pudesse editar esses arquivos poderia conceder permissões a si mesmo, ou adicionar um hook ou servidor MCP que o Claude Code executa fora do sandbox. O sistema de permissões tem seus próprios caminhos protegidos, que controlam o que o Claude Code aprova antes de uma ferramenta ser executada; a lista do sandbox se aplica a um comando que já está em execução. Ela abrange quatro grupos de caminhos:

  • No seu diretório de trabalho e nos diretórios acima dele: os arquivos de configuração .claude, os diretórios .claude/skills, .claude/agents, .claude/commands e .claude/hooks, .mcp.json e os arquivos que o Claude Code executa por conta própria, como .claude/workflows e .claude/scheduled_tasks.json
  • Somente no seu diretório de trabalho: arquivos de inicialização do shell, como .bashrc e .zshrc, .gitconfig, os diretórios .vscode e .idea, e hooks e config dentro de .git
  • Arquivos que transformariam seu diretório de trabalho em um repositório git bare: HEAD, objects e refs no nível superior, além das entradas config e hooks existentes ali quando há um HEAD ao lado delas. Um arquivo chamado config é negado mesmo sem HEAD. No Linux e no WSL2, o sandbox exclui um arquivo HEAD ou um diretório objects ou refs de nível superior que apareça enquanto um comando em sandbox está em execução
  • Em ~/.claude, ou no diretório para o qual CLAUDE_CONFIG_DIR aponta: a maior parte de seu conteúdo, além de ~/.claude.json e do armazenamento de credenciais .credentials.json

Se um link simbólico aparecer no caminho de um arquivo de configuração protegido durante a sessão, o sandbox também nega escritas no arquivo para o qual ele aponta, a partir do próximo comando.

Não há como isentar um desses caminhos: uma entrada allowWrite ou uma regra de permissão allow de Edit que abranja o caminho não remove a proteção. A única forma de desativar a proteção é filesystem.disabled, que desativa o isolamento do sistema de arquivos para todos os caminhos. Para ver a maioria desses caminhos resolvidos para a sua máquina, execute /sandbox e abra a aba Config, que os lista em Denied within allowed, misturados com suas próprias entradas denyWrite.

Se git merge ou git checkout falhar com unable to unlink old em um desses caminhos, consulte Um comando git falha com unable to unlink old.

Isolamento de rede

Um comando em sandbox não tem rota direta para a rede:

  • Linux e WSL2: o comando é executado em um namespace de rede separado que não tem conexão com a sua rede
  • macOS: o framework de sandbox Seatbelt, por padrão, bloqueia conexões que não sejam a conexão com o proxy do sandbox

O Claude Code executa o proxy do sandbox na sua máquina, fora do sandbox, e direciona os comandos para ele com HTTP_PROXY, HTTPS_PROXY, ALL_PROXY e variáveis de ambiente relacionadas. O proxy verifica o hostname de cada conexão em relação aos seus domínios permitidos e negados.

O que uma ferramenta pode alcançar depende de ela usar o proxy:

  • Ferramentas que leem as variáveis de proxy: curl, npm, git via HTTPS e ferramentas semelhantes se conectam assim que seu host é permitido. Uma entrada allowedDomains sem porta permite todas as portas desse host
  • Ferramentas que ignoram as variáveis de proxy: ssh simples, a maioria dos drivers de banco de dados e ferramentas semelhantes não conseguem se conectar, mesmo a um host permitido. Consulte Um cliente de banco de dados ou outra ferramenta não HTTP não consegue alcançar um host permitido
  • Qualquer coisa que não seja TCP: UDP, HTTP/3 sobre QUIC e ferramentas ICMP como ping não conseguem sair do sandbox

As seguintes configurações e comportamentos controlam quais hosts o proxy permite:

  • Restrições de domínio: seus domínios permitidos começam vazios. Hosts fora dos seus domínios permitidos aborda o que acontece na primeira vez que um comando precisa de um novo domínio.
  • Opções de aprovação: se você escolher Yes quando solicitado, o Claude Code permite o host pelo restante da sessão atual. Se você escolher "Yes, and don't ask again", o Claude Code salva uma regra de permissão allow WebFetch(domain:...) nas suas configurações locais, para que o host continue permitido em sessões futuras. Enquanto o sandbox for exigido pelo administrador, o Claude Code salva a regra nas suas configurações de usuário, onde ela se aplica em todos os projetos.
  • Domínios pré-permitidos: pré-permita domínios com allowedDomains para evitar o prompt completamente. O Claude Code também pré-permite domínios de regras de permissão allow WebFetch(domain:...), conforme descrito em Regras de permissão.
  • Allowlist estrita: se você definir strictAllowlist como true nas configurações de usuário, gerenciadas ou de --settings da CLI, o Claude Code nega aos comandos em sandbox o acesso a qualquer host fora da allowlist em vez de solicitar confirmação. A allowlist é allowedDomains mais os domínios de regras de permissão allow WebFetch(domain:...), ou apenas as entradas das configurações gerenciadas quando allowManagedDomainsOnly está definido. Bloqueios que se aplicam sem um sandbox exigido pelo administrador aborda as entradas de um repositório. O Claude Code aplica isso somente a comandos em sandbox; ferramentas em processo, como WebFetch, continuam seguindo suas regras de permissão. Defini-la no .claude/settings.json ou .claude/settings.local.json de um repositório não tem efeito. Requer Claude Code v2.1.219 ou posterior.
  • Bloqueio gerenciado: se allowManagedDomainsOnly estiver definido nas configurações gerenciadas, domínios não permitidos são bloqueados automaticamente em vez de solicitar confirmação, e somente allowedDomains e as regras de permissão allow WebFetch(domain:...) das configurações gerenciadas são respeitados.
  • Proxy corporativo: quando sua rede exige que o tráfego de saída passe por um proxy corporativo, defina HTTPS_PROXY, HTTP_PROXY e NO_PROXY conforme descrito em configuração de proxy, no bloco env das suas configurações, para que os agentes em segundo plano também as recebam, ou no ambiente a partir do qual você inicia o Claude Code. O Claude Code aplica a allowlist de domínios e então encaminha por túnel as conexões permitidas através desse proxy upstream. URLs de proxy http:// e https:// funcionam, com autenticação básica na URL se você precisar.

Em uma regra WebFetch(domain:...), o sandbox respeita duas formas de curinga: um *. inicial, como *.example.com, e um * isolado. A forma * isolada requer Claude Code v2.1.186 ou posterior. Um curinga em qualquer outra posição, como WebFetch(domain:example.*), ainda corresponde a fetches, mas não tem efeito sobre comandos em sandbox.

Hosts fora dos seus domínios permitidos

Quando um comando em sandbox se conecta a um host que não está nos seus domínios permitidos, o comando permanece no sandbox e aguarda uma decisão. Em uma sessão de terminal interativa, a decisão depende do seu modo de permissão:

Modo de permissão O que acontece com a conexão
Modo bypassPermissions e modo de planejamento com bypass de permissões disponível Permitida sem prompt
Modo manual, modo acceptEdits e modo de planejamento nos demais casos Você recebe um prompt
Modo auto Recusada, a menos que o comando tenha listado o host e o classificador tenha aprovado a lista
Modo dontAsk Recusada

Com strictAllowlist ou allowManagedDomainsOnly ativado, o proxy integrado do sandbox recusa a conexão em todos os modos de permissão. No modo bypassPermissions, hosts fora dos seus domínios permitidos são permitidos, a menos que um deles esteja ativado. A saída de emergência de nova tentativa fora do sandbox aborda quando um comando pode sair do sandbox nesse modo. Uma conexão com um host em deniedDomains também é recusada em todos os modos de permissão.

Hostnames que resolvem para endereços locais

Depois que um hostname passa pela allowlist, o proxy do sandbox o resolve e recusa a conexão quando o nome resolve apenas para endereços locais. Endereços locais incluem endereços de loopback como 127.0.0.1, endereços link-local como o endpoint de metadados de nuvem 169.254.169.254 e endereços atribuídos à sua própria máquina. Os nomes localhost e *.localhost podem resolver para loopback.

Um hostname de intranet permitido que resolve para um intervalo privado como 10.0.0.0/8 se conecta. Para permitir que um nome resolva para um endereço recusado, adicione esse endereço IP a allowedDomains, como "127.0.0.1:8080".

A verificação se aplica a hostnames. Seus domínios permitidos e seu modo de permissão decidem uma conexão com um endereço IP. O proxy também ignora a verificação para conexões que ele envia através de um proxy corporativo upstream, porque esse proxy resolve o nome.

Domínios permitidos por comando no modo auto

No modo auto com o sandboxing ativado, o Claude nomeia os hosts de que um comando precisa no próprio comando, em vez de acionar uma aprovação de rede para cada conexão. Cada comando Bash, PowerShell ou Monitor executado no sandbox pode carregar uma lista de hosts além da allowlist do sandbox: um domínio como registry.npmjs.org, um curinga como *.pythonhosted.org ou um endereço IP, cada um com um :port opcional. O classificador revisa os hosts junto com o comando. Requer Claude Code v2.1.271 ou posterior.

Uma lista aprovada abre esses hosts apenas para aquele comando, enquanto ele estiver em execução. Nada é adicionado aos hosts permitidos da sua sessão nem às suas configurações; o próximo comando nomeia seus próprios hosts.

Um comando que carrega hosts vai para o classificador em vez de ser aprovado por uma regra de permissão ou pelo modo de permissão automática do sandbox. Se uma regra ask forçar um prompt para o comando, a caixa de diálogo de permissão no seu terminal lista os hosts ao lado dele, e aprovar ali abrange ambos.

Uma lista por comando amplia apenas o que o sandbox nega por padrão. As entradas de deniedDomains continuam bloqueando. Quando strictAllowlist ou allowManagedDomainsOnly bloqueia a allowlist, o Claude Code recusa listas por comando.

Enquanto as listas por comando se aplicam, o Claude Code recusa uma conexão com um host que nenhum comando aprovado listou, sem prompt nem verificação do classificador. A recusa nomeia o host no resultado do comando, e o Claude executa o comando novamente com o host adicionado.

Endereços IPv6 em listas de domínios

Para corresponder a um endereço IPv6 em allowedDomains, deniedDomains ou em uma regra WebFetch(domain:...), escreva o endereço entre colchetes: "[::1]" corresponde a esse endereço em todas as portas, e "[::1]:443" corresponde a ele apenas na porta 443. A forma entre colchetes requer Claude Code v2.1.229 ou posterior.

Uma entrada sem colchetes como ::1:443 é ambígua entre um endereço e um endereço com uma porta:

  • Listas de negação: o Claude Code nega todas as leituras possíveis da entrada, de modo que qualquer que seja a leitura pretendida, ela é bloqueada. Para uma entrada sem nenhuma leitura analisável, o Claude Code não bloqueia nada
  • Listas de permissão: o Claude Code nunca permite mais do que você escreveu. Ele reescreve uma entrada ambígua para sua leitura de host e porta quando essa leitura é analisada corretamente, e pode descartar a entrada completamente em vez de ampliar a allowlist

Para encontrar entradas ambíguas, execute claude doctor no seu terminal e procure o aviso Sandbox network domain entries have unreliable spellings. Reescreva cada entrada ambígua na forma entre colchetes.

Aplicação no nível do sistema operacional

A ferramenta Bash em sandbox usa primitivas de segurança do sistema operacional:

  • macOS: usa o Seatbelt para a aplicação do sandbox
  • Linux: usa o bubblewrap para isolamento
  • WSL2: usa o bubblewrap, assim como o Linux

Você também pode executar o pacote @anthropic-ai/sandbox-runtime de forma independente para envolver o processo do Claude Code. Consulte Sandbox runtime.

Como o 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 cobrem 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 o 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, exceto que uma regra de negação ou pergunta não pode bloquear EndConversation enquanto qualquer outra ferramenta permanecer.
  • Sandboxing fornece aplicação em nível de SO que restringe o que os comandos shell podem acessar no nível do sistema de arquivos e rede. Aplica-se apenas aos comandos Bash, PowerShell e Monitor e seus processos filhos.

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

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

Configuração ou regra O que faz
sandbox.filesystem.allowWrite Concede acesso de escrita ao subprocesso para caminhos fora do diretório de trabalho
sandbox.filesystem.denyWrite e sandbox.filesystem.denyRead Bloqueiam acesso do subprocesso a caminhos específicos
sandbox.filesystem.allowRead Permite novamente a leitura de caminhos específicos dentro de uma região denyRead
sandbox.filesystem.disabled Desativa a camada de sistema de arquivos inteiramente enquanto mantém isolamento de rede
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 WebFetch(domain:...) Controlam acesso a domínios
allowedDomains do Sandbox Controla quais domínios os comandos Bash podem alcançar
deniedDomains do Sandbox Bloqueia domínios específicos mesmo quando um wildcard allowedDomains mais amplo permitiria de outra forma

Caminhos e domínios das configurações de sandbox e regras de permissão são mesclados 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, em modo auto-allow
Modo automático 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; as ações que nenhum modo auto-aprova ainda se aplicam

O modo auto-allow do sandbox é separado do modo automático: auto-allow aprova comandos Bash porque o limite do sandbox os contém, enquanto modo automático usa um classificador para revisar ações. Os dois funcionam independentemente e podem ser combinados, com as exceções listadas em Modos de sandbox. Para escolher um limite de isolamento para execuções autônomas, consulte Ambientes de sandbox. Para uma tabela de emparelhamentos comuns de modo de permissão e sandbox com os sinalizadores que iniciam cada um, consulte Configurações comuns.

Configure o sandbox para sua organização

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.

Imponha o sandboxing com configurações gerenciadas

Para exigir o sandbox para cada desenvolvedor, entregue as chaves sandbox através de configurações gerenciadas, seja como um arquivo gerenciado pelo seu MDM ou através de configurações gerenciadas pelo servidor no claude.ai.

A seguinte configuração de configurações gerenciadas habilita o sandbox, recusa iniciar o Claude Code quando a plataforma não é suportada ou uma dependência está faltando 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 impede o Claude Code de iniciar em vez de recorrer à execução sem sandbox
  • allowUnsandboxedCommands: false: o Claude Code ignora o escape hatch dangerouslyDisableSandbox, portanto quando um comando falha sob o sandbox, Claude não consegue tentá-lo novamente sem sandbox

Considere estas adições junto com elas:

Esta configuração coloca em sandbox os comandos que Claude executa. Um desenvolvedor ainda pode digitar um comando no prompt de shell-mode com ! e executá-lo fora do sandbox, com o mesmo acesso que já possui em qualquer terminal fora do Claude Code. Veja modo de sandbox estrito para as sessões onde comandos digitados são executados em sandbox.

O sandbox não é executado no Windows nativo, portanto com failIfUnavailable definido, o Claude Code encerra na inicialização nessas máquinas. Se sua frota inclui hosts Windows, você pode:

Impeça que desenvolvedores ampliem a política

Quando as configurações gerenciadas definem uma chave booleana como enabled ou failIfUnavailable, o Claude Code usa o valor gerenciado e ignora qualquer coisa que um desenvolvedor defina localmente. Para chaves de array como allowRead, o Claude Code mescla entradas dos escopos que a sessão carrega, portanto um desenvolvedor pode anexar entradas que ampliem a política, a menos que um bloqueio cubra essa chave.

A menos que as configurações gerenciadas as definam, as configurações de usuário de um desenvolvedor ou --settings podem ativar as seguintes chaves. O .claude/settings.json de um repositório também pode, a menos que o sandbox seja exigido pelo administrador. Cada uma enfraquece o sandbox, portanto defina-a como false nas configurações gerenciadas se você não quiser que seja usada:

Defina allowManagedReadPathsOnly como true nas configurações gerenciadas para que apenas entradas allowRead das configurações gerenciadas sejam honradas. 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. Com o bloqueio ativado, apenas as configurações gerenciadas podem definir uma porta de proxy.

Quando as configurações gerenciadas configuram sandbox.filesystem ou listam qualquer entrada sandbox.credentials.files com "mode": "deny", apenas as configurações gerenciadas podem definir filesystem.disabled, portanto desenvolvedores não conseguem desativar restrições de filesystem implantadas pelo administrador. Uma entrada mask válida não bloqueia a chave. Veja Quais configurações podem desativá-lo.

Configurações do repositório sob um sandbox exigido pelo administrador

O sandbox é exigido pelo administrador enquanto uma destas configurações estiver em vigor:

  • allowUnsandboxedCommands definido como false nas configurações gerenciadas, ou com a flag --settings, a menos que as configurações gerenciadas o definam como true
  • allowManagedDomainsOnly definido como true nas configurações gerenciadas

Essas configurações não ativam o sandbox, portanto defina enabled também.

Enquanto o sandbox é exigido pelo administrador, o Claude Code aceita as configurações que o afrouxam apenas das configurações gerenciadas, da flag --settings e do ~/.claude/settings.json de cada desenvolvedor. Ele ignora estas configurações no .claude/settings.json e no .claude/settings.local.json de um repositório:

Configuração do repositório O que o Claude Code ignora
excludedCommands, ignoreViolations, network.allowedDomains, network.allowUnixSockets, network.allowMachLookup, network.httpProxyPort, network.socksProxyPort Todas as entradas
filesystem.allowWrite, regras de permissão Edit(...), permissions.additionalDirectories O acesso de escrita que cada entrada concede a comandos em sandbox. As ferramentas de arquivo do Claude ainda seguem as regras Edit(...) e os diretórios adicionais
Regras de permissão WebFetch(domain:...) O host que cada regra adiciona à allowlist do sandbox. A ferramenta WebFetch ainda segue a regra
enableWeakerNestedSandbox, enableWeakerNetworkIsolation, network.allowAllUnixSockets, network.allowLocalBinding true. Um false ainda se aplica
enabled, failIfUnavailable false, quando o ~/.claude/settings.json do desenvolvedor define true
filesystem.allowRead Uma entrada em ou sob um caminho cuja leitura as configurações gerenciadas, --settings ou as configurações de usuário negam, ou um glob que possa corresponder a um

Estas configurações ainda se aplicam enquanto o sandbox é exigido pelo administrador:

  • Nos arquivos de um repositório: entradas de negação e o valor de autoAllowBashIfSandboxed. Defina a chave nas configurações gerenciadas para impedir que um repositório a altere
  • Nas configurações do próprio desenvolvedor: as configurações da tabela ainda se aplicam a partir de ~/.claude/settings.json ou --settings, a menos que um bloqueio exclusivo das configurações gerenciadas, como allowManagedDomainsOnly, as cubra. A maioria delas, como excludedCommands e filesystem.allowWrite, não tem bloqueio exclusivo das configurações gerenciadas

A configuração em Imponha o sandboxing com configurações gerenciadas torna o sandbox exigido pelo administrador. Adicione às configurações gerenciadas as entradas excludedCommands, allowWrite e de sockets de que suas ferramentas aprovadas precisam, porque um repositório não pode fornecê-las.

Requer Claude Code v2.1.285 ou posterior. Da v2.1.282 à v2.1.284, as mesmas configurações faziam o Claude Code ignorar as entradas excludedCommands de um repositório.

Bloqueios que se aplicam sem um sandbox exigido pelo administrador

Algumas configurações fazem o Claude Code ignorar as chaves do repositório que sobrescrevem diretamente uma restrição, mesmo quando o sandbox não é exigido pelo administrador. Cada uma tem esse efeito apenas quando você a define em um arquivo indicado em sua linha, e as outras configurações de sandbox do repositório ainda se aplicam. Requer Claude Code v2.1.285 ou posterior.

Configuração Onde você a define O que o Claude Code ignora nas configurações de um repositório
network.deniedDomains ou uma regra de negação WebFetch(domain:...) Configurações gerenciadas, --settings httpProxyPort e socksProxyPort
network.strictAllowlist Configurações gerenciadas, --settings, configurações de usuário As portas de proxy, allowedDomains e regras de permissão WebFetch(domain:...)
filesystem.denyRead, uma regra de negação Read(...) ou uma entrada credentials.files Configurações gerenciadas, --settings Uma entrada allowRead, allowWrite, de permissão Edit(...) ou additionalDirectories em ou sob um caminho cuja leitura as configurações gerenciadas, --settings ou as configurações de usuário negam, ou um glob que possa corresponder a um

Esses bloqueios alteram o que os comandos em sandbox podem alcançar. A ferramenta WebFetch e as ferramentas de arquivo do Claude ainda seguem as regras e os diretórios adicionais de um repositório.

Configuração de proxy personalizado

Para inspecionar, filtrar ou registrar em log o tráfego do sandbox com suas próprias ferramentas, substitua o proxy integrado do sandbox por um proxy que você executa na mesma máquina.

Para rotear o tráfego do sandbox através de um proxy corporativo em outro lugar da sua rede, defina HTTPS_PROXY em vez disso, como descreve a entrada Corporate proxy em Isolamento de rede. Dessa forma, a allowlist do Claude Code ainda se aplica.

Para direcionar comandos em sandbox para seu proxy, defina as portas de localhost em que ele escuta nas configurações do sandbox:

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

Se você definir uma porta e também definir HTTPS_PROXY ou HTTP_PROXY, o Claude Code não encaminha o que os comandos em sandbox enviam ao seu proxy para o proxy indicado por essas variáveis. Para alcançar um proxy corporativo, configure seu próprio proxy para encaminhar para ele.

Quais arquivos podem definir uma porta depende das suas outras configurações de sandbox. Aplica-se o primeiro caso que corresponder:

  • allowManagedDomainsOnly está ativado: apenas configurações gerenciadas
  • O sandbox é exigido pelo administrador, ou um bloqueio de rede mais restrito se aplica: configurações gerenciadas, --settings e configurações de usuário
  • Caso contrário: qualquer arquivo de configurações

O Claude Code ignora uma porta definida em qualquer outro lugar. Antes da v2.1.285, qualquer arquivo de configurações podia definir uma porta.

Solução de problemas

Alguns comandos falham dentro do sandbox mesmo que funcionem fora dele. Encontre o título que corresponde ao seu sintoma ou mensagem de erro.

Se o sandbox da sua organização for exigido pelo administrador, o Claude Code ignora as configurações que essas correções mencionam nos arquivos de configurações de um projeto, então salve-as em ~/.claude/settings.json, onde elas se aplicam em todos os projetos. Se uma correção ainda não tiver efeito, as configurações gerenciadas da sua organização podem definir essa chave.

Uma correção que adiciona um padrão a excludedCommands remove o sandbox dos comandos que correspondem ao padrão. Consulte o que um comando excluído pode fazer.

Comandos falham com um erro host-not-allowed

Muitas ferramentas CLI precisam alcançar hosts específicos. Aprove o host quando solicitado ou adicione-o a allowedDomains. Se a sua organização bloquear a allowlist com allowManagedDomainsOnly, não há prompt, então peça ao seu administrador para adicionar o host.

`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. Para executar essas ferramentas fora do sandbox, adicione um padrão para cada ferramenta, como gh *, a excludedCommands. A ferramenta então é executada com seu acesso completo e suas credenciais armazenadas. Se você estiver usando httpProxyPort com um proxy MITM e CA personalizado, defina enableWeakerNetworkIsolation como true em vez disso.

`open`, `osascript`, ou fluxos de autenticação baseados em navegador falham com erro `-600` no macOS

O sandbox bloqueia Apple Events por padrão. Defina allowAppleEvents como true em suas configurações de usuário, gerenciadas ou CLI para permiti-los. O Claude Code ignora esta chave nas configurações do projeto.

Habilitar allowAppleEvents remove o isolamento de execução de código, pois comandos em sandbox podem então iniciar outras aplicações sem sandbox sem prompt do usuário e enviar comandos AppleScript para aplicações em execução, sujeito ao prompt de consentimento de automação do macOS (TCC). Alternativamente, adicione um padrão como open * a excludedCommands. Cada chamada de open então passa pelo fluxo de permissão, e open pode iniciar qualquer arquivo ou aplicativo, incluindo um que o Claude escreveu.

Comandos `docker` falham

docker é incompatível com o sandbox. Tire do sandbox os comandos docker de que você precisa com um padrão em excludedCommands, como docker compose *. Executar comandos fora do sandbox com excludedCommands explica o que um comando docker excluído pode alcançar. Um padrão mais restrito tira menos comandos do sandbox.

`pbcopy`, `xclip`, ou `wl-copy` não atualiza a área de transferência

Os utilitários de área de transferência pbcopy, xclip e wl-copy podem falhar ao alcançar a área de transferência do sistema de dentro do sandbox, caso em que o texto canalizado para eles não chega.

Para colocar a saída do Claude em sua área de transferência, peça ao Claude para imprimi-la em sua resposta e execute /copy. /copy escreve na área de transferência do processo Claude Code em vez de um comando em sandbox.

Quando Claude canaliza texto para uma dessas ferramentas, adicionar a ferramenta a excludedCommands não tira essa chamada do sandbox por si só.

git merge, git checkout e comandos similares falham com unable to unlink old quando precisam substituir um arquivo no qual o sandbox nega gravações. No Linux e WSL2 o erro termina com Read-only file system. O arquivo pode estar em um destes lugares:

  • Sob um caminho protegido como .claude/skills
  • Sob uma de suas entradas denyWrite
  • Fora dos diretórios em que o sandbox permite que comandos gravem

Após a falha, Claude pode oferecer executar novamente o comando fora do sandbox. Aprove essa nova tentativa ou execute o comando git você mesmo em outro terminal. Se você definiu allowUnsandboxedCommands como false, Claude não pode oferecer a nova tentativa, então execute o comando você mesmo.

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, então comandos em sandbox falham com um erro bwrap como Can't mount proc on /newroot/proc: Operation not permitted. Defina enableWeakerNestedSandbox como true para que o sandbox 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 a configuração expõe informações de processo a comandos em sandbox que uma montagem /proc fresca ocultaria.

Arquivos somente leitura de 0 bytes aparecem em caminhos de configurações `.claude`, e "Sim, e não pergunte novamente" não salva

No Linux e WSL2, o sandbox mantém uma negação de gravação em um arquivo que ainda não existe criando um espaço reservado somente leitura de 0 bytes lá enquanto um comando em sandbox é executado. O sandbox remove o espaço reservado depois. Se uma sessão for encerrada antes dessa limpeza ser executada, por exemplo por SIGKILL, os espaços reservados permanecem. Sessões posteriores vinculam os espaços reservados como somente leitura novamente a cada início, então uma gravação de configurações como salvar uma escolha de permissão falha em um caminho onde um espaço reservado permanece.

Execute claude doctor no seu terminal para listar os arquivos de espaço reservado restantes. O aviso Stale sandbox mask files left by a killed session nomeia alguns deles e conta o resto. Delete cada arquivo com rm enquanto nenhuma outra sessão Claude Code está sendo executada nesse projeto. Antes da v2.1.257, Claude Code deixava os mesmos espaços reservados para trás sem sinalizá-los.

`git` via SSH falha com o sandbox ativado

No macOS, git fetch, git pull e git push contra um remoto SSH falham dentro do sandbox mesmo quando o host é permitido. No Linux e WSL2, eles funcionam assim que o host é permitido. O Claude Code encaminha a conexão SSH do git por um túnel através do proxy do sandbox, e o túnel do macOS não consegue se autenticar nesse proxy.

No Linux e WSL2, verifique estes pontos se a conexão ainda falhar:

  • O host é permitido na porta 22: uma entrada em allowedDomains sem porta, como "git.example.com", cobre isso
  • Seu proxy corporativo permite a porta 22: se a sua rede exigir um proxy upstream, o túnel também passa por ele
  • A chave pode ser lida como arquivo: o sandbox pode bloquear o socket do ssh-agent, e uma entrada denyRead ou credentials para ~/.ssh oculta seus arquivos de chave

No macOS, mude o remoto para HTTPS, o que exige credenciais HTTPS, como um token de acesso pessoal:

git remote set-url origin https://git.example.com/example-org/example-repo.git

Se você precisar manter o remoto SSH, tire os comandos de rede do git do sandbox com excludedCommands:

{
  "sandbox": {
    "excludedCommands": ["git fetch *", "git pull *", "git push *"]
  }
}

Essas entradas correspondem a git push origin main. Uma chamada que adiciona um cd, usa git -C ou contém uma substituição de comando permanece no sandbox. Os comandos git excluídos podem alcançar qualquer host, não apenas os que estão em allowedDomains.

ssh, scp e rsync simples via SSH falham pelo motivo que a entrada sobre clientes de banco de dados apresenta.

Um cliente de banco de dados ou outra ferramenta não HTTP falha ao alcançar um host permitido

Uma ferramenta que ignora as variáveis de ambiente de proxy não consegue se conectar de dentro do sandbox, mesmo a um host em allowedDomains. Um comando em sandbox não tem rota direta para a rede, então uma ferramenta que abre sua própria conexão falha. A maioria dos drivers de banco de dados, o ssh simples e ferramentas que usam UDP se comportam dessa forma.

A falha se parece com um erro de rede ou de resolução de nomes:

  • macOS: Operation not permitted, ou um erro de resolução de nomes como Could not resolve host
  • Linux e WSL2: Network is unreachable, ou um erro de resolução de nomes como Temporary failure in name resolution

Uma ferramenta que usa o proxy falha de forma diferente quando seu host não é permitido. Você recebe um prompt de rede, ou a ferramenta recebe uma resposta 403 do proxy.

Para permitir que a ferramenta se conecte, execute o comando que precisa dela fora do sandbox com excludedCommands. Este exemplo exclui um script e adiciona uma regra ask para que você aprove cada execução:

{
  "sandbox": {
    "excludedCommands": ["python scripts/load_orders.py *"]
  },
  "permissions": {
    "ask": ["Bash(python scripts/load_orders.py *)"]
  }
}

O script é executado com seu acesso completo, e o Claude pode editar um script que esteja dentro do seu diretório de trabalho, então revise-o quando o prompt aparecer.

Um comando falha ao alcançar um servidor em localhost

Por padrão, um comando em sandbox não consegue se conectar diretamente a um servidor que está em execução na sua máquina fora do sandbox, como um servidor de desenvolvimento ou um banco de dados em um container. O que você pode alterar depende da sua plataforma:

  • macOS: defina network.allowLocalBinding como true. Comandos em sandbox podem então escutar em portas de rede e se conectar a qualquer porta em localhost, o que inclui todos os outros serviços escutando ali. Um serviço em localhost que não exige autenticação, como um depurador, pode então agir em nome do comando fora do sandbox, e um comando que escuta em um endereço que não é de loopback aceita conexões de outras máquinas
  • Linux e WSL2: o localhost de um comando em sandbox é privado para esse comando. O comando pode escutar em uma porta e alcançar servidores que ele mesmo iniciou. Uma conexão direta a localhost ou 127.0.0.1 não alcança servidores no host, e allowLocalBinding não tem efeito. Execute o comando que precisa do servidor do host fora do sandbox com excludedCommands, onde ele não tem limites de sistema de arquivos ou de rede. Para conexões que passam pelo proxy do sandbox, consulte Nomes de host que resolvem para endereços locais

Este exemplo ativa a configuração para macOS:

{
  "sandbox": {
    "network": {
      "allowLocalBinding": true
    }
  }
}

Uma entrada em allowedDomains para localhost se aplica a conexões que passam pelo proxy, então ela não altera uma conexão direta. O Claude Code define NO_PROXY para comandos em sandbox para que eles se conectem a localhost diretamente em vez de através do proxy. A entrada também expõe todas as portas do localhost da sua máquina a um comando que usa o proxy. Para um nome de host de desenvolvimento que aponta para 127.0.0.1, consulte Um nome de host permitido é recusado com resolved to a loopback address.

Um nome de host permitido é recusado com `resolved to a loopback address`

O proxy do sandbox recusa um nome de host permitido que resolve para um endereço local, o que afeta nomes de desenvolvimento como myapp.test que apontam para 127.0.0.1. O comando vê uma resposta 403 cujo corpo indica o tipo de endereço, como Connection to myapp.test blocked: resolved to a loopback address.

Adicione o endereço IP para o qual o nome resolve junto com o nome de host em allowedDomains, cada um com a porta em que seu servidor escuta:

{
  "sandbox": {
    "network": {
      "allowedDomains": ["myapp.test:3000", "127.0.0.1:3000"]
    }
  }
}

Uma entrada de endereço IP sem porta permite que comandos em sandbox alcancem todos os serviços escutando nesse endereço.

Antes da v2.1.284, o proxy se conectava a qualquer endereço para o qual um nome de host permitido resolvesse.

`/sandbox` falha com `Sandbox settings are overridden by a higher-priority configuration`

/sandbox imprime Error: Sandbox settings are overridden by a higher-priority configuration and cannot be changed locally. em vez de abrir seu painel quando um nível de configurações superior define sandbox.enabled, sandbox.autoAllowBashIfSandboxed ou sandbox.allowUnsandboxedCommands. O painel salva suas escolhas em .claude/settings.local.json, e um valor salvo ali não pode sobrescrever esses níveis.

As configurações gerenciadas e --settings têm prioridade sobre as configurações locais. Para ver quais delas esta sessão carregou, execute /status e leia a linha Setting sources:

  • Command line arguments: se você iniciou o Claude Code com --settings, verifique se o arquivo ou JSON que você passou define uma dessas chaves. Se definir, altere o valor ali ou inicie o Claude Code novamente sem essas chaves.
  • Enterprise managed settings: as configurações gerenciadas da sua organização estão carregadas. Se elas definirem uma dessas chaves, você não pode alterar essa chave pelo /sandbox nem por nenhum arquivo de configurações que você controla, então consulte seu administrador.

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 sandbox restringe quais domínios os processos podem se conectar. Por padrão, o proxy integrado não termina ou inspeciona TLS no tráfego de saída, portanto o conteúdo de conexões criptografadas não é examinado. A configuração experimental network.tlsTerminate termina TLS no proxy para substituição de credenciais mask, mas não adiciona filtragem de conteúdo. 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 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. Esta opção enfraquece consideravelmente a segurança e deve ser usada apenas quando isolamento adicional é de outra forma imposto.
  • Apple Events no macOS: o sandbox macOS bloqueia Apple Events por padrão. A configuração allowAppleEvents remove essa restrição para que ferramentas como open e osascript funcionem, mas remove isolamento de execução de código: comandos em sandbox podem iniciar outras aplicações sem sandbox sem nenhum prompt do usuário, e podem enviar comandos AppleScript para aplicações em execução, sujeito ao prompt de consentimento de automação macOS por aplicativo (TCC). Isso é apenas honrado a partir de configurações de usuário, gerenciadas ou CLI. Configurações de projeto não podem habilitá-lo.

Escopo

O sandbox isola comandos de shell e seus processos filhos. O que é executado fora do sandbox lista as ferramentas e os processos auxiliares que ele não cobre. Computer use e subagentes se relacionam com o sandbox da seguinte forma:

  • 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.
  • Subagentes: subagentes são executados no mesmo processo que a sessão pai e usam a mesma configuração de sandbox. Comandos Bash dentro de um subagente são colocados em sandbox quando sandboxing está habilitado na sessão pai.
  • Mods: um mod é um plugin que executa seu próprio código dentro do Claude Code, e um processo iniciado por um mod é executado fora do sandbox. Consulte O que um mod pode alcançar.

Veja também