Claude Code sandbox: aísla el bash del agente sin Docker

Le pides a Claude Code que arregle un test que falla. Lee el error, decide que falta una dependencia y lanza un npm install. El paquete trae un script postinstall. Ese script corre con tu usuario, en tu máquina, con acceso a tu ~/.ssh y a la red.

Y aquí está la trampa: aprobaste el npm install porque tenía sentido. El permiso que diste era para el comando, no para todo lo que ese comando ejecuta por debajo. El Claude Code sandbox existe para cerrar ese hueco sin que tengas que montar Docker.

En corto: el Claude Code sandbox (/sandbox) aísla a nivel de sistema operativo los comandos de shell del agente y sus procesos hijos: solo escriben en el proyecto y solo salen a la red por los dominios que permites. Viene desactivado y funciona en macOS, Linux y WSL2, no en Windows nativo. No cubre las herramientas de archivos, los servidores MCP ni los hooks.

¿Qué es el Claude Code sandbox?

El Claude Code sandbox es un límite que impone el sistema operativo alrededor de los comandos de shell que ejecuta el agente, restringiendo qué archivos pueden escribir y a qué dominios de red pueden conectarse, incluidos los procesos que esos comandos lancen.

Lo importante es quién lo impone. Una regla de permisos lee el texto del comando antes de ejecutarlo. El sandbox actúa sobre el proceso mientras corre. La documentación oficial de sandboxing (consultada el 10 de octubre de 2026) dice que el límite se mantiene "aunque un comando permitido haga más de lo que su nombre sugiere". Justo el postinstall del ejemplo.

Por debajo usa Seatbelt en macOS y bubblewrap más socat en Linux y WSL2, sobre el paquete open source @anthropic-ai/sandbox-runtime.

Qué aísla /sandbox en Claude Code por defecto

Por defecto, un comando sandboxed escribe solo en el proyecto, el temp por usuario y los directorios añadidos, y sale a la red solo por un proxy local con una lista de dominios que empieza vacía. Pero dos valores por defecto conviene leerlos dos veces:

Acceso	Por defecto	Con qué se cambia
Escritura	Directorio de trabajo, temp por usuario, directorios añadidos	filesystem.allowWrite, filesystem.denyWrite
Lectura	Casi toda la máquina, incluidos ~/.ssh y ~/.aws/credentials	filesystem.denyRead, credentials
Red	Sin ruta directa; proxy con lista de dominios vacía	network.allowedDomains, network.deniedDomains
Variables de entorno	Heredadas de Claude Code, secretos incluidos	credentials, CLAUDE_CODE_SUBPROCESS_ENV_SCRUB

Fuente: tabla "What the sandbox restricts" de la doc oficial, octubre de 2026.

El Claude Code sandbox impide que el agente escriba fuera del proyecto o salga a un host no aprobado. No impide que lea tus credenciales: no hay lista bloqueada de serie, solo se protege lo que declaras.

Dentro del proyecto, eso sí, protege los archivos de configuración (.claude/settings*, .claude/hooks, .mcp.json, .bashrc, los hooks de .git), para que un comando no pueda darse permisos ni registrar un hook que corra fuera.

Cómo activar el Claude Code sandbox

Ejecuta /sandbox en una sesión o pon sandbox.enabled: true en tus settings:

/sandbox

En Mode eliges auto-allow (los comandos sandboxed no piden permiso; es el valor por defecto) o permisos regulares (apruebas cada comando). Se guarda en .claude/settings.local.json, solo para ese proyecto.

Mi regla: configúralo en ~/.claude/settings.json, no en el panel, para que valga en todos los proyectos, y endurécelo:

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false,
    "network": {
      "allowedDomains": ["registry.npmjs.org"]
    },
    "credentials": {
      "files": [
        { "path": "~/.ssh", "mode": "deny" },
        { "path": "~/.aws/credentials", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" }
      ]
    }
  }
}

Ojo: denegar ~/.ssh oculta tus claves, así que git push y git pull por SSH dejan de funcionar dentro del sandbox (en macOS ya fallan de serie). Usa remotos HTTPS o saca esos comandos con excludedCommands.

