Sandboxing y permisos de agentes: qué límites poner y cuál es cada uno
El sandbox limita qué archivos y dominios alcanzan los comandos de un agente; los permisos deciden qué herramientas usa. Cómo se combinan en la práctica.
¿Qué controla cada capa?
Los permisos actúan antes de que una herramienta se ejecute. Dicen si el agente puede leer un archivo, editar código, pedir una página web o correr un comando, y si para hacerlo necesita tu aprobación. Se evalúan sobre la acción que el agente quiere hacer.
El sandbox actúa mientras el comando corre. Lo limita a nivel del sistema operativo: qué directorios puede escribir, qué dominios puede contactar, qué variables de entorno hereda. Aplica a los comandos de shell y a los procesos que estos inician.
La diferencia práctica: un permiso dice “puedes correr npm test”. El sandbox dice “y mientras corre, solo puede escribir en esta carpeta y no tiene salida a internet salvo a estos dominios”.
Aquí van los límites técnicos. Para las pantallas donde la persona decide, lee aprobación de acciones de un agente y UX de permisos para agentes.
¿Por qué necesitas las dos?
Porque cada una falla de forma distinta. Los permisos dependen de que la regla sea correcta y de que la persona apruebe bien. La documentación de Claude Code avisa de que una regla de Bash se compara con el texto del comando que escribe el agente, no con el programa en cualquier forma en que se invoque, así que una regla de bloqueo no es una barrera de seguridad alrededor de ese programa. El sandbox, en cambio, protege aunque el comando haga algo que su nombre no sugiere, porque la restricción está en el proceso.
Claude Code lo resume así: las dos capas son complementarias, y las restricciones del sandbox siguen aplicando aunque una inyección de instrucciones (texto malicioso escondido en algo que el agente lee) engañe al modelo.
¿Qué aísla realmente el sandbox de Claude Code?
Según la documentación, el sandbox está apagado por defecto y se activa con /sandbox o con sandbox.enabled en la configuración. Funciona en macOS, Linux y WSL2; en Windows nativo los comandos corren sin sandbox. Cuando está encendido:
| Acceso | Comportamiento por defecto |
|---|---|
| Escritura | Directorio de trabajo, carpeta temporal del usuario y directorios añadidos |
| Lectura | Casi todo el equipo, incluidas credenciales como ~/.ssh y ~/.aws/credentials |
| Red | Sin salida directa; todo pasa por un proxy que solo deja pasar dominios permitidos, y la lista empieza vacía |
| Variables de entorno | Se heredan de Claude Code, incluidos los secretos que estén en su entorno |
Tres detalles que sorprenden:
- La lectura por defecto es amplia. Para cerrarla hay que configurarlo (por ejemplo, con
denyRead). - Las herramientas de archivos (leer, editar, escribir),
WebFetchyWebSearchno pasan por el sandbox: dependen de los permisos. Los hooks y los servidores MCP locales también corren fuera. - Con el sandbox activo, los comandos de Bash que quedan dentro se ejecutan sin preguntar (modo auto-allow). Para que sigan pasando por el flujo normal de permisos hay que poner
sandbox.autoAllowBashIfSandboxedenfalse.
Además, si un comando falla por una restricción, Claude puede reintentarlo sin sandbox con el parámetro dangerouslyDisableSandbox; quién aprueba ese reintento depende del modo de permisos. Se puede impedir con allowUnsandboxedCommands: false.
¿Qué modos de permisos existen?
| Modo (valor en la configuración) | Qué hace |
|---|---|
Manual (default) | Pide permiso la primera vez que se usa cada herramienta |
Aceptar ediciones (acceptEdits) | Acepta ediciones y comandos comunes como mkdir, mv o cp dentro del directorio de trabajo |
Plan (plan) | Explora y lee, pero no edita tu código fuente hasta que apruebes el plan |
Automático (auto) | Un clasificador revisa las acciones en lugar de la persona; la documentación aclara que reduce los avisos pero no garantiza seguridad |
No preguntar (dontAsk) | Rechaza todo lo que pediría permiso; pensado para CI y scripts cerrados |
Omitir permisos (bypassPermissions) | Desactiva los avisos y las comprobaciones de seguridad, salvo unas pocas acciones que ningún modo aprueba |
La documentación advierte que el modo que omite permisos solo debe usarse en entornos aislados, como contenedores o máquinas virtuales, y que no protege contra inyección de instrucciones. El modo plan tiene su propio artículo: modo plan.
¿Cómo lo resuelven Codex y Cursor?
Ambos separan también las dos capas, con otros nombres.
Codex (OpenAI) tiene tres modos de sandbox: read-only, workspace-write y danger-full-access, y una política de aprobación aparte (on-request, never o una política granular). En carpetas con control de versiones, el valor recomendado es workspace-write con on-request; en carpetas sin control de versiones, read-only. La red viene apagada por defecto. La opción --dangerously-bypass-approvals-and-sandbox (alias --yolo) quita sandbox y aprobaciones, y la propia documentación la marca como no recomendada.
Cursor ejecuta los comandos de terminal en un sandbox: puede escribir en el espacio de trabajo, protege rutas como .git/hooks y .cursorignore, y bloquea la red por defecto salvo lo que permita sandbox.json y una lista de dominios de gestores de paquetes. Sus modos de ejecución se llaman Auto-review, Allowlist y Run Everything. Su documentación advierte que “Auto-review is not a security boundary”: el clasificador puede permitir llamadas que tú habrías bloqueado, o al revés.
Los nombres cambian entre herramientas y versiones: abre la documentación vigente antes de configurar.
¿Cuándo NO conviene confiar solo en el sandbox?
- Cuando permites dominios amplios. La documentación advierte que permitir dominios como
github.compuede crear rutas de salida de datos, porque el proxy decide por el nombre del dominio sin inspeccionar el tráfico cifrado. - Cuando permites sockets de Unix. Permitir el socket de Docker (
/var/run/docker.sock), por ejemplo, equivale a dar acceso al sistema anfitrión. - Cuando das permiso de escritura a rutas peligrosas, como carpetas con ejecutables del
PATHo archivos de configuración de la shell (.bashrc,.zshrc). - Cuando el sandbox está apagado, o en Windows nativo, y el agente corre en tu máquina con tus credenciales a la vista.
- Cuando necesitas aislar también hooks y servidores MCP: la documentación sugiere entonces correr Claude Code entero dentro de su sandbox runtime o de un dev container.
Para aislar el trabajo de varios agentes en copias separadas del repositorio, mira git worktrees para agentes. Los worktrees separan archivos, no reemplazan al sandbox.
Ejemplo
Ejemplo ilustrativo: un agente va a depurar una prueba. Activas el sandbox, le permites correr npm test sin preguntar y añades a la lista de dominios permitidos solo el registro de paquetes. Sus escrituras quedan limitadas a la carpeta del proyecto. Como la lectura por defecto es amplia, agregas ~/.ssh a denyRead en la configuración del sandbox. Si la prueba necesita una base de datos en la nube, añades ese dominio a los permitidos, no a la lista de comandos “sin preguntar”. Resultado: el agente avanza sin preguntar lo que es seguro, y cada excepción queda escrita en un archivo que otra persona puede revisar.
Errores comunes
- Tratar el sandbox como un permiso más. Es una barrera del sistema operativo, con alcance distinto.
- Creer que una regla de bloqueo de comandos es una barrera de seguridad. Solo cubre la forma en que el agente suele escribir el comando.
- Aprobar “no volver a preguntar” para comandos amplios como
findcon acciones de borrado. - Permitir dominios comodín sin pensar en qué se puede enviar hacia ellos.
- Usar el modo de omitir permisos en tu máquina de trabajo.
- Creer que el agente no puede leer tus credenciales porque no las escribe. La lectura por defecto es amplia.