Referencia de sandbox.json
Configura el comportamiento de sandbox mediante un archivo sandbox.json para controlar el acceso de red, las rutas del sistema de archivos y más.
Ubicaciones de archivos
Coloca sandbox.json en una o ambas ubicaciones:
| Ubicación | Ámbito | Prioridad |
|---|---|---|
~/.cursor/sandbox.json | Todos los espacios de trabajo (por usuario) | Menor |
<workspace>/.cursor/sandbox.json | Un único espacio de trabajo (por repositorio) | Mayor |
Ambos archivos son opcionales. Cuando existen los dos, se fusionan y los ajustes por repositorio tienen prioridad. Las políticas de los administradores de equipos Enterprise y las reglas de seguridad integradas de Cursor se aplican además y ninguno de los dos archivos puede debilitarlas.
Campos de nivel superior
Todos los campos son opcionales. Los campos omitidos usan los valores predeterminados que se muestran a continuación.
| Campo | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
type | string | "workspace_readwrite" | Modo de sandbox. "workspace_readwrite" proporciona acceso de lectura y escritura en el espacio de trabajo. "workspace_readonly" restringe el acceso a solo lectura. "insecure_none" desactiva completamente el sandbox. |
additionalReadwritePaths | string[] | [] | Rutas adicionales en las que el agente puede leer y escribir. Solo se aplica cuando type es "workspace_readwrite". |
additionalReadonlyPaths | string[] | [] | Rutas adicionales que el agente puede leer. |
disableTmpWrite | boolean | false | Cuando es true, elimina el acceso de escritura predeterminado a /tmp y a los directorios temporales del sistema. |
enableSharedBuildCache | boolean | false | Redirige las cachés de herramientas de compilación (npm, cargo, pip, etc.) a un directorio temporal compartido para que los comandos en sandbox y fuera de él compartan las mismas cachés. |
Objeto networkPolicy
| Campo | Tipo | Predeterminado | Descripción |
|---|---|---|---|
default | "allow" | "deny" | "deny" |
allow | string[] | [] | Patrones permitidos. Admite dominios exactos, comodines y notación CIDR. |
deny | string[] | [] | Patrones denegados. Tiene la máxima prioridad; bloquea siempre, incluso si un patrón también aparece en allow. |
Sintaxis de patrones de red
Los arrays allow y deny admiten tres formatos de patrón:
| Formato | Ejemplo | Coincide con |
|---|---|---|
| Dominio exacto | "registry.npmjs.org" | Ese host exacto |
| Comodín | "*.example.com" | Cualquier subdominio de example.com, incluido example.com |
| CIDR | "10.0.0.0/8" | Cualquier IP de ese rango |
Reglas clave:
- Deny siempre prevalece sobre allow. Si un host coincide con ambas listas, se bloquea.
- Las direcciones privadas/RFC 1918 (
10.x,172.16.x,192.168.x,127.x) y los endpoints de metadatos de la nube (169.254.169.254) se bloquean de forma predeterminada para evitar SSRF. - Las direcciones IPv6 privadas (
::1,fe80::/10,fc00::/7) también se bloquean. - Las rutas de las URL se ignoran; la coincidencia se realiza únicamente por dominio/IP.
Cómo se fusionan las políticas
Cuando hay varias fuentes de políticas, se fusionan según el orden de prioridad:
per-user < per-repo < team-admin < hardcoded(menor) (mayor)Reglas de fusión:
- Rutas (
additionalReadwritePaths,additionalReadonlyPaths): se combinan de todas las fuentes. - Listas de permitidos de red: se combinan, salvo que exista una lista de permitidos de administrador de equipo (que sustituye la combinación).
- Listas de denegados de red: siempre se combinan.
networkPolicy.default:"deny"prevalece sobre"allow".- Booleanos restrictivos (
disableTmpWrite,networkPolicyStrict): prevalecetrue.
Rutas protegidas
Ciertas rutas están siempre protegidas contra escritura, independientemente de la configuración de sandbox.json:
.cursor/*.json,.cursor/**/*.json,.cursor/.workspace-trusted.claude/*.json,.claude/**/*.json.vscode/**.code-workspace.git/hooks/**,.git/config,.git/info/attributes.cursorignore
Los siguientes subdirectorios de .cursor sí se pueden modificar: rules/, commands/, worktrees/, skills/, agents/.
Las rutas de los certificados SSL y ~/.ssh siempre se pueden leer.
Variables de entorno
Además de la configuración anterior, Cursor inyecta variables de entorno en los procesos secundarios aislados, entre ellas CURSOR_SANDBOX, CURSOR_ORIG_UID y CURSOR_ORIG_GID. Consulta Modos de ejecución: variables de entorno para ver la lista completa y las indicaciones de uso.
Ejemplos
Permitir dominios específicos
{ "networkPolicy": { "default": "deny", "allow": [ "registry.npmjs.org", "pypi.org", "*.githubusercontent.com" ] }}El tráfico de red se bloquea de forma predeterminada. Solo se puede acceder a los dominios enumerados.
Permitir todo el acceso a la red
{ "networkPolicy": { "default": "allow" }}Se permite todo el tráfico de red saliente dentro del sandbox.
Proyecto web full stack
Un proyecto en el que el agente necesita instalar paquetes, descargar imágenes de contenedor, acceder a una base de datos en la red local y leer un repositorio compartido 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 configuración permite al agente:
- Instalar paquetes de npm/pip y descargar imágenes de Docker.
- Acceder a las API de Google Cloud.
- Bloquear el acceso a servicios internos de la empresa.
- Escribir en
~/.dockerpara operaciones con contenedores. - Leer (sin modificar) un directorio compartido de design-tokens.
- Compartir las cachés de npm/pip/cargo entre ejecuciones con y sin sandbox.