Configurar políticas de sandbox

Se uma execução de agente corre em sandbox decide-se no servidor, no arranque (--sandbox). O interruptor Ativar sandboxing e o seletor Backend em Definições → Servidor → Diagnóstico e privacidade são preferências guardadas no seu dispositivo. A deteção de anfitrião do cartão Sandbox reporta o que o anfitrião do servidor consegue envolver.

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

O que limita uma execução de agente

Seis coisas limitam um agente. A primeira é a sandbox do sistema operativo e é a única condicional — as outras cinco valem em todos os anfitriões.

Fronteira	O que faz
A sandbox do sistema operativo	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 sua própria worktree	Cada conversa recebe um checkout copy-on-write. O checkout original é incorporado na execução como um caminho de negação de escrita e é a sandbox que o aplica
Credenciais intermediadas	O corretor de credenciais emite um ambiente por execução e revoga-o quando a execução termina. O seu token do GitHub pode ler, mas não fazer push: um push passa pelo Control Center, que pergunta primeiro à regra de push
Barreiras de ação	Cada ferramenta que altera o estado declara as suas classes de efeito e o motor de políticas resolve-as antes de a chamada ser executada. Um `prompt` sem nenhum aprovador ligado é negado
Sanitização do ambiente	O ACP e a ferramenta `bash` do harness recebem um ambiente filtrado. O Claude Code através do `NoSandboxAdapter` herda o ambiente do anfitrião
A superfície de ferramentas do modo	Um modo só de leitura remove por completo as ferramentas que alteram a worktree e fixa o próprio verbo de saída do modo, para que ainda consiga entregar

Três coisas permanecem 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 Claude Code não. O Claude Code em particular é lançado com --dangerously-skip-permissions, porque um claude -p não interativo bloquearia para sempre no seu próprio pedido de aprovação — por isso as próprias chamadas de leitura, escrita e edição do Claude não são vistas nem sujeitas a portão pelo Control Center, e os seus comandos de bash só são verificados por um hook que lê a linha de comandos. Onde a sandbox está ligada, é ela a fronteira à sua volta.
As ferramentas de ficheiros em processo do harness (read, write, edit, apply patch, search, find, search_files) correm dentro do processo do servidor, pelo que nenhum perfil de sandbox as limita. Só a ferramenta bash passa pelo executor de comandos em sandbox. O que limita essas ferramentas é o seu próprio confinamento de caminhos, mais as barreiras de ação.
Num anfitrião sem backend, a primeira linha não se aplica de todo. O ACP e a ferramenta bash do harness recaem na sanitização do ambiente mais a política de comandos; o Claude Code herda o ambiente do anfitrião através do NoSandboxAdapter. O servidor di-lo no seu registo de arranque. Verifique o seu abaixo.

Decidir o que um agente pode enviar

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

Regra	Predefinição	O que abrange
Fazer push para um remoto	Perguntar primeiro	Cada `git push` para o GitHub, seja qual for 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 num rastreador externo	Perguntar primeiro	Escritas de tickets através das ferramentas do Control Center e `gh issue`
Aceder à rede	Permitir	Se a sandbox tem rede, e as ferramentas web do harness

Aceda a Definições → Espaço de trabalho → Permissões dos agentes
Escolha o âmbito — Espaço de trabalho, Agente ou Espaço — e, na linha da regra, escolha Permitir, Perguntar primeiro ou Negar

As 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 que faça push de um branch. Com Perguntar primeiro, recebe uma aprovação que indica o repositório e as refs; com Negar, o git mostra ! [remote rejected] <ref> (Control Center policy: …).

Como cada regra chega à execução:

O push é imposto por aquilo que a execução detém. O seu token do GitHub é um token de instalação da GitHub App só de leitura, que pode ler conteúdo e trabalhar com pull requests. A sua configuração do git envia cada push para o GitHub para um gateway de loopback no cc_server, que pergunta à regra e só então reencaminha o push com um token de escrita que o agente nunca vê. O gateway só reencaminha para o repositório da própria worktree ou para um repositório do GitHub associado ao espaço de trabalho. Isto vale para todos os adaptadores.
Pull requests e issues a partir de uma shell são reconhecidos pela linha de comandos, na ferramenta bash do harness e, através de um hook, na ferramenta Bash do Claude Code. Um agente que esconda o comando (um script, eval, uma chamada direta à API) passa esta verificação, mas não o gateway de push.
As chaves de tickets nunca são colocadas na sandbox. Os agentes escrevem tickets através das ferramentas MCP do Control Center, que perguntam à regra.
A rede é resolvida uma única vez, quando a execução arranca. Negar desliga a rede da sandbox; Permitir e Perguntar primeiro mantêm-na ligada, e com Perguntar primeiro as ferramentas web_fetch e web_search do harness continuam a perguntar em 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 correm em sandbox

