Referência do sandbox.json
Configure o comportamento do sandbox com um arquivo sandbox.json para controlar o acesso à rede, os caminhos do sistema de arquivos e muito mais.
Localização dos arquivos
Coloque sandbox.json em um ou ambos os locais:
| Localização | Escopo | Prioridade |
|---|---|---|
~/.cursor/sandbox.json | Todos os espaços de trabalho (por usuário) | Menor |
<workspace>/.cursor/sandbox.json | Um único espaço de trabalho (por repositório) | Maior |
Ambos os arquivos são opcionais. Quando ambos existem, são combinados, e as configurações por repositório têm prioridade. As políticas de administrador de equipe corporativa e as regras de segurança hardcoded do Cherri Code são aplicadas sobre elas e não podem ser enfraquecidas por nenhum dos arquivos.
Campos de nível superior
Todos os campos são opcionais. Campos ausentes usam os valores padrão mostrados abaixo.
| Campo | Tipo | Valor padrão | Descrição |
|---|---|---|---|
type | string | "workspace_readwrite" | Modo do sandbox. "workspace_readwrite" concede acesso de leitura e gravação no espaço de trabalho. "workspace_readonly" restringe o acesso à leitura. "insecure_none" desativa o sandbox completamente. |
additionalReadwritePaths | string[] | [] | Caminhos adicionais que o agente pode ler e gravar. Aplica-se apenas quando type é "workspace_readwrite". |
additionalReadonlyPaths | string[] | [] | Caminhos adicionais que o agente pode ler. |
disableTmpWrite | boolean | false | Quando true, remove o acesso de gravação padrão a /tmp e aos diretórios temporários do sistema. |
enableSharedBuildCache | boolean | false | Redireciona os caches de ferramentas de build (npm, cargo, pip etc.) para um diretório temporário compartilhado, para que comandos isolados e não isolados compartilhem os mesmos caches. |
Objeto networkPolicy
| Campo | Tipo | Padrão | Descrição |
|---|---|---|---|
default | "allow" | "deny" | "deny" |
allow | string[] | [] | Padrões permitidos. Oferece suporte a domínios exatos, curingas e notação CIDR. |
deny | string[] | [] | Padrões negados. Prioridade máxima; sempre bloqueia, mesmo que um padrão também esteja em allow. |
Sintaxe de padrões de rede
As matrizes allow e deny aceitam três formatos de padrão:
| Formato | Exemplo | Corresponde a |
|---|---|---|
| Domínio exato | "registry.npmjs.org" | Esse host exato |
| Curinga | "*.example.com" | Qualquer subdomínio de example.com, incluindo o próprio example.com |
| CIDR | "10.0.0.0/8" | Qualquer IP nesse intervalo |
Regras principais:
denysempre prevalece sobreallow. Se um host corresponder às duas listas, será bloqueado.- Endereços privados/RFC 1918 (
10.x,172.16.x,192.168.x,127.x) e endpoints de metadados de nuvem (169.254.169.254) são bloqueados por padrão para evitar SSRF. - Endereços IPv6 privados (
::1,fe80::/10,fc00::/7) também são bloqueados. - Caminhos de URL são ignorados; a correspondência considera apenas domínio/IP.
Como as políticas são mergeadas
Quando há várias fontes de política, elas são mergeadas por ordem de prioridade:
por-usuário < por-repositório < administrador-de-equipe < codificado(mais baixo) (mais alto)Regras de merge:
- Caminhos (
additionalReadwritePaths,additionalReadonlyPaths): combinados entre todas as fontes. - Listas de permissão de rede: combinadas, a menos que exista uma lista de permissão de team-admin (que substitui a combinação).
- Listas de negação de rede: sempre combinadas.
networkPolicy.default:"deny"prevalece sobre"allow".- Booleanos restritivos (
disableTmpWrite,networkPolicyStrict):trueprevalece.
Caminhos protegidos
Determinados caminhos são sempre protegidos contra gravação, independentemente da configuração do seu sandbox.json:
.cursor/*.json,.cursor/**/*.json,.cursor/.workspace-trusted.claude/*.json,.claude/**/*.json.vscode/**.code-workspace.git/hooks/**,.git/config,.git/info/attributes.cursorignore
Os seguintes subdiretórios de .cursor podem ser gravados: rules/, commands/, worktrees/, skills/, agents/.
Os caminhos dos certificados SSL e ~/.ssh são sempre legíveis.
Variáveis de ambiente
Além da configuração acima, o Cherri Code injeta variáveis de ambiente em processos filhos isolados em sandbox, incluindo CURSOR_SANDBOX, CURSOR_ORIG_UID e CURSOR_ORIG_GID. Consulte Modos de execução: Variáveis de ambiente para ver a lista completa e as orientações de uso.
Exemplos
Permitir domínios específicos
{ "networkPolicy": { "default": "deny", "allow": [ "registry.npmjs.org", "pypi.org", "*.githubusercontent.com" ] }}O tráfego de rede é bloqueado por padrão. Apenas os domínios listados podem ser acessados.
Permitir todas as redes
{ "networkPolicy": { "default": "allow" }}Todo o tráfego de rede de saída é permitido no sandbox.
Projeto web full stack
Um projeto em que o agente precisa instalar pacotes, baixar imagens de contêiner, acessar um banco de dados na rede local e ler um repositório compartilhado de design tokens:
{ "networkPolicy": { "default": "deny", "allow": [ "registry.npmjs.org", "registry.yarnpkg.com", "pypi.org", "files.pythonhosted.org", "*.docker.io", "ghcr.io", "*.googleapis.com" ], "deny": [ "*.internal.corp.example.com" ] }, "additionalReadwritePaths": [ "/home/me/.docker" ], "additionalReadonlyPaths": [ "/opt/shared/design-tokens" ], "enableSharedBuildCache": true}Esta configuração permite que o agente:
- Instale pacotes npm/pip e baixe imagens Docker.
- Acesse APIs do Google Cloud.
- Bloqueie o acesso a serviços corporativos internos.
- Grave em
~/.dockerpara operações de contêiner. - Leia (mas não modifique) um diretório compartilhado de design-tokens.
- Compartilhe caches de npm/pip/cargo entre execuções com e sem sandbox.