La sandbox de Claude Code es un límite que el sistema operativo impone alrededor de los comandos de shell que ejecuta Claude, restringiendo a qué archivos y hosts de red pueden acceder esos comandos. La activas con /sandbox o estableciendo sandbox.enabled a true en un archivo de configuración, y una vez activa Claude Code puede ejecutar comandos aislados sin detenerse a pedirte que apruebes cada uno. Ese es el verdadero atractivo: menos solicitudes de permiso sin entregarle a un agente autónomo una shell abierta en tu portátil.
Esta guía cubre qué restringe realmente la sandbox, cómo activarla en macOS, Linux y WSL2, los dos modos de aprobación y las partes que se ejecutan fuera del límite: el hueco que a principios de este año se convirtió en un verdadero fallo de exfiltración de datos. Nosotros ejecutamos Claude Code en automatización headless para publicar este sitio, así que acertar con el límite de la shell no es algo teórico para nosotros.
¿Qué es la sandbox de Claude Code?
La sandbox está integrada en Claude Code y envuelve cada comando de Bash, PowerShell y Monitor, además de los procesos hijos que esos comandos generan. Traza dos límites a la vez: lo que un comando puede tocar en disco y lo que puede alcanzar por la red. El sistema operativo impone ambos mientras el comando se ejecuta, y por eso un comando aislado puede aprobarse automáticamente: es el kernel, no una solicitud, quien mantiene la línea.
Viene desactivada por defecto. En macOS utiliza el framework Seatbelt integrado, así que no hay nada que instalar. En Linux y WSL2 depende de bubblewrap para el aislamiento del sistema de archivos y de socat para redirigir el tráfico de red a través de un proxy local; el panel de /sandbox te indica si falta alguno de los dos. En Windows nativo no hay sandbox en absoluto: los comandos se ejecutan sin aislamiento a menos que ejecutes Claude Code dentro de una distribución WSL2. Por debajo se apoya en el paquete de código abierto @anthropic-ai/sandbox-runtime.
Cómo funcionan el aislamiento del sistema de archivos y de red
Los dos límites tienen valores por defecto distintos, y amplías o restringes cada uno de forma independiente. La tabla siguiente muestra el estado inicial y los ajustes que lo modifican.
| Acceso | Comportamiento por defecto | Cámbialo con |
|---|---|---|
| Escrituras | El directorio de trabajo, un directorio temporal por usuario y cualquier directorio que añadas con --add-dir. Las rutas protegidas siguen con la escritura denegada | filesystem.allowWrite, filesystem.denyWrite |
| Lecturas | La mayor parte de la máquina, incluidos archivos de credenciales como ~/.ssh y ~/.aws/credentials | filesystem.denyRead, credentials |
| Red | Sin ruta directa de salida; cada conexión pasa por un proxy local que comprueba el host contra tus dominios permitidos, que empiezan vacíos | network.allowedDomains, network.deniedDomains |
La asimetría que conviene interiorizar: las escrituras están bloqueadas por defecto, pero las lecturas están abiertas de par en par. Un comando aislado no puede escribir fuera de tu proyecto, pero aún puede leer tus claves SSH y tus credenciales de la nube a menos que añadas una regla denyRead o uses la protección credentials. En el lado de la red ocurre lo contrario: denegación por defecto, con una lista de permitidos que vas construyendo a medida que los comandos necesitan hosts concretos.
Cómo activar la sandbox de Claude Code
La vía más rápida es la interactiva:
- Ejecuta
/sandboxen una sesión. El panel tiene una pestaña Mode, una pestaña Overrides (la alternativaallowUnsandboxedCommands) y una pestaña Config que muestra la configuración resuelta. En Linux aparece una pestaña Dependencies si faltabubblewrap,socato ripgrep. - Elige un modo (explicado más abajo) y pídele a Claude que ejecute una compilación o una batería de pruebas. Al seleccionar un modo se escribe en el
.claude/settings.local.jsondel proyecto. - Actívala en todas partes estableciendo
sandbox.enabledatrueen~/.claude/settings.json, o imponla a todo un equipo con la configuración gestionada.
Para una única sesión sin tocar un archivo de configuración, pásalo en la CLI:
claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'
Para verificar que está activa, pídele a Claude que ejecute touch ~/sandbox-probe (debería fallar con Operation not permitted o Read-only file system) y curl --noproxy '*' https://example.com (debería fallar con Could not resolve host). Si necesitas que el agente se detenga por completo cuando la sandbox no pueda arrancar —en lugar de volver silenciosamente al modo sin aislamiento— establece sandbox.failIfUnavailable a true. Ese ajuste marca la diferencia entre «la sandbox es una comodidad» y «la sandbox es una barrera de seguridad».
Modos de la sandbox: aprobación automática frente a permisos normales
Ambos modos imponen los mismos límites de sistema de archivos y de red. La única diferencia es la aprobación.
- El modo de aprobación automática ejecuta los comandos aislados sin ninguna solicitud. Aquí reside la recompensa frente a la fatiga de permisos: un comando que solo escribe dentro del límite simplemente se ejecuta, incluso en modo manual. Las reglas de denegación se siguen respetando,
rmcontra una ruta crítica sigue solicitando confirmación y las reglas de pregunta acotadas al contenido, comoBash(git push *), siguen forzando una solicitud. - El modo de permisos normales envía cada comando de Bash por el flujo de permisos habitual incluso estando aislado: más control, más clics.
La primera vez que un comando necesita un nuevo dominio de red, Claude Code te pide que lo añadas a la lista de permitidos. En modo automático el modelo, en cambio, declara los hosts que un comando necesita en el propio comando, y un clasificador del lado del servidor los revisa. Ten en cuenta que el modo de planificación no hereda la aprobación automática: sigue filtrando los comandos mientras planificas.
Qué se ejecuta fuera de la sandbox (la parte que la gente pasa por alto)
La sandbox envuelve los comandos de shell. No lo envuelve todo, y esto es lo peor entendido de ella. Se ejecutan fuera del límite:
- Las herramientas integradas de archivos y web: Read, Edit, Write, WebFetch y WebSearch siguen las reglas de permisos en su lugar. Una entrada
denyReadno detiene a la herramienta Read, yallowedDomainsno limita a WebFetch. - Los servidores MCP y los hooks: ambos se ejecutan sin aislamiento.
- Los comandos que escribes en el prompt de shell
!, cualquier cosa que coincida conexcludedCommandsy cualquier reintento sin aislamiento, en el que Claude vuelve a ejecutar un comando fallido condangerouslyDisableSandbox.
Así que un denyRead sobre ~/.aws/credentials bloquea un cat aislado, pero no a la herramienta Read ni a un servidor MCP que acceda al mismo archivo. Si quieres un único límite alrededor de todo eso, la sandbox es la capa equivocada: ejecuta el proceso completo de Claude Code dentro de un contenedor o una máquina virtual. Esto importa sobre todo cuando ejecutas Claude Code en modo headless en CI, donde no hay ningún humano que pueda rechazar un reintento sin aislamiento.
Una sandbox no es una cárcel: la lección del bypass de salida
Trata la lista de dominios permitidos como defensa en profundidad, no como una caja fuerte. Investigadores de seguridad revelaron un bypass de salida de red en la sandbox de Claude Code que afectaba a las versiones 2.0.24 hasta la 2.1.89 —unas 130 versiones— en el que un truco de nombre de host con byte nulo en SOCKS5 permitía que los comandos alcanzaran dominios bloqueados y exfiltraran claves de API, tokens y código fuente. Un nombre de host manipulado como attacker.com\x00.google.com superaba la comprobación de la lista de permitidos en JavaScript (veía el sufijo .google.com), mientras que el resolutor del sistema operativo lo truncaba en el byte nulo y conectaba con el atacante. Anthropic incorporó una validación de nombres de host más estricta en la v2.1.90 el 1 de abril de 2026, al parecer sin un CVE ni una nota en el registro de cambios.
Las conclusiones prácticas: mantén Claude Code actualizado, mantén allowedDomains tan corta como la tarea permita, establece sandbox.failIfUnavailable allí donde la sandbox sea un control real y, para cualquier cosa que maneje secretos de producción, aísla el proceso completo, no solo su shell. La sandbox eleva de forma apreciable el coste de un error o de una inyección de prompt, pero es una sola capa, y las capas han tenido agujeros.
Preguntas frecuentes
¿La sandbox de Claude Code está activada por defecto?
No. Está desactivada hasta que ejecutas /sandbox o estableces sandbox.enabled a true en un archivo de configuración. En Windows nativo no se ejecuta en absoluto a menos que uses WSL2.
¿La sandbox impide que Claude lea mis credenciales?
No por defecto. Los comandos aislados pueden leer la mayor parte de la máquina, incluidos ~/.ssh y ~/.aws/credentials. Añade una regla filesystem.denyRead o usa la protección credentials, y recuerda que la herramienta Read y los servidores MCP quedan por completo fuera de la sandbox.
¿Qué necesito instalar en Linux?
bubblewrap y socat son obligatorios; ripgrep viene con el binario nativo, y un filtro seccomp opcional (de @anthropic-ai/sandbox-runtime) añade el bloqueo de sockets Unix. La pestaña Dependencies de /sandbox enumera lo que falta.
¿La sandbox reducirá las solicitudes de permiso?
Sí, en el modo de aprobación automática: los comandos aislados se ejecutan sin preguntar, porque el sistema operativo impone el límite. Las reglas de denegación, el rm contra rutas críticas y las reglas de pregunta acotadas al contenido siguen solicitando confirmación.
¿Basta la sandbox para ejecutar un agente de forma segura sobre datos de producción?
Trátala como una sola capa. Restringe los comandos de shell, pero no las herramientas de archivos, los servidores MCP ni los hooks, y ha tenido al menos un fallo de bypass de salida. Para los secretos de producción, ejecuta el proceso completo en un contenedor o una máquina virtual.
Fuentes
- Documentación de Claude Code — Configurar la herramienta Bash aislada: qué restringe la sandbox, claves de configuración, modos, dependencias y qué se ejecuta fuera de ella.
- GBHackers — Un fallo en la sandbox de Claude Code puede comprometer los secretos del usuario: el bypass de salida con byte nulo en SOCKS5, las versiones afectadas 2.0.24–2.1.89 y la corrección en la v2.1.90.
- anthropics/sandbox-runtime (GitHub): el paquete de código abierto sobre el que se construye la sandbox integrada.
Waqas Ahmed Waseer
Waqas Ahmed Waseer es desarrollador y creador de automatizaciones con más de 8 años construyendo sistemas en producción que usan más de 100.000 personas. Crea SaaS multiinquilino a medida, automatización con IA (n8n, flujos LLM, bots de WhatsApp) e infraestructura de hosting (WHM/cPanel, CloudLinux), y es el creador de WaSphere, FlowMaticX y la marca de hosting WaseerHost. Más de 100 proyectos entregados para pymes, agencias y startups financiadas.