Duas coisas decidem-no, ambas no servidor: se o anfitrião oferece um backend e se o --sandbox está ligado. Verifique-as por essa ordem.

Aceda a Definições → Servidor → Diagnóstico e privacidade
Leia o cartão Sandbox. O dado Host é a máquina em que o cc_server corre, não a máquina que está a ver. 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 invólucro que o servidor usa de facto.
Leia o registo de arranque do servidor. 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 sugestão de instalação, quando existe — as execuções não são envolvidas
- agent sandbox DISABLED by --sandbox off — uma exclusão deliberada

O GET /healthz não reporta o estado da sandbox, pelo que o registo de arranque é a verificação.

Para desligar a sandbox deliberadamente — um anfitrião onde o perfil se comporta mal é a razão pela qual ela existe —, inicie o servidor com --sandbox off, ou defina CC_SERVER_SANDBOX=off. A predefinição é on e on significa “usar um backend se o anfitrião tiver um”, nunca “exigir um”.

Há duas situações que nunca recebem um invólucro de sandbox nativa. No Windows, a sonda nativa reporta sempre indisponível e não há nada para instalar — o despacho de agentes usa none. O backend microvm é separado (terminais interativos e rigs) e está sujeito a sonda no seu próprio runtime. No Linux e no WSL2, tanto o bwrap como o socat têm de estar no PATH; sem eles, a sonda reporta indisponível e nomeia os pacotes em falta.

No Linux/WSL2 com o bubblewrap instalado, os globs de ficheiros de segredos da política padrão não podem ser aplicados a ficheiros que um agente crie mais tarde. Uma execução nativa nessas condições agora falha, em vez de ignorar as regras em silêncio. Uma sonda de arranque positiva não garante, por isso, que um despacho em Linux consiga arrancar. O --sandbox off é uma exclusão deliberada sem confinamento, não uma fronteira de segurança substituta.

Saber o que um modo já proíbe

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

Modo	Worktree	Recusado pela predefinição
Agente (`chat`)	Gravável	Nada — aplicam-se as predefinições incorporadas
Plano	Só de leitura	Eliminar um ficheiro, escrever fora da árvore de trabalho, criar um commit, fazer push, abrir uma PR, publicar ou fazer merge, escrever num rastreador externo, instalar um pacote, executar um processo, alterar a estrutura do espaço de trabalho, iniciar ou controlar um recinto
Revisão	Só de leitura	As mesmas onze. Não é selecionável pelo utilizador — o compositor oferece apenas Agente, Plano e Orquestração
Orquestração	Só de leitura	As mesmas onze

O acesso à rede e o acesso a segredos não são deliberadamente recusados por um modo só de leitura: a investigação é o propósito de um deles.

Exigir aprovação antes de uma ação ser executada

A aprovação é uma decisão das barreiras, não uma definição da sandbox.

Aceda a Definições → Espaço de trabalho → Permissões dos agentes
Defina a classe de ações como Perguntar primeiro no âmbito do espaço de trabalho, do agente ou do espaço

Uma decisão Perguntar primeiro interrompe a execução e pergunta-lhe. Sem nenhum aprovador ligado, falha de forma fechada e a ação é negada. Consulte Configurar guardrails para a ordem de resolução completa.

Resolução de problemas

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

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á associado ao espaço de trabalho. Control Center has no GitHub credential that can push … significa que a GitHub App não está instalada nesse repositório e nenhuma credencial alternativa conseguiu fazer push: instale a App nesse repositório ou ligue o GitHub.

O cartão Sandbox não reporta nenhuma sandbox nativa

Então as execuções de agentes nesse anfitrião não são envolvidas pelo Seatbelt nem pelo bubblewrap e as fronteiras restantes são tudo o que tem. No Linux e no WSL2, instale ambas as ferramentas em falta — sudo apt-get install bubblewrap socat — e reinicie o servidor; o registo de arranque deverá então indicar que a sandbox está ligada. No Windows não há nenhum backend nativo para instalar, pelo que deve reforçar antes as barreiras: consulte Configurar guardrails.

Um agente chegou a um ficheiro fora da sua worktree

A ferramenta que lá chegou decide se isto é de esperar.

As ferramentas de ficheiros em processo do harness (read, write, edit, apply patch, search, find, search_files) correm no processo do servidor, pelo que nenhum perfil de sandbox lhes é aplicável — o seu limite é 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 registados ficam com a escrita negada dentro desse invólucro em todos os modos, incluindo as suas grafias resolvidas por ligação simbólica (no macOS, um caminho alcançado através de /tmp ou /var/folders resolve-se em /private e ambas as grafias são agora negadas). Num anfitrião sem backend, nada disto se aplica. De qualquer forma, as barreiras conseguem recusar Escrever fora da árvore de trabalho de imediato.