Sandbox do Claude Code

Problema: Um agente de IA com acesso livre ao teu disco e rede é um risco que não podes ignorar. Cada npm install descarrega código escrito por estranhos. Cada script de build corre com os teus privilégios completos. Cada injeção de prompt que entra tem o mesmo alcance que tu tens. Uma dependência maliciosa, sem barreiras, pode ler chaves SSH, enviar variáveis de ambiente para outro lado, ou modificar os teus ficheiros de configuração do shell em silêncio.

O sandbox do Claude Code fecha essa porta. Empurra os limites de sistema de ficheiros e rede para o kernel, por isso as regras já não dependem de confiança ou de como um prompt é formulado.

Configuração rápida: Um comando ativa o sandbox agora mesmo:

> /sandbox

Aparece um menu para escolher o modo de sandbox. No macOS a funcionalidade já está disponível. Para Linux ou WSL2, é preciso instalar dois pacotes primeiro, bubblewrap e socat (instruções abaixo).

Por Que os Pedidos de Permissão Não Chegam Sozinhos

Passa algum tempo real com Claude Code e o padrão fica familiar. Claude quer executar um comando. Aprova. Claude quer escrever um ficheiro. Aprova. Claude quer correr os testes. Aprova. Trinta cliques depois, estás a aprovar o fluxo sem ler um único prompt.

Isso é fadiga de aprovação. É um problema de segurança disfarçado de funcionalidade de segurança.

Mais prompts significa menos atenção em cada um. A investigação de UX de segurança continua a encontrar o mesmo resultado: diálogos repetidos treinam as pessoas a clicar em seguida. Perdes duas vezes. O fluxo continua interrompido e a proteção continua a degradar-se.

O sandbox inverte o modelo. Em vez de perguntar "esta ação pode acontecer?" a cada passo, configuras as barreiras uma vez. Aqui é onde as leituras podem acontecer. Aqui é onde as escritas podem acontecer. Aqui é o que a rede pode alcançar. Dentro dessas barreiras, nada pergunta. Fora, o OS bloqueia a ação, não um diálogo.

O ganho é menos interrupções, defesas mais fortes, e um agente livre para trabalhar de forma autónoma dentro de limites seguros conhecidos.

Como Funciona o Sandbox do Claude Code

Duas camadas de isolamento funcionam em paralelo. Ambas importam. Retira qualquer uma e a que fica tem buracos por onde passa um camião.

Isolamento de Sistema de Ficheiros

A ferramenta bash isolada mantém o acesso a ficheiros numa lista curta de diretórios:

Escritas ficam dentro do diretório de trabalho e tudo o que está por baixo
Leituras cobrem todo o sistema, exceto os caminhos que marcaste como negados
Edições fora da árvore falham a menos que dês permissão explicitamente
Caminhos personalizados abrem ou fecham diretórios extra através das definições do sandbox

Na prática, Claude lê ficheiros do projeto e edita código dentro do teu repositório, mas ~/.bashrc, /usr/local/bin, e tudo em ~/.ssh ficam fora do alcance. Um pacote npm malicioso que tenta escrever para além dessas barreiras é bloqueado pelo próprio OS.

Isolamento de Rede

O tráfego de saída é encaminhado por um servidor proxy que vive fora do sandbox:

Lista de domínios permitidos limita os hosts que qualquer processo pode alcançar
Domínios desconhecidos mostram um prompt de permissão, por isso cada novo host aparece à tua frente
Limites herdados viajam com cada processo filho, por isso um shell que um script de build cria não escapa às regras
Proxies personalizados permitem que empresas enviem tráfego do sandbox para o seu próprio pipeline de inspeção

As barreiras de sistema de ficheiros sozinhas deixam um buraco. Um agente comprometido pode ainda assim enviar código fonte para um host controlado pelo atacante. As barreiras de rede sozinhas deixam o buraco oposto. Ambas as camadas têm de funcionar em paralelo. O design assenta nisso.

Aplicação ao Nível do Kernel

O sandbox não depende de verificações na camada da aplicação. Um exploit inteligente pode sempre contornar essas. O que faz o trabalho é um conjunto de primitivas de segurança do kernel:

macOS: Seatbelt, o mesmo framework que a Apple usa para isolar aplicações da App Store
Linux: bubblewrap (bwrap), a pequena ferramenta de sandbox sem privilégios na qual o Flatpak é construído
WSL2: bubblewrap outra vez, não diferente do Linux nativo

WSL1 está fora. O bubblewrap precisa de funcionalidades que o kernel só expõe sob WSL2, nomeadamente namespaces de utilizador e de montagem. Um build nativo para Windows está planeado mas ainda não foi lançado.