failIfUnavailable importa: por defecto, si falta una dependencia o la plataforma no está soportada, Claude Code ejecuta los comandos sin sandbox y sigue. En true, se niega a arrancar.

Para comprobarlo, pídele a Claude (no lo teclees con !, eso corre fuera) que ejecute touch ~/sandbox-probe. Debe fallar con Operation not permitted en macOS o Read-only file system en Linux y WSL2.

En el curso Construye con IA montamos el flujo completo con Claude Code; el sandbox es la capa que conviene añadir antes de darle más autonomía.

Claude Code sandbox en Windows: hazlo con WSL2

En Windows nativo no hay sandbox: Claude Code ejecuta los comandos sin aislar. La única vía sin contenedores es correr Claude Code dentro de una distribución WSL2.

Los pasos, según la doc:

1. En PowerShell, wsl -l -v. Si tu distro sale con versión 1, conviértela a WSL2: con WSL1 el sandbox no arranca.
2. Dentro de Ubuntu o Debian: sudo apt-get install bubblewrap socat.
3. En Ubuntu 24.04 o superior, ejecuta sysctl kernel.apparmor_restrict_unprivileged_userns. Si devuelve 1, AppArmor impide a bubblewrap crear user namespaces y tienes que añadir el perfil de bwrap que da la doc.
4. Instala Claude Code dentro de WSL2, reinícialo después de instalar los paquetes y ejecuta /sandbox. Si falta bubblewrap o socat, el panel solo muestra la pestaña Dependencies; si solo falta el filtro seccomp, que es opcional, Dependencies aparece junto a las demás.

Ojo: desde WSL2, lanzar binarios de Windows (cmd.exe, /mnt/c/) pasa por un socket Unix al host; bloquearlo exige el filtro seccomp opcional (npm install -g @anthropic-ai/sandbox-runtime).

Esto no siempre funcionó: en el issue #10567 (octubre de 2025, v2.0.28), /sandbox rechazaba WSL2. Hoy la doc lo lista como soportado, pero el issue sigue abierto y en agosto de 2026 aún había quien lo reportaba en la v2.1.175. Por eso conviene failIfUnavailable: si en tu WSL2 no arranca, te enteras al iniciar y no a mitad de sesión.

¿Sandbox nativo, Docker o nada? Cómo aislar un agente de IA

Para aislar un agente de IA en tu máquina, /sandbox es la opción más barata, pero solo cubre la shell; Docker o una VM cubren el proceso entero:

Opción	Qué aísla	Qué NO aísla	Coste de montarlo	Riesgo principal
Nada (solo permisos)	Nada a nivel de SO; depende de que apruebes bien	Todo lo que haga el comando aprobado y sus hijos	Cero	Un comando legítimo ejecuta código no revisado con tu usuario
/sandbox nativo	Bash, PowerShell, Monitor y sus procesos hijos	Herramientas de archivos, MCP, hooks, comandos que tecleas con !	Mínimo en macOS; bajo en Linux/WSL2	Lectura de credenciales si no las declaras; fallback silencioso sin failIfUnavailable
Sandbox runtime (npx @anthropic-ai/sandbox-runtime claude)	El proceso entero de Claude Code, MCP y hooks incluidos	Lo que permitas en su config	Bajo, pero es beta	Formato de configuración que puede cambiar
Dev container con firewall	Entorno completo dentro de Docker	Lo que montes con escritura y los tokens que metas dentro	Medio: Docker + .devcontainer/	El proyecto montado sigue siendo modificable

Fuente: Choose a sandbox environment, doc oficial, octubre de 2026.

Mi regla: /sandbox para el trabajo diario, cuando tú sigues mirando lo que pasa. Para dejar al agente solo con --dangerously-skip-permissions, contenedor, VM o el sandbox runtime. La doc lo dice: el sandbox de Bash "no es suficiente" para ejecuciones desatendidas, porque archivos, MCP y hooks siguen en el host.

