Configurar políticas de sandbox

Se uma execução de agente roda em sandbox é decidido no servidor, na inicialização (--sandbox). O interruptor Ativar sandboxing e o seletor Backend, em Configurações → Servidor → Diagnóstico e privacidade, são preferências armazenadas no seu dispositivo. A detecção de host do cartão Sandbox informa o que o host do servidor consegue envolver.

Dois controles chegam a uma execução e este guia cobre os dois: as regras de ação em Configurações → Espaço de trabalho → Permissões dos agentes, que decidem o que um agente pode enviar, abrir ou alcançar, e a própria flag --sandbox do servidor.

O que restringe uma execução de agente

Seis coisas limitam um agente. A primeira é o sandbox do sistema operacional, e é a única condicional — as outras cinco valem em todo host.

Fronteira	O que ela faz
O sandbox do sistema operacional	Seatbelt no macOS, bubblewrap no Linux e no WSL2. Envolve a CLI do Claude Code, os adaptadores ACP e a ferramenta `bash` do harness. Ausente no Windows e no Linux sem `bwrap` e `socat`
A própria worktree	Cada conversa recebe um checkout com copy-on-write. O checkout original é incorporado à execução como um caminho de negação de escrita, e é o sandbox quem o aplica
Credenciais intermediadas pelo broker	O broker de credenciais emite um ambiente por execução e o revoga quando a execução é desmontada. O token do GitHub dele pode ler, mas não fazer push: um push passa pelo Control Center, que pergunta primeiro à regra de push
Barreiras de ação	Toda ferramenta mutável declara suas classes de efeito, e a barreira as resolve antes de a chamada rodar. Um `prompt` sem nenhum aprovador conectado é negado
Higienização do ambiente	O ACP e a ferramenta `bash` do harness recebem um ambiente filtrado. O Claude Code por meio do `NoSandboxAdapter` herda o ambiente do host
A superfície de ferramentas do modo	Um modo somente leitura remove por completo as ferramentas que mutam a worktree e fixa o próprio verbo de saída do modo para que ele ainda consiga entregar

Três coisas continuam mais fracas do que parecem:

Só o harness integrado aplica o portão de ferramentas, os contratos de conclusão e as regras estruturais do modo. O adaptador do Claude Code não. Em particular, o Claude Code é iniciado com --dangerously-skip-permissions, porque um claude -p não interativo bloquearia para sempre no próprio prompt — então as próprias chamadas de leitura, escrita e edição do Claude não são vistas nem controladas pelo Control Center, e os comandos de bash dele só são verificados por um hook que lê a linha de comando. Onde o sandbox está ligado, ele é a fronteira em volta delas.
As ferramentas de arquivo em processo do harness (read, write, edit, apply patch, search, find, search_files) rodam dentro do processo do servidor, então nenhum perfil de sandbox as restringe. Só a ferramenta bash passa pelo executor de comandos com sandbox. Essas ferramentas são limitadas pelo próprio confinamento de caminhos delas mais as barreiras de ação.
Em um host sem backend, a primeira linha não se aplica de forma alguma. O ACP e a ferramenta bash do harness recorrem à higienização do ambiente mais a política de comandos; o Claude Code herda o ambiente do host por meio do NoSandboxAdapter. O servidor informa isso no log de inicialização. Confira o seu abaixo.

Decidir o que um agente pode enviar

Não há interruptor por agente para git push, GitHub, tickets ou rede. Cada um é uma regra de ação:

Regra	Padrão integrado	O que ela cobre
Fazer push para um remoto	Perguntar primeiro	Todo `git push` para o GitHub, qualquer que seja o adaptador
Abrir um pull request	Perguntar primeiro	`gh pr create` e as ferramentas de pull request
Publicar uma revisão ou fazer merge	Perguntar primeiro	`gh pr merge`, `gh pr review`, `gh pr comment`, `gh pr close`
Escrever em um rastreador externo	Perguntar primeiro	Escritas de tickets pelas ferramentas do Control Center e `gh issue`
Acessar a rede	Permitir	Se o sandbox tem rede, e as ferramentas web do harness

Acesse Configurações → Espaço de trabalho → Permissões dos agentes
Escolha o escopo — Espaço de trabalho, Agente ou Espaço — e, na linha da regra, escolha Permitir, Perguntar primeiro ou Negar

Regras de push limitadas a branches, como uma que nega push para main, também se aplicam: consulte Barreiras.

Ponto de verificação: peça ao agente para fazer push de um branch. Com Perguntar primeiro, você recebe uma aprovação que cita o repositório e os refs; com Negar, o git mostra ! [remote rejected] <ref> (Control Center policy: …).

Como cada regra chega à execução:

O push é aplicado pelo que a execução tem. O token do GitHub dela é um token de instalação do GitHub App somente leitura, que pode ler conteúdo e trabalhar com pull requests. A configuração do git dela manda todo push para o GitHub a um gateway de loopback no cc_server, que pergunta à regra e só então encaminha o push com um token de escrita que o agente nunca vê. O gateway só encaminha para o repositório da própria worktree ou para um repositório do GitHub vinculado ao espaço de trabalho. Isso vale para todo adaptador.
Pull requests e issues a partir de um shell são reconhecidos pela linha de comando, na ferramenta bash do harness e, por meio de um hook, na ferramenta Bash do Claude Code. Um agente que esconda o comando (um script, eval, uma chamada direta à API) passa por essa verificação, mas não pelo gateway de push.
Chaves de tickets nunca são colocadas no sandbox. Os agentes escrevem tickets pelas ferramentas MCP do Control Center, que perguntam à regra.
A rede é resolvida uma única vez, quando a execução começa. Negar desliga a rede do sandbox; Permitir e Perguntar primeiro a mantêm ligada, e com Perguntar primeiro as ferramentas web_fetch e web_search do harness continuam perguntando a cada chamada. Enquanto a rede está ligada, o GitHub está sempre na lista de permissões de saída.

