Qué es el sandbox
La documentación describe el límite en una frase: "Mientras el sandbox está activado, los comandos de shell que ejecuta Claude se inician dentro de su límite, al igual que los procesos que estos inician".
Está desactivado hasta que lo activas. La documentación dice: "El sandbox está desactivado por defecto".
La aplicación se produce a nivel del sistema operativo. En macOS, Claude Code utiliza el framework integrado Seatbelt. En Linux y WSL2, se apoya en dos paquetes, bubblewrap y socat. La documentación señala que Claude Code construye el sandbox sobre el paquete de tiempo de ejecución de sandbox de código abierto de Anthropic.
Cómo activarlo
Ejecuta /sandbox en una sesión. Se abrirá un panel con tres pestañas:
- Mode, donde eliges auto-allow (permitir automáticamente) o permisos regulares.
- Overrides, donde eliges si los comandos que fallan en el sandbox pueden recurrir a ejecutarse sin sandbox.
- Config, que muestra la configuración del sandbox resuelta.
En Linux, aparece una pestaña de Dependencies cuando falta algo. Si es la única pestaña, el sandbox aún no puede iniciarse.
El lugar donde se guarda la configuración es importante. Cuando eliges un modo en el panel, Claude Code lo guarda en .claude/settings.local.json, por lo que se aplica al proyecto actual. Para activar el sandbox en todos los proyectos, establece sandbox.enabled en true en tu configuración de usuario en ~/.claude/settings.json.
Hay un valor predeterminado que debes revisar. La documentación advierte: "Por defecto, cuando la plataforma no soporta el sandbox o la comprobación de dependencias al inicio falla, Claude Code ejecuta los comandos sin sandboxing". Si confías en el sandbox como una barrera de seguridad, establece sandbox.failIfUnavailable en true para que Claude Code se cierre al inicio en su lugar.
Para comprobar que funciona, la documentación sugiere pedirle a Claude que ejecute un comando que escriba en tu directorio personal, como crear un archivo de prueba allí. Dentro del sandbox, fallará con un error de operación no permitida en macOS, o un error de sistema de archivos de solo lectura en Linux. Escribir el comando tú mismo no sirve para probarlo, porque los comandos que escribes en el prompt del shell suelen ejecutarse fuera del sandbox.
Qué restringe por defecto
La documentación ofrece una tabla de valores predeterminados. En resumen:
Escrituras. Los comandos en sandbox pueden escribir en el directorio de trabajo, en un directorio temporal por usuario y en los directorios que hayas añadido con --add-dir o /add-dir. Las rutas protegidas permanecen denegadas.
Lecturas. La mayor parte de la máquina es legible, incluidos los archivos de credenciales como tus claves SSH y credenciales de AWS. Tú mismo limitas las lecturas con filesystem.denyRead o la configuración de credenciales.
Red. "No hay ruta directa de salida. Las conexiones pasan por un proxy en tu máquina que comprueba cada host contra tus dominios permitidos, que inicialmente están vacíos". La primera vez que un comando necesita un nuevo dominio, Claude Code solicita aprobación.
Variables de entorno. Los comandos heredan el entorno de Claude Code, "incluyendo cualquier secreto en su entorno", a menos que los limpies o los ocultes (mask).
Ese segundo punto es importante si esperabas que un sandbox lo ocultara todo. Las lecturas son amplias por defecto. El trabajo predeterminado del sandbox es detener las escrituras fuera de tu proyecto y el tráfico de red hacia hosts que no hayas permitido.
Las rutas protegidas
Dentro de las carpetas en las que un comando en sandbox puede escribir, algunas rutas permanecen con la escritura denegada. La documentación las enumera en cuatro grupos:
- En tu directorio de trabajo y los directorios superiores: los archivos de configuración de
.claude, los directorios.claude/skills,.claude/agents,.claude/commandsy.claude/hooks,.mcp.jsony los archivos que Claude Code ejecuta por su cuenta, como.claude/workflowsy.claude/scheduled_tasks.json. - Solo en tu directorio de trabajo: archivos de inicio del shell como
.bashrcy.zshrc,.gitconfig, los directorios.vscodee.idea, y las entradashooksyconfigdentro de.git. - Archivos que convertirían tu directorio de trabajo en un repositorio git desnudo:
HEAD,objectsyrefsen el nivel superior, y entradas relacionadas. - En
~/.claude, o la carpeta a la que apunteCLAUDE_CONFIG_DIR: la mayor parte de su contenido, además de~/.claude.jsony el almacén de credenciales.
El hilo conductor es la configuración que Claude Code lee y el código que ejecuta. Una skill son instrucciones que Claude sigue. Un hook es un script que Claude Code ejecuta. La configuración decide los permisos. Si un comando en sandbox pudiera reescribir cualquiera de estos, la siguiente sesión comenzaría con lo que ese comando escribió.
No puedes ampliar esto por accidente. La documentación dice que si añades un permiso de escritura o una regla de edición que cubra una de estas rutas, "la protección sigue aplicándose". La única forma de levantarla es desactivando por completo el aislamiento del sistema de archivos, lo que también elimina el resto de la capa del sistema de archivos.
Para ver las rutas resueltas para tu máquina, ejecuta /sandbox y abre la pestaña Config, donde aparecen entre las entradas denegadas dentro de las permitidas.
Esto también explica el ejemplo inicial. El bloqueo del sandbox se aplica a los comandos de shell en sandbox. La herramienta Edit integrada de Claude sigue las reglas de permisos, no el sandbox, y el sistema de permisos mantiene su propia lista de rutas protegidas, por lo que una edición a través de esa herramienta se decide allí.
Si un checkout o merge de git falla porque no puede actualizar una de estas rutas, la documentación tiene una entrada de solución de problemas para ese caso, y una versión reciente de Claude Code añadió una nota que le indica a Claude cuándo un comando git en sandbox no pudo actualizar archivos protegidos.
Qué se ejecuta fuera del sandbox
La documentación es precisa sobre el alcance: "El sandbox envuelve los comandos de shell". Varias cosas no son comandos de shell que Claude ejecuta:
- Herramientas integradas de archivos y web. Read, Edit, Write, WebFetch y WebSearch siguen las reglas de permisos en su lugar. Una entrada de denegación de lectura en el sandbox no detiene la herramienta Read, y la lista de dominios permitidos no limita WebFetch.
- Otros procesos que inicia Claude Code. Los hooks de comandos, los servidores MCP locales, los monitores de plugins y los servidores LSP se ejecutan fuera de él.
- Mods, que ejecutan su propio código dentro de Claude Code.
Algunos comandos de shell también se ejecutan fuera de él:
- Comandos que escribes en el prompt de shell
!, en la mayoría de las sesiones. - Comandos excluidos, que coinciden con una entrada en
excludedCommands. - Reintentos sin sandbox, cubiertos a continuación.
La documentación sugiere una herramienta diferente si quieres que todo esto esté bajo un mismo límite: ejecuta el proceso de Claude Code en un contenedor, una máquina virtual o el runtime del sandbox.
Auto-allow frente a permisos regulares
Ambos modos aplican las mismas restricciones de sistema de archivos y red. La diferencia son las aprobaciones.
Auto-allow aprueba un comando sin aviso cuando se ejecuta dentro del sandbox. Algunas cosas siguen pidiendo confirmación: comandos que coinciden con una regla de denegación de Bash, rm dirigido a una ruta crítica y reglas de consulta (ask) con alcance a contenido específico, como una regla para git push. Los comandos que establecen una variable delante del programa, como uno que establece una variable de entorno antes de ejecutar pruebas, también pasan por el flujo regular, porque la variable puede cambiar qué programa se ejecuta.
Regular permissions envía cada comando de Bash a través del flujo normal de permisos, esté en sandbox o no. La documentación lo describe como más control con más aprobaciones.
Cuándo Claude pide reintentar sin sandbox
La documentación llama al reintento una vía de escape: "El reintento sin sandbox es una vía de escape para los comandos que fallan dentro del sandbox, como las herramientas que son incompatibles con él".
Cuando el sandbox bloquea una conexión de red, Claude Code nombra al host denegado en el resultado del comando, para que Claude pueda ver qué falló. Claude puede entonces reintentar con un parámetro que desactiva el sandbox para ese único comando. Quién aprueba el reintento depende de tu modo de permisos:
- En los modos Manual y accept-edits, recibes un aviso titulado Bash command (unsandboxed).
- En modo auto, un modelo clasificador evalúa el comando.
- En modo bypass-permissions, se ejecuta sin aviso.
- En modo don't-ask, se deniega.
Dos configuraciones cambian esto. Una regla de permiso (allow) que coincida con el comando también aprueba su reintento. Y una regla de consulta (ask) para el parámetro disable-sandbox fuerza un aviso incluso en los modos auto y bypass.
Para eliminar la vía de escape, establece allowUnsandboxedCommands en false. La documentación llama a esto modo de sandbox estricto. Los comandos que ejecuta Claude permanecen entonces en sandbox a menos que coincidan con un comando excluido. Si tú o tu administrador lo establecen en configuraciones gestionadas o con --settings, el sandbox pasa a ser requerido por el administrador, y Claude Code ignora las configuraciones del repositorio que intenten suavizarlo.
Protección de credenciales
Debido a que las lecturas son amplias por defecto, las credenciales necesitan reglas explícitas. La documentación es clara en que nada se bloquea automáticamente: "No hay una lista de denegación de credenciales integrada, por lo que solo se restringen los archivos y variables que tú enumeres".
La configuración sandbox.credentials acepta rutas de archivos y nombres de variables de entorno, cada uno con un modo:
- Deny bloquea las lecturas del archivo y elimina la variable antes de cada comando en sandbox.
- Mask muestra al comando un marcador de posición, y el proxy del sandbox sustituye el valor real solo en las peticiones a los hosts que permitas.
Las entradas de denegación de cada ámbito de configuración se fusionan, y ningún ámbito puede eliminar una que otro ámbito haya añadido. El enmascaramiento (masking) necesita más configuración, incluyendo la terminación TLS en el proxy, y solo se respeta desde la configuración de usuario, la configuración gestionada o --settings.
Configuraciones que un proyecto no puede cambiar
Algunas configuraciones del sandbox solo se consideran confiables desde ciertos lugares. El ejemplo más claro es desactivar el aislamiento del sistema de archivos. La documentación explica el riesgo: con él desactivado y los comandos permitidos automáticamente, un comando en sandbox puede escribir archivos que comandos posteriores lean, como ~/.claude/settings.json, "y usarlos para ampliar su propio acceso en la siguiente ejecución".
Por lo tanto, las configuraciones de proyecto en .claude/settings.json y .claude/settings.local.json no pueden establecerlo. Solo pueden hacerlo las configuraciones de usuario, las gestionadas y --settings. Si has desactivado el reintento, un false en tu configuración de usuario también se mantiene cuando la configuración de un proyecto dice true.
Cubrimos cómo Codex traza una línea similar, manteniendo sus propias carpetas de configuración como de solo lectura dentro de un espacio de trabajo editable, en nuestra guía sobre perfiles de permisos de Codex.
Lo que la gente intenta primero
Esperar que el sandbox esté activado. Está desactivado por defecto.
Esperar que oculte las credenciales. Las lecturas son amplias hasta que añades reglas de credenciales.
Añadir una regla de permiso para .claude. Las rutas protegidas permanecen protegidas.
Esperar que cubra hooks y servidores MCP. Se ejecutan fuera de él.
Asumir que un inicio fallido detiene Claude Code. Sin failIfUnavailable, los comandos se ejecutan sin sandbox.
La solución: Configurar el sandbox a propósito
Paso 1: Actívalo donde lo quieras
Usa /sandbox para un proyecto, o la configuración de usuario para todos ellos.
Paso 2: Añade reglas de credenciales
Deniega u oculta los archivos y variables que los comandos no deberían ver.
Paso 3: Decide sobre la vía de escape
Mantén los reintentos sin sandbox con avisos, o desactívalos con el modo estricto.
Paso 4: Anota por qué existe cada configuración
Registra qué dominios, carpetas y exclusiones permitiste, y el motivo de cada uno.
Configurando esto en MemoryLake
Las configuraciones del sandbox son líneas cortas en un archivo de configuración. Los motivos detrás de ellas, como por qué se permite un dominio, qué herramienta necesitó una exclusión o por qué los reintentos están desactivados en un repositorio, son contexto del proyecto que un archivo de configuración no explica. Cuando alguien pregunta meses después si una regla sigue siendo necesaria, el motivo es lo que ayuda.
MemoryLake es una capa de memoria para ese tipo de contexto de proyecto, como decisiones de seguridad, excepciones permitidas y los motivos detrás de ellas, mantenidos en un solo lugar que tú controlas y disponibles para los asistentes que conectes, como ChatGPT, Claude Code y Codex.
Tú mismo escribes las entradas, con tus propias palabras. No se lee nada de, ni se escribe en, ni se borra de tu configuración de Claude Code, tu carpeta .claude, tu configuración de sandbox, tus sesiones o el almacén de cualquier proveedor. El sandbox funciona de la manera que Anthropic describe.
Paso 1: Crea una clave API
Inicia sesión y genera una clave desde el panel de control. Guárdala fuera de tus repositorios, como cualquier otra credencial.