El montaje con Docker está en entornos reproducibles con Docker y Dev Containers. Y por qué un límite del sistema operativo vale más que una lista de comandos prohibidos lo medimos en guardrails para agentes: con una blocklist típica pasaban 16 de 20 comandos destructivos. Si usas otro agente, compáralo con Pi, que no trae sistema de permisos.

Límites del Claude Code sandbox: lo que no resuelve

El Claude Code sandbox reduce el daño de un comando, pero la doc avisa: no es un límite de aislamiento completo.

No cubre las herramientas de archivos, ni MCP, ni los hooks. Read, Edit y Write se rigen por las reglas de permisos, no por el sandbox: un denyRead no frena a la herramienta Read, y allowedDomains no limita WebFetch. Los servidores MCP locales y los hooks corren con tu acceso completo.

El reintento fuera del sandbox existe. Si un comando falla dentro, Claude puede reintentarlo con dangerouslyDisableSandbox. En bypassPermissions pasa sin preguntar, y una regla de allow como Bash(curl *) también lo aprueba. En el issue #34315 (marzo de 2026), un usuario en modo acceptEdits vio el bypass ocurrir sin ningún prompt.

Se cerró como corregido en la v2.1.113, aunque ese mismo día otro usuario dijo que seguía pasando en la 2.1.114 y el hilo se bloqueó sin reabrirse. La solución de fondo la dio otro usuario en el mismo hilo: "allowUnsandboxedCommands": false, con la que Claude Code ignora ese parámetro.

No impide la exfiltración por la red. El proxy decide por el nombre de host que declara el cliente y, por defecto, no inspecciona TLS. Eso abre dos vías. Un dominio amplio como github.com ya es un canal de salida: si el agente lee un secreto (la lectura está abierta por defecto) y lo sube ahí, el sandbox no lo ve. Y con domain fronting, un comando puede llegar a hosts que ni siquiera están en tu lista. Si eso entra en tu modelo de amenaza, la doc recomienda un proxy propio que termine e inspeccione TLS. Es la cadena de la inyección indirecta de prompts.

Rompe herramientas. docker es incompatible, jest necesita --no-watchman y en macOS fallan git por SSH y CLIs en Go como gh. Cada excludedCommands que añades es una puerta abierta.

El ebook gratuito El Developer Agéntico dedica una parte a la seguridad de agentes: tools, MCP y por qué el aislamiento es una capa, no la solución.

¿Cómo empezar con /sandbox en Claude Code hoy?

Abre ~/.claude/settings.json y pega el bloque de arriba: failIfUnavailable en true, allowUnsandboxedCommands en false y tus credenciales declaradas. Deja en allowedDomains solo el registro que uses de verdad y añade hosts cuando un comando falle por necesitarlos.

El Claude Code sandbox te dice dónde puede actuar el agente. Qué debe hacer lo define la especificación que le das antes de empezar: es el método que explico en el libro Spec-Driven Development.

Preguntas frecuentes

¿El Claude Code sandbox viene activado por defecto?

No. Viene desactivado. Se activa con /sandbox dentro de una sesión o con "sandbox": { "enabled": true } en un archivo de settings como ~/.claude/settings.json.

¿Funciona /sandbox en Windows?

En Windows nativo, no: Claude Code ejecuta los comandos sin aislar. Tienes que correr Claude Code dentro de una distribución WSL2 con bubblewrap y socat instalados, o usar un contenedor o una VM.

¿El sandbox protege mis claves SSH y mis tokens?

No por defecto. Un comando sandboxed puede leer casi toda la máquina, incluidos ~/.ssh y ~/.aws/credentials, y hereda las variables de entorno. Tienes que declararlos en sandbox.credentials con "mode": "deny".

¿Es lo mismo /sandbox que el modo auto o --dangerously-skip-permissions?

No. Los modos de permisos deciden si una acción se ejecuta. El sandbox limita a qué puede acceder un comando de shell mientras corre. Para ejecuciones desatendidas con --dangerously-skip-permissions, la doc recomienda contenedor, VM o el sandbox runtime, no solo /sandbox.

---

Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.