Tutorial del sandbox de Claude Code: guía de configuración de /sandbox
Ejecuta /sandbox, elige auto-allow y mete cada comando bash dentro de un perímetro impuesto por el sistema operativo — con las claves de ajustes reales, no folklore. 12 pasos verificados contra la documentación oficial.
TL;DR
- El comando /sandbox abre un panel con las pestañas Mode, Overrides y Config. El modo auto-allow ejecuta comandos bash aislados sin pedir permiso; regular permissions conserva cada confirmación.
- El perímetro lo impone el kernel, no los avisos: Seatbelt en macOS, bubblewrap en Linux y WSL2. El Windows nativo y WSL1 no están soportados.
- Los comandos aislados solo pueden escribir en tu directorio de trabajo, un directorio temporal por usuario y las rutas de --add-dir. El tráfico de red pasa por un proxy que no pre-autoriza ningún dominio.
- Las lecturas no se bloquean por defecto — ~/.ssh y ~/.aws siguen legibles hasta que añadas reglas sandbox.credentials. El diálogo Sandbox de VS Code llegó en la v2.1.280.
Claude Code Sandbox Explained
Canal:The Art of Vibe Coding4:29
How auto mode works with Claude Code
Canal:Claude5:42
Configure the sandboxed Bash tool (official docs)
Docs:code.claude.com
El primer vídeo es una pieza de motion graphics — sus fotogramas en esta página son ilustraciones estilizadas, no capturas, y algunas de sus afirmaciones se corrigen en los pasos de abajo (las credenciales son legibles por defecto; sus claves de ajustes de ejemplo no coinciden con las reales). El segundo vídeo es la grabación oficial de Anthropic; solo se usan su terminal real y su UI de ajustes.
Datos contrastados con code.claude.com/docs/en/sandboxing y el CHANGELOG de anthropics/claude-code (v2.1.280–2.1.283). Las capturas citan fragmentos breves de las grabaciones para el comentario.
Configura el sandbox de Claude Code en 12 pasos
Entiende el perímetro
- 1
Reconoce el problema de la fatiga de aprobación
Sin sandbox, cada comando sugerido se detiene a la espera de un y/n: npm install, git status, y el siguiente. Anthropic midió que el 97% de las solicitudes de permiso de Claude Code se aprueban, que es exactamente por lo que el sandbox saca la comprobación de cada comando y la lleva a un perímetro que configuras una vez.
Una recreación del bucle y/n por comando que el sandbox reemplaza — pulsar Enter 47 veces y dejar de leer.Ver en 0:22 - 2
Arranca Claude Code en una plataforma soportada
Abre una sesión en tu proyecto. El aislamiento viene integrado en macOS, donde Seatbelt viene con el sistema y no hay nada que instalar. En Linux y WSL2, instala primero bubblewrap y socat con tu gestor de paquetes. El Windows nativo y WSL1 no tienen soporte — los usuarios de Windows ejecutan Claude Code dentro de una distro WSL2.
Una sesión en ~/Documents/code/acme — ese directorio de trabajo es lo que el sandbox tratará como escribible.Ver en 0:35 - 3
Ejecuta /sandbox y lee el panel
Escribe /sandbox en la sesión. El panel tiene tres pestañas: Mode (cómo se aprueban los comandos aislados), Overrides (si los comandos que fallan pueden reintentarse fuera del sandbox — el ajuste allowUnsandboxedCommands) y Config (los ajustes de sandbox totalmente resueltos). Linux añade una pestaña Dependencies que lista lo que falte, como bubblewrap, socat o el filtro seccomp opcional. Desde la v2.1.281 puedes cambiar de pestaña con las flechas, y VS Code recibió un diálogo Sandbox con los mismos ajustes en la v2.1.280.
Actívalo
- 4
Elige auto-allow o permisos normales
En la pestaña Mode, auto-allow ejecuta los comandos aislados sin preguntar, mientras que regular permissions conserva las preguntas incluso para comandos aislados. La elección se guarda en el .claude/settings.local.json del proyecto, al que Claude Code añade el gitignore por ti. Para cubrir todos los proyectos, pon "sandbox": undefined en ~/.claude/settings.json; para una sola sesión, pásalo con --settings.
La guía rápida de dos pasos: /sandbox elige el modo, settings.json guarda lo duradero.Ver en 4:00 - 5
Sabe qué sigue preguntando el auto-allow
Auto-allow no es un botón de silencio. Las reglas deny explícitas siempre ganan, un rm o rmdir apuntado a rutas críticas sigue preguntando, y las reglas ask por contenido como Bash(git push *) siguen forzando confirmación. Los comandos que no pueden ejecutarse aislados caen al flujo normal con un aviso titulado "Bash command (unsandboxed)". El auto-allow también funciona de forma independiente de tu modo de permisos — el bash aislado corre sin avisos incluso en modo Manual.
shift+tab rota los modos de permiso — un control separado del auto-allow del sandbox.Ver en 0:28 - 6
Mira cómo el SO traza el perímetro
Las restricciones las impone el kernel, no son sugerencias educadas: macOS usa Seatbelt, Linux y WSL2 usan bubblewrap. Un comando con inyección de prompt que intente leer ~/.ssh o llamar a casa choca contra la misma pared, porque las reglas ligan al proceso en ejecución y a cada hijo que genere — ante el kernel no hay retórica que valga.
Las comprobaciones de permisos a nivel de aplicación se pueden esquivar; la capa del kernel no.Ver en 2:07
Sistema de archivos, credenciales y red
- 7
Entiende los valores por defecto del sistema de archivos — y la trampa de lectura
Los comandos aislados pueden escribir en el directorio de trabajo y sus subdirectorios, en un directorio temporal por usuario y en las carpetas añadidas con --add-dir o permissions.additionalDirectories. Las lecturas están abiertas por defecto: todo el disco es legible, incluidos ~/.aws/credentials y ~/.ssh, hasta que lo bloquees. Los vídeos explicativos suelen decir que las credenciales quedan “invisibles” — la documentación es tajante: protegerlas es cosa tuya, con sandbox.credentials o reglas denyRead.
Las escrituras se detienen en el muro del sandbox; las lecturas siguen abiertas hasta que las cierres en el siguiente paso.Ver en 1:30 - 8
Protege las credenciales antes de volverte autónomo
Añade un bloque sandbox.credentials: lista archivos como ~/.ssh o ~/.aws/credentials con "mode": "deny", y variables de entorno sensibles como GITHUB_TOKEN para que se vacíen dentro de cada comando aislado. El modo mask va más allá — el comando ve un valor centinela y el proxy del sandbox lo cambia por el real solo en los hosts que permitas. Las reglas Read de permissions.deny cubren las herramientas de archivo por encima.
Reglas deny para curl y lecturas de .env — el mismo archivo de ajustes lleva tu bloque sandbox.Ver en 4:35 - 9
Permite los dominios de red que necesita tu stack
Todo el tráfico aislado pasa por un proxy, y no hay dominios pre-autorizados. La primera vez que un comando necesite un host, Claude Code pregunta; responde "Yes, and don't ask again" y guarda una regla allow WebFetch(domain:...) para las próximas sesiones. Pre-autoriza registros con sandbox.network.allowedDomains, bloquea hosts concretos con deniedDomains y activa strictAllowlist para que la lista sea un techo duro y no una lista de preguntas.
Las descargas del registry pasan el proxy; un postinstall que llama a evil.com no pasa.Ver en 1:51 - 10
Acota la configuración: proyecto, usuario o gestionada
Los ajustes de proyecto en .claude/settings.json pueden añadir rutas escribibles y dominios, pero no pueden desactivar el aislamiento del sistema de archivos ni activar Apple Events — esas claves solo se honran desde ajustes de usuario, ajustes gestionados o la bandera --settings, así que un repositorio clonado no puede debilitar tu sandbox. Los equipos imponen el sandbox mediante ajustes gestionados con enabled, failIfUnavailable y allowUnsandboxedCommands en true/false/false.
Un archivo de ajustes gestionados describe el entorno de confianza de la organización — lo configuran los administradores, los desarrolladores lo heredan.Ver en 4:10
Verifica y corrige
- 11
Verifica con una tarea real
Pide una compilación o una pasada de tests. Los comandos aislados se ejecutan sin preguntar, y cuando algo se bloquea, la violación nombra la ruta o el host en el resultado del comando para que Claude se adapte. Abre la pestaña Config de /sandbox para leer cada regla resuelta, incluidas las rutas protegidas que ningún ajuste puede anular. Para una prueba estricta puntual, lanza con: claude --settings 'undefined}'.
Una tarea escrita, cero avisos por comando — el perímetro aguanta sin ti.Ver en 0:32 - 12
Diagnostica los fallos de siempre
jest se cuelga — watchman es incompatible, corre jest --no-watchman. docker falla — no puede correr aislado, añade "docker *" a excludedCommands. open u osascript falla con error -600 en macOS — Apple Events está bloqueado salvo que allowAppleEvents sea true. git merge o checkout falla con "unable to unlink old" — una ruta protegida o una regla denyWrite se interpone, así que aprueba el reintento fuera del sandbox o corre el comando tú mismo. bwrap reporta Operation not permitted dentro de un contenedor — activa enableWeakerNestedSandbox. Las tuberías al portapapeles fallan — usa /copy en lugar de pbcopy.
Los ajustes del sandbox que importan
El panel de /sandbox escribe lo básico, pero la palanca real está en settings.json. Estas son las claves que documenta la referencia oficial de sandboxing — todas viven bajo un bloque "sandbox" (la última bajo "permissions").
- 1sandbox.enabled — apagado hasta que lo actives. true en ~/.claude/settings.json cubre todos tus proyectos; el panel de /sandbox escribe la copia local del proyecto en .claude/settings.local.json.
- 2sandbox.autoAllowBashIfSandboxed — el interruptor de auto-allow, true por defecto. Ponlo en false para conservar los avisos de permiso incluso para comandos dentro del sandbox.
- 3sandbox.allowUnsandboxedCommands y sandbox.failIfUnavailable — false en la primera mata el reintento dangerouslyDisableSandbox (mostrado como Strict sandbox mode en la pestaña Overrides); true en la segunda convierte las dependencias ausentes en un fallo duro de arranque en lugar de un aviso.
- 4sandbox.filesystem — allowWrite para rutas fuera del proyecto que las herramientas necesiten ("~/.kube", "/tmp/build"), denyRead más allowRead para lugares secretos, y disabled (v2.1.216+) para retirar la capa de sistema de archivos manteniendo el aislamiento de red.
- 5sandbox.network — allowedDomains y deniedDomains, strictAllowlist (v2.1.219+) para prohibir todo lo no listado, allowLocalBinding para que los dev servers puedan bindear puertos, y tlsTerminate para el enmascaramiento de credenciales en el proxy.
- 6sandbox.credentials — entradas de files y envVars con modos deny o mask; los masks requieren tlsTerminate y solo se honran desde fuentes user, managed o --settings. Combínalo con permissions.blockReadsOutsideWorkingDirectories para cortar todas las lecturas fuera de tus directorios de trabajo.
Seatbelt vs bubblewrap: diferencias por plataforma
macOS usa Seatbelt, integrado en el sistema — no hay nada que instalar. Las asperezas son concretas: las CLI basadas en Go como gh, gcloud y terraform pueden fallar la verificación TLS bajo Seatbelt, así que añádelas a excludedCommands; open, osascript y los flujos de autenticación de navegador fallan con error -600 hasta que actives allowAppleEvents, lo que debilita el aislamiento y se ignora en los ajustes de proyecto.
Linux y WSL2 usan bubblewrap más socat, instalables con tu gestor de paquetes. El filtro seccomp opcional (npm install -g @anthropic-ai/sandbox-runtime) añade bloqueo de Unix domain sockets y es lo que permite a WSL2 mantener fuera los binarios de Windows. Ubuntu 24.04 y posteriores traen una política AppArmor que impide a bubblewrap crear user namespaces — añade el perfil bwrap de la documentación y recarga AppArmor. Dentro de un contenedor sin privilegios, activa enableWeakerNestedSandbox para que bubblewrap haga bind-mount del /proc existente.
WSL1 no tiene soporte alguno — bubblewrap necesita funciones del kernel que solo WSL2 tiene. La sobrecarga de rendimiento es mínima, aunque algunas operaciones de sistema de archivos corren algo más lento. Los subagentes corren en el mismo proceso que la sesión padre y heredan su configuración de sandbox, así que el bash en segundo plano dentro de un agente también queda aislado.
El manejo del sandbox sigue moviéndose entre versiones: la v2.1.280 añadió el diálogo Sandbox de VS Code, la v2.1.281 mejoró la navegación de pestañas de /sandbox y el aviso de allowLocalBinding para dev servers, y la v2.1.282–2.1.283 arregló el emparejamiento de excludedCommands, las escrituras a TMPDIR y el parseo de ajustes gestionados. Hojea el CHANGELOG antes de confiar en comportamientos de caso límite.