Paso 2: Sube tus primeras memorias
Empieza con lo que escribiste en el Paso 4 de la solución: cada excepción del sandbox y su motivo. Una excepción por entrada.

Paso 3: Conecta tu IA y agentes
Conecta Claude Code, Codex y los otros asistentes que utilices. Cada uno puede comprobar una excepción propuesta contra los motivos que ya registraste.

Qué cambia esto en la práctica
La primera diferencia es que las revisiones son más fáciles. Una excepción viene acompañada del motivo por el que se añadió.
La segunda es que hay menos reglas generales. Cuando la necesidad original está clara, es más fácil elegir una ruta o dominio estrecho.
La tercera es la consistencia entre herramientas. Las mismas decisiones de seguridad están disponibles en Claude Code y Codex.
Mejores prácticas para el sandbox de Claude Code
Establece failIfUnavailable si dependes de él. De lo contrario, un inicio fallido ejecuta los comandos sin sandbox.
Prefiere rutas de escritura estrechas a las exclusiones. Un comando excluido se ejecuta con todo tu acceso.
Enumera las credenciales explícitamente. Ninguna credencial se deniega por defecto.
No toques las rutas protegidas. Protegen lo que Claude Code carga a continuación.
Usa un contenedor para un aislamiento total. Los hooks, servidores MCP y herramientas integradas se sitúan fuera del sandbox.
Prueba con un comando de sondeo. Pídele a Claude que lo ejecute, no lo escribas tú mismo.
Conclusión
El sandbox de Claude Code envuelve los comandos de shell que ejecuta Claude y los procesos que estos inician. Está desactivado por defecto. Una vez activado, los comandos pueden escribir en tu directorio de trabajo, en un directorio temporal y en directorios añadidos; las lecturas siguen siendo amplias y el tráfico de red pasa por un proxy que permite solo los hosts que apruebes.
Dentro de las carpetas editables, las rutas protegidas permanecen con la escritura denegada, incluyendo la configuración de .claude, skills, agentes, comandos, hooks y la mayor parte de ~/.claude, para que un comando no pueda reescribir la configuración que carga la siguiente sesión. Las herramientas integradas, los hooks y los servidores MCP se ejecutan fuera del sandbox, y un comando fallido puede reintentarse sin sandbox a menos que desactives eso con el modo estricto.