Sandbox en Claude Code y agentes de IA: qué aísla y qué no
Una sandbox para agentes de IA es un entorno aislado en el que se ejecutan los comandos que lanza el agente, con límites que pone el sistema operativo y no el modelo: qué carpetas puede escribir, qué puede leer y a qué servidores puede conectarse. Si el agente se equivoca, o si un texto malicioso lo convence de hacer algo que no debía, el daño se queda dentro de la caja.
Activas la sandbox de Claude Code y un comando del agente todavía puede leer tu ~/.ssh. No es un fallo: es lo que hace por defecto. «Tengo la sandbox activada» suena a «está todo aislado», y en Claude Code no es así. El 16 de noviembre de 2026, Simon Willison publicó una propuesta de sandbox externa para agentes, una protección que, en sus palabras, no depende del juicio de ningún modelo; al conectarla con Claude Code aparece el mismo límite que tiene la sandbox integrada (la comparación es nuestra). Este artículo explica qué aísla de verdad una sandbox, con la documentación oficial de Claude Code y una prueba ejecutada, y dónde encaja en un trabajo con agentes que tenga que durar. Es la idea de la IA Limpia: las barreras que no dependen de que el modelo «se porte bien».
Un símil: la vitrina del taller
Imagina un taller donde un aprendiz muy rápido hace pruebas con productos químicos. Para que no se haga daño, le pones una vitrina con guantes: todo lo que mezcla, lo mezcla dentro. Pero el aprendiz también tiene una mano libre para abrir los cajones de la mesa, leer los cuadernos y cambiar las etiquetas de los frascos. La vitrina protege de las mezclas, no de los cajones.
Así funciona la sandbox de Claude Code: los comandos de terminal van dentro de la vitrina; las herramientas para leer y editar ficheros, no. El símil se queda corto en una cosa: en el taller ves al aprendiz abrir el cajón. Con un agente, solo lo ves si revisas lo que ha hecho.
Qué es la sandbox de Claude Code
Según la documentación oficial de Claude Code, la sandbox es una frontera que impone el sistema operativo alrededor de los comandos de terminal (Bash, PowerShell y Monitor) y de los procesos que lanzan. Viene desactivada por defecto.
Por debajo usa mecanismos del sistema:
| Sistema | Cómo aísla |
|---|---|
| macOS | Seatbelt, el mecanismo de aislamiento de Apple: bloquea toda conexión salvo la del proxy |
| Linux y WSL2 | bubblewrap, que aísla los ficheros y mete el comando en una red propia sin salida (network namespace), y socat, que la conecta con el proxy |
| Windows nativo | No hay sandbox: los comandos se ejecutan sin aislar. Hace falta WSL2 |
La red pasa por un proxy en tu máquina que comprueba cada servidor contra una lista de dominios permitidos, que empieza vacía. El proxy decide por el nombre del servidor y, por defecto, no mira el contenido cifrado. Por eso la documentación avisa de que un dominio amplio, como github.com, puede servir para sacar datos: permite solo los que necesites.
Lo que cubre y lo que no
Es la parte clave. La documentación lo dice sin rodeos: «The sandbox covers shell commands only. Claude’s file tools, MCP servers, and hooks run outside it» (la sandbox solo cubre los comandos de terminal; las herramientas de ficheros de Claude, los servidores MCP y los hooks se ejecutan fuera, traducción nuestra).
| Qué | Dónde se ejecuta |
|---|---|
| Comandos de terminal (Bash, PowerShell, Monitor) | Dentro |
| Leer, editar y escribir ficheros (Read, Edit, Write) | Fuera |
| Buscar y descargar de la web (WebSearch, WebFetch) | Fuera |
| Servidores MCP locales, hooks y otros procesos auxiliares | Fuera |
Lo que escribes tú con ! (casi siempre) y los comandos excluidos |
Fuera |
Un detalle que lo muestra bien: según la misma página, bloquear la lectura de una carpeta en la sandbox no impide que la herramienta Read la lea, y la lista de dominios permitidos no limita a WebFetch. Para esas herramientas mandan las reglas de permisos, que son otra cosa.
Lo que permite por defecto
Activada y sin tocar nada, la sandbox deja esto:
| Acceso | Por defecto |
|---|---|
| Escribir | La carpeta de trabajo, la temporal del usuario y las carpetas añadidas. Los ajustes de .claude, .git/hooks y otros ficheros sensibles del proyecto siguen protegidos |
| Leer | Casi todo el equipo, incluidos ficheros de credenciales como ~/.ssh y ~/.aws/credentials |
| Red | Nada directo: solo a través del proxy, con la lista de dominios permitidos |
| Variables de entorno | Las hereda de Claude Code, secretos incluidos. Se pueden quitar o enmascarar una a una con las entradas credentials (el enmascarado es experimental) |
Hay otro detalle que conviene saber antes de fiarse: si la plataforma no la admite o al arrancar falta una dependencia, los comandos se ejecutan sin sandbox, salvo que actives sandbox.failIfUnavailable.
Cómo activar la sandbox en Claude Code
Se activa con el comando /sandbox dentro de una sesión, que deja elegir entre dos modos: en el automático, los comandos que corren dentro de la sandbox se aprueban solos; en el normal, siguen pidiendo permiso como siempre. O se activa en los ajustes, con sandbox.enabled. En Linux y WSL2 necesita antes bubblewrap y socat, que se instalan con permisos de administrador.
Un ejemplo de ajustes, montado con las claves de la documentación oficial. [SIN EJECUTAR]: en el equipo de prueba no está socat, así que no se ha activado la sandbox real.
{
"sandbox": {
"enabled": true,
"failIfUnavailable": true,
"allowUnsandboxedCommands": false,
"filesystem": {
"denyRead": ["~/"],
"allowRead": ["."]
},
"network": {
"allowedDomains": ["registry.npmjs.org"]
}
}
}
Qué hace cada parte:
denyReadcon~/yallowReadcon.cierran la lectura de tu carpeta personal y abren solo el proyecto: gana la regla más concreta. Es el patrón que propone la documentación. Si solo cierras carpetas sueltas, como~/.ssh, se escapan otras credenciales:~/.npmrc,~/.config/gho el.envde otro proyecto. Algunas herramientas pueden necesitar que abras su caché.allowedDomainscon un dominio concreto, no uno amplio.failIfUnavailablehace que falle si no puede aislar, en vez de seguir sin avisar.allowUnsandboxedCommands: falsecierra la vía de escape: cuando un comando falla dentro, el agente puede pedir reintentarlo fuera, y según el modo de permisos eso se aprueba con una pregunta, con un clasificador, sin preguntar o se deniega. Con esta opción, no hay reintento fuera.
Si quieres que lo use todo el equipo, ponlo en los ajustes compartidos del proyecto, para que entre en el repositorio y se revise como el código.
Qué hace la caja por debajo: una prueba en Linux
En Linux, la caja la pone bubblewrap. Se puede ver qué significa con una prueba que se parece a la configuración por defecto: Claude Code también parte de un sistema en solo lectura (--ro-bind / /) y sin red (--unshare-net), aunque añade el proxy, la carpeta temporal con escritura y las rutas protegidas. No es la sandbox de Claude Code, sino la herramienta en la que se apoya.
La prueba usa una carpeta proyecto y, a su lado, una carpeta credenciales con una clave falsa que solo puede leer su dueño:
mkdir proyecto credenciales
echo clave-falsa > credenciales/clave.txt
chmod 600 credenciales/clave.txt
cd proyecto
Dentro de proyecto, un script prueba.sh intenta cuatro cosas:
echo hola > dentro.txt && echo "1. escribir dentro: sí"
(echo x > ../fuera.txt) 2>/dev/null \
&& echo "2. escribir fuera: sí" \
|| echo "2. escribir fuera: no"
cat ../credenciales/clave.txt >/dev/null 2>&1 \
&& echo "3. leer la credencial: sí" \
|| echo "3. leer la credencial: no"
curl -sS --max-time 5 https://example.com -o /dev/null
Se ejecuta dentro de la caja, con escritura solo en el proyecto y sin red:
bwrap --ro-bind / / --dev /dev --proc /proc \
--bind "$PWD" "$PWD" --unshare-net --chdir "$PWD" \
bash prueba.sh
1. escribir dentro: sí
2. escribir fuera: no
3. leer la credencial: sí
curl: (6) Could not resolve host: example.com
Escribe donde le dejas, no escribe fuera, no sale a la red (dentro solo existe la red local de la propia caja, así que curl ni siquiera puede averiguar la dirección del servidor) y lee la credencial. Eso último es lo que hay que recordar.
Ahora con la carpeta de credenciales tapada, que es como la sandbox de Claude Code aplica denyRead en Linux:
bwrap --ro-bind / / --dev /dev --proc /proc \
--bind "$PWD" "$PWD" --unshare-net --chdir "$PWD" \
--tmpfs "$(dirname "$PWD")/credenciales" \
bash prueba.sh
1. escribir dentro: sí
2. escribir fuera: no
3. leer la credencial: no
curl: (6) Could not resolve host: example.com
Si quieres que lo de fuera también quede dentro
La documentación de Claude Code tiene su propia respuesta al hueco, en la página «Choose a sandbox environment»: meter el proceso entero en la caja.
| Opción | Qué aísla, según la documentación |
|---|---|
| Sandbox de comandos | Solo los comandos de terminal y sus procesos |
Sandbox runtime (srt claude) |
Todo el proceso de Claude Code: herramientas de ficheros, MCP y hooks. En beta |
| Dev container o contenedor propio | Todo el entorno de desarrollo |
| Máquina virtual | Todo el sistema operativo, con su propio núcleo |
Lo dice con claridad: la sandbox de comandos sola «is not sufficient for fully unattended runs» (no basta para dejar al agente trabajar sin supervisión). Y si lo lanzas con --dangerously-skip-permissions, pide hacerlo siempre dentro de un contenedor, una máquina virtual o el sandbox runtime.
La sandbox externa de Willison
El artículo de Simon Willison en el blog de Prime Radiant, «External sandboxes for coding agents» (16 de noviembre de 2026), propone otra forma de lo mismo: el agente sigue en tu equipo, pero envía sus comandos a una máquina virtual Linux aparte, en el mismo equipo, que por defecto no puede comunicarse con el exterior. Publica tres prototipos con la misma interfaz local: uno con un emulador en WebAssembly que funciona con Node.js 22.19 o posterior, y dos que necesitan un Mac con Apple Silicon.
Dos ideas del artículo se pueden aplicar sin usar sus prototipos:
- Las credenciales no entran en la caja. Un proxy con lista blanca sustituye un token de mentira por el real al salir, así que el agente nunca lo ve. El artículo avisa de que un servidor permitido podría devolver la credencial, así que solo debe usarse con servicios de confianza. Claude Code tiene algo parecido, todavía experimental: las entradas
credentialsen modomask. - El límite se dice en voz alta. Con Claude Code, la sandbox externa recibe los comandos de terminal a través de la variable
CLAUDE_CODE_SHELL_PREFIX, y el artículo lo reconoce: «Unlike the other agents, Claude Code’s read and edit tools do not run via the sandbox» (a diferencia de los otros agentes, las herramientas de lectura y edición de Claude Code no pasan por la sandbox, traducción nuestra). Es, según la documentación de Claude Code, el mismo límite que tiene la sandbox integrada (la comparación es nuestra).
Willison avisa de que los prototipos son experimentales y no están auditados para cargas sensibles.
Dónde encaja la sandbox en el arnés
Esta sección es interpretación nuestra, dentro del enfoque de esta web.
Una sandbox es una capa más del arnés de un agente, junto a los tests, los linters, los hooks y la integración continua. No es solo una opinión de esta web: el Technology Radar de Thoughtworks (vol. 35, 4 de noviembre de 2026) coloca la sandbox de agentes en Adopt, como opción por defecto para todos los agentes, y pide decidir el nivel de aislamiento con un modelo de amenazas. Cada capa tapa un hueco distinto:
| Capa | De qué protege | De qué no |
|---|---|---|
| Sandbox | De que un comando borre, escriba o envíe datos fuera de lo permitido | De que el código esté mal |
| Permisos | De que una herramienta se use sin preguntar | De lo que hace un comando ya aprobado |
| Tests y CI | De romper lo que ya funcionaba | De lo que ningún test comprueba |
| Revisión humana | De lo que nadie había previsto | Del cansancio, si el agente produce más de lo que se revisa |
Es el dilema de la IA Limpia en pequeño: la sandbox permite que el agente corra solo sin que un comando haga daño; que el código dure sigue dependiendo de los tests y la revisión.
Por eso «tengo sandbox» no responde a «¿es seguro dejar que el agente trabaje solo?». Responde a una pregunta más pequeña: si un comando sale mal, ¿hasta dónde llega el daño? Las instrucciones, permisos, hooks y tests siguen haciendo falta, sobre todo frente a la inyección de instrucciones, que es justo el caso en que el agente hace algo que no le pediste. Hace falta cerrar las dos mitades, ficheros y red: con la red abierta, lo que se puede leer se puede sacar.
Errores frecuentes
- Creer que cubre la lectura y la edición de ficheros. En Claude Code solo cubre los comandos.
- Dejar abierta la lectura de credenciales. Por defecto,
~/.sshy~/.awsse leen. - Permitir dominios amplios.
github.comsirve también para sacar datos. - Excluir comandos que ejecutan ficheros del proyecto. La documentación avisa de que un comando excluido se ejecuta con todos tus permisos, y que si el patrón cubre un intérprete o una herramienta como
docker compose, el agente puede escribir el fichero dentro y ejecutarlo fuera. - No enterarse de que no arrancó. Sin
failIfUnavailable, si falta una dependencia, todo sigue funcionando sin aislar.
Límites
- Lo que dice la documentación cambia con cada versión. Este artículo usa las páginas de Claude Code consultadas el 20 de noviembre de 2026, que no llevan fecha. Comprueba la vigente antes de configurar.
- No se ha ejecutado la sandbox de Claude Code. En Linux necesita
socat, que se instala con permisos de administrador. La prueba usa bubblewrap directamente, con una configuración parecida, no la sandbox completa. - La caja no cambia lo que ve el modelo. Lo que el agente lee se envía al proveedor del modelo con sandbox o sin ella, como recuerda la propia documentación.
- Una sandbox no detecta errores de lógica. Un agente puede escribir, dentro de la caja, código que compila, pasa tus tests y está mal. Eso lo cubren los tests y la revisión.
Tu siguiente paso
Si usas un agente que ejecuta comandos, haz la pregunta en voz alta: ¿qué puede leer ahora mismo? Si la respuesta incluye ~/.ssh, tus credenciales en la nube o el .env de otro proyecto, ciérralo con la sandbox o con las reglas de permisos antes de dejarle trabajar sin supervisión. Y si quieres poner el resto de barreras, sigue con los hooks de Claude Code.
Si decides cómo trabaja tu equipo con agentes, la pregunta pasa de una persona a todas: ¿qué puede leer el agente en cada máquina, y qué ocurre si la sandbox no arranca? Pon la respuesta en los ajustes compartidos del proyecto, y si el agente va a trabajar sin supervisión, en un contenedor o una máquina virtual. Y no lo cuentes como seguridad completa: es una capa del arnés, junto a los tests y la revisión.
Fuentes
Consultadas el 20 de noviembre de 2026.
- Anthropic, «Sandboxing» en la documentación de Claude Code (sin fecha; menciona versiones hasta la 2.1.315): qué cubre y qué no, valores por defecto, mecanismos por sistema, ajustes,
credentials, reintento sin sandbox, aviso sobre dominios amplios y comandos excluidos. - Anthropic, «Choose a sandbox environment»: comparación de opciones, sandbox runtime en beta, que la sandbox de comandos no basta para trabajar sin supervisión y que aislar no cambia lo que se envía al modelo.
- Simon Willison, «External sandboxes for coding agents», blog de Prime Radiant (16 de noviembre de 2026): el patrón de sandbox externa, los tres prototipos, el proxy con credenciales y el límite con Claude Code.
- Thoughtworks, Technology Radar, «Agent sandboxing» (vol. 35, 4 de noviembre de 2026): en Adopt.
Código: la prueba con bubblewrap se ejecutó el 20 de noviembre de 2026 con bubblewrap 0.11.1 y curl 8.18.0 en Linux, en una carpeta de prueba. Los ajustes JSON combinan claves de la documentación oficial y no se han ejecutado.