Verificar se as suas execuções de agente estão em sandbox

Duas coisas decidem isso, ambas no servidor: se o host oferece um backend e se o --sandbox está ligado. Verifique-as nessa ordem.

Acesse Configurações → Servidor → Diagnóstico e privacidade
Leia o cartão Sandbox. O dado Host é a máquina em que o cc_server roda, não a máquina que você está olhando. O campo Backend lista Native sandbox (Seatbelt no macOS, bubblewrap no Linux e no WSL2) ou No isolation. O dado Em vigor é a preferência deste dispositivo, não o envelope que o servidor realmente usa.
Leia o log de inicialização do servidor. Ele imprime exatamente uma de três linhas:
- agent sandbox ON mais a nota do backend — as execuções são envolvidas
- no OS-native agent sandbox on this host mais uma dica de instalação quando existe — as execuções não são envolvidas
- agent sandbox DISABLED by --sandbox off — uma desativação deliberada

GET /healthz não informa o estado do sandbox, então o log de inicialização é a verificação.

Para desligar o sandbox de propósito — um host em que o perfil se comporta mal é o motivo de isso existir —, inicie o servidor com --sandbox off ou defina CC_SERVER_SANDBOX=off. O padrão é on, e on significa “usar um backend se o host tiver um”, nunca “exigir um”.

Duas situações nunca recebem um envelope de sandbox nativo. No Windows, a sonda nativa sempre informa indisponível e não há nada a instalar — o despacho de agentes usa none. O backend microvm é separado (terminais interativos e rigs) e depende da sonda do próprio runtime. No Linux e no WSL2, tanto o bwrap quanto o socat precisam estar no PATH; sem eles, a sonda informa indisponível e nomeia os pacotes que faltam.

Em Linux/WSL2 com bubblewrap instalado, os globs de arquivos de segredo da política padrão não podem ser aplicados a arquivos que um agente crie depois. Uma execução nativa assim agora falha em vez de ignorar as regras em silêncio. Uma sonda de inicialização positiva, portanto, não garante que um despacho no Linux consiga iniciar. --sandbox off é uma desativação deliberada sem confinamento, não uma fronteira de segurança substituta.

Saber o que um modo já proíbe

O modo é armazenado por espaço e alimenta o resolvedor de barreiras como a camada de predefinição de modo. Três dos quatro modos são somente leitura, e um modo somente leitura recusa onze classes de efeito de imediato:

Modo	Worktree	Recusadas pela predefinição
Agente (`chat`)	Gravável	Nada — os padrões integrados se aplicam
Plano	Somente leitura	Excluir um arquivo, escrever fora do worktree, criar um commit, fazer push, abrir uma PR, publicar ou fazer merge, escrever em um rastreador externo, instalar um pacote, executar um processo, alterar a estrutura do espaço de trabalho, inicializar ou controlar um recinto
Revisão	Somente leitura	As mesmas onze. Não é selecionável pelo usuário — o compositor oferece apenas Agente, Plano e Orquestração
Orquestração	Somente leitura	As mesmas onze

O acesso à rede e o acesso a segredos deliberadamente não são recusados por um modo somente leitura: a pesquisa é justamente o objetivo dele.

Exigir aprovação antes de uma ação rodar

A aprovação é uma decisão de barreira, não uma configuração de sandbox.

Acesse Configurações → Espaço de trabalho → Permissões dos agentes
Defina a classe de ação como Perguntar primeiro no escopo do espaço de trabalho, do agente ou do espaço

Uma decisão Perguntar primeiro interrompe a execução e pergunta a você. Sem nenhum aprovador conectado, ela falha fechada e a ação é negada. Consulte Configurar guardrails para ver a ordem de resolução completa.

Solução de problemas

Um agente não consegue fazer push e eu nunca neguei isso

Leia o que o git mostrou. Control Center policy: … significa que uma regra negou o push ou que um Perguntar primeiro ficou sem resposta. … is not linked to this workspace significa que o push visa um repositório que não é o da worktree nem está vinculado ao espaço de trabalho. Control Center has no GitHub credential that can push … significa que o GitHub App não está instalado nesse repositório e nenhuma credencial de fallback conseguiu fazer push: instale o App nele ou conecte o GitHub.

O cartão Sandbox informa que não há sandbox nativo

Então as execuções de agente nesse host não são envolvidas por Seatbelt nem por bubblewrap, e as fronteiras restantes são o que você tem. No Linux e no WSL2, instale as duas ferramentas que faltam — sudo apt-get install bubblewrap socat — e reinicie o servidor; o log de inicialização deve então dizer que o sandbox está ligado. No Windows não há backend nativo a instalar, então aperte as barreiras em vez disso: consulte Configurar guardrails.

Um agente acessou um arquivo fora da sua worktree

Qual ferramenta o acessou decide se isso é esperado.

As ferramentas de arquivo em processo do harness (read, write, edit, apply patch, search, find, search_files) rodam no processo do servidor, então nenhum perfil de sandbox se aplica a elas — o limite delas é o próprio confinamento de caminhos mais as barreiras. Um comando bash ou a CLI do Claude Code é envolvido onde existe um backend, e os seus checkouts registrados recebem negação de escrita dentro desse envelope em todo modo, inclusive nas suas grafias resolvidas por symlink (no macOS, um caminho alcançado por /tmp ou /var/folders é resolvido sob /private, e ambas as grafias agora são negadas). Em um host sem backend, nada disso se aplica. De um jeito ou de outro, as barreiras podem recusar Escrever fora do worktree de imediato.