A opção --sandbox executa o CLI com isolamento em nível de sistema operacional, aplicando os escopos ativos de permissão de leitura e gravação no próprio sistema operacional e, opcionalmente, restringindo o tráfego de rede.
Quando o sandbox está ativo:
- Os caminhos graváveis são derivados dos escopos de permissão
Write(...) concedidos, mais o diretório do workspace
- Os caminhos legíveis são derivados dos escopos
Read(...) concedidos (padrões da plataforma, como /usr/bin, são sempre legíveis)
- Escopos concedidos no meio da sessão expandem dinamicamente o sandbox para os comandos subsequentes
Se a resolução do sandbox falhar (por exemplo, se as ferramentas de sandbox não estiverem disponíveis na plataforma do usuário), a CLI se recusará a iniciar em vez de ser executada fora do sandbox. Esse comportamento de falha segura se aplica tanto quando o sandbox foi ativado por uma configuração da equipe quanto pelo usuário ao passar --sandbox diretamente, garantindo que a intenção de segurança nunca seja contornada silenciosamente.Causas comuns de falha na resolução do sandbox:
- Windows: o sandbox em nível de SO não tem suporte no Windows no momento. As sessões no Windows falharão imediatamente quando
--sandbox for passado ou quando a imposição do sandbox for obrigatória, inclusive quando a CLI for executada como um servidor ACP dentro de uma IDE (por exemplo, Devin Desktop).
- Linux: o sandbox exige que
bubblewrap (bwrap) e socat estejam instalados. As sessões falham imediatamente com instruções de instalação quando eles não estão presentes.
- Erros de escopo de permissão: caminhos inválidos em escopos de permissão que não podem ser resolvidos.
A filtragem de rede do sandbox está instável no momento. Se você precisar desse recurso, entre em contato com o representante da sua conta para saber a previsão de estabilização.
sandbox do seu arquivo de configuração (apenas na configuração do usuário). Quando --sandbox está ativo e a filtragem de domínio está configurada, um proxy de rede gerenciado é iniciado na interface de loopback, e o sandbox restringe todo o tráfego dos processos filhos para passar por ele.
| Opção | Tipo | Padrão | Descrição |
|---|
allowed_domains | string[] | [] | Padrões de domínio permitidos pelo proxy. Quando não estiver vazio, apenas os domínios que corresponderem aos padrões serão permitidos (modo de lista de permissões) |
denied_domains | string[] | [] | Padrões de domínio sempre bloqueados. As regras de negação têm precedência sobre as regras de permissão |
network_mode | string | "full" | "full" permite todos os métodos HTTP; "limited" permite apenas GET/HEAD/OPTIONS |
| Padrão | Correspondência |
|---|
example.com | Apenas correspondência exata |
*.example.com | Qualquer subdomínio (não o domínio raiz) |
**.example.com | Domínio raiz e qualquer subdomínio |
{
"sandbox": {
"allowed_domains": [
"github.com",
"**.npmjs.org",
"**.crates.io",
"**.pypi.org"
],
"denied_domains": ["evil.example.com"],
"network_mode": "full"
}
}
A filtragem de domínio se aplica quando o sandbox está ativo (--sandbox). Sem --sandbox, a seção do sandbox é ignorada.
git que precisam acessar credenciais ou hooks bloqueados pelo sandbox. A seção de configuração sandbox.excluded permite excluir do isolamento do sandbox os comandos correspondentes, usando a mesma sintaxe de regra Exec(...) de permissão:
| Opção | Tipo | Descrição |
|---|
excluded.allow | string[] | Comandos correspondentes são executados fora do sandbox automaticamente |
excluded.ask | string[] | Comandos correspondentes são executados fora do sandbox após o usuário aprovar a solicitação |
excluded.deny | string[] | Comandos correspondentes nunca são excluídos — eles sempre permanecem dentro do sandbox |
{
"sandbox": {
"excluded": {
"allow": ["Exec(git status *)"],
"ask": ["Exec(git push *)"],
"deny": ["Exec(git tag *)"]
}
}
}
Exec(git push *) prevalece sobre Exec(git *)), e, quando tanto a configuração do usuário quanto as Configurações da equipe se aplicam, prevalece a decisão mais restritiva (deny > ask > allow). Comandos sem nenhuma regra correspondente — inclusive quando sandbox.excluded não está configurado — sempre são executados dentro do sandbox.
- Somente regras
Exec(...) têm suporte em sandbox.excluded; qualquer outro tipo de regra (por exemplo, Read(...), Write(...)) é ignorado com um aviso.
- A exclusão é fail-closed: se um comando não puder ser resolvido com segurança (por exemplo, se não puder ser analisado), ele permanece dentro do sandbox.
- As exclusões se aplicam ao caminho de execução padrão de cada comando. Comandos executados por meio de um shell PTY persistente (sessões interativas ou quando
pty_for_noninteractive_exec está ativado) sempre permanecem dentro do sandbox.
Aplicação obrigatória no Enterprise
Modo de imposição do sandbox
--sandbox em toda a sua organização:
- Opcional (padrão) — Os usuários escolhem se querem informar
--sandbox. Sem imposição.
- Obrigatório — A flag
--sandbox é aplicada a todos os usuários, mesmo que eles não a informem na linha de comando. Todas as sessões de CLI são executadas com sandbox de sistema de arquivos em nível de SO, que aplica escopos de permissão de leitura/gravação.
No futuro, um modo Strict poderá restringir totalmente a configuração do sandbox, impedindo que os usuários modifiquem suas configurações.
Certifique-se de que todas as máquinas de destino estejam provisionadas antes de definir o modo de imposição do sandbox como Obrigatório em toda a sua organização. Se algum usuário usar Windows, não conseguirá executar a CLI até que o sandbox em nível de SO tenha suporte no Windows ou que a política seja flexibilizada para Opcional.
Filtragem de domínios no Enterprise
- Lista de permissões de domínios — Quando definida, somente os domínios desta lista podem ser acessados pelo proxy de rede do sandbox. Esta lista é definitiva: ela substitui completamente qualquer
allowed_domains configurado pelo usuário. Os usuários não podem adicionar domínios extras para contornar as restrições do administrador.
- Lista de bloqueio de domínios — Domínios que são sempre bloqueados. Os domínios bloqueados no Enterprise são aditivos: eles são mesclados com o
denied_domains local do usuário, tornando a lista combinada mais restritiva.
Como as listas de domínios do Enterprise e do usuário interagem:
| Cenário | Configuração do Enterprise | Configuração do usuário | Resultado efetivo |
|---|
| Administrador define lista de permissões | allowed_domains: ["github.com"] | allowed_domains: ["npmjs.org"] | Somente github.com é permitido (o Enterprise substitui a lista do usuário) |
| Administrador define lista de bloqueio | denied_domains: ["evil.com"] | denied_domains: ["risky.io"] | Tanto evil.com quanto risky.io são bloqueados (mesclados) |
| Sem lista de permissões do administrador | allowed_domains: [] | allowed_domains: ["github.com"] | A lista de permissões do usuário é usada |
Como o denied_domains local do usuário é preservado e mesclado de forma aditiva, o usuário pode bloquear um domínio que aparece na lista de permissões do Enterprise. Isso é intencional: o efeito combinado é sempre mais restritivo, nunca menos. Se isso causar problemas de acesso, o usuário deve remover a entrada conflitante da configuração local.
Comandos excluídos no Enterprise
- Excluded allow / ask — regras
Exec(...) para comandos que podem ser executados fora do sandbox em toda a organização, automaticamente ou após uma confirmação.
- Excluded deny — regras
Exec(...) para comandos que nunca devem ser executados fora do sandbox. Um deny da equipe tem precedência sobre qualquer allow ou ask em nível de usuário para comandos correspondentes, então os usuários não podem excluir comandos que seus administradores restringiram.
As regras da equipe e do usuário são avaliadas em conjunto: a regra correspondente mais específica prevalece dentro de cada origem, e a decisão mais restritiva prevalece entre as origens (deny > ask > allow).
Exemplo: bloquear todas as exclusões, exceto gh. Um deny curinga com uma exceção allow mantém todos os comandos dentro do sandbox, exceto gh, independentemente do que os usuários configurarem localmente. Esses valores vão na configuração de comandos excluídos das Configurações da equipe (não no arquivo de configuração do usuário, portanto não há uma chave sandbox de nível superior):
{
"excluded": {
"deny": ["Exec(**)"],
"allow": ["Exec(gh *)"]
}
}
Exec(gh *) prevalece sobre o curinga Exec(**), os comandos gh são executados fora do sandbox, enquanto todo o restante permanece dentro — e o curinga deny no nível da equipe se sobrepõe a quaisquer regras allow ou ask no nível do usuário para outros comandos.
