El sandbox de Claude Code encierra los comandos de shell que ejecuta el asistente dentro de un límite del sistema operativo: solo puede escribir en tu proyecto y solo puede salir a internet hacia dominios que tú permitas. Con la versión 2.1.325 del changelog oficial cambia cómo se combina con los permisos: los comandos de Bash dentro del sandbox pasan por el flujo normal de permisos, salvo que actives sandbox.autoAllowBashIfSandboxed. Aquí tienes qué cambió, cómo activarlo y qué riesgos siguen vigentes.
Qué cambió en la versión 2.1.325
El changelog oficial de Claude Code lista la 2.1.325 como la versión más reciente en la fecha de esta revisión (16 de noviembre de 2026); esa página no muestra fecha de lanzamiento, así que no la damos. Entre sus cambios hay varios que afectan al sandbox y a los permisos:
- El Bash dentro del sandbox sigue por defecto el flujo normal de permisos. Para que corra sin preguntar hay que poner
sandbox.autoAllowBashIfSandboxed: true. En configuraciones gestionadas por una organización, se recomienda fijarlo en la fuente de mayor rango. - El sandbox rechaza escrituras a la configuración, skills, agentes, comandos y hooks de
.claudeen directorios añadidos con--add-dir. - Los programas auxiliares del sandbox (y ripgrep y git local) se ejecutan sin tus tokens de sesión ni claves de API.
- Las tareas programadas y
/looppreguntan antes de ejecutar una skill que declareallowed-toolso hooks; para dejarlas sin supervisión se añadeSkill(nombre)apermissions.allow.
Ojo con un detalle: la página de documentación del sandbox, cuando la leí, todavía describe el auto-permiso como valor por defecto activado. El changelog y la documentación no coinciden del todo, así que no des por hecho ningún valor: comprueba en tu instalación qué modo aparece en /sandbox, pestaña Config, y fija el ajuste de forma explícita en tu settings.json.
Requisitos
- macOS: usa Seatbelt, que ya viene con el sistema; no hay que instalar nada.
- Linux y WSL2: hacen falta
bubblewrapysocat. WSL1 no es compatible. - Windows nativo: no está soportado; los comandos corren sin sandbox. Usa WSL2.
- Ubuntu 24.04 o superior: si
sysctl kernel.apparmor_restrict_unprivileged_usernsdevuelve 1, la documentación pide añadir un perfil de AppArmor para bwrap.
Si todavía no tienes Claude Code, empieza por la guía de instalación paso a paso.
Paso a paso para activarlo
1. Instala las dependencias (solo Linux y WSL2)
sudo apt-get install bubblewrap socat # Ubuntu / Debian
sudo dnf install bubblewrap socat # Fedora
2. Abre el panel del sandbox
Dentro de Claude Code escribe /sandbox. El panel tiene pestañas para el modo (auto-permiso o permisos normales), los overrides y la configuración resuelta, y también una pestaña de dependencias que te avisa de lo que falte. Tras instalar algo, reinicia Claude Code. Lo que elijas se guarda en .claude/settings.local.json, solo para ese proyecto.
3. Fija la configuración en settings.json
Para que valga en todos tus proyectos, edita ~/.claude/settings.json. Este ejemplo activa el sandbox, mantiene el auto-permiso de forma explícita, impide el reintento sin sandbox y hace que Claude Code se detenga si el sandbox no puede arrancar:
{
"sandbox": {
"enabled": true,
"autoAllowBashIfSandboxed": true,
"allowUnsandboxedCommands": false,
"failIfUnavailable": true,
"network": {
"allowedDomains": ["registry.npmjs.org", "pypi.org"]
}
}
}
Si prefieres que cada comando siga pidiendo confirmación aunque esté dentro del sandbox, pon autoAllowBashIfSandboxed en false. También puedes probarlo solo en una sesión pasando el JSON con claude --settings.
4. Comprueba que de verdad bloquea
Pídele a Claude (no uses el prompt con !, que normalmente corre fuera del sandbox) que ejecute estas dos pruebas. Las dos deben fallar:
touch ~/sandbox-probe
curl --noproxy '*' https://example.com
La primera debe dar un error de escritura denegada o sistema de archivos de solo lectura; la segunda, que no resuelve el host. Estos comandos vienen de la documentación oficial y no los ejecuté para este artículo.
Cómo interpretar los ajustes
| Ajuste | Qué hace |
|---|---|
sandbox.enabled | Activa el sandbox; por defecto está apagado. |
autoAllowBashIfSandboxed | true: los comandos sandboxeados corren sin preguntar. false: pasan por los permisos normales. |
allowUnsandboxedCommands | En false se ignora el reintento fuera del sandbox con dangerouslyDisableSandbox. |
failIfUnavailable | Si el sandbox no puede arrancar, Claude Code sale en vez de seguir sin protección. |
excludedCommands | Patrones de comandos que corren fuera del sandbox, con acceso completo. |
filesystem.allowWrite / denyRead | Rutas extra que se pueden escribir o que se bloquean para lectura. |
network.allowedDomains | Lista de dominios permitidos; empieza vacía. |
Por defecto, el sandbox permite escribir en el directorio de trabajo, sus subcarpetas y el directorio temporal, y mantiene protegidos la configuración de .claude, .mcp.json, los archivos de arranque del shell y .gitconfig. La red no tiene ruta directa: todo pasa por un proxy con la lista de dominios. Por eso herramientas que ignoran las variables de proxy, como ssh sin configurar o muchos drivers de bases de datos, fallan dentro del sandbox. Aunque un comando auto-permitido no pregunte, las reglas de denegación, el borrado en rutas críticas y las reglas ask con contenido, como Bash(git push *), siguen mandando.
Seguridad: lo que el sandbox no cubre
- Solo cubre comandos de shell. Las herramientas Read, Edit y Write, WebFetch, WebSearch, los servidores MCP y los hooks no están dentro del sandbox, así que
denyReadyallowedDomainsno los restringen. - La lectura es amplia por defecto. Incluye carpetas como
~/.sshy credenciales de nube salvo que las niegues. Puedes usarsandbox.credentialsopermissions.blockReadsOutsideWorkingDirectories. - Las exclusiones y los reintentos tienen acceso total. Un patrón demasiado amplio, como
docker *, puede permitir que Claude escriba un archivo en tu proyecto y lo ejecute fuera del sandbox. - No es una frontera perfecta. Para aislamiento fuerte, la propia documentación recomienda un contenedor o una máquina virtual.
Qué significa para quien programa
El cambio empuja hacia un equilibrio más prudente: el sandbox reduce el daño posible, pero la decisión de ejecutar sin preguntas pasa a ser explícita. Si trabajas en proyectos propios con dependencias conocidas, activar el sandbox con auto-permiso y una lista corta de dominios ahorra muchas interrupciones. Si abres repositorios ajenos, deja los permisos normales y revisa cada comando. Define también el contexto del proyecto con un buen CLAUDE.md comentado, y si te interesa cómo Claude orquesta herramientas, mira el artículo sobre Code Mode.
Preguntas frecuentes
¿El sandbox funciona en Windows?
No en Windows nativo, donde los comandos corren sin sandbox. Usa WSL2; WSL1 tampoco es compatible.
¿Con el sandbox activo ya no necesito revisar nada?
Sí necesitas revisar. El sandbox solo envuelve los comandos de shell; las herramientas de edición, los MCP y los hooks quedan fuera, y los comandos excluidos corren con acceso completo.
¿Qué pasa si faltan bubblewrap o socat?
Por defecto Claude Code avisa y ejecuta los comandos sin sandbox. Con failIfUnavailable: true se detiene al arrancar en lugar de continuar sin protección.
Fuentes
- Documentación oficial: Sandboxing de Claude Code
- Changelog oficial de Claude Code (versión 2.1.325)
- Referencia de ajustes de Claude Code
Última revisión: 16 de noviembre de 2026. Este artículo fue preparado con ayuda de IA; consulta cómo usamos la IA. Los comandos y ajustes provienen de la documentación oficial y no se ejecutaron para esta guía.