Cada processo filho que um comando isolado cria herda os mesmos limites. Corre npm install dentro do sandbox, e qualquer hook postinstall também fica dentro da caixa.

Pré-requisitos e Instalação

macOS

Nada extra para instalar. O sandbox corre imediatamente no framework Seatbelt já presente no OS. Escreve /sandbox e escolhe um modo.

Linux e WSL2

Precisas de dois pacotes. O bubblewrap faz o isolamento do sistema de ficheiros e o socat trata da canalização do proxy de rede:

Ubuntu/Debian:

sudo apt-get install bubblewrap socat

Fedora:

sudo dnf install bubblewrap socat

Com esses instalados, escreve /sandbox no Claude Code. Se ainda faltar uma dependência, o menu mostra as instruções de instalação para a tua plataforma.

Modos de Sandbox: Auto-Allow vs Permissões Regulares

Existem dois modos. As barreiras de sistema de ficheiros e rede são idênticas em ambos. O que muda é se um comando isolado ainda precisa do teu clique para correr.

Modo Auto-Allow

Um comando bash tenta correr sob o sandbox, e se encaixar, nada te pergunta primeiro. Se esse mesmo comando precisar de um host que não está na tua lista de permitidos, o fluxo normal de permissão é ativado. Qualquer regra de aprovação ou negação já configurada ainda dispara.

A maioria dos builders quer este modo. O agente tem espaço máximo dentro das barreiras, e os prompts só voltam quando algo vai cruzar uma barreira.

Vale a pena saber uma coisa. O auto-allow corre independentemente do modo de permissão. Mesmo com "aceitar edições" desativado, um comando bash isolado corre sem prompt sempre que o auto-allow está ativo. As edições de ficheiros através da ferramenta Edit continuam a obedecer às tuas regras de permissão normais. Apenas o bash dentro do sandbox passa por ali.

Modo de Permissões Regulares

Cada comando bash, isolado ou não, ainda passa pelo diálogo de permissão normal. As barreiras permanecem, e cada comando também te pergunta primeiro.

Escolhe este quando queres proteção de sandbox sem abdicar da revisão por comando. Um bom ajuste para ambientes rigorosos, ou para os primeiros dias de ajuste de uma nova configuração de sandbox.

Configurar o Teu Sandbox

O comportamento do sandbox é ajustado através do teu settings.json. Um exemplo funcional fica assim:

{
  "sandbox": {
    "mode": "auto-allow",
    "allowedDomains": ["registry.npmjs.org", "api.github.com", "pypi.org"],
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

Definições Principais

mode: Define como "auto-allow" ou "regular". Esse flag decide se os comandos isolados correm sozinhos ou esperam por um clique.

allowedDomains: Hosts que o bash pode alcançar sem pedir. Novos domínios que visitas mostram um prompt, e aceitar escreve o domínio nesta lista para a próxima vez.

allowUnixSockets: Controla o acesso a sockets. Cuidado aqui. Permitir /var/run/docker.sock é efetivamente um passe para o host através da API do Docker, o que contorna as barreiras do sandbox.

allowUnsandboxedCommands: Por omissão é true. Quando uma regra do sandbox mata um comando, Claude pode voltar a correr esse comando sem sandbox depois da tua confirmação. Muda para false para eliminar o caminho de retry.

excludedCommands: Uma lista de comandos que ignoram o sandbox sempre. Bom para ferramentas que simplesmente se recusam a cooperar, como docker.

enableWeakerNestedSandbox: Um ajuste apenas para Linux para configurações Docker sem privilégios. Enfraquece as barreiras, por isso usa-o apenas quando o contentor exterior está a fazer o seu próprio isolamento.

Como o Sandbox Se Encaixa ao Lado das Permissões

As permissões e o sandbox são duas camadas de segurança independentes que se apoiam mutuamente:

Permissões decidem quais ferramentas estão ao alcance do Claude Code. Correm antes de qualquer chamada a ferramenta, e aplicam-se a todas as ferramentas: Bash, Read, Edit, WebFetch, ferramentas MCP, o conjunto todo.

Sandboxing é aplicado pelo OS, e apenas molda o que um comando Bash (ou os seus subprocessos) pode fazer com o sistema de ficheiros e a rede.

Pensa em defesa em profundidade. Primeira barreira: esta ferramenta está sequer permitida? Segunda barreira: uma vez que corre, até onde pode chegar?

Benefícios de Segurança

Proteção Contra Injeção de Prompt

A injeção de prompt é o maior risco ativo para um agente de IA. Um atacante esconde instruções dentro de um ficheiro, um README, ou uma página web. Claude lê-as como se tu as tivesses escrito, e começa a executar comandos do atacante.

Com o sandbox ativo, mesmo uma injeção bem-sucedida esbarra em barreiras rígidas:

Proteção do sistema de ficheiros:

Ficheiros rc do shell como ~/.bashrc e ~/.zshrc estão fora do alcance
Binários do sistema em /bin/ ou /usr/local/bin/ não podem ser tocados
Qualquer caminho marcado como negado nas tuas regras de permissão é ilegível

Proteção de rede:

Servidores controlados pelo atacante não podem ser usados para exfiltração de dados
Scripts maliciosos de domínios desconhecidos não podem ser descarregados
Chamadas de API a serviços que não aprovaste não passam
Qualquer domínio que não esteja na lista de permitidos é inacessível

Uma Superfície de Ataque Menor

Para além da injeção, o sandbox também limita os danos dos riscos do dia a dia:

Dependências más: qualquer biblioteca npm, pip, ou outra que esconda lógica maliciosa em postinstall
Ferramentas de build com falhas: utilitários de tempo de build com as suas próprias vulnerabilidades
Engenharia social: comandos perigosos que um utilizador foi enganado a executar
Ataques à cadeia de fornecimento: pacotes a montante adulterados, por isso o tempo de instalação torna-se injeção de código

Limitações Que Deves Conhecer

Nenhum sandbox é perfeito. Ser claro sobre onde as barreiras têm lacunas é como escolhes um modelo de ameaça realista.

Domain Fronting

O filtro de rede escolhe domínios, mas não faz inspeção profunda de pacotes. O domain fronting, onde o tráfego parece dirigido para um host mas acaba noutro, pode escapar ao filtro de domínio em alguns casos.

Escalada por Unix Socket

allowUnixSockets pode silenciosamente conceder acesso poderoso. Permite /var/run/docker.sock e o processo isolado agora tem a API Docker completa no seu bolso, o que na prática significa acesso ao host.

Escalada de Permissão do Sistema de Ficheiros

Escritas demasiado permissivas concedem caminhos de escalada. Permite que o sandbox escreva em qualquer pasta com binários no $PATH, diretórios de configuração do sistema, ou ficheiros rc do shell do utilizador e o código pode acabar a correr num contexto de segurança diferente.

Dicas Práticas e Compatibilidade

Docker Não Funciona Bem

Os comandos Docker não funcionam sob o sandbox. Precisam de uma linha direta para o daemon Docker. Coloca docker em excludedCommands para que corra sempre fora.

Watchman Também Não Funciona Bem

O watchman de file watching da Facebook não coopera com um processo isolado. A correr Jest? Adiciona o flag --no-watchman.

A Saída de Emergência

De vez em quando um comando isolado falha por causa das próprias barreiras. Claude pode analisar a falha e oferecer-se para voltar a tentar com dangerouslyDisableSandbox. Esse retry corre fora do sandbox, e ainda espera pela tua aprovação através do fluxo de permissão normal.

Configuração de Proxy Personalizado para Empresas

Organizações com necessidades de segurança de rede mais profundas podem encaminhar tráfego do sandbox através de um proxy próprio para inspeção, registo, e integração com o resto da pilha de segurança.

O ganho é a capacidade de:

Terminar e inspecionar tráfego HTTPS
Aplicar regras que vão além de um simples bloqueio de domínio
Escrever cada pedido de saída num registo de auditoria
Ligar o sandbox a um SIEM ou pilha de segurança existente
Distribuir regras de toda a organização através do âmbito de definições geridas

Runtime de Sandbox Open Source

O runtime é distribuído como o seu próprio pacote npm, open source. Usa-o em qualquer projeto de agente que queiras. Não é preciso Claude Code:

npx @anthropic-ai/sandbox-runtime <command-to-sandbox>

O código fonte está alojado em github.com/anthropic-experimental/sandbox-runtime.

Configurar o Teu Primeiro Sandbox

Um caminho prático do zero a uma configuração funcional:

Deps primeiro (apenas Linux/WSL2): sudo apt-get install bubblewrap socat
Escreve /sandbox no Claude Code e escolhe um modo no menu
Escolhe auto-allow se queres o equilíbrio certo entre segurança e velocidade
Usa Claude normalmente e aprova qualquer novo domínio que os prompts peçam
Revê a configuração após uma ou duas sessões, e verifica a lista de domínios
Remove o que não precisas retirando domínios desatualizados

Começa restrito. Abre apenas quando a necessidade for real. Relaxar uma regra é mais barato do que limpar os danos de uma que nunca existiu.

Sandbox do Claude Code

On this page