Configura la herramienta Bash en el sandbox

Restringe los archivos y hosts de red a los que pueden acceder los comandos de shell de Claude Code con el sandbox integrado. Actívalo, define el límite y corrige lo que deje de funcionar.

El sandbox de Bash es un límite que el sistema operativo impone alrededor de los comandos de shell que Claude ejecuta en tu máquina. Tú defines a qué archivos y dominios de red pueden acceder esos comandos, y los límites se aplican a los comandos de Bash, PowerShell y Monitor, y a los procesos que estos inician. Como el sistema operativo aplica los límites mientras se ejecuta un comando, Claude Code puede ejecutar comandos en el sandbox sin pedirte que apruebes cada uno.

El sandbox cubre solo los comandos de shell. Las herramientas de archivos de Claude, los servidores MCP y los hooks se ejecutan fuera de él.

El sandbox funciona en macOS, Linux y WSL2. En Windows nativo, Claude Code ejecuta los comandos fuera del sandbox. Para usar el sandbox en una máquina con Windows, ejecuta Claude Code dentro de una distribución de WSL2.

Qué restringe el sandbox

Mientras el sandbox está activado, los comandos de shell que Claude ejecuta se inician dentro de sus límites, y lo mismo ocurre con los procesos que esos comandos inician. El sandbox está desactivado de forma predeterminada. Para activarlo, ejecuta /sandbox en una sesión, como se muestra en Primeros pasos, o establece sandbox.enabled en true en un archivo de configuración como ~/.claude/settings.json.

La tabla muestra a qué puede acceder un comando en el sandbox de forma predeterminada y los ajustes que cambian cada valor predeterminado.

Acceso	Predeterminado	Cámbialo con
Escrituras	El directorio de trabajo, un directorio temporal por usuario y los directorios que hayas agregado. 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 hacia el exterior. Las conexiones pasan por un proxy en tu máquina que verifica cada host contra tus dominios permitidos, que inicialmente están vacíos. Tu modo de permisos decide qué ocurre con los demás hosts	`network.allowedDomains`, `network.deniedDomains`
Variables de entorno	Heredadas de Claude Code, incluidos los secretos que haya en su entorno	`credentials`, `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`

Claude Code construye el sandbox sobre el paquete de código abierto @anthropic-ai/sandbox-runtime.

Qué se ejecuta fuera del sandbox

El sandbox envuelve los comandos de shell. Estas herramientas y procesos se ejecutan fuera de él:

Herramientas integradas de archivos y web: herramientas como Read, Edit, Write, WebFetch y WebSearch siguen, en cambio, las reglas de permisos. Una entrada denyRead no detiene la herramienta Read, y allowedDomains no limita WebFetch
Otros procesos que inicia Claude Code: los hooks de comando, los servidores MCP locales, los monitores de plugins, los servidores LSP y los comandos auxiliares, como el comando de tu línea de estado y apiKeyHelper, se ejecutan con tu acceso completo

Algunos comandos de shell también se ejecutan fuera del sandbox, según tu configuración:

Comandos que escribes tú mismo: un comando que introduces en el prompt del modo shell ! se ejecuta fuera del sandbox en la mayoría de las sesiones. El modo sandbox estricto enumera las sesiones en las que un comando que escribes se ejecuta dentro del sandbox
Comandos excluidos: los comandos que coinciden con excludedCommands se ejecutan fuera del sandbox
Reintentos fuera del sandbox: Claude puede pedir ejecutar un comando fuera del sandbox, normalmente después de que falle dentro del sandbox

Para poner las herramientas, los procesos y los comandos de esta sección detrás de un único límite, ejecuta el propio proceso de Claude Code en un contenedor, una máquina virtual o el sandbox runtime.

Primeros pasos

El sandbox está integrado en Claude Code. Lo que instalas depende de tu plataforma:

macOS: el sandboxing usa el framework Seatbelt integrado, así que puedes ir directamente a los pasos
Linux y WSL2: el sandbox depende de bubblewrap y socat, que se explican en Configurar Linux y WSL2. Aunque todavía no los hayas instalado, puedes empezar con /sandbox, porque su panel muestra si falta algo

Ejecuta /sandbox

Inicia una sesión de Claude Code y ejecuta el comando /sandbox:

/sandbox

Esto abre el panel del sandbox con tres pestañas, más una pestaña Dependencies en Linux cuando falta el filtro seccomp opcional:

Mode: elige cómo se aprueban los comandos ejecutados en el sandbox, lo que se explica en el siguiente paso
Overrides: elige si los comandos que fallan dentro del sandbox pueden recurrir a ejecutarse fuera de él. Este es el ajuste allowUnsandboxedCommands
Config: consulta la configuración resuelta del sandbox

Si el panel muestra solo una pestaña Dependencies, falta un paquete obligatorio. Instálalo como se describe en Configurar Linux y WSL2, reinicia Claude Code y vuelve a ejecutar /sandbox.

Elige un modo

En la pestaña Mode, selecciona auto-allow o permisos regulares. Auto-allow ejecuta los comandos del sandbox sin pedir confirmación, y los permisos regulares mantienen las solicitudes de permiso habituales incluso cuando los comandos se ejecutan en el sandbox. Consulta Modos del sandbox para ver qué comandos siguen pidiendo confirmación en el modo auto-allow.

Ejecuta un comando de Bash

Pídele a Claude que ejecute un comando, como una compilación o un conjunto de pruebas. De forma predeterminada, los comandos dentro del sandbox pueden escribir en el directorio de trabajo, en un directorio temporal por usuario y en cualquier directorio que hayas agregado con --add-dir, /add-dir o permissions.additionalDirectories.

La primera vez que un comando necesita un nuevo dominio de red, Claude Code pide aprobación; en el modo automático, Claude, en cambio, indica los hosts que necesita un comando en el propio comando para que el clasificador los revise junto con él.

Para ampliar o restringir lo que permite el sandbox, consulta Configurar el sandboxing.

Si los comandos del sandbox fallan con Operation not permitted dentro de un contenedor, consulta Bubblewrap no se inicia dentro de un contenedor.

Cuando seleccionas un modo en el panel, Claude Code lo guarda en la configuración local de tu proyecto en .claude/settings.local.json, que se aplica al proyecto actual. Claude Code agrega ese archivo a tu gitignore global cuando guarda un ajuste en él. Para habilitar el sandbox en todos tus proyectos, establece sandbox.enabled en true en tu configuración de usuario en ~/.claude/settings.json. Para imponer el sandboxing a todos los desarrolladores de una organización, usa la configuración administrada.

Para cambiar el sandbox durante una sesión sin escribir en un archivo de configuración, inicia Claude Code con --settings. Por ejemplo, este comando inicia una sesión en el sandbox en la que Claude no puede reintentar un comando bloqueado fuera del sandbox:

claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'

Confirmar que los comandos se ejecutan dentro del sandbox

Para comprobar que el sandbox funciona, pídele a Claude que ejecute cada línea de la tabla. Lo que escribes en el prompt ! normalmente se ejecuta fuera del sandbox, así que escribir una línea tú mismo no lo pone a prueba.

Comando	Resultado dentro del sandbox
`touch ~/sandbox-probe`	Falla con `Operation not permitted` en macOS, o `Read-only file system` en Linux y WSL2
`curl --noproxy '*' https://example.com`	Falla con `Could not resolve host`, porque el comando no tiene ninguna ruta que evite el proxy del sandbox

Si Claude pide reintentar un comando fallido fuera del sandbox, rechaza el reintento. Si touch tiene éxito y tu directorio home no es uno de los directorios en los que el sandbox permite escribir a los comandos, elimina ~/sandbox-probe. Luego ejecuta /sandbox para comprobar que el sandbox está activado y que sus dependencias están instaladas.

Configurar Linux y WSL2

En Linux y WSL2, el sandbox depende de estos paquetes:

bubblewrap: la herramienta de sandboxing sin privilegios que aplica el aislamiento del sistema de archivos
socat: el relé que se usa para enrutar el tráfico de red a través del proxy del sandbox

Instálalos con el gestor de paquetes de tu distribución:

sudo apt-get install bubblewrap socat

sudo dnf install bubblewrap socat

Cuando falta una dependencia, la pestaña Dependencies de /sandbox indica cuáles de ripgrep, bubblewrap, socat y el filtro seccomp le faltan a tu plataforma. Si no ves la pestaña después de instalarlos y reiniciar Claude Code, todas las dependencias están presentes.

Ripgrep viene incluido con el binario nativo de Claude Code. El filtro seccomp es opcional y añade el bloqueo de sockets de dominio Unix. Instálalo con npm install -g @anthropic-ai/sandbox-runtime si falta.

Cuando falta una dependencia obligatoria, la pestaña Dependencies es la única que se muestra hasta que la instales. Cuando solo falta el filtro seccomp opcional, la pestaña Dependencies aparece junto con las demás pestañas. La comprobación de dependencias se ejecuta al iniciar, así que reinicia Claude Code después de instalar paquetes para que /sandbox los detecte.

En Ubuntu 24.04 y posteriores, la política predeterminada de AppArmor impide que bubblewrap cree los espacios de nombres de usuario que necesita para el aislamiento.

Para comprobar si tu entorno aplica esta restricción, incluso dentro de WSL2, ejecuta `sysctl kernel.apparmor_restrict_unprivileged_userns`. Si el comando devuelve `0`, omite este paso. Si muestra un error `No such file or directory`, la clave no existe y puedes omitir este paso. Si devuelve `1`, agrega un perfil de AppArmor que le otorgue esta capacidad a `bwrap`:

```bash theme={null}
sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF
```

El perfil se aplica solo a `bwrap`, no a los comandos que ejecuta dentro del sandbox. Recarga AppArmor para aplicarlo:

```bash theme={null}
sudo systemctl reload apparmor
```

Notas sobre WSL2

Comprueba tu versión de WSL con wsl -l -v desde PowerShell. Si ves Sandboxing requires WSL2, tu distribución está ejecutando WSL1. Actualízala a WSL2 o ejecuta Claude Code sin sandboxing.

En WSL2, WSL transfiere el lanzamiento de un binario de Windows, como cmd.exe, powershell.exe o cualquier cosa bajo /mnt/c/, al host de Windows a través de un socket Unix, por lo que que un comando del sandbox pueda lanzar uno depende de los ajustes de sockets Unix del sandbox: el filtro seccomp opcional tiene que estar instalado para que el socket se bloquee en primer lugar. Para permitir estos lanzamientos, establece allowAllUnixSockets, que abre todos los sockets Unix a los comandos del sandbox.

Modos del sandbox

Claude Code ofrece dos modos del sandbox. En ambos, el sandbox aplica las mismas restricciones de sistema de archivos y de red; la diferencia está solo en si los comandos del sandbox se aprueban automáticamente o requieren permiso explícito.

Modo auto-allow

Claude Code aprueba un comando automáticamente, sin pedir confirmación, cuando el comando se ejecuta dentro del sandbox. Un comando pasa por el flujo de permisos habitual cuando se ejecuta fuera del sandbox porque coincide con excludedCommands o porque Claude lo reintenta fuera del sandbox.

Un comando del sandbox que se conecta a un host que no has permitido permanece en el sandbox. Hosts fuera de tus dominios permitidos explica quién decide si la conexión se realiza.

Incluso en el modo auto-allow, sigue aplicándose lo siguiente:

Las reglas de denegación explícitas siempre se respetan
Los comandos rm o rmdir que apuntan a una ruta crítica siguen pasando por el flujo de permisos habitual
Las reglas de consulta limitadas por contenido, como Bash(git push *), siguen forzando una solicitud de permiso incluso para los comandos del sandbox
Una regla de consulta Bash sin más, o la forma equivalente Bash(*), se omite para los comandos que se ejecutan en el sandbox; sigue aplicándose a los comandos que recurren al flujo de permisos habitual. En el modo plan, la regla no se omite: también pide confirmación para los comandos del sandbox, incluidos los de solo lectura

Info

El modo auto-allow funciona de forma independiente de tu ajuste de modo de permisos, con tres excepciones: el modo plan, un comando del modo automático que lleva dominios permitidos por comando y la revisión del clasificador del lado del servidor de los comandos del sandbox en el modo automático. Aunque no estés en el modo "accept edits", los comandos de Bash del sandbox se ejecutan automáticamente cuando auto-allow está habilitado. Esto significa que los comandos de Bash que modifican archivos dentro de los límites del sandbox se ejecutan sin pedir confirmación, incluso en el modo Manual, donde las herramientas de edición de archivos sí la pedirían.

En el modo plan, auto-allow no amplía las aprobaciones; consulta el modo plan para ver cómo Claude Code controla los comandos mientras planificas.

Modo de permisos regulares

Todos los comandos de Bash pasan por el flujo de permisos habitual, incluso cuando se ejecutan en el sandbox. Esto proporciona más control, pero requiere más aprobaciones.

La vía de escape del reintento fuera del sandbox

El reintento fuera del 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 indica el host denegado en el resultado del comando, así Claude ve qué se bloqueó. Claude analiza el fallo y puede reintentar el comando con el parámetro dangerouslyDisableSandbox.

El comando reintentado se ejecuta fuera del sandbox. En una sesión interactiva de la terminal, quién lo aprueba depende de tu modo de permisos:

Modo bypassPermissions: el reintento se ejecuta sin pedir confirmación
Modo Manual y modo acceptEdits: recibes una solicitud titulada "Bash command (unsandboxed)"
Modo automático: un modelo clasificador independiente evalúa el comando subyacente
Modo dontAsk: Claude Code deniega el reintento
Modo plan: consulta cómo Claude Code controla los comandos mientras planificas

Estas reglas y ajustes cambian quién aprueba el reintento:

Una regla de permiso que coincida: si una regla de permiso como Bash(curl *) coincide con el comando, también aprueba el reintento, por lo que el comando se ejecuta fuera del sandbox sin pedir confirmación
Una regla de consulta para el parámetro: agrega una regla de consulta para Bash(dangerouslyDisableSandbox:true) para que se te pida confirmación en los reintentos de Bash. También recibes la solicitud en el modo automático y en el modo bypassPermissions, y la regla tiene precedencia sobre una regla de permiso que coincida
permissions.blockReadsOutsideWorkingDirectories: Acciones que ningún modo aprueba automáticamente explica los reintentos que piden confirmación mientras está activado

Desactivar el reintento con el modo estricto del sandbox

Puedes desactivar el reintento fuera del sandbox estableciendo "allowUnsandboxedCommands": false en tu configuración del sandbox. Con el reintento desactivado, Claude Code ignora el parámetro dangerouslyDisableSandbox. Mientras el sandbox está en ejecución, los comandos que ejecuta Claude se ejecutan entonces en el sandbox, a menos que coincidan con una entrada de excludedCommands. Para evitar que Claude Code ejecute comandos fuera del sandbox cuando este no puede iniciarse, establece también failIfUnavailable. La pestaña Overrides de /sandbox muestra este ajuste como Strict sandbox mode.

Un false en tu configuración de usuario, en --settings o en la configuración administrada se mantiene incluso cuando la configuración de un proyecto establece true. Un false en tu configuración de usuario no convierte el sandbox en obligatorio por parte del administrador, por lo que los demás ajustes del sandbox de un proyecto siguen aplicándose. Antes de la v2.1.285, el true de un proyecto sobrescribía un false de tu configuración de usuario.

Si tú o tu administrador desactivan el reintento en la configuración administrada o con el flag --settings, el sandbox pasa a ser obligatorio por parte del administrador. Claude Code entonces ignora los ajustes de los archivos de un repositorio que relajan el sandbox, incluidas las entradas de excludedCommands. Configuración del repositorio con un sandbox obligatorio por parte del administrador los enumera.

El modo estricto del sandbox se aplica a los comandos que ejecuta Claude. Los comandos que escribes tú mismo en el prompt ! del modo shell se ejecutan fuera del sandbox, a menos que la sesión sea una de estas:

Una sesión en segundo plano: el modo estricto del sandbox también cubre los comandos del modo shell
Una sesión de Linux con CLAUDE_CODE_SUBPROCESS_ENV_SCRUB establecida: todos los comandos se ejecutan en el sandbox, incluidos los del modo shell

Antes de la v2.1.260, el modo estricto del sandbox ejecutaba en el sandbox los comandos del modo shell en todas las sesiones.

Directorios temporales

Un directorio temporal por usuario es escribible dentro del sandbox de forma predeterminada, junto con el directorio de trabajo. A menos que desactives el aislamiento del sistema de archivos, Claude Code establece $TMPDIR en este directorio para los comandos del sandbox, de modo que las herramientas que escriben archivos temporales funcionan sin configuración adicional.

Los comandos fuera del sandbox heredan el $TMPDIR de tu shell cuando está establecido, así que, mientras el aislamiento del sistema de archivos está activado, los comandos dentro y fuera del sandbox resuelven $TMPDIR en directorios distintos. Si tu shell deja $TMPDIR sin establecer o vacío, un comando fuera del sandbox que hace referencia a $TMPDIR recibe tu sobrescritura de CLAUDE_CODE_TMPDIR, o el directorio temporal del sistema operativo cuando no has establecido ninguna o la sobrescritura es una ruta larga, para que la variable no se expanda a una cadena vacía. Para pasar archivos temporales entre ambos, escríbelos en el directorio de trabajo.

Configurar el sandboxing

Personaliza el comportamiento del sandbox a través de tu archivo settings.json. Consulta Configuración para ver la referencia completa de configuración.

De forma predeterminada, los comandos aislados en el sandbox pueden escribir en el directorio de trabajo actual, en el directorio temporal por usuario y en cualquier directorio que hayas agregado con --add-dir, /add-dir o permissions.additionalDirectories. Si comandos de subprocesos como kubectl, terraform o npm necesitan escribir fuera de esos directorios, usa sandbox.filesystem.allowWrite para conceder acceso a rutas específicas:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

Estas rutas se aplican a nivel del sistema operativo, por lo que todos los comandos que se ejecutan dentro del sandbox, incluidos sus procesos hijos, las respetan. Este es el enfoque recomendado cuando una herramienta necesita acceso de escritura a una ubicación específica, en lugar de excluir la herramienta del sandbox por completo con excludedCommands.

Cuando defines el mismo arreglo de sistema de archivos en varios alcances de configuración, Claude Code los combina, uniendo las rutas de todos los alcances en lugar de reemplazar el arreglo de un alcance con el de otro.

Si excluyes una fuente con --setting-sources en la CLI o con settingSources en el Agent SDK, Claude Code ignora sus entradas de sandbox.filesystem, sus reglas de permisos de Edit y sus reglas de denegación de Read al construir la configuración del sandbox. Requiere Claude Code v2.1.246 o posterior.

Cuando editas estas listas del sistema de archivos durante una sesión, Claude Code aplica el cambio a la sesión en ejecución, por lo que el siguiente comando aislado en el sandbox se ejecuta con las nuevas rutas.

Las rutas del sistema de archivos del sandbox usan las convenciones estándar: /tmp/build es absoluta y ~/.kube es relativa a tu directorio home. Esto difiere de las reglas de permisos de Read y Edit, que usan //path para rutas absolutas y /path para rutas relativas al proyecto. Para rutas relativas, barras finales y comodines, consulta Prefijos de ruta del sandbox.

También puedes denegar el acceso de escritura o lectura con sandbox.filesystem.denyWrite y sandbox.filesystem.denyRead, y volver a permitir rutas específicas dentro de una región denegada con sandbox.filesystem.allowRead. Cuando las reglas de lectura se superponen, se aplica la regla con la ruta más específica:

Reglas de ejemplo	Resultado
`"denyRead": ["~/"]` con `"allowRead": ["~/projects"]`	`~/projects` se puede leer y el resto del directorio home sigue bloqueado. El permiso más específico vuelve a abrir esa parte de la región denegada
`"allowRead": ["~/"]` con `"denyRead": ["~/.env"]`	`~/.env` sigue bloqueado y el resto del directorio home se puede leer. La denegación se mantiene dentro de un permiso más amplio, de modo que un permiso general no puede volver a exponer un secreto sin que lo notes
`"allowRead": ["~/"]` con `"denyRead": ["~/**/.env"]`	Todos los `.env` dentro del directorio home siguen bloqueados y el resto se puede leer. Una denegación con comodín se mantiene dentro de un permiso más amplio de la misma forma que una ruta exacta

El siguiente ejemplo bloquea la lectura de todo el directorio home y a la vez permite las lecturas del proyecto actual. Colócalo en el .claude/settings.json de tu proyecto, porque la ruta relativa . se resuelve como la raíz del proyecto solo cuando la configuración está en la configuración del proyecto:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

Si colocaras la misma configuración en ~/.claude/settings.json, . se resolvería como ~/.claude, y los archivos del proyecto seguirían bloqueados por la regla denyRead.

Para denegar a los comandos aislados en el sandbox el acceso de lectura a los directorios home y a los volúmenes montados, manteniendo legibles los directorios de trabajo, configura permissions.blockReadsOutsideWorkingDirectories en lugar de escribir reglas de rutas.

Ejecutar comandos fuera del sandbox con `excludedCommands`

Agrega un patrón de comando a sandbox.excludedCommands para ejecutar los comandos que coincidan fuera del sandbox, lo que significa sin restricciones del sistema de archivos y sin proxy de red. Úsalo para una herramienta que no puede funcionar dentro del sandbox y a la que le confías todo tu acceso. Una herramienta que necesita un directorio más o un host más puede funcionar con allowWrite o allowedDomains, que mantienen el comando dentro del sandbox.

Este ejemplo saca del sandbox los comandos docker compose. Guárdalo en ~/.claude/settings.json para aplicarlo a todos tus proyectos:

{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["docker compose *"]
  }
}

Claude Code compara tus entradas con cada llamada a Bash y Monitor. Una llamada es la línea de comandos completa que envía Claude, que puede encadenar varios comandos. Las siguientes reglas deciden si una llamada sale del sandbox:

Termina el patrón con *: las entradas usan la misma sintaxis que una regla de permisos Bash(...), donde un patrón sin comodín es una coincidencia exacta. docker coincide solo con docker sin argumentos. docker * coincide con docker con o sin argumentos
Todos los comandos de la llamada deben coincidir: npm ci && docker compose build sigue dentro del sandbox a menos que otra entrada cubra npm ci
Claude Code compara el texto de la llamada: un script o un objetivo de make que llama a docker internamente no coincide, y tampoco /usr/local/bin/docker
Algunas llamadas permanecen en el sandbox: una redirección a un archivo, un cd o una sustitución de comandos como $(...) mantiene toda la llamada dentro del sandbox. La entrada de referencia enumera más llamadas que permanecen en el sandbox
Dónde guardas la entrada puede importar: mientras el sandbox sea obligatorio por el administrador, Claude Code ignora las entradas de .claude/settings.json y .claude/settings.local.json

Un comando excluido pasa por el flujo de permisos habitual:

Los comandos de solo lectura y los comandos que cubren tus reglas de permiso se ejecutan sin pedir confirmación
En modo automático, el clasificador revisa los demás comandos excluidos
En modo bypassPermissions, un comando excluido se ejecuta sin pedir confirmación a menos que coincida con una regla de consulta

Para confirmar que una entrada coincide, cambia al modo Manual y pídele a Claude que ejecute un comando coincidente que cambie algo, como docker compose up -d. La solicitud de permiso se titula "Bash command (unsandboxed)".

Desactivar el aislamiento del sistema de archivos

Establece sandbox.filesystem.disabled en true para omitir el aislamiento del sistema de archivos y mantener el aislamiento de red. El siguiente ejemplo desactiva el aislamiento del sistema de archivos y mantiene una lista de dominios de red permitidos:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "disabled": true
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

El sandbox tiene dos capas independientes: el aislamiento del sistema de archivos controla qué rutas pueden leer y escribir los comandos aislados en el sandbox, y el aislamiento de red controla a qué dominios pueden acceder. Con la capa del sistema de archivos desactivada, los comandos aislados en el sandbox obtienen acceso de lectura y escritura sin restricciones al sistema de archivos del host, mientras que su tráfico de red saliente sigue limitado a tus dominios permitidos. Desactiva esta capa cuando uses el sandbox para controlar a dónde se conectan los comandos y no lo que escriben.

sandbox.filesystem.disabled tiene false como valor predeterminado. Requiere Claude Code v2.1.216 o posterior.

Qué configuraciones pueden desactivarlo

Como desactivar el aislamiento del sistema de archivos amplía lo que pueden hacer los comandos aislados en el sandbox, Claude Code respeta filesystem.disabled solo desde estas fuentes de configuración:

La configuración de usuario, la configuración administrada y el flag de CLI --settings pueden establecerlo. La configuración del proyecto en .claude/settings.json y .claude/settings.local.json no puede, de modo que un proyecto descargado no puede desactivar el aislamiento del sistema de archivos.
Cuando la configuración administrada configura sandbox.filesystem de cualquier forma, o incluye alguna entrada de sandbox.credentials.files con "mode": "deny", solo la configuración administrada puede establecer la clave. Esto mantiene vigentes las restricciones del sistema de archivos desplegadas por el administrador; para flexibilizar un despliegue así, establece "disabled": true en la configuración administrada.
Cuando CLAUDE_CODE_SUBPROCESS_ENV_SCRUB está establecida, Claude Code ignora filesystem.disabled desde cualquier fuente, incluida la configuración administrada, y mantiene activado el aislamiento del sistema de archivos.

Una entrada mask válida no fija la clave, incluso cuando Claude Code recurre a deny para ella al iniciar. Incluye una ruta que no se puede enmascarar, como un directorio de credenciales, como una entrada deny explícita en la configuración administrada, lo que fija la clave.

Qué cambia cuando el aislamiento del sistema de archivos está desactivado

Establecer filesystem.disabled elimina las protecciones que aplica la propia capa del sistema de archivos. Las protecciones que aplican otras capas siguen vigentes:

Protección	Con el aislamiento del sistema de archivos desactivado
Bloqueos de lectura de `filesystem.denyRead` y de `deny` en `credentials.files`	No se aplican. La capa del sistema de archivos aplica ambos
Entradas `deny` y `mask` de `credentials.envVars`	Se aplican. La limpieza de variables de entorno es independiente de la capa del sistema de archivos
Entradas `mask` de `credentials.files` aplicadas como máscaras	Se aplican: el enmascaramiento es independiente de la capa del sistema de archivos. Una entrada que recurrió a `deny` no se aplica, como cualquier entrada `deny`

Cambian otras dos cosas:

Los comandos aislados en el sandbox heredan el $TMPDIR de tu shell en lugar del directorio temporal por usuario, porque todos los directorios temporales se pueden escribir y Claude Code ya no redirige los comandos al directorio por usuario.

En Linux, la variable a menudo no está establecida en el shell principal. Las indicaciones de la herramienta Bash le dicen a Claude que cree directorios temporales con mktemp -d en lugar de depender de $TMPDIR.
autoAllowBashIfSandboxed sigue teniendo true como valor predeterminado, por lo que los comandos aislados en el sandbox siguen ejecutándose sin pedir confirmación. Establécelo en false para que se pida confirmación para los comandos aislados en el sandbox.

Proteger credenciales

El ajuste sandbox.credentials declara los archivos de credenciales y las variables de entorno que se deben proteger de los comandos aislados en el sandbox. Cada entrada indica una ruta de archivo o una variable de entorno y un mode. El bloque dedicado credentials mantiene las reglas de credenciales agrupadas y separadas de las reglas generales del sistema de archivos.

En las entradas con "mode": "deny", se deniega la lectura de las rutas de archivo dentro del sandbox, la misma restricción que aplica filesystem.denyRead, y las variables de entorno se eliminan antes de que se ejecute cada comando aislado en el sandbox. La protección de archivos forma parte de la capa del sistema de archivos, por lo que no se aplica si desactivas el aislamiento del sistema de archivos; la protección de variables de entorno sí se sigue aplicando.

El siguiente ejemplo bloquea la lectura del archivo de credenciales de AWS y del directorio SSH, y elimina GITHUB_TOKEN y NPM_TOKEN del entorno de los comandos aislados en el sandbox:

{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" },
        { "name": "NPM_TOKEN", "mode": "deny" }
      ]
    }
  }
}

Las entradas de variables de entorno y de archivos también aceptan "mode": "mask", que se describe en Enmascarar credenciales.

Las rutas de archivo siguen las mismas reglas de prefijos que los ajustes sandbox.filesystem.*.

Claude Code combina las entradas deny de todos los alcances de configuración que carga la sesión. Una entrada deny solo restringe el acceso, por lo que cualquier alcance puede agregar una, pero ningún alcance puede eliminar una que haya agregado otro alcance.

Cuando excluyes una fuente de configuración:

Configuración del proyecto o local: Claude Code no aplica ninguna de sus entradas de credentials. Requiere Claude Code v2.1.246 o posterior.
Configuración de usuario: Claude Code sigue aplicando las entradas deny de ~/.claude/settings.json y mantiene sus entradas mask de archivos como restricciones que ya no autorizan al proxy a sustituir el valor real, pero descarta sus entradas mask de variables de entorno.

No hay una lista de denegación de credenciales integrada, por lo que solo se restringen los archivos y las variables que indiques.

sandbox.credentials afecta solo a los comandos Bash aislados en el sandbox. Para quitar credenciales de todos los subprocesos independientemente del sandboxing, establece CLAUDE_CODE_SUBPROCESS_ENV_SCRUB.

Enmascarar credenciales

Cuando enmascaras una credencial, Claude Code muestra a los comandos aislados en el sandbox un marcador por sesión llamado centinela, y el proxy del sandbox sustituye el valor real en las solicitudes salientes a los hosts que permitas. Una entrada deny de Proteger credenciales, en cambio, bloquea la credencial. En el caso de los archivos en macOS, Claude Code bloquea el archivo en su lugar en lugar de enmascararlo.

Enmascarar variables de entorno requiere Claude Code v2.1.199 o posterior. La referencia de sandbox.credentials enumera todos los campos.

El enmascaramiento requiere lo siguiente:

Terminación TLS: el proxy sustituye el valor real dentro del contenido de la solicitud, por lo que necesita verlo. Configura network.tlsTerminate para que el proxy termine TLS por sí mismo. Sin esto, el enmascaramiento falla sin exponer nada: el comando sigue viendo solo el centinela, pero el centinela llega al servidor sin cambios y la autenticación falla. Claude Code informa de esta configuración incorrecta al iniciar.
Un destino permitido: cada entrada mask puede incluir injectHosts, los hosts a los que puede llegar el valor real. El proxy solo inyecta en las conexiones que admite la lista de dominios permitidos, por lo que cada host de injectHosts también debe ser accesible a través de network.allowedDomains. En una entrada mask sin injectHosts, el proxy sustituye el valor real en las solicitudes a todos los hosts de network.allowedDomains.
Un alcance de configuración de confianza: el enmascaramiento autoriza al proxy a enviar tu credencial real a algún lugar, por lo que Claude Code respeta las entradas mask, network.tlsTerminate, credentials.allowPlaintextInject, awsPairs y sigv4 solo desde la configuración de usuario, la configuración administrada y el flag --settings. Los ignora en el .claude/settings.json o el .claude/settings.local.json de un repositorio. Cuando tu administrador entrega entradas mask, network.tlsTerminate o credentials.allowPlaintextInject a través de la configuración administrada por el servidor, cuentan como configuraciones que requieren aprobación.

Enmascarar variables de entorno

Para enmascarar una variable de entorno, establece "mode": "mask" en su entrada de credentials.envVars. El comando y todo lo que registra nunca contienen la credencial real, pero sus solicitudes se siguen autenticando. Cuando la misma variable aparece con deny en cualquier alcance, deny tiene precedencia.

El siguiente ejemplo enmascara dos tokens. GH_TOKEN se sustituye solo en las solicitudes a api.github.com, mientras que NPM_TOKEN no tiene injectHosts y se sustituye en las solicitudes a todos los hosts de network.allowedDomains:

{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com", "registry.npmjs.org"]
    },
    "credentials": {
      "envVars": [
        { "name": "GH_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] },
        { "name": "NPM_TOKEN", "mode": "mask" }
      ]
    }
  }
}

De forma predeterminada, el enmascaramiento reemplaza el valor completo. Para un valor con estructura, como una cadena de conexión DATABASE_URL o un JWT, usa los campos extract, decode, maskClaims y onExtractNoMatch para que las herramientas que analizan el valor sigan funcionando.

Para un destino IPv6, escribe la dirección de forma distinta en las dos listas:

network.allowedDomains: la forma entre corchetes, como "[::1]"
injectHosts: la dirección sin corchetes en su forma canónica comprimida, como "::1"

El proxy compara cada entrada de injectHosts con la dirección de destino sin corchetes de la conexión, ignorando los puertos, por lo que una forma entre corchetes, con ID de zona o comprimida de otra manera nunca coincide. claude doctor marca las entradas que nunca pueden coincidir con la advertencia Sandbox credential injectHosts entries can never match their destination. Esta comprobación requiere Claude Code v2.1.229 o posterior.

Volver a firmar solicitudes de AWS

Las solicitudes de AWS llevan firmas SigV4 sobre el contenido de la solicitud, así que enmascara AWS_ACCESS_KEY_ID y AWS_SECRET_ACCESS_KEY juntas. El proxy detecta una solicitud SigV4 por el centinela de la clave de acceso y vuelve a firmar la solicitud con los valores reales, lo que requiere Claude Code v2.1.221 o posterior. Si enmascaras solo el secreto, las solicitudes se firman con un marcador que el proxy no puede detectar, por lo que fallan en AWS.

Claude Code vincula automáticamente las variables convencionales AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY y AWS_SESSION_TOKEN en una sola credencial cuando enmascaras sus valores completos. Si tu credencial de AWS está en variables con otros nombres, agrúpalas con credentials.awsPairs, que requiere Claude Code v2.1.224 o posterior.

Las cargas en streaming, las URL prefirmadas y las solicitudes SigV4A llevan firmas que el proxy no puede recalcular. Cuando una de estas solicitudes está firmada con el marcador de un par enmascarado, el proxy la hace fallar en lugar de reenviar una firma rota. Las solicitudes firmadas con credenciales sin enmascarar no se ven afectadas. Usa credentials.sigv4, que requiere Claude Code v2.1.224 o posterior, para reenviar en su lugar una de estas formas de solicitud. AWS sigue rechazando la solicitud, de modo que la herramienta que llama recibe la respuesta de rechazo propia de AWS en lugar de un error del proxy.

Enmascarar archivos de credenciales

Para enmascarar un archivo de credenciales, establece "mode": "mask" en su entrada de credentials.files. Enmascarar archivos requiere Claude Code v2.1.221 o posterior. Lo que ve un comando aislado en el sandbox depende de la plataforma:

Linux y WSL2: los comandos aislados en el sandbox leen una copia centinela del archivo, y el proxy sustituye el valor real en las solicitudes salientes.
macOS: los comandos aislados en el sandbox no pueden leer el archivo en absoluto. Claude Code no crea ninguna copia centinela, por lo que las herramientas que se autentican con el archivo no funcionan dentro del sandbox, el mismo efecto que deny. El bloqueo de lectura se mantiene incluso cuando desactivas el aislamiento del sistema de archivos.

El siguiente ejemplo enmascara un token de GitHub almacenado en ~/.config/gh/hosts.yml. El patrón extract marca qué parte del archivo es el secreto, de modo que en Linux y WSL2 gh sigue analizando el resto de su configuración:

{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com"]
    },
    "credentials": {
      "files": [
        {
          "path": "~/.config/gh/hosts.yml",
          "mode": "mask",
          "extract": "oauth_token:\\s*(\\S+)",
          "injectHosts": ["api.github.com"]
        }
      ]
    }
  }
}

Para confirmar que la máscara está activa, pídele a Claude que ejecute cat ~/.config/gh/hosts.yml en un comando aislado en el sandbox. En Linux y WSL2 la salida muestra un centinela en lugar del token, y en macOS la lectura falla.

Sin extract ni decode, Claude Code reemplaza todo el archivo con un único centinela, lo que es adecuado para un archivo que contiene un único secreto simple. Usa los campos extract, decode, maskClaims, onExtractNoMatch y maskDuplicates para controlar el enmascaramiento parcial y qué ocurre cuando el patrón no coincide con nada.

mask se aplica a un único archivo, así que indica cada archivo de credenciales por separado. Claude Code recurre a deny para una entrada mask que no puede enmascarar de forma segura: una ruta de directorio, un patrón glob, un archivo de más de 8 MiB o un archivo que no es texto UTF-8.

Cómo funciona el sandboxing

Aislamiento del sistema de archivos

La herramienta Bash en el sandbox restringe el acceso al sistema de archivos a directorios específicos:

Comportamiento de escritura predeterminado: acceso de lectura y escritura al directorio de trabajo actual y sus subdirectorios, a cualquier directorio que hayas agregado con --add-dir, /add-dir o permissions.additionalDirectories, además del directorio temporal por usuario al que apunta $TMPDIR
Comportamiento de lectura predeterminado: acceso de lectura a toda la computadora, excepto ciertos directorios denegados. Este valor predeterminado aún permite leer archivos de credenciales, así que protege las credenciales que no quieras que los comandos lean.
Bloqueo de lectura: con permissions.blockReadsOutsideWorkingDirectories activado, los comandos en el sandbox también pierden el acceso de lectura a tu directorio home y a los demás directorios que contienen archivos de usuario, salvo las rutas que enumera Comandos en el sandbox bajo el bloqueo. Esa sección también indica cuándo no se aplica esta parte del bloqueo.
Git worktrees: cuando el directorio de trabajo es un worktree de git vinculado, el sandbox también permite escrituras en el directorio .git compartido del repositorio principal para que comandos como git commit puedan actualizar las refs y el índice. Las escrituras en hooks/ y config dentro de ese directorio siguen denegadas.

Para omitir por completo el aislamiento del sistema de archivos y mantener el aislamiento de red, configura sandbox.filesystem.disabled.

Rutas protegidas

Dentro de los directorios en los que los comandos en el sandbox pueden escribir, el sandbox sigue denegando escrituras en los archivos desde los que Claude Code carga configuración y código. Un comando que pudiera editar esos archivos podría otorgarse permisos a sí mismo, o agregar un hook o un servidor MCP que Claude Code ejecute fuera del sandbox. El sistema de permisos tiene sus propias rutas protegidas, que controlan lo que Claude Code aprueba antes de que se ejecute una herramienta; la lista del sandbox se aplica a un comando que ya se está ejecutando. Abarca cuatro grupos de rutas:

En tu directorio de trabajo y los directorios superiores: los archivos de configuración de .claude, los directorios .claude/skills, .claude/agents, .claude/commands y .claude/hooks, .mcp.json, y los archivos que Claude Code ejecuta por sí mismo, como .claude/workflows y .claude/scheduled_tasks.json
Solo en tu directorio de trabajo: archivos de inicio del shell como .bashrc y .zshrc, .gitconfig, los directorios .vscode y .idea, y hooks y config dentro de .git
Archivos que convertirían tu directorio de trabajo en un repositorio git bare: HEAD, objects y refs en el nivel superior, además de las entradas config y hooks existentes allí cuando hay un HEAD junto a ellas. Un archivo llamado config se deniega incluso sin HEAD. En Linux y WSL2, el sandbox elimina un archivo HEAD o un directorio objects o refs de nivel superior que aparezca mientras se ejecuta un comando en el sandbox
En ~/.claude, o el directorio al que apunta CLAUDE_CONFIG_DIR: la mayor parte de su contenido, además de ~/.claude.json y el almacén de credenciales .credentials.json

Si aparece un enlace simbólico en la ruta de un archivo de configuración protegido durante la sesión, el sandbox también deniega las escrituras en el archivo al que apunta, a partir del siguiente comando.

No hay forma de exceptuar una de estas rutas: una entrada allowWrite o una regla de permiso Edit que cubra la ruta no elimina la protección. La única forma de desactivar la protección es filesystem.disabled, que desactiva el aislamiento del sistema de archivos para todas las rutas. Para ver la mayoría de estas rutas resueltas para tu máquina, ejecuta /sandbox y abre la pestaña Config, que las enumera en Denied within allowed, mezcladas con tus propias entradas denyWrite.

Si git merge o git checkout falla con unable to unlink old en una de estas rutas, consulta Un comando de git falla con unable to unlink old.

Aislamiento de red

Un comando en el sandbox no tiene una ruta directa a la red:

Linux y WSL2: el comando se ejecuta en un espacio de nombres de red separado que no tiene conexión con tu red
macOS: el framework de sandbox Seatbelt bloquea de forma predeterminada las conexiones distintas de la que va al proxy del sandbox

Claude Code ejecuta el proxy del sandbox en tu máquina, fuera del sandbox, y dirige los comandos hacia él con HTTP_PROXY, HTTPS_PROXY, ALL_PROXY y variables de entorno relacionadas. El proxy compara el nombre de host de cada conexión con tus dominios permitidos y denegados.

Lo que una herramienta puede alcanzar depende de si usa el proxy:

Herramientas que leen las variables del proxy: curl, npm, git sobre HTTPS y herramientas similares se conectan una vez que su host está permitido. Una entrada de allowedDomains sin puerto permite todos los puertos de ese host
Herramientas que ignoran las variables del proxy: ssh simple, la mayoría de los controladores de bases de datos y herramientas similares no pueden conectarse, ni siquiera a un host permitido. Consulta Un cliente de base de datos u otra herramienta que no es HTTP no logra alcanzar un host permitido
Todo lo que no sea TCP: UDP, HTTP/3 sobre QUIC y herramientas ICMP como ping no pueden salir del sandbox

Los siguientes ajustes y comportamientos controlan qué hosts permite el proxy:

Restricciones de dominio: tus dominios permitidos empiezan vacíos. Hosts fuera de tus dominios permitidos explica qué sucede la primera vez que un comando necesita un dominio nuevo.
Opciones de aprobación: si eliges Yes cuando se te solicita, Claude Code permite el host durante el resto de la sesión actual. Si eliges "Yes, and don't ask again", Claude Code guarda una regla de permiso WebFetch(domain:...) en tu configuración local, de modo que el host sigue permitido en sesiones futuras. Mientras el sandbox sea obligatorio por el administrador, Claude Code guarda la regla en tu configuración de usuario, donde se aplica en todos los proyectos.
Dominios permitidos previamente: permite dominios previamente con allowedDomains para evitar la solicitud por completo. Claude Code también permite previamente los dominios de las reglas de permiso WebFetch(domain:...), como se describe en Reglas de permisos.
Lista de permitidos estricta: si configuras strictAllowlist en true en la configuración de usuario, administrada o de --settings de la CLI, Claude Code deniega a los comandos en el sandbox el acceso a cualquier host fuera de la lista de permitidos en lugar de pedir confirmación. La lista de permitidos es allowedDomains más los dominios de las reglas de permiso WebFetch(domain:...), o solo las entradas de la configuración administrada cuando allowManagedDomainsOnly está configurado. Bloqueos que se aplican sin un sandbox obligatorio por el administrador cubre las entradas de un repositorio. Claude Code aplica esto solo a los comandos en el sandbox; las herramientas en proceso como WebFetch siguen sus reglas de permisos. Configurarlo en .claude/settings.json o .claude/settings.local.json de un repositorio no tiene efecto. Requiere Claude Code v2.1.219 o posterior.
Bloqueo administrado: si allowManagedDomainsOnly está configurado en la configuración administrada, los dominios no permitidos se bloquean automáticamente en lugar de pedir confirmación, y solo se respetan allowedDomains y las reglas de permiso WebFetch(domain:...) de la configuración administrada.
Proxy corporativo: cuando tu red requiere que el tráfico saliente pase por un proxy corporativo, configura HTTPS_PROXY, HTTP_PROXY y NO_PROXY como se describe en configuración del proxy, en el bloque env de tu configuración para que los agentes en segundo plano también las reciban, o en el entorno desde el que inicias Claude Code. Claude Code aplica la lista de dominios permitidos y luego canaliza las conexiones permitidas a través de ese proxy upstream. Funcionan las URL de proxy http:// y https://, con autenticación básica en la URL si la necesitas.

En una regla WebFetch(domain:...), el sandbox respeta dos formas de comodín: un *. inicial, como *.example.com, y un * solo. La forma * sola requiere Claude Code v2.1.186 o posterior. Un comodín en cualquier otra posición, como WebFetch(domain:example.*), sigue coincidiendo con las solicitudes de fetch pero no tiene efecto en los comandos en el sandbox.

Hosts fuera de tus dominios permitidos

Cuando un comando en el sandbox se conecta a un host que no está en tus dominios permitidos, el comando permanece en el sandbox y espera una decisión. En una sesión interactiva de terminal, la decisión depende de tu modo de permisos:

Modo de permisos	Qué sucede con la conexión
Modo `bypassPermissions`, y modo plan con bypass de permisos disponible	Se permite sin solicitud
Modo manual, modo `acceptEdits` y modo plan en otros casos	Recibes una solicitud
Modo automático	Se rechaza a menos que el comando haya listado el host y el clasificador haya aprobado la lista
Modo `dontAsk`	Se rechaza

Con strictAllowlist o allowManagedDomainsOnly activado, el proxy integrado del sandbox rechaza la conexión en todos los modos de permisos. En el modo bypassPermissions, los hosts fuera de tus dominios permitidos se permiten a menos que uno de ellos esté activado. La vía de escape de reintento sin sandbox explica cuándo un comando puede salir del sandbox en ese modo. Una conexión a un host en deniedDomains también se rechaza en todos los modos de permisos.

Nombres de host que se resuelven en direcciones locales

Después de que un nombre de host pasa la lista de permitidos, el proxy del sandbox lo resuelve y rechaza la conexión cuando el nombre se resuelve solo en direcciones locales. Las direcciones locales incluyen direcciones de loopback como 127.0.0.1, direcciones de enlace local como el endpoint de metadatos en la nube 169.254.169.254, y direcciones asignadas a tu propia máquina. Los nombres localhost y *.localhost pueden resolverse en loopback.

Un nombre de host de intranet permitido que se resuelve en un rango privado como 10.0.0.0/8 se conecta. Para permitir que un nombre se resuelva en una dirección rechazada, agrega esa dirección IP a allowedDomains, como "127.0.0.1:8080".

La comprobación se aplica a nombres de host. Tus dominios permitidos y tu modo de permisos deciden una conexión a una dirección IP. El proxy también omite la comprobación para las conexiones que envía a través de un proxy corporativo upstream, porque ese proxy resuelve el nombre.

Dominios permitidos por comando en el modo automático

En el modo automático con el sandboxing activado, Claude indica en el propio comando los hosts que este necesita en lugar de activar una aprobación de red para cada conexión. Cada comando Bash, PowerShell o Monitor que se ejecuta en el sandbox puede llevar una lista de hosts más allá de la lista de permitidos del sandbox: un dominio como registry.npmjs.org, un comodín como *.pythonhosted.org o una dirección IP, cada uno con un :port opcional. El clasificador revisa los hosts junto con el comando. Requiere Claude Code v2.1.271 o posterior.

Una lista aprobada abre esos hosts solo para ese comando, mientras se ejecute. No se agrega nada a los hosts permitidos de tu sesión ni a tu configuración; el siguiente comando indica sus propios hosts.

Un comando que lleva hosts pasa al clasificador en lugar de ser aprobado por una regla de permisos o por el modo de permiso automático del sandbox. Si una regla ask fuerza una solicitud para el comando, el diálogo de permisos en tu terminal enumera los hosts junto a él, y aprobar allí cubre ambos.

Una lista por comando amplía solo lo que el sandbox deniega de forma predeterminada. Las entradas de deniedDomains siguen bloqueando. Cuando strictAllowlist o allowManagedDomainsOnly bloquea la lista de permitidos, Claude Code rechaza las listas por comando.

Mientras se aplican las listas por comando, Claude Code rechaza una conexión a un host que ningún comando aprobado haya listado, sin solicitud ni comprobación del clasificador. El rechazo indica el host en el resultado del comando, y Claude vuelve a ejecutar el comando con el host agregado.

Direcciones IPv6 en listas de dominios

Para que coincida una dirección IPv6 en allowedDomains, deniedDomains o una regla WebFetch(domain:...), escribe la dirección entre corchetes: "[::1]" coincide con esa dirección en todos los puertos, y "[::1]:443" coincide con ella solo en el puerto 443. La forma entre corchetes requiere Claude Code v2.1.229 o posterior.

Una entrada sin corchetes como ::1:443 es ambigua entre una dirección y una dirección con un puerto:

Listas de denegación: Claude Code deniega todas las interpretaciones con las que se puede analizar la entrada, de modo que se bloquea la interpretación que hayas querido decir. Para una entrada sin ninguna interpretación analizable, Claude Code no bloquea nada
Listas de permitidos: Claude Code nunca permite más de lo que escribiste. Reescribe una entrada ambigua a su interpretación de host y puerto cuando esa interpretación se analiza correctamente, y puede descartar la entrada por completo en lugar de ampliar la lista de permitidos

Para encontrar entradas ambiguas, ejecuta claude doctor en tu terminal y busca la advertencia Sandbox network domain entries have unreliable spellings. Reescribe cada entrada ambigua en la forma entre corchetes.

Aplicación a nivel del sistema operativo

La herramienta Bash en el sandbox usa primitivas de seguridad del sistema operativo:

macOS: usa Seatbelt para aplicar el sandbox
Linux: usa bubblewrap para el aislamiento
WSL2: usa bubblewrap, igual que Linux

También puedes ejecutar el paquete @anthropic-ai/sandbox-runtime por sí solo para envolver el proceso de Claude Code. Consulta Sandbox runtime.

Cómo se relaciona el sandboxing con los permisos y modos de permiso

El sandboxing, las reglas de permiso y los modos de permiso son capas complementarias. Las secciones a continuación cubren cómo el sandbox interactúa con cada una.

Reglas de permiso

Las reglas de permiso y el sandboxing controlan cosas diferentes:

Reglas de permiso controlan qué herramientas puede usar Claude Code y se evalúan antes de que se ejecute cualquier herramienta. Se aplican a todas las herramientas: Bash, Read, Edit, WebFetch, MCP y otras, excepto que una regla de denegación o solicitud no puede bloquear EndConversation mientras que cualquier otra herramienta permanezca.
Sandboxing proporciona aplicación a nivel del sistema operativo que restringe lo que los comandos Bash pueden acceder a nivel del sistema de archivos y la red. Se aplica solo a comandos Bash, PowerShell y Monitor y sus procesos secundarios.

Las dos capas también difieren en cómo se aplican. Claude Code evalúa las decisiones de permiso antes de que se ejecute un comando, basándose en la cadena de comando y, en modo automático, el juicio de un clasificador separado sobre si el comando es seguro. El sistema operativo aplica el límite del sandbox en el proceso en ejecución, por lo que se mantiene independientemente de lo que el modelo eligió ejecutar e incluso si un comando permitido hace más de lo que su nombre sugiere.

Las restricciones del sistema de archivos y la red se configuran tanto a través de la configuración del sandbox como de las reglas de permiso:

Configuración o regla	Qué hace
`sandbox.filesystem.allowWrite`	Otorga acceso de escritura de subproceso a rutas fuera del directorio de trabajo
`sandbox.filesystem.denyWrite` y `sandbox.filesystem.denyRead`	Bloquea el acceso de subproceso a rutas específicas
`sandbox.filesystem.allowRead`	Permite nuevamente la lectura de rutas específicas dentro de una región `denyRead`
`sandbox.filesystem.disabled`	Desactiva la capa del sistema de archivos por completo mientras mantiene el aislamiento de red
Reglas de permitir `Edit`	Otorga acceso de escritura a rutas específicas, de la misma manera que `sandbox.filesystem.allowWrite`
Reglas de denegar `Read` y `Edit`	Bloquea el acceso a archivos o directorios específicos
Reglas de permitir y denegar `WebFetch(domain:...)`	Controla el acceso al dominio
`allowedDomains` del sandbox	Controla qué dominios pueden alcanzar los comandos Bash
`deniedDomains` del sandbox	Bloquea dominios específicos incluso cuando un comodín `allowedDomains` más amplio de otra manera los permitiría

Las rutas y dominios de ambas configuraciones del sandbox y reglas de permiso se fusionan en la configuración final del sandbox.

El directorio de ejemplos del repositorio claude-code incluye configuraciones de configuración de inicio para escenarios de implementación comunes, incluidos ejemplos específicos del sandbox. Úselos como puntos de partida y ajústelos para que se adapten a sus necesidades.

Modos de permiso

/sandbox no es un modo de permiso. Los modos de permiso deciden si se ejecuta una llamada de herramienta y si se le solicita primero, mientras que el sandbox restringe lo que un comando Bash puede acceder una vez que se ejecuta. Difieren en lo que controlan y qué reemplaza la solicitud por acción:

	Qué controla	Qué reemplaza la solicitud
`/sandbox`	Lo que un comando Bash puede acceder una vez que se ejecuta	El límite del sandbox en sí, en modo auto-allow
Modo automático	Si se ejecuta cada llamada de herramienta	Un clasificador que revisa acciones
`--dangerously-skip-permissions`	Si se ejecuta cada llamada de herramienta	Nada. Las verificaciones de ruta protegida también se omiten; las acciones que ningún modo auto-aprueba aún se aplican

El modo auto-allow del sandbox es separado del modo automático: auto-allow aprueba comandos Bash porque el límite del sandbox los contiene, mientras que el modo automático usa un clasificador para revisar acciones. Los dos funcionan independientemente y pueden combinarse, con las excepciones enumeradas en Modos sandbox. Para elegir un límite de aislamiento para ejecuciones desatendidas, consulte Entornos sandbox. Para una tabla de emparejamientos comunes de modo de permiso y sandbox con los indicadores que inician cada uno, consulte Configuraciones comunes.

Configurar el sandbox para tu organización

Los administradores pueden requerir sandboxing para cada usuario, evitar que los desarrolladores amplíen la política y enrutar el tráfico del sandbox a través de un proxy corporativo.

Aplicar sandboxing con configuración administrada

Para requerir el sandbox para cada desarrollador, entrega las claves sandbox a través de la configuración administrada, ya sea como un archivo administrado por tu MDM o a través de la configuración administrada por servidor en claude.ai.

La siguiente configuración administrada habilita el sandbox, se niega a iniciar Claude Code cuando la plataforma no es compatible o falta una dependencia, y evita que el modelo reintente comandos fuera del sandbox:

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

Las dos claves más allá de enabled controlan qué sucede cuando el sandbox no puede ejecutar un comando:

failIfUnavailable: una dependencia faltante como bubblewrap en Linux impide que Claude Code se inicie en lugar de volver a la ejecución sin aislar
allowUnsandboxedCommands: false: Claude Code ignora la salida de emergencia dangerouslyDisableSandbox, por lo que cuando un comando falla bajo el sandbox, Claude no puede reintentarlo sin aislar

Considera estas adiciones junto con ellas:

Agrega excludedCommands para cualquier herramienta aprobada por la organización que deba ejecutarse sin aislamiento, porque esta configuración impide que la configuración de un repositorio saque comandos del sandbox
Agrega entradas sandbox.credentials para directorios de credenciales como ~/.aws y ~/.ssh y para variables de entorno secretas, ya que la política de lectura predeterminada aún las permite

Esta configuración aísla los comandos que ejecuta Claude. Un desarrollador aún puede escribir un comando en el prompt del modo shell ! y ejecutarlo fuera del sandbox, con el mismo acceso que ya tiene en cualquier terminal fuera de Claude Code. Consulta el modo de sandbox estricto para las sesiones donde los comandos escritos se ejecutan aislados.

El sandbox no se ejecuta en Windows nativo, por lo que con failIfUnavailable establecido, Claude Code se cierra al iniciar en esas máquinas. Si tu flota incluye hosts de Windows, puedes:

Entregar la configuración por sistema operativo: impleméntala a través de tu MDM o como un archivo de configuración administrada solo en máquinas macOS y Linux. La configuración administrada por servidor se aplica a todos los usuarios de la organización
Mover a los usuarios de Windows a un entorno compatible: haz que ejecuten Claude Code dentro de WSL2 o un contenedor

Evitar que los desarrolladores amplíen la política

Cuando la configuración administrada establece una clave booleana como enabled o failIfUnavailable, Claude Code usa el valor administrado e ignora cualquier cosa que un desarrollador establezca localmente. Para claves de array como allowRead, Claude Code combina las entradas de los alcances que carga la sesión, por lo que un desarrollador puede agregar entradas que amplíen la política, a menos que un bloqueo cubra esa clave.

A menos que la configuración administrada las establezca, la configuración de usuario de un desarrollador o --settings pueden activar las siguientes claves. El .claude/settings.json de un repositorio también puede hacerlo, a menos que el sandbox sea requerido por el administrador. Cada una debilita el sandbox, así que establécela en false en la configuración administrada si no quieres que se use:

enableWeakerNestedSandbox
enableWeakerNetworkIsolation
network.allowAllUnixSockets
network.allowLocalBinding
allowAppleEvents, que un repositorio no puede activar

Establece allowManagedReadPathsOnly en true en la configuración administrada para que solo se respeten las entradas allowRead de la configuración administrada. Esto evita que los desarrolladores amplíen el acceso de lectura más allá de las rutas aprobadas por la organización.

Para bloquear los dominios de red a los valores administrados de la misma manera, establece allowManagedDomainsOnly. Con el bloqueo activado, solo la configuración administrada puede establecer un puerto de proxy.

Cuando la configuración administrada configura sandbox.filesystem o enumera cualquier entrada sandbox.credentials.files con "mode": "deny", solo la configuración administrada puede establecer filesystem.disabled, por lo que los desarrolladores no pueden desactivar las restricciones del sistema de archivos implementadas por el administrador. Una entrada mask válida no bloquea la clave. Consulta Qué configuración puede desactivarla.

Configuración del repositorio con un sandbox requerido por el administrador

El sandbox es requerido por el administrador mientras uno de estos ajustes esté en vigor:

allowUnsandboxedCommands establecido en false en la configuración administrada, o con el flag --settings a menos que la configuración administrada lo establezca en true
allowManagedDomainsOnly establecido en true en la configuración administrada

Estos ajustes no activan el sandbox, así que establece también enabled.

Mientras el sandbox es requerido por el administrador, Claude Code toma los ajustes que lo flexibilizan solo de la configuración administrada, el flag --settings y el ~/.claude/settings.json de cada desarrollador. Ignora estos ajustes en el .claude/settings.json y el .claude/settings.local.json de un repositorio:

Ajuste del repositorio	Lo que Claude Code ignora
`excludedCommands`, `ignoreViolations`, `network.allowedDomains`, `network.allowUnixSockets`, `network.allowMachLookup`, `network.httpProxyPort`, `network.socksProxyPort`	Todas las entradas
`filesystem.allowWrite`, reglas de permiso `Edit(...)`, `permissions.additionalDirectories`	El acceso de escritura que cada entrada otorga a los comandos aislados. Las herramientas de archivos de Claude siguen respetando las reglas `Edit(...)` y los directorios adicionales
Reglas de permiso `WebFetch(domain:...)`	El host que cada regla agrega a la lista de permitidos del sandbox. La herramienta WebFetch sigue respetando la regla
`enableWeakerNestedSandbox`, `enableWeakerNetworkIsolation`, `network.allowAllUnixSockets`, `network.allowLocalBinding`	`true`. Un `false` sigue aplicándose
`enabled`, `failIfUnavailable`	`false`, cuando el `~/.claude/settings.json` del desarrollador establece `true`
`filesystem.allowRead`	Una entrada en o bajo una ruta cuya lectura deniegan la configuración administrada, `--settings` o la configuración de usuario, o un glob que podría coincidir con una

Estos ajustes siguen aplicándose mientras el sandbox es requerido por el administrador:

En los archivos de un repositorio: las entradas de denegación y el valor de autoAllowBashIfSandboxed. Establece la clave en la configuración administrada para evitar que un repositorio la cambie
En la configuración propia de un desarrollador: los ajustes de la tabla siguen aplicándose desde ~/.claude/settings.json o --settings, a menos que un bloqueo solo administrado como allowManagedDomainsOnly los cubra. La mayoría de ellos, como excludedCommands y filesystem.allowWrite, no tienen un bloqueo solo administrado

La configuración en Aplicar sandboxing con configuración administrada hace que el sandbox sea requerido por el administrador. Agrega a la configuración administrada las entradas de excludedCommands, allowWrite y sockets que necesitan tus herramientas aprobadas, porque un repositorio no puede proporcionarlas.

Requiere Claude Code v2.1.285 o posterior. De v2.1.282 a v2.1.284, los mismos ajustes hacían que Claude Code ignorara las entradas excludedCommands de un repositorio.

Bloqueos que se aplican sin un sandbox requerido por el administrador

Algunos ajustes hacen que Claude Code ignore las claves del repositorio que sobrescriben directamente una restricción, incluso cuando el sandbox no es requerido por el administrador. Cada uno tiene este efecto solo cuando lo estableces en un archivo que nombra su fila, y los demás ajustes del sandbox del repositorio siguen aplicándose. Requiere Claude Code v2.1.285 o posterior.

Ajuste	Dónde lo estableces	Lo que Claude Code ignora en la configuración de un repositorio
`network.deniedDomains` o una regla de denegación `WebFetch(domain:...)`	Configuración administrada, `--settings`	`httpProxyPort` y `socksProxyPort`
`network.strictAllowlist`	Configuración administrada, `--settings`, configuración de usuario	Los puertos de proxy, `allowedDomains` y las reglas de permiso `WebFetch(domain:...)`
`filesystem.denyRead`, una regla de denegación `Read(...)` o una entrada `credentials.files`	Configuración administrada, `--settings`	Una entrada `allowRead`, `allowWrite`, de permiso `Edit(...)` o `additionalDirectories` en o bajo una ruta cuya lectura deniegan la configuración administrada, `--settings` o la configuración de usuario, o un glob que podría coincidir con una

Estos bloqueos cambian lo que pueden alcanzar los comandos aislados. La herramienta WebFetch y las herramientas de archivos de Claude siguen respetando las reglas y los directorios adicionales de un repositorio.

Configuración de proxy personalizado

Para inspeccionar, filtrar o registrar el tráfico del sandbox con tus propias herramientas, reemplaza el proxy integrado del sandbox por un proxy que ejecutes en la misma máquina.

Para enrutar el tráfico del sandbox a través de un proxy corporativo ubicado en otra parte de tu red, establece HTTPS_PROXY en su lugar, como describe la entrada Proxy corporativo en Aislamiento de red. De esa manera, la lista de permitidos de Claude Code sigue aplicándose.

Para dirigir los comandos aislados a tu proxy, establece los puertos de localhost en los que escucha en la configuración del sandbox:

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

Si estableces un puerto y también estableces HTTPS_PROXY o HTTP_PROXY, Claude Code no reenvía lo que los comandos aislados envían a tu proxy hacia el proxy que nombran esas variables. Para llegar a un proxy corporativo, configura tu propio proxy para que reenvíe a él.

Qué archivos pueden establecer un puerto depende de tus demás ajustes del sandbox:

allowManagedDomainsOnly está activado: solo la configuración administrada
El sandbox es requerido por el administrador, o se aplica un bloqueo de red más limitado: la configuración administrada, --settings y la configuración de usuario
En cualquier otro caso: cualquier archivo de configuración

Claude Code ignora un puerto establecido en cualquier otro lugar. Antes de v2.1.285, cualquier archivo de configuración podía establecer un puerto.

Solución de problemas

Algunos comandos fallan dentro del sandbox aunque funcionen fuera de él. Busca el encabezado que coincida con tu síntoma o mensaje de error.

Si el sandbox de tu organización es obligatorio por parte del administrador, Claude Code ignora los ajustes que mencionan estas correcciones en los archivos de configuración de un proyecto, así que guárdalos en ~/.claude/settings.json, donde se aplican en todos los proyectos. Si una corrección sigue sin tener efecto, es posible que la configuración administrada de tu organización establezca esa clave.

Una corrección que agrega un patrón a excludedCommands quita el sandbox de los comandos que coinciden con el patrón. Consulta qué puede hacer un comando excluido.

Los comandos fallan con un error de host no permitido

Muchas herramientas CLI necesitan alcanzar hosts específicos. Aprueba el host cuando se te solicite, o agrégalo a allowedDomains. Si tu organización bloquea la lista de dominios permitidos con allowManagedDomainsOnly, no hay solicitud, así que pide a tu administrador que agregue el host.

`jest` se cuelga o falla

watchman es incompatible con el sandbox. Ejecuta jest --no-watchman en su lugar.

Las CLI basadas en Go fallan en la verificación de TLS en macOS

Herramientas como gh, gcloud y terraform pueden fallar en la verificación de TLS bajo Seatbelt. Para ejecutar estas herramientas fuera del sandbox, agrega un patrón para cada herramienta, como gh *, a excludedCommands. La herramienta se ejecuta entonces con tu acceso completo y sus credenciales almacenadas. Si estás usando httpProxyPort con un proxy MITM y CA personalizado, establece enableWeakerNetworkIsolation en true en su lugar.

`open`, `osascript` o los flujos de autenticación basados en navegador fallan con el error `-600` en macOS

El sandbox bloquea Apple Events de forma predeterminada. Establece allowAppleEvents en true en tu configuración de usuario, administrada o CLI para permitirlos. Claude Code ignora esta clave en la configuración del proyecto.

Habilitar allowAppleEvents elimina el aislamiento de ejecución de código, ya que los comandos aislados pueden entonces lanzar otras aplicaciones sin aislar sin solicitud del usuario, y pueden enviar comandos AppleScript a aplicaciones en ejecución, sujeto a la solicitud de consentimiento de automatización de macOS (TCC). Alternativamente, agrega un patrón como open * a excludedCommands. Cada llamada a open pasa entonces por el flujo de permisos, y open puede lanzar cualquier archivo o aplicación, incluido uno que Claude haya escrito.

Los comandos `docker` fallan

docker es incompatible con el sandbox. Saca del sandbox los comandos docker que necesites con un patrón de excludedCommands como docker compose *. Ejecutar comandos fuera del sandbox con excludedCommands explica a qué puede acceder un comando docker excluido. Un patrón más específico saca menos comandos del sandbox.

`pbcopy`, `xclip` o `wl-copy` no actualiza el portapapeles

Las utilidades de portapapeles pbcopy, xclip y wl-copy pueden fallar al alcanzar el portapapeles del sistema desde dentro del sandbox, en cuyo caso el texto canalizado hacia ellas no llega.

Para poner la salida de Claude en tu portapapeles, pide a Claude que la imprima en su respuesta, luego ejecuta /copy. /copy escribe en el portapapeles desde el proceso Claude Code en lugar de desde un comando aislado.

Cuando Claude canaliza texto a una de estas herramientas, agregar la herramienta a excludedCommands no saca esa llamada del sandbox por sí sola.

Un comando git falla con `unable to unlink old`

git merge, git checkout y comandos similares fallan con unable to unlink old cuando necesitan reemplazar un archivo al que el sandbox deniega escrituras. En Linux y WSL2 el error termina con Read-only file system. El archivo puede estar en uno de estos lugares:

Bajo una ruta protegida como .claude/skills
Bajo una de tus entradas denyWrite
Fuera de los directorios en los que el sandbox permite que los comandos escriban en absoluto

Después de la falla, Claude puede ofrecer ejecutar nuevamente el comando fuera del sandbox. Aprueba ese reintento o ejecuta el comando git tú mismo en otra terminal. Si has establecido allowUnsandboxedCommands en false, Claude no puede ofrecer el reintento, así que ejecuta el comando tú mismo.

Bubblewrap falla al iniciarse dentro de un contenedor

En un contenedor sin privilegios, bubblewrap no puede montar un sistema de archivos /proc nuevo, por lo que los comandos aislados fallan con un error bwrap como Can't mount proc on /newroot/proc: Operation not permitted. Establece enableWeakerNestedSandbox en true para que el sandbox monte mediante bind el /proc existente del contenedor en su lugar. Solo usa este ajuste cuando el contenedor externo ya proporcione el límite de aislamiento que necesitas, ya que el ajuste expone información de proceso a comandos aislados que un montaje /proc nuevo ocultaría.

Los archivos de solo lectura de 0 bytes aparecen en las rutas de configuración `.claude`, y "Sí, y no preguntar de nuevo" no guarda

En Linux y WSL2, el sandbox mantiene una denegación de escritura en un archivo que aún no existe creando un marcador de posición de solo lectura de 0 bytes allí mientras se ejecuta un comando aislado. El sandbox elimina el marcador de posición después. Si una sesión se mata antes de que se ejecute esa limpieza, por ejemplo por SIGKILL, los marcadores de posición permanecen. Las sesiones posteriores vuelven a vincular los marcadores de posición como de solo lectura en cada inicio, por lo que una escritura de configuración como guardar una opción de permiso falla en una ruta donde permanece un marcador de posición.

Ejecuta claude doctor en tu terminal para enumerar los archivos de marcador de posición restantes. La advertencia Stale sandbox mask files left by a killed session nombra algunos de ellos y cuenta el resto. Elimina cada archivo con rm mientras no se ejecute ninguna otra sesión de Claude Code en ese proyecto. Antes de v2.1.257, Claude Code dejaba los mismos marcadores de posición sin marcarlos.

`git` sobre SSH falla con el sandbox activado

En macOS, git fetch, git pull y git push contra un remoto SSH fallan dentro del sandbox incluso cuando el host está permitido. En Linux y WSL2, funcionan una vez que el host está permitido. Claude Code canaliza la conexión SSH de git a través del proxy del sandbox, y el túnel de macOS no puede autenticarse ante ese proxy.

En Linux y WSL2, revisa lo siguiente si la conexión sigue fallando:

El host está permitido en el puerto 22: una entrada de allowedDomains sin puerto, como "git.example.com", lo cubre
Tu proxy corporativo permite el puerto 22: si tu red requiere un proxy ascendente, el túnel también pasa por él
La clave se puede leer como archivo: el sandbox puede bloquear el socket de ssh-agent, y una entrada denyRead o credentials para ~/.ssh oculta tus archivos de clave

En macOS, cambia el remoto a HTTPS, lo que requiere credenciales HTTPS como un token de acceso personal:

git remote set-url origin https://git.example.com/example-org/example-repo.git

Si tienes que mantener el remoto SSH, saca los comandos de red de git del sandbox con excludedCommands:

{
  "sandbox": {
    "excludedCommands": ["git fetch *", "git pull *", "git push *"]
  }
}

Estas entradas coinciden con git push origin main. Una llamada que agrega un cd, usa git -C o contiene una sustitución de comandos permanece en el sandbox. Los comandos git excluidos pueden alcanzar cualquier host, no solo los que están en allowedDomains.

ssh, scp y rsync sobre SSH por sí solos fallan por la razón que indica la entrada del cliente de base de datos.

Un cliente de base de datos u otra herramienta no HTTP no logra alcanzar un host permitido

Una herramienta que ignora las variables de entorno del proxy no puede conectarse desde dentro del sandbox, ni siquiera a un host que esté en allowedDomains. Un comando aislado no tiene una ruta directa a la red, por lo que una herramienta que abre su propia conexión falla. La mayoría de los controladores de bases de datos, ssh por sí solo y las herramientas que usan UDP se comportan de esta manera.

La falla se ve como un error de red o de resolución de nombres:

macOS: Operation not permitted, o un error de resolución de nombres como Could not resolve host
Linux y WSL2: Network is unreachable, o un error de resolución de nombres como Temporary failure in name resolution

Una herramienta que usa el proxy falla de otra manera cuando su host no está permitido. Recibes una solicitud de red, o la herramienta recibe una respuesta 403 del proxy.

Para permitir que la herramienta se conecte, ejecuta el comando que la necesita fuera del sandbox con excludedCommands. Este ejemplo excluye un script y agrega una regla ask para que apruebes cada ejecución:

{
  "sandbox": {
    "excludedCommands": ["python scripts/load_orders.py *"]
  },
  "permissions": {
    "ask": ["Bash(python scripts/load_orders.py *)"]
  }
}

El script se ejecuta con tu acceso completo, y Claude puede editar un script que esté dentro de tu directorio de trabajo, así que revísalo cuando aparezca la solicitud.

Un comando no logra alcanzar un servidor en localhost

De forma predeterminada, un comando aislado no puede conectarse directamente a un servidor que se ejecuta en tu máquina fuera del sandbox, como un servidor de desarrollo o una base de datos en un contenedor. Lo que puedes cambiar depende de tu plataforma:

macOS: establece network.allowLocalBinding en true. Los comandos aislados pueden entonces escuchar en puertos de red y conectarse a cualquier puerto en localhost, lo que incluye todos los demás servicios que escuchan allí. Un servicio de localhost que no requiere autenticación, como un depurador, puede entonces actuar en nombre del comando fuera del sandbox, y un comando que escucha en una dirección que no es de loopback acepta conexiones de otras máquinas
Linux y WSL2: el localhost de un comando aislado es privado para ese comando. El comando puede escuchar en un puerto y alcanzar servidores que él mismo inició. Una conexión directa a localhost o 127.0.0.1 no alcanza los servidores del host, y allowLocalBinding no tiene efecto. Ejecuta el comando que necesita el servidor del host fuera del sandbox con excludedCommands, donde no tiene límites de sistema de archivos ni de red. Para conexiones que pasan por el proxy del sandbox, consulta Nombres de host que se resuelven en direcciones locales

Este ejemplo activa el ajuste para macOS:

{
  "sandbox": {
    "network": {
      "allowLocalBinding": true
    }
  }
}

Una entrada de allowedDomains para localhost se aplica a las conexiones que pasan por el proxy, por lo que no cambia una conexión directa. Claude Code establece NO_PROXY para los comandos aislados de modo que se conecten a localhost directamente en lugar de a través del proxy. La entrada también expone todos los puertos del localhost de tu máquina a un comando que sí usa el proxy. Para un nombre de host de desarrollo que apunta a 127.0.0.1, consulta Un nombre de host permitido se rechaza con resolved to a loopback address.

Un nombre de host permitido se rechaza con `resolved to a loopback address`

El proxy del sandbox rechaza un nombre de host permitido que se resuelve en una dirección local, lo que afecta a nombres de desarrollo como myapp.test que apuntan a 127.0.0.1. El comando ve una respuesta 403 cuyo cuerpo indica el tipo de dirección, como Connection to myapp.test blocked: resolved to a loopback address.

Agrega la dirección IP en la que se resuelve el nombre junto al nombre de host en allowedDomains, cada uno con el puerto en el que escucha tu servidor:

{
  "sandbox": {
    "network": {
      "allowedDomains": ["myapp.test:3000", "127.0.0.1:3000"]
    }
  }
}

Una entrada de dirección IP sin puerto permite que los comandos aislados alcancen todos los servicios que escuchan en esa dirección.

Antes de v2.1.284, el proxy se conectaba a cualquier dirección en la que se resolviera un nombre de host permitido.

`/sandbox` falla con `Sandbox settings are overridden by a higher-priority configuration`

/sandbox imprime Error: Sandbox settings are overridden by a higher-priority configuration and cannot be changed locally. en lugar de abrir su panel cuando un nivel de configuración superior establece sandbox.enabled, sandbox.autoAllowBashIfSandboxed o sandbox.allowUnsandboxedCommands. El panel guarda tus elecciones en .claude/settings.local.json, y un valor guardado allí no puede sobrescribir esos niveles.

La configuración administrada y --settings tienen prioridad sobre la configuración local. Para ver cuáles de ellas cargó esta sesión, ejecuta /status y lee la línea Setting sources:

Command line arguments: si iniciaste Claude Code con --settings, comprueba si el archivo o JSON que pasaste establece una de esas claves. Si es así, cambia el valor allí, o inicia Claude Code de nuevo sin esas claves.
Enterprise managed settings: la configuración administrada de tu organización está cargada. Si establece una de esas claves, no puedes cambiar esa clave desde /sandbox ni desde ningún archivo de configuración que controles, así que consulta a tu administrador.

Limitaciones

El sandboxing reduce el riesgo pero no es un límite de aislamiento completo. Revisa las limitaciones a continuación antes de confiar en él como un control de seguridad duro.

Limitaciones de seguridad

Filtrado de red: el sandbox restringe los dominios a los que se permite que se conecten los procesos. De forma predeterminada, el proxy integrado no termina ni inspecciona TLS en el tráfico saliente, por lo que el contenido de las conexiones cifradas no se examina. El ajuste experimental network.tlsTerminate termina TLS en el proxy para sustitución de credenciales mask pero no añade filtrado de contenido. Eres responsable de asegurarte de que solo se permitan dominios confiables en tu política.

Escalada de privilegios a través de sockets Unix: la configuración allowUnixSockets puede otorgar inadvertidamente acceso a servicios del sistema que podrían llevar a omisiones del sandbox. Por ejemplo, permitir acceso a /var/run/docker.sock efectivamente otorga acceso al sistema host a través del socket de Docker. Considera cuidadosamente cualquier socket Unix que permitas a través del sandbox.
Escalada de permisos del sistema de archivos: los permisos de escritura del sistema de archivos demasiado amplios pueden permitir ataques de escalada de privilegios. Permitir escrituras en directorios que contienen ejecutables en $PATH, directorios de configuración del sistema o archivos de configuración de shell del usuario como .bashrc o .zshrc puede llevar a ejecución de código en diferentes contextos de seguridad cuando otros usuarios o procesos del sistema acceden a estos archivos.
Fortaleza del sandbox de Linux: la implementación de Linux proporciona un fuerte aislamiento del sistema de archivos y la red pero incluye un modo enableWeakerNestedSandbox que le permite funcionar dentro de entornos Docker sin espacios de nombres privilegiados. Esta opción debilita considerablemente la seguridad y solo debe usarse cuando se aplica aislamiento adicional de otra manera.
Apple Events en macOS: el sandbox de macOS bloquea Apple Events de forma predeterminada. El ajuste allowAppleEvents levanta esta restricción para que herramientas como open y osascript funcionen, pero elimina el aislamiento de ejecución de código: los comandos aislados pueden lanzar otras aplicaciones sin aislar sin solicitud del usuario, y pueden enviar comandos AppleScript a aplicaciones en ejecución, sujeto a la solicitud de consentimiento de automatización por aplicación de macOS (TCC). Solo se honra desde configuración de usuario, administrada o CLI. La configuración del proyecto no puede habilitarlo.

Alcance

El sandbox aísla los comandos de shell y sus procesos hijos. Qué se ejecuta fuera del sandbox enumera las herramientas y los procesos auxiliares que no cubre. El uso de computadora y los subagentes se relacionan con el sandbox de la siguiente manera:

Uso de computadora: cuando Claude abre aplicaciones y controla tu pantalla, se ejecuta en tu escritorio real en lugar de en un entorno aislado. Las solicitudes de permiso por aplicación controlan cada aplicación. Consulta uso de computadora en la CLI o uso de computadora en Desktop.
Subagentes: los subagentes se ejecutan en el mismo proceso que la sesión padre y usan la misma configuración de sandbox. Los comandos Bash dentro de un subagente están aislados cuando el sandboxing está habilitado en la sesión padre.
Mods: un mod es un plugin que ejecuta su propio código dentro de Claude Code, y un proceso que inicia un mod se ejecuta fuera del sandbox. Consulta Qué puede alcanzar un mod.

Ver también

Entornos sandbox: comparar el sandbox integrado con contenedores de desarrollo, contenedores y máquinas virtuales
Seguridad: características de seguridad integral y mejores prácticas
Permisos: configuración de permisos y control de acceso
Toda la configuración: cada clave de configuración
Referencia de CLI: opciones de línea de comandos

sandboxing.md +606 −307

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.3> Use this file to discover all available pages before exploring further.

4 4

~~5# Configurar la herramienta Bash aislada~~5# Configura la herramienta Bash en el sandbox

6 6

~~7> Aprenda cómo la herramienta Bash aislada de Claude Code proporciona aislamiento del sistema de archivos y la red para una ejecución de agentes más segura y autónoma.~~7> Restringe los archivos y hosts de red a los que pueden acceder los comandos de shell de Claude Code con el sandbox integrado. Actívalo, define el límite y corrige lo que deje de funcionar.

8 8

9El sandbox de Bash permite que Claude ejecute la mayoría de comandos de shell sin detenerse para pedir permiso. En lugar de aprobar cada comando, usted define qué archivos y dominios de red pueden tocar los comandos, y el sistema operativo aplica ese límite para cada comando Bash, PowerShell o Monitor y sus procesos secundarios.9El sandbox de Bash es un límite que el sistema operativo impone alrededor de los comandos de shell que Claude ejecuta en tu máquina. Tú defines a qué archivos y dominios de red pueden acceder esos comandos, y los límites se aplican a los comandos de Bash, PowerShell y Monitor, y a los procesos que estos inician. Como el sistema operativo aplica los límites mientras se ejecuta un comando, Claude Code puede [ejecutar comandos en el sandbox sin pedirte](#sandbox-modes) que apruebes cada uno.

11El sandbox cubre solo los comandos de shell. Las herramientas de archivos de Claude, los servidores MCP y los hooks [se ejecutan fuera de él](#what-runs-outside-the-sandbox).

13El sandbox funciona en macOS, Linux y WSL2. En Windows nativo, Claude Code ejecuta los comandos fuera del sandbox. Para usar el sandbox en una máquina con Windows, ejecuta Claude Code dentro de una distribución de WSL2.

10 14

11<Note>15<Note>

12 Para comparar otros enfoques de aislamiento como contenedores de desarrollo, contenedores personalizados y máquinas virtuales, consulte [Entornos sandbox](/docs/es/sandbox-environments). Para reducir solicitudes de permiso para herramientas distintas de Bash, consulte [modos de permiso](/docs/es/permission-modes).16 Esta página trata sobre el sandbox alrededor de los comandos de shell en tu propia máquina. Otras páginas abordan temas relacionados:

18 * Para saber cómo se aísla una sesión en la nube, consulta [Seguridad y aislamiento](/docs/es/claude-code-on-the-web#security-and-isolation)

19 * Para comparar otros enfoques de aislamiento, como dev containers, contenedores personalizados y máquinas virtuales, consulta [Entornos de sandbox](/docs/es/sandbox-environments)

20 * Para reducir las solicitudes de permiso de herramientas distintas de Bash, consulta [modos de permisos](/docs/es/permission-modes)

13</Note>21</Note>

14 22

23<h2 id="what-the-sandbox-restricts">

24 Qué restringe el sandbox

25</h2>

27Mientras el sandbox está activado, los comandos de shell que Claude ejecuta se inician dentro de sus límites, y lo mismo ocurre con los procesos que esos comandos inician. El sandbox está desactivado de forma predeterminada. Para activarlo, ejecuta `/sandbox` en una sesión, como se muestra en [Primeros pasos](#get-started), o establece [`sandbox.enabled`](/docs/es/settings-reference#sandbox-enabled) en `true` en un [archivo de configuración](/docs/es/settings) como `~/.claude/settings.json`.

29La tabla muestra a qué puede acceder un comando en el sandbox de forma predeterminada y los ajustes que cambian cada valor predeterminado.

31| Acceso | Predeterminado | Cámbialo con |

32| :- | :- | :- |

33| Escrituras | El directorio de trabajo, un directorio temporal por usuario y los [directorios que hayas agregado](/docs/es/permissions#additional-directories-grant-file-access-not-configuration). Las [rutas protegidas](#protected-paths) siguen con la escritura denegada | [`filesystem.allowWrite`](/docs/es/settings-reference#sandbox-filesystem-allowwrite), [`filesystem.denyWrite`](/docs/es/settings-reference#sandbox-filesystem-denywrite) |

34| Lecturas | La mayor parte de la máquina, incluidos archivos de credenciales como `~/.ssh` y `~/.aws/credentials` | [`filesystem.denyRead`](/docs/es/settings-reference#sandbox-filesystem-denyread), [`credentials`](#protect-credentials) |

35| Red | Sin ruta directa hacia el exterior. Las conexiones pasan por un proxy en tu máquina que verifica cada host contra tus dominios permitidos, que inicialmente están vacíos. Tu modo de permisos decide [qué ocurre con los demás hosts](#hosts-outside-your-allowed-domains) | [`network.allowedDomains`](/docs/es/settings-reference#sandbox-network-alloweddomains), [`network.deniedDomains`](/docs/es/settings-reference#sandbox-network-denieddomains) |

36| Variables de entorno | Heredadas de Claude Code, incluidos los secretos que haya en su entorno | [`credentials`](#protect-credentials), [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/es/env-vars) |

38Claude Code construye el sandbox sobre el paquete de código abierto [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropics/sandbox-runtime).

40<h3 id="what-runs-outside-the-sandbox">

41 Qué se ejecuta fuera del sandbox

42</h3>

44El sandbox envuelve los comandos de shell. Estas herramientas y procesos se ejecutan fuera de él:

46* **Herramientas integradas de archivos y web**: herramientas como Read, Edit, Write, WebFetch y WebSearch siguen, en cambio, las [reglas de permisos](/docs/es/permissions). Una entrada `denyRead` no detiene la herramienta Read, y `allowedDomains` no limita WebFetch

47* **Otros procesos que inicia Claude Code**: los [hooks](/docs/es/hooks) de comando, los [servidores MCP](/docs/es/mcp) locales, los [monitores de plugins](/docs/es/plugins/components#monitors), los [servidores LSP](/docs/es/tools-reference#lsp-tool-behavior) y los comandos auxiliares, como el comando de tu [línea de estado](/docs/es/statusline) y `apiKeyHelper`, se ejecutan con tu acceso completo

49Algunos comandos de shell también se ejecutan fuera del sandbox, según tu configuración:

51* **Comandos que escribes tú mismo**: un comando que introduces en el [prompt del modo shell `!`](/docs/es/interactive-mode#shell-mode-with-prefix) se ejecuta fuera del sandbox en la mayoría de las sesiones. El [modo sandbox estricto](#turn-off-the-retry-with-strict-sandbox-mode) enumera las sesiones en las que un comando que escribes se ejecuta dentro del sandbox

52* **Comandos excluidos**: los comandos que coinciden con [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands) se ejecutan fuera del sandbox

53* **Reintentos fuera del sandbox**: Claude puede [pedir ejecutar un comando fuera del sandbox](#the-unsandboxed-retry-escape-hatch), normalmente después de que falle dentro del sandbox

55Para poner las herramientas, los procesos y los comandos de esta sección detrás de un único límite, ejecuta el propio proceso de Claude Code en un [contenedor, una máquina virtual o el sandbox runtime](/docs/es/sandbox-environments).

15<h2 id="get-started">57<h2 id="get-started">

16 Primeros pasos58 Primeros pasos

17</h2>59</h2>

18 60

~~19El sandbox está integrado en Claude Code y se ejecuta en macOS, Linux y WSL2. Windows nativo no es compatible. En Windows, ejecute Claude Code dentro de una distribución WSL2.~~61El sandbox está integrado en Claude Code. Lo que instalas depende de tu plataforma:

20 62

21En macOS, no hay nada que instalar: el sandboxing utiliza el marco Seatbelt integrado. En Linux y WSL2, el sandbox se basa en dos paquetes, cubiertos en [Configurar Linux y WSL2](#set-up-linux-and-wsl2). Incluso si aún no los ha instalado, puede comenzar con `/sandbox`, porque su panel muestra si falta algo.63* **macOS**: el sandboxing usa el framework Seatbelt integrado, así que puedes ir directamente a los pasos

64* **Linux y WSL2**: el sandbox depende de `bubblewrap` y `socat`, que se explican en [Configurar Linux y WSL2](#set-up-linux-and-wsl2). Aunque todavía no los hayas instalado, puedes empezar con `/sandbox`, porque su panel muestra si falta algo

22 65

23<Steps>66<Steps>

~~24 <Step title="Ejecutar /sandbox">~~67 <Step title="Ejecuta /sandbox">

~~25 Inicie una sesión de Claude Code y ejecute el comando `/sandbox`:~~68 Inicia una sesión de Claude Code y ejecuta el comando `/sandbox`:

26 69

27 ```text theme={null}70 ```text theme={null}

28 /sandbox71 /sandbox

29 ```72 ```

30 73

~~31 Esto abre el panel de sandbox con tres pestañas, más una pestaña Dependencies en Linux cuando falta el filtro seccomp opcional:~~74 Esto abre el panel del sandbox con tres pestañas, más una pestaña Dependencies en Linux cuando falta el filtro seccomp opcional:

32 75

~~33 * **Mode**: elija cómo se aprueban los comandos aislados, cubierto en el siguiente paso~~76 * **Mode**: elige cómo se aprueban los comandos ejecutados en el sandbox, lo que se explica en el siguiente paso

34 * **Overrides**: elija si los comandos que fallan bajo el sandbox pueden volver a ejecutarse sin aislar. Esta es la configuración [`allowUnsandboxedCommands`](/docs/es/settings-reference#sandbox-allowunsandboxedcommands)77 * **Overrides**: elige si los comandos que fallan dentro del sandbox pueden recurrir a ejecutarse fuera de él. Este es el ajuste [`allowUnsandboxedCommands`](/docs/es/settings-reference#sandbox-allowunsandboxedcommands)

~~35 * **Config**: vea la configuración de sandbox resuelta~~78 * **Config**: consulta la configuración resuelta del sandbox

36 79

37 Si el panel muestra solo una pestaña Dependencies, falta un paquete requerido. Instálelo como se describe en [Configurar Linux y WSL2](#set-up-linux-and-wsl2), reinicie Claude Code y ejecute `/sandbox` nuevamente.80 Si el panel muestra solo una pestaña Dependencies, falta un paquete obligatorio. Instálalo como se describe en [Configurar Linux y WSL2](#set-up-linux-and-wsl2), reinicia Claude Code y vuelve a ejecutar `/sandbox`.

38 </Step>81 </Step>

39 82

~~40 <Step title="Elegir un modo">~~83 <Step title="Elige un modo">

41 En la pestaña Mode, seleccione auto-allow o permisos regulares. Auto-allow ejecuta comandos aislados sin solicitar, y permisos regulares mantiene las solicitudes de permiso regulares incluso cuando los comandos están aislados. Consulte [Modos de sandbox](#sandbox-modes) para ver qué comandos aún solicitan en modo auto-allow.84 En la pestaña Mode, selecciona auto-allow o permisos regulares. Auto-allow ejecuta los comandos del sandbox sin pedir confirmación, y los permisos regulares mantienen las solicitudes de permiso habituales incluso cuando los comandos se ejecutan en el sandbox. Consulta [Modos del sandbox](#sandbox-modes) para ver qué comandos siguen pidiendo confirmación en el modo auto-allow.

42 </Step>85 </Step>

43 86

~~44 <Step title="Ejecutar un comando Bash">~~87 <Step title="Ejecuta un comando de Bash">

45 Pida a Claude que ejecute un comando, como una compilación o un conjunto de pruebas. De forma predeterminada, los comandos dentro del sandbox pueden escribir en el directorio de trabajo, un [directorio temporal por usuario](/docs/es/env-vars), y cualquier [directorio que haya agregado](/docs/es/permissions#additional-directories-grant-file-access-not-configuration) con `--add-dir`, `/add-dir` o `permissions.additionalDirectories`.88 Pídele a Claude que ejecute un comando, como una compilación o un conjunto de pruebas. De forma predeterminada, los comandos dentro del sandbox pueden escribir en el directorio de trabajo, en un [directorio temporal por usuario](/docs/es/env-vars) y en cualquier [directorio que hayas agregado](/docs/es/permissions#additional-directories-grant-file-access-not-configuration) con `--add-dir`, `/add-dir` o `permissions.additionalDirectories`.

46 89

47 La primera vez que un comando necesita un nuevo dominio de red, Claude Code solicita aprobación; en [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode), Claude en su lugar nombra los hosts que un comando necesita [en el comando mismo](#per-command-allowed-domains-in-auto-mode) para que el clasificador lo revise con él.90 La primera vez que un comando necesita un nuevo dominio de red, Claude Code pide aprobación; en el [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode), Claude, en cambio, indica los hosts que necesita un comando [en el propio comando](#per-command-allowed-domains-in-auto-mode) para que el clasificador los revise junto con él.

48 91

49 Los comandos que no pueden ejecutarse aislados vuelven al flujo de permiso regular. Claude Code titula su solicitud de permiso "Bash command (unsandboxed)" en lugar de "Bash command", para que pueda saber qué comandos se ejecutaron fuera del sandbox. Para ampliar o reducir lo que permite el sandbox, consulte [Configurar sandboxing](#configure-sandboxing).92 Para ampliar o restringir lo que permite el sandbox, consulta [Configurar el sandboxing](#configure-sandboxing).

50 93

~~51 Si los comandos aislados fallan con `Operation not permitted` dentro de un contenedor, consulte la entrada Bubblewrap en [Solución de problemas](#troubleshooting).~~94 Si los comandos del sandbox fallan con `Operation not permitted` dentro de un contenedor, consulta [Bubblewrap no se inicia dentro de un contenedor](#bubblewrap-fails-to-start-inside-a-container).

52 </Step>95 </Step>

53</Steps>96</Steps>

54 97

55Cuando selecciona un modo en el panel, Claude Code lo guarda en la configuración local de su proyecto en `.claude/settings.local.json`, que se aplica al proyecto actual. Claude Code agrega ese archivo a su gitignore global cuando guarda una configuración allí. Para habilitar el sandbox en todos sus proyectos, establezca [`sandbox.enabled`](/docs/es/settings-reference#sandbox-enabled) en `true` en su configuración de usuario en `~/.claude/settings.json`. Para aplicar sandboxing para cada desarrollador en una organización, use [configuración administrada](#enforce-sandboxing-with-managed-settings).98Cuando seleccionas un modo en el panel, Claude Code lo guarda en la configuración local de tu proyecto en `.claude/settings.local.json`, que se aplica al proyecto actual. Claude Code agrega ese archivo a tu gitignore global cuando guarda un ajuste en él. Para habilitar el sandbox en todos tus proyectos, establece [`sandbox.enabled`](/docs/es/settings-reference#sandbox-enabled) en `true` en tu configuración de usuario en `~/.claude/settings.json`. Para imponer el sandboxing a todos los desarrolladores de una organización, usa la [configuración administrada](#enforce-sandboxing-with-managed-settings).

56 99

57Para cambiar el sandbox para una sesión sin escribir en un archivo de configuración, inicie Claude Code con [`--settings`](/docs/es/settings#change-a-setting-for-one-session). Por ejemplo, este comando inicia una sesión aislada en la que Claude no puede reintentar un comando bloqueado fuera del sandbox:100Para cambiar el sandbox durante una sesión sin escribir en un archivo de configuración, inicia Claude Code con [`--settings`](/docs/es/settings#change-a-setting-for-one-session). Por ejemplo, este comando inicia una sesión en el sandbox en la que Claude no puede reintentar un comando bloqueado fuera del sandbox:

58 101

59```bash theme={null}102```bash theme={null}

60claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'103claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'

61```104```

62 105

63<Warning>106<Warning>

64 De forma predeterminada, si el sandbox no puede iniciarse porque faltan dependencias o la plataforma no es compatible, Claude Code muestra una advertencia y ejecuta comandos sin sandboxing. Para hacer que esto sea un error grave en su lugar, establezca [`sandbox.failIfUnavailable`](/docs/es/settings-reference#sandbox-failifunavailable) en `true`. Esto está destinado a implementaciones administradas que requieren sandboxing como una puerta de seguridad.107 De forma predeterminada, si el sandbox no puede iniciarse porque falta una dependencia o la plataforma no es compatible, Claude Code ejecuta los comandos sin sandboxing. Para que Claude Code se cierre al iniciar en su lugar, establece [`sandbox.failIfUnavailable`](/docs/es/settings-reference#sandbox-failifunavailable) en `true`. Los despliegues administrados que exigen el sandboxing como barrera de seguridad pueden usar este ajuste.

65</Warning>108</Warning>

66 109

110<h3 id="confirm-commands-run-inside-the-sandbox">

111 Confirmar que los comandos se ejecutan dentro del sandbox

112</h3>

113

114Para comprobar que el sandbox funciona, pídele a Claude que ejecute cada línea de la tabla. Lo que escribes en el [prompt `!`](#what-runs-outside-the-sandbox) normalmente se ejecuta fuera del sandbox, así que escribir una línea tú mismo no lo pone a prueba.

115

116| Comando | Resultado dentro del sandbox |

117| :- | :- |

118| `touch ~/sandbox-probe` | Falla con `Operation not permitted` en macOS, o `Read-only file system` en Linux y WSL2 |

119| `curl --noproxy '*' https://example.com` | Falla con `Could not resolve host`, porque el comando no tiene ninguna ruta que evite el proxy del sandbox |

120

121Si Claude pide reintentar un comando fallido fuera del sandbox, rechaza el reintento. Si `touch` tiene éxito y tu directorio home no es uno de los directorios en los que el sandbox permite escribir a los comandos, elimina `~/sandbox-probe`. Luego ejecuta `/sandbox` para comprobar que el sandbox está activado y que sus dependencias están instaladas.

122

67<h3 id="set-up-linux-and-wsl2">123<h3 id="set-up-linux-and-wsl2">

68 Configurar Linux y WSL2124 Configurar Linux y WSL2

69</h3>125</h3>

70 126

~~71En Linux y WSL2, el sandbox se basa en dos paquetes:~~127En Linux y WSL2, el sandbox depende de estos paquetes:

72 128

~~73* [`bubblewrap`](https://github.com/containers/bubblewrap): la herramienta de sandboxing sin privilegios que aplica aislamiento del sistema de archivos~~129* [`bubblewrap`](https://github.com/containers/bubblewrap): la herramienta de sandboxing sin privilegios que aplica el aislamiento del sistema de archivos

~~74* [`socat`](http://www.dest-unreach.org/socat/): el relé utilizado para enrutar el tráfico de red a través del proxy del sandbox~~130* [`socat`](http://www.dest-unreach.org/socat/): el relé que se usa para enrutar el tráfico de red a través del proxy del sandbox

75 131

~~76Instálelos con el gestor de paquetes de su distribución:~~132Instálalos con el gestor de paquetes de tu distribución:

77 133

78<Tabs>134<Tabs>

79 <Tab title="Ubuntu/Debian">135 <Tab title="Ubuntu/Debian">

89 </Tab>145 </Tab>

90</Tabs>146</Tabs>

91 147

92Cuando falta una dependencia, la pestaña Dependencies en `/sandbox` enumera cuál de `ripgrep`, `bubblewrap`, `socat` y el filtro seccomp le falta a su plataforma. Si no ve la pestaña después de instalar y reiniciar Claude Code, todas las dependencias están presentes.148Cuando falta una dependencia, la pestaña Dependencies de `/sandbox` indica cuáles de `ripgrep`, `bubblewrap`, `socat` y el filtro seccomp le faltan a tu plataforma. Si no ves la pestaña después de instalarlos y reiniciar Claude Code, todas las dependencias están presentes.

93 149

94Ripgrep se incluye con el binario nativo de Claude Code. El filtro seccomp es opcional y agrega bloqueo de socket de dominio Unix. Instálelo con `npm install -g @anthropic-ai/sandbox-runtime` si falta.150Ripgrep viene incluido con el binario nativo de Claude Code. El filtro seccomp es opcional y añade el bloqueo de sockets de dominio Unix. Instálalo con `npm install -g @anthropic-ai/sandbox-runtime` si falta.

95 151

96Cuando falta una dependencia requerida, la pestaña Dependencies es la única pestaña mostrada hasta que la instale. Cuando solo falta el filtro seccomp opcional, la pestaña Dependencies aparece junto con las otras pestañas. La verificación de dependencia se ejecuta al inicio, así que reinicie Claude Code después de instalar paquetes para que `/sandbox` los detecte.152Cuando falta una dependencia obligatoria, la pestaña Dependencies es la única que se muestra hasta que la instales. Cuando solo falta el filtro seccomp opcional, la pestaña Dependencies aparece junto con las demás pestañas. La comprobación de dependencias se ejecuta al iniciar, así que reinicia Claude Code después de instalar paquetes para que `/sandbox` los detecte.

97 153

98<AccordionGroup>154<AccordionGroup>

~~99 <Accordion title="Ubuntu 24.04 y posterior: permitir que bubblewrap cree espacios de nombres de usuario">~~155 <Accordion title="Ubuntu 24.04 y posteriores: permitir que bubblewrap cree espacios de nombres de usuario">

100 En Ubuntu 24.04 y posterior, la política de AppArmor predeterminada impide que bubblewrap cree los espacios de nombres de usuario que necesita para el aislamiento.156 En Ubuntu 24.04 y posteriores, la política predeterminada de AppArmor impide que bubblewrap cree los espacios de nombres de usuario que necesita para el aislamiento.

101 157

102 Para verificar si su entorno aplica esta restricción, incluso dentro de WSL2, ejecute `sysctl kernel.apparmor_restrict_unprivileged_userns`. Si el comando devuelve `0`, omita este paso. Si imprime un error `No such file or directory`, la clave no existe y puede omitir este paso. Si devuelve `1`, agregue un perfil de AppArmor que otorgue a `bwrap` esta capacidad:158 Para comprobar si tu entorno aplica esta restricción, incluso dentro de WSL2, ejecuta `sysctl kernel.apparmor_restrict_unprivileged_userns`. Si el comando devuelve `0`, omite este paso. Si muestra un error `No such file or directory`, la clave no existe y puedes omitir este paso. Si devuelve `1`, agrega un perfil de AppArmor que le otorgue esta capacidad a `bwrap`:

103 159

104 ```bash theme={null}160 ```bash theme={null}

105 sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'161 sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'

113 EOF169 EOF

114 ```170 ```

115 171

116 El perfil se aplica solo a `bwrap` en sí, no a los comandos que se ejecutan dentro del sandbox. Recargue AppArmor para aplicarlo:172 El perfil se aplica solo a `bwrap`, no a los comandos que ejecuta dentro del sandbox. Recarga AppArmor para aplicarlo:

117 173

118 ```bash theme={null}174 ```bash theme={null}

119 sudo systemctl reload apparmor175 sudo systemctl reload apparmor

120 ```176 ```

121 </Accordion>177 </Accordion>

122 178

123 <Accordion title="Notas de WSL2">179 <Accordion title="Notas sobre WSL2">

124 Verifique su versión de WSL con `wsl -l -v` desde PowerShell. Si ve `Sandboxing requires WSL2`, su distribución está ejecutando WSL1. Actualícela a WSL2 o ejecute Claude Code sin sandboxing.180 Comprueba tu versión de WSL con `wsl -l -v` desde PowerShell. Si ves `Sandboxing requires WSL2`, tu distribución está ejecutando WSL1. Actualízala a WSL2 o ejecuta Claude Code sin sandboxing.

125 181

126 En WSL2, WSL entrega un lanzamiento de un binario de Windows como `cmd.exe`, `powershell.exe` o cualquier cosa bajo `/mnt/c/` al host de Windows a través de un socket Unix, por lo que si un comando aislado puede lanzar uno sigue la configuración [Unix-socket](/docs/es/settings-reference#sandbox-network-allowunixsockets) del sandbox: el filtro seccomp opcional tiene que estar instalado para bloquear el socket en primer lugar. Para permitir estos lanzamientos, establezca `allowAllUnixSockets`; para mantenerlos fuera del sandbox completamente, agregue el comando a [`excludedCommands`](/docs/es/settings-reference#sandbox-excludedcommands).182 En WSL2, WSL transfiere el lanzamiento de un binario de Windows, como `cmd.exe`, `powershell.exe` o cualquier cosa bajo `/mnt/c/`, al host de Windows a través de un socket Unix, por lo que que un comando del sandbox pueda lanzar uno depende de los [ajustes de sockets Unix](/docs/es/settings-reference#sandbox-network-allowunixsockets) del sandbox: el filtro seccomp opcional tiene que estar instalado para que el socket se bloquee en primer lugar. Para permitir estos lanzamientos, establece `allowAllUnixSockets`, que abre todos los sockets Unix a los comandos del sandbox.

127 </Accordion>183 </Accordion>

128</AccordionGroup>184</AccordionGroup>

129 185

130<h3 id="sandbox-modes">186<h3 id="sandbox-modes">

131 Modos de sandbox187 Modos del sandbox

132</h3>188</h3>

133 189

134Claude Code ofrece dos modos de sandbox. En ambos, el sandbox aplica las mismas restricciones de sistema de archivos y red; la diferencia es solo si los comandos aislados se aprueban automáticamente o requieren permiso explícito.190Claude Code ofrece dos modos del sandbox. En ambos, el sandbox aplica las mismas restricciones de sistema de archivos y de red; la diferencia está solo en si los comandos del sandbox se aprueban automáticamente o requieren permiso explícito.

135 191

136<h4 id="auto-allow-mode">192<h4 id="auto-allow-mode">

137 Modo auto-allow193 Modo auto-allow

138</h4>194</h4>

139 195

140Cuando un comando puede ser aislado, Claude Code lo ejecuta dentro del sandbox y lo aprueba automáticamente, sin pedirle permiso. Los comandos que no pueden ser aislados, como aquellos que necesitan acceso a la red a hosts no permitidos, vuelven al flujo de permiso regular, donde Claude Code verifica sus [reglas de permiso](/docs/es/permissions) y bloquea cualquier comando que esas reglas no permitan, con una solicitud en modo Manual.196Claude Code aprueba un comando automáticamente, sin pedir confirmación, cuando el comando se ejecuta dentro del sandbox. Un comando pasa por el [flujo de permisos](/docs/es/permissions) habitual cuando se ejecuta fuera del sandbox porque coincide con [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands) o porque Claude [lo reintenta fuera del sandbox](#the-unsandboxed-retry-escape-hatch).

197

198Un comando del sandbox que se conecta a un host que no has permitido permanece en el sandbox. [Hosts fuera de tus dominios permitidos](#hosts-outside-your-allowed-domains) explica quién decide si la conexión se realiza.

141 199

142Incluso en modo auto-allow, lo siguiente sigue siendo válido:200Incluso en el modo auto-allow, sigue aplicándose lo siguiente:

143 201

144* Las [reglas de denegación](/docs/es/permissions) explícitas siempre se respetan202* Las [reglas de denegación](/docs/es/permissions) explícitas siempre se respetan

145* Los comandos `rm` o `rmdir` que apunten a una [ruta crítica](/docs/es/permission-modes#critical-paths) aún pasan por el flujo de permiso regular203* Los comandos `rm` o `rmdir` que apuntan a una [ruta crítica](/docs/es/permission-modes#critical-paths) siguen pasando por el flujo de permisos habitual

146* Las [reglas de solicitud](/docs/es/permissions) con alcance de contenido como `Bash(git push *)` aún fuerzan una solicitud incluso para comandos aislados204* Las [reglas de consulta](/docs/es/permissions) limitadas por contenido, como `Bash(git push *)`, siguen forzando una solicitud de permiso incluso para los comandos del sandbox

147* Una regla de solicitud `Bash` simple, o la forma equivalente `Bash(*)`, se omite para comandos que se ejecutan aislados; aún se aplica a comandos que vuelven al flujo de permiso regular. En [modo de plan](/docs/es/permission-modes#analyze-before-you-edit-with-plan-mode), la regla no se omite: solicita comandos aislados también, incluyendo los de solo lectura. Antes de v2.1.212, la omisión se aplicaba en modo de plan también205* Una regla de consulta `Bash` sin más, o la forma equivalente `Bash(*)`, se omite para los comandos que se ejecutan en el sandbox; sigue aplicándose a los comandos que recurren al flujo de permisos habitual. En el [modo plan](/docs/es/permission-modes#analyze-before-you-edit-with-plan-mode), la regla no se omite: también pide confirmación para los comandos del sandbox, incluidos los de solo lectura

148 206

149<Info>207<Info>

150 El modo auto-allow funciona independientemente de su configuración de modo de permiso, con tres excepciones: [modo de plan](/docs/es/permission-modes#analyze-before-you-edit-with-plan-mode), un comando en modo automático que lleva [dominios permitidos por comando](#per-command-allowed-domains-in-auto-mode), y [revisión del clasificador del lado del servidor](/docs/es/permission-modes#how-the-classifier-evaluates-actions) de comandos aislados en modo automático. Incluso si no está en modo "aceptar ediciones", los comandos Bash aislados se ejecutan automáticamente cuando auto-allow está habilitado. Esto significa que los comandos Bash que modifican archivos dentro de los límites del sandbox se ejecutan sin solicitar, incluso en modo Manual, donde las herramientas de edición de archivos solicitarían.208 El modo auto-allow funciona de forma independiente de tu ajuste de modo de permisos, con tres excepciones: el [modo plan](/docs/es/permission-modes#analyze-before-you-edit-with-plan-mode), un comando del modo automático que lleva [dominios permitidos por comando](#per-command-allowed-domains-in-auto-mode) y la [revisión del clasificador del lado del servidor](/docs/es/permission-modes#how-the-classifier-evaluates-actions) de los comandos del sandbox en el modo automático. Aunque no estés en el modo "accept edits", los comandos de Bash del sandbox se ejecutan automáticamente cuando auto-allow está habilitado. Esto significa que los comandos de Bash que modifican archivos dentro de los límites del sandbox se ejecutan sin pedir confirmación, incluso en el modo Manual, donde las herramientas de edición de archivos sí la pedirían.

151 209

152 En modo de plan, auto-allow no amplía las aprobaciones; consulte [modo de plan](/docs/es/permission-modes#analyze-before-you-edit-with-plan-mode) para ver cómo Claude Code bloquea comandos mientras planifica. Antes de v2.1.212, auto-allow ejecutaba comandos aislados sin solicitud en modo de plan también.210 En el modo plan, auto-allow no amplía las aprobaciones; consulta el [modo plan](/docs/es/permission-modes#analyze-before-you-edit-with-plan-mode) para ver cómo Claude Code controla los comandos mientras planificas.

153</Info>211</Info>

154 212

155<h4 id="regular-permissions-mode">213<h4 id="regular-permissions-mode">

156 Modo de permisos regulares214 Modo de permisos regulares

157</h4>215</h4>

158 216

159Todos los comandos Bash pasan por el flujo de permiso regular, incluso cuando están aislados. Esto proporciona más control pero requiere más aprobaciones.217Todos los comandos de Bash pasan por el flujo de permisos habitual, incluso cuando se ejecutan en el sandbox. Esto proporciona más control, pero requiere más aprobaciones.

160 218

161<h4 id="the-unsandboxed-retry-escape-hatch">219<h4 id="the-unsandboxed-retry-escape-hatch">

162 La salida de emergencia de reintento sin sandbox220 La vía de escape del reintento fuera del sandbox

221</h4>

222

223El reintento fuera del 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 indica el host denegado en el resultado del comando, así Claude ve qué se bloqueó. Claude analiza el fallo y puede reintentar el comando con el parámetro `dangerouslyDisableSandbox`.

224

225El comando reintentado se ejecuta fuera del sandbox. En una sesión interactiva de la terminal, quién lo aprueba depende de tu modo de permisos:

226

227* **Modo `bypassPermissions`**: el reintento se ejecuta sin pedir confirmación

228* **Modo Manual y modo `acceptEdits`**: recibes una solicitud titulada "Bash command (unsandboxed)"

229* **[Modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode)**: un modelo clasificador independiente evalúa el comando subyacente

230* **Modo `dontAsk`**: Claude Code deniega el reintento

231* **Modo plan**: consulta [cómo Claude Code controla los comandos mientras planificas](/docs/es/permission-modes#analyze-before-you-edit-with-plan-mode)

232

233Estas reglas y ajustes cambian quién aprueba el reintento:

234

235* **Una regla de permiso que coincida**: si una regla de permiso como `Bash(curl *)` coincide con el comando, también aprueba el reintento, por lo que el comando se ejecuta fuera del sandbox sin pedir confirmación

236* **Una regla de consulta para el parámetro**: agrega una [regla de consulta](/docs/es/permissions#match-by-input-parameter) para `Bash(dangerouslyDisableSandbox:true)` para que se te pida confirmación en los reintentos de Bash. También recibes la solicitud en el modo automático y en el modo `bypassPermissions`, y la regla tiene precedencia sobre una regla de permiso que coincida

237* **[`permissions.blockReadsOutsideWorkingDirectories`](/docs/es/settings-reference#permissions-blockreadsoutsideworkingdirectories)**: [Acciones que ningún modo aprueba automáticamente](/docs/es/permission-modes#actions-no-mode-auto-approves) explica los reintentos que piden confirmación mientras está activado

238

239<h4 id="turn-off-the-retry-with-strict-sandbox-mode">

240 Desactivar el reintento con el modo estricto del sandbox

163</h4>241</h4>

164 242

165Algunos comandos no pueden ejecutarse dentro del sandbox en absoluto, como herramientas que son incompatibles con él o que necesitan un host que no ha permitido. Claude Code reporta violaciones de sandbox en el resultado del comando bloqueado, nombrando la ruta u host que el sandbox denegó, para que Claude vea qué bloqueó el sandbox. En lugar de fallar la tarea o requerirle que apague el sandboxing, Claude Code incluye una salida de emergencia: Claude analiza la violación y puede reintentar el comando con el parámetro `dangerouslyDisableSandbox`.243Puedes desactivar el reintento fuera del sandbox estableciendo `"allowUnsandboxedCommands": false` en tu [configuración del sandbox](/docs/es/settings-reference#sandbox-settings). Con el reintento desactivado, Claude Code ignora el parámetro `dangerouslyDisableSandbox`. Mientras el sandbox está en ejecución, los comandos que ejecuta Claude se ejecutan entonces en el sandbox, a menos que coincidan con una entrada de `excludedCommands`. Para evitar que Claude Code ejecute comandos fuera del sandbox cuando este no puede iniciarse, establece también [`failIfUnavailable`](/docs/es/settings-reference#sandbox-failifunavailable). La pestaña **Overrides** de `/sandbox` muestra este ajuste como **Strict sandbox mode**.

166 244

167El comando reintentado se ejecuta fuera del sandbox, por lo que pasa por el flujo de permiso regular. En modo Manual obtiene una solicitud de confirmación. En [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode), el clasificador evalúa el comando subyacente. Mientras [`permissions.blockReadsOutsideWorkingDirectories`](/docs/es/settings-reference#permissions-blockreadsoutsideworkingdirectories) esté activado, un reintento que necesita aprobación para ejecutarse fuera del sandbox le solicita en su lugar. Para que se le solicite en cada reintento sin sandbox incluso en modo automático, agregue una [regla de solicitud](/docs/es/permissions#match-by-input-parameter) para `Bash(dangerouslyDisableSandbox:true)`.245Un `false` en tu configuración de usuario, en `--settings` o en la configuración administrada se mantiene incluso cuando la configuración de un proyecto establece `true`. Un `false` en tu configuración de usuario no convierte el sandbox en obligatorio por parte del administrador, por lo que los demás ajustes del sandbox de un proyecto siguen aplicándose. Antes de la v2.1.285, el `true` de un proyecto sobrescribía un `false` de tu configuración de usuario.

168 246

169Puede deshabilitar esta salida de emergencia estableciendo `"allowUnsandboxedCommands": false` en su [configuración de sandbox](/docs/es/settings-reference#sandbox-settings). Con la salida de emergencia deshabilitada, Claude Code ignora el parámetro `dangerouslyDisableSandbox`, y cada comando que Claude ejecuta debe ejecutarse aislado a menos que lo haya listado en `excludedCommands`. La pestaña **Overrides** de `/sandbox` muestra esta configuración como **Strict sandbox mode**.247Si tú o tu administrador desactivan el reintento en la configuración administrada o con el flag `--settings`, el sandbox pasa a ser obligatorio por parte del administrador. Claude Code entonces ignora los ajustes de los archivos de un repositorio que relajan el sandbox, incluidas las entradas de `excludedCommands`. [Configuración del repositorio con un sandbox obligatorio por parte del administrador](#repository-settings-under-an-admin-required-sandbox) los enumera.

170 248

171El modo de sandbox estricto se aplica a los comandos que Claude ejecuta. Los comandos que usted escribe en el símbolo del sistema de modo shell [`!`](/docs/es/interactive-mode#shell-mode-with-prefix) se ejecutan fuera del sandbox a menos que la sesión sea una de estas:249El modo estricto del sandbox se aplica a los comandos que ejecuta Claude. Los comandos que escribes tú mismo en el [prompt `!` del modo shell](/docs/es/interactive-mode#shell-mode-with-prefix) se ejecutan fuera del sandbox, a menos que la sesión sea una de estas:

172 250

173* **Una [sesión de fondo](/docs/es/agent-view)**: el modo de sandbox estricto cubre comandos de modo shell también251* **Una [sesión en segundo plano](/docs/es/agent-view)**: el modo estricto del sandbox también cubre los comandos del modo shell

174* **Una sesión de Linux con [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/es/env-vars#variables) establecido**: cada comando se ejecuta aislado, comandos de modo shell incluidos252* **Una sesión de Linux con [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/es/env-vars#variables) establecida**: todos los comandos se ejecutan en el sandbox, incluidos los del modo shell

175 253

176Antes de v2.1.260, el modo de sandbox estricto aislaba comandos de modo shell en cada sesión.254Antes de la v2.1.260, el modo estricto del sandbox ejecutaba en el sandbox los comandos del modo shell en todas las sesiones.

177 255

178<h4 id="temporary-directories">256<h4 id="temporary-directories">

179 Directorios temporales257 Directorios temporales

180</h4>258</h4>

181 259

182El directorio temporal por usuario es escribible dentro del sandbox de forma predeterminada, junto con el directorio de trabajo. A menos que [deshabilite el aislamiento del sistema de archivos](#disable-filesystem-isolation), Claude Code establece `$TMPDIR` en este directorio para comandos aislados, por lo que las herramientas que escriben archivos temporales funcionan sin configuración adicional.260Un directorio temporal por usuario es escribible dentro del sandbox de forma predeterminada, junto con el directorio de trabajo. A menos que [desactives el aislamiento del sistema de archivos](#disable-filesystem-isolation), Claude Code establece `$TMPDIR` en este directorio para los comandos del sandbox, de modo que las herramientas que escriben archivos temporales funcionan sin configuración adicional.

183 261

184Los comandos sin aislar heredan su `$TMPDIR` de shell cuando está establecido, por lo que mientras el aislamiento del sistema de archivos esté activado, los comandos aislados y sin aislar resuelven `$TMPDIR` a directorios diferentes. Si su shell deja `$TMPDIR` sin establecer o vacío, un comando sin aislar que hace referencia a `$TMPDIR` recibe su anulación [`CLAUDE_CODE_TMPDIR`](/docs/es/env-vars), o el directorio temporal del sistema operativo cuando no ha establecido uno o la anulación es una ruta larga, por lo que la variable no se expande a una cadena vacía. Para pasar archivos temporales entre los dos, escríbalos en el directorio de trabajo en su lugar.262Los comandos fuera del sandbox heredan el `$TMPDIR` de tu shell cuando está establecido, así que, mientras el aislamiento del sistema de archivos está activado, los comandos dentro y fuera del sandbox resuelven `$TMPDIR` en directorios distintos. Si tu shell deja `$TMPDIR` sin establecer o vacío, un comando fuera del sandbox que hace referencia a `$TMPDIR` recibe tu sobrescritura de [`CLAUDE_CODE_TMPDIR`](/docs/es/env-vars), o el directorio temporal del sistema operativo cuando no has establecido ninguna o la sobrescritura es una ruta larga, para que la variable no se expanda a una cadena vacía. Para pasar archivos temporales entre ambos, escríbelos en el directorio de trabajo.

185 263

186<h2 id="configure-sandboxing">264<h2 id="configure-sandboxing">

187 Configurar sandboxing265 Configurar el sandboxing

188</h2>266</h2>

189 267

190Personalice el comportamiento del sandbox a través de su archivo `settings.json`. Consulte [Configuración](/docs/es/settings-reference#sandbox-settings) para obtener la referencia de configuración completa.268Personaliza el comportamiento del sandbox a través de tu archivo `settings.json`. Consulta [Configuración](/docs/es/settings-reference#sandbox-settings) para ver la referencia completa de configuración.

191 269

192De forma predeterminada, los comandos aislados pueden escribir en el directorio de trabajo actual, el directorio temporal de la sesión y cualquier [directorio que haya agregado](/docs/es/permissions#additional-directories-grant-file-access-not-configuration) con `--add-dir`, `/add-dir` o `permissions.additionalDirectories`. Si comandos de subproceso como `kubectl`, `terraform` o `npm` necesitan escribir fuera de esos directorios, use `sandbox.filesystem.allowWrite` para otorgar acceso a rutas específicas:270De forma predeterminada, los comandos aislados en el sandbox pueden escribir en el directorio de trabajo actual, en el directorio temporal por usuario y en cualquier [directorio que hayas agregado](/docs/es/permissions#additional-directories-grant-file-access-not-configuration) con `--add-dir`, `/add-dir` o `permissions.additionalDirectories`. Si comandos de subprocesos como `kubectl`, `terraform` o `npm` necesitan escribir fuera de esos directorios, usa `sandbox.filesystem.allowWrite` para conceder acceso a rutas específicas:

193 271

194```json theme={null}272```json theme={null}

195{273{

202}280}

203```281```

204 282

205Estas rutas se aplican a nivel del sistema operativo, por lo que todos los comandos que se ejecutan dentro del sandbox, incluidos sus procesos secundarios, las respetan. Este es el enfoque recomendado cuando una herramienta necesita acceso de escritura a una ubicación específica, en lugar de excluir la herramienta del sandbox por completo con `excludedCommands`.283Estas rutas se aplican a nivel del sistema operativo, por lo que todos los comandos que se ejecutan dentro del sandbox, incluidos sus procesos hijos, las respetan. Este es el enfoque recomendado cuando una herramienta necesita acceso de escritura a una ubicación específica, en lugar de excluir la herramienta del sandbox por completo con `excludedCommands`.

206 284

207Cuando define el mismo array del sistema de archivos en múltiples [ámbitos de configuración](/docs/es/settings#settings-precedence), Claude Code los fusiona, combinando rutas de cada ámbito en lugar de reemplazar el array de un ámbito con otro.285Cuando defines el mismo arreglo de sistema de archivos en varios [alcances de configuración](/docs/es/settings#settings-precedence), Claude Code los combina, uniendo las rutas de todos los alcances en lugar de reemplazar el arreglo de un alcance con el de otro.

208 286

209Si excluye una fuente con [`--setting-sources`](/docs/es/cli-reference) en la CLI o [`settingSources`](/docs/es/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources) en el Agent SDK, Claude Code ignora sus entradas `sandbox.filesystem`, sus reglas de permiso `Edit` y sus reglas de denegación `Read` al construir la configuración del sandbox. Requiere Claude Code v2.1.246 o posterior.287Si excluyes una fuente con [`--setting-sources`](/docs/es/cli-reference) en la CLI o con [`settingSources`](/docs/es/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources) en el Agent SDK, Claude Code ignora sus entradas de `sandbox.filesystem`, sus reglas de permisos de `Edit` y sus reglas de denegación de `Read` al construir la configuración del sandbox. Requiere Claude Code v2.1.246 o posterior.

210 288

211Cuando edita estas listas del sistema de archivos durante una sesión, Claude Code [aplica el cambio a la sesión en ejecución](/docs/es/settings#when-edits-take-effect), por lo que el siguiente comando aislado se ejecuta bajo las nuevas rutas.289Cuando editas estas listas del sistema de archivos durante una sesión, Claude Code [aplica el cambio a la sesión en ejecución](/docs/es/settings#when-edits-take-effect), por lo que el siguiente comando aislado en el sandbox se ejecuta con las nuevas rutas.

212 290

213Los prefijos de ruta controlan cómo se resuelven las rutas:291Las rutas del sistema de archivos del sandbox usan las convenciones estándar: `/tmp/build` es absoluta y `~/.kube` es relativa a tu directorio home. Esto difiere de las [reglas de permisos de Read y Edit](/docs/es/permissions#read-and-edit), que usan `//path` para rutas absolutas y `/path` para rutas relativas al proyecto. Para rutas relativas, barras finales y comodines, consulta [Prefijos de ruta del sandbox](/docs/es/settings-reference#sandbox-path-prefixes).

214 292

215| Prefijo | Significado | Ejemplo |293También puedes denegar el acceso de escritura o lectura con `sandbox.filesystem.denyWrite` y `sandbox.filesystem.denyRead`, y volver a permitir rutas específicas dentro de una región denegada con `sandbox.filesystem.allowRead`. Cuando las reglas de lectura se superponen, se aplica la regla con la ruta más específica:

216| :- | :- | :- |

217| `/` | Ruta absoluta desde la raíz del sistema de archivos | `/tmp/build` se mantiene como `/tmp/build` |

218| `~/` | Relativo al directorio de inicio | `~/.kube` se convierte en `$HOME/.kube` |

219| `./` o sin prefijo | Relativo a la raíz del proyecto para configuración de proyecto, o a `~/.claude` para configuración de usuario | `./output` en `.claude/settings.json` se resuelve a `<project-root>/output` |

~~220~~

221Esta sintaxis difiere de las [reglas de permiso Read y Edit](/docs/es/permissions#read-and-edit), que usan `//path` para absoluto y `/path` para relativo al proyecto. Las rutas del sistema de archivos del sandbox usan convenciones estándar: `/tmp/build` es absoluto. Para saber cómo Claude Code trata una barra diagonal final o un comodín en estas rutas, consulte [Prefijos de ruta del sandbox](/docs/es/settings-reference#sandbox-path-prefixes).

~~222~~

223También puede denegar acceso de escritura o lectura usando `sandbox.filesystem.denyWrite` y `sandbox.filesystem.denyRead`, y permitir nuevamente rutas específicas dentro de una región denegada usando `sandbox.filesystem.allowRead`. Cuando las reglas de lectura se superponen, la ruta más específica gana:

224 294

225| Reglas de ejemplo | Resultado |295| Reglas de ejemplo | Resultado |

226| :- | :- |296| :- | :- |

227| `"denyRead": ["~/"]` con `"allowRead": ["~/projects"]` | `~/projects` es legible y el resto del directorio de inicio permanece bloqueado. El permiso más estrecho reabre esa parte de la región denegada |297| `"denyRead": ["~/"]` con `"allowRead": ["~/projects"]` | `~/projects` se puede leer y el resto del directorio home sigue bloqueado. El permiso más específico vuelve a abrir esa parte de la región denegada |

228| `"allowRead": ["~/"]` con `"denyRead": ["~/.env"]` | `~/.env` permanece bloqueado y el resto del directorio de inicio es legible. La denegación se mantiene dentro de un permiso más amplio, por lo que un permiso amplio no puede reexponer silenciosamente un secreto |298| `"allowRead": ["~/"]` con `"denyRead": ["~/.env"]` | `~/.env` sigue bloqueado y el resto del directorio home se puede leer. La denegación se mantiene dentro de un permiso más amplio, de modo que un permiso general no puede volver a exponer un secreto sin que lo notes |

229| `"allowRead": ["~/"]` con `"denyRead": ["~/**/.env"]` | Cada `.env` bajo el directorio de inicio permanece bloqueado y el resto es legible. Un [comodín de denegación](/docs/es/settings-reference#sandbox-path-prefixes) se mantiene dentro de un permiso más amplio de la misma manera que una ruta exacta |299| `"allowRead": ["~/"]` con `"denyRead": ["~/**/.env"]` | Todos los `.env` dentro del directorio home siguen bloqueados y el resto se puede leer. Una [denegación con comodín](/docs/es/settings-reference#sandbox-path-prefixes) se mantiene dentro de un permiso más amplio de la misma forma que una ruta exacta |

230 300

231El ejemplo a continuación bloquea la lectura de todo el directorio de inicio mientras aún permite lecturas del proyecto actual. Colóquelo en el `.claude/settings.json` de su proyecto, porque la ruta relativa `.` se resuelve a la raíz del proyecto solo cuando la configuración se encuentra en la configuración del proyecto:301El siguiente ejemplo bloquea la lectura de todo el directorio home y a la vez permite las lecturas del proyecto actual. Colócalo en el `.claude/settings.json` de tu proyecto, porque la ruta relativa `.` se resuelve como la raíz del proyecto solo cuando la configuración está en la configuración del proyecto:

232 302

233```json theme={null}303```json theme={null}

234{304{

242}312}

243```313```

244 314

245Si colocara la misma configuración en `~/.claude/settings.json`, `.` se resolvería a `~/.claude` en su lugar, y los archivos del proyecto permanecerían bloqueados por la regla `denyRead`.315Si colocaras la misma configuración en `~/.claude/settings.json`, `.` se resolvería como `~/.claude`, y los archivos del proyecto seguirían bloqueados por la regla `denyRead`.

316

317Para denegar a los comandos aislados en el sandbox el acceso de lectura a los directorios home y a los volúmenes montados, manteniendo legibles los directorios de trabajo, configura [`permissions.blockReadsOutsideWorkingDirectories`](/docs/es/settings-reference#permissions-blockreadsoutsideworkingdirectories) en lugar de escribir reglas de rutas.

318

319<h3 id="run-commands-outside-the-sandbox-with-excludedcommands">

320 Ejecutar comandos fuera del sandbox con `excludedCommands`

321</h3>

322

323Agrega un patrón de comando a [`sandbox.excludedCommands`](/docs/es/settings-reference#sandbox-excludedcommands) para ejecutar los comandos que coincidan fuera del sandbox, lo que significa sin restricciones del sistema de archivos y sin proxy de red. Úsalo para una herramienta que no puede funcionar dentro del sandbox y a la que le confías todo tu acceso. Una herramienta que necesita un directorio más o un host más puede funcionar con `allowWrite` o `allowedDomains`, que mantienen el comando dentro del sandbox.

324

325Este ejemplo saca del sandbox los comandos `docker compose`. Guárdalo en `~/.claude/settings.json` para aplicarlo a todos tus proyectos:

326

327```json theme={null}

328{

329 "sandbox": {

330 "enabled": true,

331 "excludedCommands": ["docker compose *"]

332 }

333}

334```

335

336Claude Code compara tus entradas con cada llamada a Bash y Monitor. Una llamada es la línea de comandos completa que envía Claude, que puede encadenar varios comandos. Las siguientes reglas deciden si una llamada sale del sandbox:

337

338* **Termina el patrón con ` *`**: las entradas usan la misma sintaxis que una [regla de permisos](/docs/es/permissions#permission-rule-syntax) `Bash(...)`, donde un patrón sin comodín es una coincidencia exacta. `docker` coincide solo con `docker` sin argumentos. `docker *` coincide con `docker` con o sin argumentos

339* **Todos los comandos de la llamada deben coincidir**: `npm ci && docker compose build` sigue dentro del sandbox a menos que otra entrada cubra `npm ci`

340* **Claude Code compara el texto de la llamada**: un script o un objetivo de `make` que llama a `docker` internamente no coincide, y tampoco `/usr/local/bin/docker`

341* **Algunas llamadas permanecen en el sandbox**: una redirección a un archivo, un `cd` o una sustitución de comandos como `$(...)` mantiene toda la llamada dentro del sandbox. La [entrada de referencia](/docs/es/settings-reference#sandbox-excludedcommands) enumera más llamadas que permanecen en el sandbox

342* **Dónde guardas la entrada puede importar**: mientras el sandbox sea [obligatorio por el administrador](#repository-settings-under-an-admin-required-sandbox), Claude Code ignora las entradas de `.claude/settings.json` y `.claude/settings.local.json`

343

344Un comando excluido pasa por el flujo de permisos habitual:

246 345

247Para denegar a los comandos aislados acceso de lectura a directorios de inicio y volúmenes montados mientras se mantienen los directorios de trabajo legibles, establezca [`permissions.blockReadsOutsideWorkingDirectories`](/docs/es/settings-reference#permissions-blockreadsoutsideworkingdirectories) en su lugar de escribir reglas de ruta.346* Los [comandos de solo lectura](/docs/es/permissions#read-only-commands) y los comandos que cubren tus reglas de permiso se ejecutan sin pedir confirmación

347* En modo automático, el clasificador revisa los demás comandos excluidos

348* En modo `bypassPermissions`, un comando excluido se ejecuta sin pedir confirmación a menos que coincida con una regla de consulta

349

350Para confirmar que una entrada coincide, cambia al modo Manual y pídele a Claude que ejecute un comando coincidente que cambie algo, como `docker compose up -d`. La solicitud de permiso se titula "Bash command (unsandboxed)".

351

352<Warning>

353 Un comando excluido se ejecuta con todo tu acceso. Una entrada amplia como `docker *` cubre todo lo que esa herramienta puede hacer. Si escribes un patrón que cubre un intérprete, un script dentro de tu directorio de trabajo o una herramienta que actúa sobre un archivo de ese directorio, como hace `docker compose` con su archivo compose, Claude puede escribir ese archivo y luego ejecutarlo fuera del sandbox. Un patrón más específico deja menos cosas que Claude pueda ejecutar fuera del sandbox.

354</Warning>

248 355

249<h3 id="disable-filesystem-isolation">356<h3 id="disable-filesystem-isolation">

250 Deshabilitar aislamiento del sistema de archivos357 Desactivar el aislamiento del sistema de archivos

251</h3>358</h3>

252 359

253Establezca `sandbox.filesystem.disabled` en `true` para omitir el aislamiento del sistema de archivos mientras se mantiene el aislamiento de red. El ejemplo a continuación desactiva el aislamiento del sistema de archivos mientras se mantiene una lista de permitidos de dominios de red:360Establece `sandbox.filesystem.disabled` en `true` para omitir el aislamiento del sistema de archivos y mantener el aislamiento de red. El siguiente ejemplo desactiva el aislamiento del sistema de archivos y mantiene una lista de dominios de red permitidos:

254 361

255```json theme={null}362```json theme={null}

256{363{

266}373}

267```374```

268 375

269El sandbox tiene dos capas independientes: el [aislamiento del sistema de archivos](#filesystem-isolation) controla qué rutas pueden leer y escribir los comandos aislados, y el [aislamiento de red](#network-isolation) controla qué dominios pueden alcanzar. Con la capa del sistema de archivos desactivada, los comandos aislados obtienen acceso de lectura y escritura sin restricciones al sistema de archivos del host, mientras que su salida de red permanece confinada a sus dominios permitidos. Desactive la capa cuando aisle para controlar dónde se conectan los comandos en lugar de lo que escriben.376El sandbox tiene dos capas independientes: el [aislamiento del sistema de archivos](#filesystem-isolation) controla qué rutas pueden leer y escribir los comandos aislados en el sandbox, y el [aislamiento de red](#network-isolation) controla a qué dominios pueden acceder. Con la capa del sistema de archivos desactivada, los comandos aislados en el sandbox obtienen acceso de lectura y escritura sin restricciones al sistema de archivos del host, mientras que su tráfico de red saliente sigue limitado a tus dominios permitidos. Desactiva esta capa cuando uses el sandbox para controlar a dónde se conectan los comandos y no lo que escriben.

270 377

271La configuración está desactivada de forma predeterminada y se aplica en las plataformas donde se ejecuta el sandbox: macOS, Linux y WSL2. Requiere Claude Code v2.1.216 o posterior.378`sandbox.filesystem.disabled` tiene `false` como valor predeterminado. Requiere Claude Code v2.1.216 o posterior.

272 379

273<Warning>380<Warning>

274 Con el aislamiento del sistema de archivos desactivado y los comandos permitidos automáticamente, un comando aislado puede escribir archivos que comandos posteriores ejecuten o lean, como archivos de inicio de shell, ejecutables en `$PATH` o `~/.claude/settings.json`, y usarlos para ampliar su propio acceso en la siguiente ejecución. Establezca `filesystem.disabled` en `true` solo para cargas de trabajo en las que confía que no escalen su propio acceso. Bloquear dominios de red con [`allowManagedDomainsOnly`](#keep-developers-from-widening-the-policy) reduce el riesgo pero no lo elimina, ya que ese bloqueo se aplica solo a los comandos que se ejecutan dentro del sandbox.381 Con el aislamiento del sistema de archivos desactivado y los comandos permitidos automáticamente, un comando aislado en el sandbox puede escribir archivos que comandos posteriores ejecutan o leen, como archivos de inicio del shell, ejecutables en `$PATH` o `~/.claude/settings.json`, y usarlos para ampliar su propio acceso en la siguiente ejecución. Establece `filesystem.disabled` en `true` solo para cargas de trabajo en las que confíes que no ampliarán su propio acceso. Bloquear los dominios de red con [`allowManagedDomainsOnly`](#keep-developers-from-widening-the-policy) reduce el riesgo, pero no lo elimina, ya que ese bloqueo se aplica solo a los comandos que se ejecutan dentro del sandbox.

275</Warning>382</Warning>

276 383

277<h4 id="which-settings-can-disable-it">384<h4 id="which-settings-can-disable-it">

278 Qué configuraciones pueden deshabilitarlo385 Qué configuraciones pueden desactivarlo

279</h4>386</h4>

280 387

281Debido a que desactivar el aislamiento del sistema de archivos amplía lo que pueden hacer los comandos aislados, Claude Code honra `filesystem.disabled` solo desde estas fuentes de configuración:388Como desactivar el aislamiento del sistema de archivos amplía lo que pueden hacer los comandos aislados en el sandbox, Claude Code respeta `filesystem.disabled` solo desde estas fuentes de configuración:

282 389

283* La configuración de usuario, la configuración administrada y la bandera CLI `--settings` pueden establecerla. La configuración del proyecto en `.claude/settings.json` y `.claude/settings.local.json` no puede, por lo que un proyecto extraído no puede desactivar el aislamiento del sistema de archivos.390* La configuración de usuario, la configuración administrada y el flag de CLI `--settings` pueden establecerlo. La configuración del proyecto en `.claude/settings.json` y `.claude/settings.local.json` no puede, de modo que un proyecto descargado no puede desactivar el aislamiento del sistema de archivos.

284* Cuando la configuración administrada configura `sandbox.filesystem` en absoluto, o enumera cualquier entrada `sandbox.credentials.files` con `"mode": "deny"`, solo la configuración administrada puede establecer la clave. Esto mantiene las restricciones del sistema de archivos implementadas por el administrador en vigor; para relajar tal implementación, establezca `"disabled": true` en la configuración administrada.391* Cuando la configuración administrada configura `sandbox.filesystem` de cualquier forma, o incluye alguna entrada de `sandbox.credentials.files` con `"mode": "deny"`, solo la configuración administrada puede establecer la clave. Esto mantiene vigentes las restricciones del sistema de archivos desplegadas por el administrador; para flexibilizar un despliegue así, establece `"disabled": true` en la configuración administrada.

285* Cuando [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/es/env-vars) está establecido, Claude Code ignora `filesystem.disabled` de cada fuente, incluida la configuración administrada, y mantiene el aislamiento del sistema de archivos activado.392* Cuando [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/es/env-vars) está establecida, Claude Code ignora `filesystem.disabled` desde cualquier fuente, incluida la configuración administrada, y mantiene activado el aislamiento del sistema de archivos.

286 393

287Si una entrada de credenciales administrada `credentials.files` fija `filesystem.disabled`, bloqueando la clave a la configuración administrada para que los desarrolladores no puedan desactivar el aislamiento del sistema de archivos, depende del `mode` de la entrada y de lo que sucede con la entrada cuando se inicia el sandbox:394Una entrada `mask` [válida](/docs/es/settings-reference#invalid-credential-entries-in-managed-settings) no fija la clave, incluso cuando Claude Code [recurre a `deny`](#mask-credential-files) para ella al iniciar. Incluye una ruta que no se puede enmascarar, como un directorio de credenciales, como una entrada `deny` explícita en la configuración administrada, lo que fija la clave.

~~288~~

289| Entrada administrada | Fija `filesystem.disabled` | Qué protege el archivo cuando el aislamiento está desactivado |

290| - | - | - |

291| `"mode": "deny"` | Sí | Nada: el bloqueo de lectura es parte de la capa del sistema de archivos |

292| `"mode": "mask"`, aplicado como máscara | No | El enmascaramiento en sí: la [copia centinela y proxy](#mask-credential-files) en Linux y WSL2, las propias reglas de lectura del sandbox en macOS |

293| `"mode": "mask"`, [retrocedido a `deny`](#mask-credential-files) en la configuración | No | Nada, igual que `deny`. Enumere una ruta que no se pueda enmascarar, como un directorio, como una entrada explícita `deny`, que fija la clave |

294| `"mode": "mask"`, [degradado a `deny` por validación](/docs/es/managed-settings#invalid-entries-in-managed-settings) | Sí, como una entrada explícita `deny` | Nada, igual que `deny` |

~~295~~

296Un retroceso ocurre cuando se inicia el sandbox, después de que Claude Code ya haya leído la configuración en la que se ejecuta la verificación de fijación, por lo que una entrada retrocedida nunca fija. La validación reescribe una entrada inválida a `deny` mientras se carga la configuración, por lo que una entrada degradada fija como una que escribió como `deny`.

297 395

298<h4 id="what-changes-when-filesystem-isolation-is-off">396<h4 id="what-changes-when-filesystem-isolation-is-off">

299 Qué cambia cuando el aislamiento del sistema de archivos está desactivado397 Qué cambia cuando el aislamiento del sistema de archivos está desactivado

300</h4>398</h4>

301 399

302Establecer `filesystem.disabled` levanta las protecciones que la capa del sistema de archivos en sí misma aplica. Las protecciones que otras capas aplican siguen aplicándose:400Establecer `filesystem.disabled` elimina las protecciones que aplica la propia capa del sistema de archivos. Las protecciones que aplican otras capas siguen vigentes:

303 401

304| Protección | Con aislamiento del sistema de archivos desactivado |402| Protección | Con el aislamiento del sistema de archivos desactivado |

305| - | - |403| - | - |

306| `filesystem.denyRead` y [`credentials.files`](#protect-credentials) bloques de lectura `deny` | No se aplica. La capa del sistema de archivos aplica ambos |404| Bloqueos de lectura de `filesystem.denyRead` y de `deny` en [`credentials.files`](#protect-credentials) | No se aplican. La capa del sistema de archivos aplica ambos |

307| `credentials.envVars` entradas `deny` y `mask` | Se aplica. El raspado de variables de entorno es independiente de la capa del sistema de archivos |405| Entradas `deny` y `mask` de `credentials.envVars` | Se aplican. La limpieza de variables de entorno es independiente de la capa del sistema de archivos |

308| Entradas [`credentials.files` `mask`](#mask-credential-files) aplicadas como máscaras | Se aplica: el enmascaramiento es independiente de la capa del sistema de archivos. Una entrada que [retrocedió a `deny`](#mask-credential-files) no se aplica, como cualquier entrada `deny` |406| [Entradas `mask` de `credentials.files`](#mask-credential-files) aplicadas como máscaras | Se aplican: el enmascaramiento es independiente de la capa del sistema de archivos. Una entrada que [recurrió a `deny`](#mask-credential-files) no se aplica, como cualquier entrada `deny` |

309 407

310Dos otras cosas cambian:408Cambian otras dos cosas:

311 409

312* Los comandos aislados heredan el `$TMPDIR` de su shell en lugar del directorio temporal de la sesión, porque cada directorio temporal es escribible y Claude Code ya no redirige los comandos al de la sesión.410* Los comandos aislados en el sandbox heredan el `$TMPDIR` de tu shell en lugar del directorio temporal por usuario, porque todos los directorios temporales se pueden escribir y Claude Code ya no redirige los comandos al directorio por usuario.

313 411

314 En Linux la variable a menudo no está establecida en el shell padre. La orientación de herramienta Bash le dice a Claude que cree directorios de trabajo con `mktemp -d` en lugar de confiar en `$TMPDIR`.412 En Linux, la variable a menudo no está establecida en el shell principal. Las indicaciones de la herramienta Bash le dicen a Claude que cree directorios temporales con `mktemp -d` en lugar de depender de `$TMPDIR`.

315* [`autoAllowBashIfSandboxed`](/docs/es/settings-reference#sandbox-autoallowbashifsandboxed) aún tiene como valor predeterminado `true`, por lo que los comandos aislados siguen ejecutándose sin indicadores. Establézcalo en `false` para solicitar comandos aislados.413* [`autoAllowBashIfSandboxed`](/docs/es/settings-reference#sandbox-autoallowbashifsandboxed) sigue teniendo `true` como valor predeterminado, por lo que los comandos aislados en el sandbox siguen ejecutándose sin pedir confirmación. Establécelo en `false` para que se pida confirmación para los comandos aislados en el sandbox.

316 414

317<h3 id="protect-credentials">415<h3 id="protect-credentials">

318 Proteger credenciales416 Proteger credenciales

319</h3>417</h3>

320 418

321La configuración `sandbox.credentials` declara archivos de credenciales y variables de entorno a proteger de los comandos aislados. Cada entrada nombra una ruta de archivo o una variable de entorno y un `mode`. El bloque dedicado `credentials` mantiene las reglas de credenciales agrupadas juntas y separadas de las reglas generales del sistema de archivos.419El ajuste `sandbox.credentials` declara los archivos de credenciales y las variables de entorno que se deben proteger de los comandos aislados en el sandbox. Cada entrada indica una ruta de archivo o una variable de entorno y un `mode`. El bloque dedicado `credentials` mantiene las reglas de credenciales agrupadas y separadas de las reglas generales del sistema de archivos.

322 420

323Para entradas con `"mode": "deny"`, las rutas de archivo se deniegan para lecturas dentro del sandbox, la misma restricción que aplica `filesystem.denyRead`, y las variables de entorno se desactivan antes de que se ejecute cada comando aislado. La protección de archivo es parte de la capa del sistema de archivos, por lo que no se aplica si [deshabilita el aislamiento del sistema de archivos](#disable-filesystem-isolation); la protección de variable de entorno aún lo hace.421En las entradas con `"mode": "deny"`, se deniega la lectura de las rutas de archivo dentro del sandbox, la misma restricción que aplica `filesystem.denyRead`, y las variables de entorno se eliminan antes de que se ejecute cada comando aislado en el sandbox. La protección de archivos forma parte de la capa del sistema de archivos, por lo que no se aplica si [desactivas el aislamiento del sistema de archivos](#disable-filesystem-isolation); la protección de variables de entorno sí se sigue aplicando.

324 422

325El ejemplo a continuación bloquea las lecturas del archivo de credenciales de AWS y el directorio SSH y elimina `GITHUB_TOKEN` y `NPM_TOKEN` del entorno de los comandos aislados:423El siguiente ejemplo bloquea la lectura del archivo de credenciales de AWS y del directorio SSH, y elimina `GITHUB_TOKEN` y `NPM_TOKEN` del entorno de los comandos aislados en el sandbox:

326 424

327```json theme={null}425```json theme={null}

328{426{

342}440}

343```441```

344 442

345Las entradas de variables de entorno y archivo también aceptan `"mode": "mask"`, descrito bajo [Enmascarar credenciales](#mask-credentials).443Las entradas de variables de entorno y de archivos también aceptan `"mode": "mask"`, que se describe en [Enmascarar credenciales](#mask-credentials).

346 444

347Las rutas de archivo siguen las mismas [reglas de prefijo](/docs/es/settings-reference#sandbox-path-prefixes) que las configuraciones `sandbox.filesystem.*`.445Las rutas de archivo siguen las mismas [reglas de prefijos](/docs/es/settings-reference#sandbox-path-prefixes) que los ajustes `sandbox.filesystem.*`.

348 446

349Claude Code fusiona las entradas `deny` de cada [ámbito de configuración](/docs/es/settings#settings-precedence) que carga la sesión. Una entrada `deny` solo estrecha el acceso, por lo que cualquier ámbito puede agregar una, pero ningún ámbito puede eliminar una que otro ámbito haya agregado.447Claude Code combina las entradas `deny` de todos los [alcances de configuración](/docs/es/settings#settings-precedence) que carga la sesión. Una entrada `deny` solo restringe el acceso, por lo que cualquier alcance puede agregar una, pero ningún alcance puede eliminar una que haya agregado otro alcance.

350 448

351Cuando [excluye una fuente de configuración](#configure-sandboxing):449Cuando [excluyes una fuente de configuración](#configure-sandboxing):

352 450

353* **Configuración de proyecto o local**: Claude Code no aplica ninguna de sus entradas `credentials`. Requiere Claude Code v2.1.246 o posterior.451* **Configuración del proyecto o local**: Claude Code no aplica ninguna de sus entradas de `credentials`. Requiere Claude Code v2.1.246 o posterior.

354* **Configuración de usuario**: Claude Code aún aplica las entradas `deny` en `~/.claude/settings.json` y mantiene sus entradas `mask` de [archivo](#mask-credential-files) como restricciones, pero descarta sus entradas `mask` de [variable de entorno](#mask-environment-variables).452* **Configuración de usuario**: Claude Code sigue aplicando las entradas `deny` de `~/.claude/settings.json` y mantiene sus [entradas `mask` de archivos](#mask-credential-files) como restricciones que ya no autorizan al proxy a sustituir el valor real, pero descarta sus [entradas `mask` de variables de entorno](#mask-environment-variables).

355 453

356No hay una lista de denegación de credenciales integrada, por lo que solo los archivos y variables que enumere están restringidos.454No hay una lista de denegación de credenciales integrada, por lo que solo se restringen los archivos y las variables que indiques.

357 455

358`sandbox.credentials` afecta solo a los comandos Bash aislados. Para eliminar las credenciales de todos los subprocesos independientemente del sandboxing, establezca [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/es/env-vars).456`sandbox.credentials` afecta solo a los comandos Bash aislados en el sandbox. Para quitar credenciales de todos los subprocesos independientemente del sandboxing, establece [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/es/env-vars).

359 457

360<h3 id="mask-credentials">458<h3 id="mask-credentials">

361 Enmascarar credenciales459 Enmascarar credenciales

362</h3>460</h3>

363 461

364El enmascaramiento va más allá de una entrada `deny` bajo [Proteger credenciales](#protect-credentials). En lugar de bloquear una credencial, Claude Code muestra a los comandos aislados un marcador de posición, el centinela, y el [proxy del sandbox](#network-isolation) intercambia el valor real en solicitudes salientes a hosts que permite. Para archivos, la sustitución es comportamiento de Linux y WSL2; [macOS bloquea el archivo en su lugar](#mask-credential-files).462Cuando enmascaras una credencial, Claude Code muestra a los comandos aislados en el sandbox un marcador por sesión llamado centinela, y el [proxy del sandbox](#network-isolation) sustituye el valor real en las solicitudes salientes a los hosts que permitas. Una entrada `deny` de [Proteger credenciales](#protect-credentials), en cambio, bloquea la credencial. En el caso de los archivos en macOS, Claude Code [bloquea el archivo en su lugar](#mask-credential-files) en lugar de enmascararlo.

~~365~~

366<h4 id="mask-environment-variables">

367 Enmascarar variables de entorno

368</h4>

~~369~~

370`"mode": "mask"` protege una credencial mientras mantiene funcionando las herramientas que se autentican con ella. `deny` elimina la variable por completo, lo que también rompe las herramientas que la necesitan, como `gh` o `npm`. Requiere Claude Code v2.1.199 o posterior.

371 463

372Con `mask`, el comando aislado ve un valor centinela por sesión en lugar del real. Cada entrada `mask` puede enumerar `injectHosts`, los hosts a los que se permite que el valor real llegue. Cuando una solicitud sale del sandbox para uno de ellos, el [proxy del sandbox](#network-isolation) reemplaza el centinela con el valor real. El comando y cualquier cosa que registre nunca contienen la credencial real, pero sus solicitudes aún se autentican.464Enmascarar variables de entorno requiere Claude Code v2.1.199 o posterior. La referencia de [`sandbox.credentials`](/docs/es/settings-reference#sandbox-credentials) enumera todos los campos.

373 465

374El proxy sustituye la credencial dentro del contenido de la solicitud, por lo que tiene que verla. Establezca [`network.tlsTerminate`](/docs/es/settings-reference#sandbox-network-tlsterminate) para que el proxy termine TLS por sí mismo.466El enmascaramiento requiere lo siguiente:

375 467

376Sin él, el enmascaramiento falla sin exponer nada: el comando aún ve solo el centinela, pero el centinela llega al servidor sin cambios y la autenticación falla. Claude Code reporta esta configuración incorrecta al inicio.468* **Terminación TLS**: el proxy sustituye el valor real dentro del contenido de la solicitud, por lo que necesita verlo. Configura [`network.tlsTerminate`](/docs/es/settings-reference#sandbox-network-tlsterminate) para que el proxy termine TLS por sí mismo. Sin esto, el enmascaramiento falla sin exponer nada: el comando sigue viendo solo el centinela, pero el centinela llega al servidor sin cambios y la autenticación falla. Claude Code informa de esta configuración incorrecta al iniciar.

469* **Un destino permitido**: cada entrada `mask` puede incluir `injectHosts`, los hosts a los que puede llegar el valor real. El proxy solo inyecta en las conexiones que admite la [lista de dominios permitidos](#network-isolation), por lo que cada host de `injectHosts` también debe ser accesible a través de `network.allowedDomains`. En una entrada `mask` sin `injectHosts`, el proxy sustituye el valor real en las solicitudes a todos los hosts de `network.allowedDomains`.

470* **Un alcance de configuración de confianza**: el enmascaramiento autoriza al proxy a enviar tu credencial real a algún lugar, por lo que Claude Code respeta las entradas `mask`, `network.tlsTerminate`, [`credentials.allowPlaintextInject`](/docs/es/settings-reference#sandbox-credentials-allowplaintextinject), `awsPairs` y `sigv4` solo desde la configuración de usuario, la configuración administrada y el flag `--settings`. Los ignora en el `.claude/settings.json` o el `.claude/settings.local.json` de un repositorio. Cuando tu administrador entrega entradas `mask`, `network.tlsTerminate` o `credentials.allowPlaintextInject` a través de la configuración administrada por el servidor, cuentan como [configuraciones que requieren aprobación](/docs/es/server-managed-settings#security-approval-dialogs).

377 471

378La sustitución cubre encabezados y cuerpos de solicitud. Las solicitudes que se autentican con una firma derivada de la credencial, en lugar de la credencial en sí, necesitan re-firmarse en el proxy; [Re-firmar solicitudes de AWS](#re-sign-aws-requests) cubre cómo funciona eso para AWS.472<h4 id="mask-environment-variables">

473 Enmascarar variables de entorno

474</h4>

379 475

380El proxy inyecta solo en conexiones que la [lista de permitidos de dominio](#network-isolation) admite, por lo que cada destino `injectHosts` también debe ser alcanzable a través de `network.allowedDomains`.476Para enmascarar una variable de entorno, establece `"mode": "mask"` en su entrada de `credentials.envVars`. El comando y todo lo que registra nunca contienen la credencial real, pero sus solicitudes se siguen autenticando. Cuando la misma variable aparece con `deny` en cualquier alcance, `deny` tiene precedencia.

381 477

382El ejemplo a continuación enmascara dos tokens. `GH_TOKEN` se sustituye solo en solicitudes a `api.github.com`, mientras que `NPM_TOKEN` no tiene `injectHosts` y se sustituye en solicitudes a cada host en `network.allowedDomains`.478El siguiente ejemplo enmascara dos tokens. `GH_TOKEN` se sustituye solo en las solicitudes a `api.github.com`, mientras que `NPM_TOKEN` no tiene `injectHosts` y se sustituye en las solicitudes a todos los hosts de `network.allowedDomains`:

383 479

384```json theme={null}480```json theme={null}

385{481{

399}495}

400```496```

401 497

402<span id="ipv6-destinations-in-injecthosts" />Deletree un destino IPv6 de manera diferente en las dos listas, porque cada lista tiene su propio comparador:498De forma predeterminada, el enmascaramiento reemplaza el valor completo. Para un valor con estructura, como una cadena de conexión `DATABASE_URL` o un JWT, usa los [campos `extract`, `decode`, `maskClaims` y `onExtractNoMatch`](/docs/es/settings-reference#sandbox-credentials-envvars) para que las herramientas que analizan el valor sigan funcionando.

~~403~~

404* **`network.allowedDomains`**: la [forma entre corchetes que usan las listas de dominios](#ipv6-addresses-in-domain-lists), como `"[::1]"`. El proxy verifica esta lista para admitir la conexión.

405* **`injectHosts`**: la dirección desnuda en su forma canónica comprimida, como `"::1"` o `"2001:db8::1"`. El proxy compara cada entrada contra la dirección de destino desnuda de la conexión, ignorando puertos, por lo que una ortografía entre corchetes, con ID de zona o comprimida de manera diferente nunca coincide y el proxy nunca inyecta la credencial allí.

~~406~~

407`claude doctor` marca entradas `injectHosts` que nunca pueden coincidir con la advertencia `Sandbox credential injectHosts entries can never match their destination`. Esta verificación requiere Claude Code v2.1.229 o posterior.

~~408~~

409A diferencia de `deny`, el enmascaramiento autoriza al proxy a enviar su credencial real a los hosts enumerados, por lo que Claude Code lo honra solo desde configuraciones que usted o su administrador controlan: configuración de usuario, configuración administrada y la bandera CLI `--settings`. Claude Code ignora entradas `mask` en el `.claude/settings.json` o `.claude/settings.local.json` de un repositorio. En esos archivos también ignora `network.tlsTerminate` y [`credentials.allowPlaintextInject`](/docs/es/settings-reference#sandbox-credentials-allowplaintextinject), la configuración que permite al proxy inyectar credenciales en solicitudes sin cifrar. Si [excluye la configuración de usuario](#configure-sandboxing), Claude Code descarta las entradas `mask` de variable de entorno en `~/.claude/settings.json` también.

~~410~~

411Cuando su administrador entrega entradas `mask`, `network.tlsTerminate` o `credentials.allowPlaintextInject` a través de configuración administrada por servidor, cuentan como [configuraciones que necesitan aprobación](/docs/es/server-managed-settings#security-approval-dialogs).

~~412~~

413Cuando la misma variable se enumera con `deny` en cualquier ámbito, `deny` tiene prioridad.

414 499

415El enmascaramiento reemplaza el valor completo de la variable de forma predeterminada, lo que se adapta a un token desnudo. Los campos de entrada opcionales, que requieren Claude Code v2.1.224 o posterior, manejan valores con estructura:500<span id="ipv6-destinations-in-injecthosts" />Para un destino IPv6, escribe la dirección de forma distinta en las dos listas:

416 501

417* `extract`: una expresión regular que Claude Code aplica en todo el valor, reemplazando solo el texto capturado por el grupo 1 de cada coincidencia, por lo que una herramienta que analiza el valor, como una cadena de conexión `DATABASE_URL`, aún funciona dentro del sandbox. El patrón debe contener al menos un grupo de captura.502* **`network.allowedDomains`**: la forma entre corchetes, como `"[::1]"`

418* `onExtractNoMatch` controla qué sucede cuando el patrón no coincide con nada:503* **`injectHosts`**: la dirección sin corchetes en su forma canónica comprimida, como `"::1"`

419 * `warn`, el valor predeterminado, advierte y pasa la variable sin enmascarar

420 * `deny` desactiva la variable dentro del sandbox

421 * `error` detiene la configuración del sandbox hasta que corrija la configuración

422* `decode: "jwt"`: para una variable que contiene un JSON Web Token (JWT). Claude Code verifica que el valor sea un JWT y lo reemplaza con un token falso estructuralmente válido, por lo que el código dentro del sandbox que decodifica el token sigue funcionando. Agregue `maskClaims` para enumerar reclamaciones de carga útil de nivel superior para enmascarar individualmente en lugar de reemplazar el token completo; las otras reclamaciones permanecen legibles. Cuando el valor no se verifica como JWT, o ninguna reclamación enumerada coincide, Claude Code pasa la variable sin enmascarar con una advertencia. `decode` no se puede combinar con `extract`.

423 504

424Consulte las [filas `credentials.envVars[]` en la referencia de configuración](/docs/es/settings-reference#sandbox-settings) para la lista de campos completa.505El proxy compara cada entrada de `injectHosts` con la dirección de destino sin corchetes de la conexión, ignorando los puertos, por lo que una forma entre corchetes, con ID de zona o comprimida de otra manera nunca coincide. `claude doctor` marca las entradas que nunca pueden coincidir con la advertencia `Sandbox credential injectHosts entries can never match their destination`. Esta comprobación requiere Claude Code v2.1.229 o posterior.

425 506

426<h4 id="re-sign-aws-requests">507<h4 id="re-sign-aws-requests">

427 Re-firmar solicitudes de AWS508 Volver a firmar solicitudes de AWS

428</h4>509</h4>

429 510

430Las solicitudes de AWS llevan firmas SigV4 sobre el contenido de la solicitud, por lo que enmascare `AWS_ACCESS_KEY_ID` y `AWS_SECRET_ACCESS_KEY` juntos. El proxy detecta una solicitud SigV4 por el centinela de la clave de acceso y la re-firma después de sustituir los valores reales. Enmascarar solo el secreto deja solicitudes firmadas con el marcador de posición, que el proxy no puede detectar, por lo que fallan en AWS; Claude Code advierte sobre este caso al inicio, pero no cuando solo se enmascara el ID de clave de acceso. Una solicitud detectada que el proxy no puede re-firmar, como una que falta su encabezado `x-amz-date`, falla con un error de proxy en lugar de llegar al servidor con una firma rota.511Las solicitudes de AWS llevan firmas SigV4 sobre el contenido de la solicitud, así que enmascara `AWS_ACCESS_KEY_ID` y `AWS_SECRET_ACCESS_KEY` juntas. El proxy detecta una solicitud SigV4 por el [centinela](#mask-credentials) de la clave de acceso y vuelve a firmar la solicitud con los valores reales, lo que requiere Claude Code v2.1.221 o posterior. Si enmascaras solo el secreto, las solicitudes se firman con un marcador que el proxy no puede detectar, por lo que fallan en AWS.

431 512

432Claude Code vincula las variables convencionales `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` y `AWS_SESSION_TOKEN` en una credencial automáticamente cuando enmascara sus valores completos. Si su credencial de AWS vive en variables con otros nombres, agrúpelas usted mismo con [`credentials.awsPairs`](/docs/es/settings-reference#sandbox-credentials-awspairs), que requiere Claude Code v2.1.224 o posterior. Este ejemplo agrega el emparejamiento a una configuración que ya enmascara `MY_KEY_ID`, `MY_SECRET_KEY` y `MY_SESSION_TOKEN` completos, como en la [configuración de enmascaramiento anterior](#mask-environment-variables):513Claude Code vincula automáticamente las variables convencionales `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` y `AWS_SESSION_TOKEN` en una sola credencial cuando enmascaras sus valores completos. Si tu credencial de AWS está en variables con otros nombres, agrúpalas con [`credentials.awsPairs`](/docs/es/settings-reference#sandbox-credentials-awspairs), que requiere Claude Code v2.1.224 o posterior.

433 514

434```json theme={null}515Las cargas en streaming, las URL prefirmadas y las solicitudes SigV4A llevan firmas que el proxy no puede recalcular. Cuando una de estas solicitudes está firmada con el marcador de un par enmascarado, el proxy la hace fallar en lugar de reenviar una firma rota. Las solicitudes firmadas con credenciales sin enmascarar no se ven afectadas. Usa [`credentials.sigv4`](/docs/es/settings-reference#sandbox-credentials-sigv4), que requiere Claude Code v2.1.224 o posterior, para reenviar en su lugar una de estas formas de solicitud. AWS sigue rechazando la solicitud, de modo que la herramienta que llama recibe la respuesta de rechazo propia de AWS en lugar de un error del proxy.

435{

436 "sandbox": {

437 "credentials": {

438 "awsPairs": [

439 {

440 "accessKeyIdVar": "MY_KEY_ID",

441 "secretAccessKeyVar": "MY_SECRET_KEY",

442 "sessionTokenVar": "MY_SESSION_TOKEN"

443 }

444 ]

445 }

446 }

447}

448```

~~449~~

450Cada entrada sigue estas reglas:

~~451~~

452* `accessKeyIdVar` y `secretAccessKeyVar` nombran las entradas `envVars` enmascaradas que contienen el ID de clave de acceso y la clave secreta. El `sessionTokenVar` opcional nombra la entrada que contiene el token de sesión para credenciales temporales; cuando se establece, el proxy envía el token real como `x-amz-security-token` en solicitudes re-firmadas.

453* Cada variable nombrada debe ser una entrada `mask` que enmascara su valor completo, sin `extract` o `decode`.

454* El proxy re-firma solicitudes en los hosts enumerados en la entrada `injectHosts` del ID de clave de acceso.

455* Nombrar cualquiera de las variables convencionales en un par reemplaza el emparejamiento automático.

~~456~~

457Como entradas `mask`, `awsPairs` se honra solo desde configuración de usuario, configuración administrada y la bandera CLI `--settings`.

~~458~~

459Tres formas de solicitud de AWS llevan firmas que el proxy no puede recomputar. Cuando tal solicitud se firma con el marcador de posición de un par enmascarado, el proxy la falla en lugar de reenviar una firma rota; las solicitudes firmadas con credenciales sin enmascarar nunca se ven afectadas. La configuración [`credentials.sigv4`](/docs/es/settings-reference#sandbox-credentials-sigv4), que requiere Claude Code v2.1.224 o posterior, relaja esto por forma: establecer la clave de una forma en `passthrough` reenvía la solicitud con su firma derivada de marcador de posición, por lo que la herramienta que llama recibe el rechazo propio de AWS en lugar de un error de proxy. Como `awsPairs`, `sigv4` se honra solo desde configuración de usuario, configuración administrada y la bandera CLI `--settings`.

~~460~~

461| Forma de solicitud | Clave `sigv4` | Por qué el proxy no puede re-firmarla |

462| :- | :- | :- |

463| cargas de transmisión aws-chunked | `streaming` | Las firmas por fragmento se encadenan desde la firma de semilla, por lo que re-firmar requeriría reescribir el cuerpo |

464| URLs pre-firmadas | `presigned` | La firma vive en la URL en sí, sin encabezado `Authorization` |

465| Firmas asimétricas SigV4A | `sigv4a` | No hay HMAC de clave compartida para recomputar |

466 516

467<h4 id="mask-credential-files">517<h4 id="mask-credential-files">

468 Enmascarar archivos de credenciales518 Enmascarar archivos de credenciales

469</h4>519</h4>

470 520

471Las entradas de archivo también aceptan `"mode": "mask"`, que requiere Claude Code v2.1.221 o posterior. Lo que ve un comando aislado depende de la plataforma:521Para enmascarar un archivo de credenciales, establece `"mode": "mask"` en su entrada de `credentials.files`. Enmascarar archivos requiere Claude Code v2.1.221 o posterior. Lo que ve un comando aislado en el sandbox depende de la plataforma:

~~472~~

473* **Linux y WSL2**: los comandos aislados leen una copia centinela del archivo, un sustituto cuyo secreto se reemplaza con un valor de marcador de posición, y el [proxy del sandbox](#network-isolation) sustituye el valor real en salida.

474* **macOS**: los comandos aislados no pueden leer el archivo enumerado en absoluto. Claude Code no construye ninguna copia centinela y no sustituye nada en salida, por lo que las herramientas que se autentican con el archivo no funcionan dentro del sandbox, el mismo efecto que `deny`. A diferencia de una entrada `deny`, el bloqueo de lectura se mantiene incluso cuando [deshabilita el aislamiento del sistema de archivos](#disable-filesystem-isolation).

475 522

476En cada plataforma, Claude Code aplica el requisito [`network.tlsTerminate`](/docs/es/settings-reference#sandbox-network-tlsterminate) e `injectHosts` de la misma manera que para [variables de entorno enmascaradas](#mask-environment-variables), e ignora configuración de repositorio de la misma manera. Si [excluye la configuración de usuario](#configure-sandboxing), Claude Code mantiene las entradas `mask` de archivo en `~/.claude/settings.json` como restricciones, pero las entradas ya no autorizan al proxy a sustituir el valor real.523* **Linux y WSL2**: los comandos aislados en el sandbox leen una copia [centinela](#mask-credentials) del archivo, y el proxy sustituye el valor real en las solicitudes salientes.

524* **macOS**: los comandos aislados en el sandbox no pueden leer el archivo en absoluto. Claude Code no crea ninguna copia centinela, por lo que las herramientas que se autentican con el archivo no funcionan dentro del sandbox, el mismo efecto que `deny`. El bloqueo de lectura se mantiene incluso cuando [desactivas el aislamiento del sistema de archivos](#disable-filesystem-isolation).

477 525

478El ejemplo a continuación enmascara un token de GitHub almacenado en `~/.config/gh/hosts.yml`; el patrón `extract`, cubierto a continuación, le dice a Claude Code qué parte del archivo es el secreto. En Linux y WSL2, los comandos aislados que leen el archivo obtienen un centinela en lugar del token, y el proxy sustituye el token real en solicitudes a `api.github.com`:526El siguiente ejemplo enmascara un token de GitHub almacenado en `~/.config/gh/hosts.yml`. El patrón `extract` marca qué parte del archivo es el secreto, de modo que en Linux y WSL2 `gh` sigue analizando el resto de su configuración:

479 527

480```json theme={null}528```json theme={null}

481{529{

499}547}

500```548```

501 549

502Para confirmar que la máscara está activa, pida a Claude que ejecute `cat ~/.config/gh/hosts.yml` en un comando aislado: en Linux y WSL2 la salida muestra un valor centinela en lugar del token, y en macOS la lectura falla en su lugar.550Para confirmar que la máscara está activa, pídele a Claude que ejecute `cat ~/.config/gh/hosts.yml` en un comando aislado en el sandbox. En Linux y WSL2 la salida muestra un centinela en lugar del token, y en macOS la lectura falla.

~~503~~

504En Linux y WSL2, el patrón `extract` es lo que mantiene el resto de `hosts.yml` legible. Claude Code aplica la expresión regular en todo el archivo y reemplaza solo el texto capturado por el grupo 1 de cada coincidencia, por lo que `gh` aún analiza su configuración y solo el token es un marcador de posición. Use `extract` para cualquier archivo estructurado que las herramientas analicen, como `.netrc`, JSON o YAML; el patrón debe contener al menos un grupo de captura. Sin `extract`, Claude Code reemplaza todo el contenido del archivo con un valor centinela, que se adapta a un archivo que contiene un único secreto desnudo y nada más.

~~505~~

506Para un archivo que contiene un JSON Web Token (JWT), establezca `decode: "jwt"` en lugar de, o junto con, `extract`. `decode` requiere Claude Code v2.1.224 o posterior. Claude Code encuentra candidatos JWT con un patrón integrado, o con su patrón `extract` cuando se establece, verifica que cada candidato sea un JWT y lo reemplaza con un token falso estructuralmente válido, por lo que el código que decodifica el token dentro del sandbox sigue funcionando. Agregue `maskClaims` para enmascarar solo las reclamaciones de carga útil de nivel superior nombradas dentro de cada token verificado y deje las otras reclamaciones legibles. Cuando ningún candidato se verifica, o ninguna reclamación nombrada coincide, el campo `onExtractNoMatch` a continuación rige el resultado, como lo hace para un patrón que no coincide con nada.

507 551

508Dos campos opcionales refinan cómo se comporta la coincidencia. Ambos se aplican solo cuando `mode` es `mask` y `extract` o `decode` está establecido. En macOS, Claude Code aplica entradas `mask` como `deny` antes de que se ejecute el patrón siempre que el aislamiento del sistema de archivos esté activado, por lo que estos campos, y los resultados de no coincidencia a continuación, tienen efecto allí solo cuando [deshabilita el aislamiento del sistema de archivos](#disable-filesystem-isolation):552Sin `extract` ni `decode`, Claude Code reemplaza todo el archivo con un único centinela, lo que es adecuado para un archivo que contiene un único secreto simple. Usa los [campos `extract`, `decode`, `maskClaims`, `onExtractNoMatch` y `maskDuplicates`](/docs/es/settings-reference#sandbox-credentials-files) para controlar el enmascaramiento parcial y qué ocurre cuando el patrón no coincide con nada.

509 553

510* `onExtractNoMatch` controla qué sucede cuando la coincidencia no encuentra nada para enmascarar en el archivo:554<Warning>

~~511~~ 555 Cuando la búsqueda no encuentra nada que enmascarar, el valor predeterminado de `onExtractNoMatch`, `warn`, omite la entrada, de modo que los comandos aislados en el sandbox pueden leer el archivo real sin enmascarar. En macOS, Claude Code aplica las entradas `mask` como `deny` antes de que se ejecute el patrón siempre que el aislamiento del sistema de archivos esté activado, por lo que los resultados sin coincidencia solo tienen efecto allí cuando [el aislamiento del sistema de archivos está desactivado](#disable-filesystem-isolation). El valor predeterminado es adecuado para credenciales que pueden estar ausentes legítimamente. Si el secreto podría estar presente pero el patrón podría no detectarlo, usa [`deny`](/docs/es/settings-reference#mask-fields-for-files).

512 * `warn`, el valor predeterminado, advierte y omite la entrada, por lo que los comandos aislados pueden leer el archivo real sin enmascarar. El valor predeterminado se adapta a credenciales que pueden estar legítimamente ausentes; si el secreto podría estar presente pero el patrón podría no detectarlo, use `deny`556</Warning>

513 * `deny` hace que el archivo sea ilegible en su lugar

514 * `error` detiene la configuración del sandbox hasta que corrija la configuración

~~515~~

516 Claude Code trata `deny` como `error` siempre que el bloqueo de lectura no se aplicaría: cuando [deshabilita el aislamiento del sistema de archivos](#disable-filesystem-isolation), y cuando una entrada `filesystem.allowRead` de cualquier fuente de configuración reabre la ruta del archivo.

517* `maskDuplicates` también reemplaza copias verbatim de cada valor de credencial enmascarado, una captura `extract` o un token verificado `decode`, encontrado fuera de los intervalos coincidentes, para un secreto repetido donde la coincidencia no llega. Coincide con subcadenas sin procesar, por lo que un valor corto o común se reemplazaría en todas partes donde aparece; resérvelo para secretos largos y de alta entropía. Valor predeterminado: false.

518 557

519`mask` se aplica a un único archivo, por lo que enumere cada archivo de credencial individualmente. Claude Code retrocede a `deny` para una entrada `mask` que no puede enmascarar de forma segura: una ruta de directorio, un patrón glob, un archivo más grande que 8 MiB o un archivo que no es texto UTF-8. Escriba directorios como entradas explícitas `deny` en su lugar; la tabla bajo [Qué configuraciones pueden deshabilitarlo](#which-settings-can-disable-it) cubre si cada forma fija `filesystem.disabled` y cómo se comporta con el aislamiento del sistema de archivos desactivado.558`mask` se aplica a un único archivo, así que indica cada archivo de credenciales por separado. Claude Code recurre a `deny` para una entrada `mask` que no puede enmascarar de forma segura: una ruta de directorio, un patrón glob, un archivo de más de 8 MiB o un archivo que no es texto UTF-8.

520 559

521<h2 id="how-sandboxing-works">560<h2 id="how-sandboxing-works">

522 Cómo funciona el sandboxing561 Cómo funciona el sandboxing

526 Aislamiento del sistema de archivos565 Aislamiento del sistema de archivos

527</h3>566</h3>

528 567

529La herramienta Bash aislada restringe el acceso al sistema de archivos a directorios específicos:568La herramienta Bash en el sandbox restringe el acceso al sistema de archivos a directorios específicos:

530 569

531* **Comportamiento de escritura predeterminado**: acceso de lectura y escritura al directorio de trabajo actual y sus subdirectorios, cualquier directorio que haya agregado con `--add-dir`, `/add-dir`, o [`permissions.additionalDirectories`](/docs/es/settings-reference#permissions-additionaldirectories), más el directorio temporal de sesión al que apunta `$TMPDIR`570* **Comportamiento de escritura predeterminado**: acceso de lectura y escritura al directorio de trabajo actual y sus subdirectorios, a cualquier directorio que hayas agregado con `--add-dir`, `/add-dir` o [`permissions.additionalDirectories`](/docs/es/settings-reference#permissions-additionaldirectories), además del directorio temporal por usuario al que apunta `$TMPDIR`

532* **Comportamiento de lectura predeterminado**: acceso de lectura a toda la computadora, excepto ciertos directorios denegados. Tenga en cuenta que este comportamiento predeterminado aún permite leer archivos de credenciales como `~/.aws/credentials` y `~/.ssh/`. Utilice [`sandbox.credentials`](#protect-credentials) para bloquear lecturas de estos archivos y desconfigurar variables de entorno secretas, o agregue las rutas a `denyRead`.571* **Comportamiento de lectura predeterminado**: acceso de lectura a toda la computadora, excepto ciertos directorios denegados. Este valor predeterminado aún permite leer archivos de credenciales, así que [protege las credenciales](#protect-credentials) que no quieras que los comandos lean.

533* **Bloqueo de lectura**: con [`permissions.blockReadsOutsideWorkingDirectories`](/docs/es/settings-reference#permissions-blockreadsoutsideworkingdirectories) activado, los comandos aislados también pierden acceso de lectura a su directorio de inicio y a los otros directorios que contienen archivos de usuario, aparte de las rutas que [Comandos aislados bajo el bloqueo](/docs/es/settings-reference#sandboxed-commands-under-the-block) enumera. Esa sección también dice cuándo esta parte del bloqueo no se aplica.572* **Bloqueo de lectura**: con [`permissions.blockReadsOutsideWorkingDirectories`](/docs/es/settings-reference#permissions-blockreadsoutsideworkingdirectories) activado, los comandos en el sandbox también pierden el acceso de lectura a tu directorio home y a los demás directorios que contienen archivos de usuario, salvo las rutas que enumera [Comandos en el sandbox bajo el bloqueo](/docs/es/settings-reference#sandboxed-commands-under-the-block). Esa sección también indica cuándo no se aplica esta parte del bloqueo.

534* **Acceso bloqueado**: no puede modificar archivos fuera del directorio de trabajo, directorios agregados y directorio temporal de sesión sin permiso explícito, incluidos archivos de configuración de shell como `~/.bashrc` y binarios del sistema en `/bin/`573* **Git worktrees**: cuando el directorio de trabajo es un [worktree de git vinculado](/docs/es/worktrees), el sandbox también permite escrituras en el directorio `.git` compartido del repositorio principal para que comandos como `git commit` puedan actualizar las refs y el índice. Las escrituras en `hooks/` y `config` dentro de ese directorio siguen denegadas.

535* **Git worktrees**: cuando el directorio de trabajo es un [git worktree vinculado](/docs/es/worktrees), el sandbox también permite escrituras en el directorio compartido `.git` del repositorio principal para que comandos como `git commit` puedan actualizar referencias e índices. Las escrituras a `hooks/` y `config` dentro de ese directorio permanecen denegadas.

536* **Configurable**: defina rutas permitidas y denegadas personalizadas a través de la configuración

537 574

538Para omitir completamente el aislamiento del sistema de archivos mientras se mantiene el aislamiento de red, establezca [`sandbox.filesystem.disabled`](#disable-filesystem-isolation).575Para omitir por completo el aislamiento del sistema de archivos y mantener el aislamiento de red, configura [`sandbox.filesystem.disabled`](#disable-filesystem-isolation).

539 576

540<h3 id="protected-paths">577<h3 id="protected-paths">

541 Rutas protegidas578 Rutas protegidas

542</h3>579</h3>

543 580

544Dentro de los directorios en los que los comandos aislados pueden escribir, el sandbox aún deniega escrituras en los archivos desde los que Claude Code carga configuración y código. Un comando que pudiera editar esos archivos podría otorgarse permisos a sí mismo, o agregar un hook o servidor MCP que Claude Code ejecuta fuera del sandbox. El sistema de permisos tiene sus propias [rutas protegidas](/docs/es/permission-modes#protected-paths), que controlan lo que Claude Code aprueba antes de que se ejecute una herramienta; la lista del sandbox se aplica a un comando que ya está en ejecución. Cubre cuatro grupos de rutas:581Dentro de los directorios en los que los comandos en el sandbox pueden escribir, el sandbox sigue denegando escrituras en los archivos desde los que Claude Code carga configuración y código. Un comando que pudiera editar esos archivos podría otorgarse permisos a sí mismo, o agregar un hook o un servidor MCP que Claude Code ejecute fuera del sandbox. El sistema de permisos tiene sus propias [rutas protegidas](/docs/es/permission-modes#protected-paths), que controlan lo que Claude Code aprueba antes de que se ejecute una herramienta; la lista del sandbox se aplica a un comando que ya se está ejecutando. Abarca cuatro grupos de rutas:

545 582

546* **En su directorio de trabajo y los directorios por encima de él**: los archivos de configuración `.claude`, los directorios `.claude/skills`, `.claude/agents`, `.claude/commands` y `.claude/hooks`, `.mcp.json`, y los archivos que Claude Code ejecuta por su cuenta, como `.claude/workflows` y `.claude/scheduled_tasks.json`583* **En tu directorio de trabajo y los directorios superiores**: los archivos de configuración de `.claude`, los directorios `.claude/skills`, `.claude/agents`, `.claude/commands` y `.claude/hooks`, `.mcp.json`, y los archivos que Claude Code ejecuta por sí mismo, como `.claude/workflows` y `.claude/scheduled_tasks.json`

547* **Solo en su directorio de trabajo**: archivos de inicio de shell como `.bashrc` y `.zshrc`, `.gitconfig`, los directorios `.vscode` e `.idea`, y `hooks` y `config` dentro de `.git`584* **Solo en tu directorio de trabajo**: archivos de inicio del shell como `.bashrc` y `.zshrc`, `.gitconfig`, los directorios `.vscode` y `.idea`, y `hooks` y `config` dentro de `.git`

548* **Archivos que convertirían su directorio de trabajo en un repositorio git desnudo**: `HEAD`, `objects` y `refs` en el nivel superior, más `config` y `hooks` allí cuando un `HEAD` se sienta junto a ellos. Un archivo denominado `config` se deniega incluso sin `HEAD`. En Linux y WSL2, el sandbox elimina un archivo `HEAD` de nivel superior o un directorio `objects` o `refs` que aparece mientras se ejecuta un comando aislado585* **Archivos que convertirían tu directorio de trabajo en un repositorio git bare**: `HEAD`, `objects` y `refs` en el nivel superior, además de las entradas `config` y `hooks` existentes allí cuando hay un `HEAD` junto a ellas. Un archivo llamado `config` se deniega incluso sin `HEAD`. En Linux y WSL2, el sandbox elimina un archivo `HEAD` o un directorio `objects` o `refs` de nivel superior que aparezca mientras se ejecuta un comando en el sandbox

549* **En `~/.claude`, o el directorio al que apunta `CLAUDE_CONFIG_DIR`**: la mayoría de su contenido, más `~/.claude.json` y el almacén de credenciales `.credentials.json`586* **En `~/.claude`, o el directorio al que apunta `CLAUDE_CONFIG_DIR`**: la mayor parte de su contenido, además de `~/.claude.json` y el almacén de credenciales `.credentials.json`

550 587

551Si aparece un enlace simbólico en la ruta de un archivo de configuración protegido durante la sesión, el sandbox también deniega escrituras en el archivo al que apunta, comenzando con el siguiente comando.588Si aparece un enlace simbólico en la ruta de un archivo de configuración protegido durante la sesión, el sandbox también deniega las escrituras en el archivo al que apunta, a partir del siguiente comando.

552 589

553No hay forma de eximir una de estas rutas: una entrada `allowWrite` o una regla de permiso `Edit` que cubra la ruta no levanta la protección. La única forma de desactivar la protección es [`filesystem.disabled`](#disable-filesystem-isolation), que desactiva el aislamiento del sistema de archivos para cada ruta. Para ver la mayoría de estas rutas resueltas para su máquina, ejecute `/sandbox` y abra la pestaña **Config**, que las enumera bajo **Denied within allowed**, mezcladas con sus propias entradas `denyWrite`.590No hay forma de exceptuar una de estas rutas: una entrada `allowWrite` o una regla de permiso `Edit` que cubra la ruta no elimina la protección. La única forma de desactivar la protección es [`filesystem.disabled`](#disable-filesystem-isolation), que desactiva el aislamiento del sistema de archivos para todas las rutas. Para ver la mayoría de estas rutas resueltas para tu máquina, ejecuta `/sandbox` y abre la pestaña **Config**, que las enumera en **Denied within allowed**, mezcladas con tus propias entradas `denyWrite`.

554 591

555Si `git merge` o `git checkout` falla con `unable to unlink old` en una de estas rutas, consulte [Troubleshooting](#troubleshooting).592Si `git merge` o `git checkout` falla con `unable to unlink old` en una de estas rutas, consulta [Un comando de git falla con `unable to unlink old`](#a-git-command-fails-with-unable-to-unlink-old).

556 593

557<h3 id="network-isolation">594<h3 id="network-isolation">

558 Aislamiento de red595 Aislamiento de red

559</h3>596</h3>

560 597

561El acceso a la red se controla a través de un servidor proxy que se ejecuta fuera del sandbox:598Un comando en el sandbox no tiene una ruta directa a la red:

599

600* **Linux y WSL2**: el comando se ejecuta en un espacio de nombres de red separado que no tiene conexión con tu red

601* **macOS**: el framework de sandbox Seatbelt bloquea de forma predeterminada las conexiones distintas de la que va al proxy del sandbox

602

603Claude Code ejecuta el proxy del sandbox en tu máquina, fuera del sandbox, y dirige los comandos hacia él con `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` y variables de entorno relacionadas. El proxy compara el nombre de host de cada conexión con tus dominios permitidos y denegados.

604

605Lo que una herramienta puede alcanzar depende de si usa el proxy:

562 606

563* **Restricciones de dominio**: Claude Code no pre-permite dominios de forma predeterminada. La primera vez que un comando necesita un nuevo dominio, Claude Code solicita aprobación; en [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode), Claude en su lugar nombra los hosts que un comando necesita en el comando mismo, según [Dominios permitidos por comando](#per-command-allowed-domains-in-auto-mode).607* **Herramientas que leen las variables del proxy**: `curl`, `npm`, `git` sobre HTTPS y herramientas similares se conectan una vez que su host está permitido. Una entrada de `allowedDomains` sin puerto permite todos los puertos de ese host

564* **Opciones de aprobación**: si elige Sí cuando se le solicite, Claude Code permite el host para el resto de la sesión actual y no solicita nuevamente para conexiones posteriores al mismo host. Si elige "Sí, y no vuelvas a preguntar", Claude Code guarda una regla de permiso `WebFetch(domain:...)` en su [configuración local](/docs/es/permissions#permission-system), por lo que el host permanece permitido en sesiones futuras.608* **Herramientas que ignoran las variables del proxy**: `ssh` simple, la mayoría de los controladores de bases de datos y herramientas similares no pueden conectarse, ni siquiera a un host permitido. Consulta [Un cliente de base de datos u otra herramienta que no es HTTP no logra alcanzar un host permitido](#a-database-client-or-other-non-http-tool-fails-to-reach-an-allowed-host)

565* **Dominios pre-permitidos**: pre-permita dominios con [`allowedDomains`](/docs/es/settings-reference#sandbox-network-alloweddomains) para evitar completamente la solicitud. Claude Code también pre-permite dominios de reglas de permiso `WebFetch(domain:...)`, como se describe en [Reglas de permisos](#permission-rules).609* **Todo lo que no sea TCP**: UDP, HTTP/3 sobre QUIC y herramientas ICMP como `ping` no pueden salir del sandbox

566* **Lista de permitidos estricta**: si establece [`strictAllowlist`](/docs/es/settings-reference#sandbox-network-strictallowlist) en `true` en la configuración de usuario, administrada o CLI `--settings`, Claude Code deniega a los comandos aislados el acceso a cualquier host fuera de la lista de permitidos en lugar de solicitar. La lista de permitidos es la misma contra la que el sandbox solicita de otra manera: `allowedDomains` más dominios de reglas de permiso `WebFetch(domain:...)`, o solo las entradas de configuración administrada cuando se establece `allowManagedDomainsOnly`. Claude Code aplica esto solo para comandos aislados; las herramientas en proceso como `WebFetch` aún siguen sus [reglas de permiso](#permission-rules). Establecerlo en `.claude/settings.json` o `.claude/settings.local.json` de un repositorio no tiene efecto. Requiere Claude Code v2.1.219 o posterior.

567* **Bloqueo administrado**: si [`allowManagedDomainsOnly`](/docs/es/settings-reference#sandbox-network-allowmanageddomainsonly) se establece en la configuración administrada, los dominios no permitidos se bloquean automáticamente en lugar de solicitar, y solo se honran `allowedDomains` y reglas de permiso `WebFetch(domain:...)` de la configuración administrada.

568* **Proxy corporativo**: cuando su red requiere que el tráfico saliente pase a través de un proxy corporativo, establezca `HTTPS_PROXY`, `HTTP_PROXY` y `NO_PROXY` como describe [proxy configuration](/docs/es/network-config#proxy-configuration), en el bloque `env` de su configuración para que [agentes de fondo](/docs/es/network-config#set-network-variables-in-settings-not-the-shell) también los obtengan, o en el entorno desde el que inicia Claude Code. Claude Code aplica la lista de permitidos de dominio y luego canaliza las conexiones permitidas a través de ese proxy ascendente.

569* **Soporte de proxy personalizado**: los usuarios avanzados pueden implementar reglas personalizadas en el tráfico saliente

570* **Cobertura integral**: las restricciones se aplican a todos los scripts, programas y subprocesos generados por comandos

571 610

572En una regla `WebFetch(domain:...)`, el sandbox honra dos formas de comodín: un `*.` inicial, como `*.example.com`, y un `*` desnudo. La forma `*` desnuda requiere Claude Code v2.1.186 o posterior. Un comodín en cualquier otra posición, como `WebFetch(domain:example.*)`, aún coincide con búsquedas pero no tiene efecto en comandos aislados.611Los siguientes ajustes y comportamientos controlan qué hosts permite el proxy:

612

613* **Restricciones de dominio**: tus dominios permitidos empiezan vacíos. [Hosts fuera de tus dominios permitidos](#hosts-outside-your-allowed-domains) explica qué sucede la primera vez que un comando necesita un dominio nuevo.

614* **Opciones de aprobación**: si eliges Yes cuando se te solicita, Claude Code permite el host durante el resto de la sesión actual. Si eliges "Yes, and don't ask again", Claude Code guarda una regla de permiso `WebFetch(domain:...)` en tu [configuración local](/docs/es/permissions#permission-system), de modo que el host sigue permitido en sesiones futuras. Mientras el sandbox sea [obligatorio por el administrador](#repository-settings-under-an-admin-required-sandbox), Claude Code guarda la regla en tu configuración de usuario, donde se aplica en todos los proyectos.

615* **Dominios permitidos previamente**: permite dominios previamente con [`allowedDomains`](/docs/es/settings-reference#sandbox-network-alloweddomains) para evitar la solicitud por completo. Claude Code también permite previamente los dominios de las reglas de permiso `WebFetch(domain:...)`, como se describe en [Reglas de permisos](#permission-rules).

616* **Lista de permitidos estricta**: si configuras [`strictAllowlist`](/docs/es/settings-reference#sandbox-network-strictallowlist) en `true` en la configuración de usuario, administrada o de `--settings` de la CLI, Claude Code deniega a los comandos en el sandbox el acceso a cualquier host fuera de la lista de permitidos en lugar de pedir confirmación. La lista de permitidos es `allowedDomains` más los dominios de las reglas de permiso `WebFetch(domain:...)`, o solo las entradas de la configuración administrada cuando `allowManagedDomainsOnly` está configurado. [Bloqueos que se aplican sin un sandbox obligatorio por el administrador](#locks-that-apply-without-an-admin-required-sandbox) cubre las entradas de un repositorio. Claude Code aplica esto solo a los comandos en el sandbox; las herramientas en proceso como `WebFetch` siguen sus [reglas de permisos](#permission-rules). Configurarlo en `.claude/settings.json` o `.claude/settings.local.json` de un repositorio no tiene efecto. Requiere Claude Code v2.1.219 o posterior.

617* **Bloqueo administrado**: si [`allowManagedDomainsOnly`](/docs/es/settings-reference#sandbox-network-allowmanageddomainsonly) está configurado en la configuración administrada, los dominios no permitidos se bloquean automáticamente en lugar de pedir confirmación, y solo se respetan `allowedDomains` y las reglas de permiso `WebFetch(domain:...)` de la configuración administrada.

618* **Proxy corporativo**: cuando tu red requiere que el tráfico saliente pase por un proxy corporativo, configura `HTTPS_PROXY`, `HTTP_PROXY` y `NO_PROXY` como se describe en [configuración del proxy](/docs/es/network-config#proxy-configuration), en el bloque `env` de tu configuración para que los [agentes en segundo plano](/docs/es/network-config#set-network-variables-in-settings-not-the-shell) también las reciban, o en el entorno desde el que inicias Claude Code. Claude Code aplica la lista de dominios permitidos y luego canaliza las conexiones permitidas a través de ese proxy upstream. Funcionan las URL de proxy `http://` y `https://`, con autenticación básica en la URL si la necesitas.

619

620En una regla `WebFetch(domain:...)`, el sandbox respeta dos formas de comodín: un `*.` inicial, como `*.example.com`, y un `*` solo. La forma `*` sola requiere Claude Code v2.1.186 o posterior. Un comodín en cualquier otra posición, como `WebFetch(domain:example.*)`, sigue coincidiendo con las solicitudes de fetch pero no tiene efecto en los comandos en el sandbox.

573 621

574<Note>622<Note>

575 El proxy integrado aplica la lista de permitidos basada en el nombre de host solicitado y, de forma predeterminada, no termina ni inspecciona el tráfico TLS. La configuración experimental [`network.tlsTerminate`](/docs/es/settings-reference#sandbox-network-tlsterminate), disponible en Claude Code v2.1.199 y posterior, hace que el proxy integrado termine TLS por sí mismo, lo que requieren las entradas de credenciales [`mask`](#mask-credentials). Consulte [Limitaciones de seguridad](#security-limitations) para las implicaciones del comportamiento predeterminado, y [Configuración de proxy personalizado](#custom-proxy-configuration) si su modelo de amenaza requiere inspección de TLS.623 El proxy integrado aplica la lista de permitidos según el nombre de host solicitado y, de forma predeterminada, no termina ni inspecciona el tráfico TLS. El ajuste experimental [`network.tlsTerminate`](/docs/es/settings-reference#sandbox-network-tlsterminate), disponible en Claude Code v2.1.199 y posterior, hace que el proxy integrado termine TLS por sí mismo, lo cual requieren las [entradas de credenciales `mask`](#mask-credentials). Consulta [Limitaciones de seguridad](#security-limitations) para conocer las implicaciones del comportamiento predeterminado, y [Configuración de proxy personalizado](#custom-proxy-configuration) si tu modelo de amenazas requiere inspección de TLS.

576</Note>624</Note>

577 625

626<h4 id="hosts-outside-your-allowed-domains">

627 Hosts fuera de tus dominios permitidos

628</h4>

629

630Cuando un comando en el sandbox se conecta a un host que no está en tus dominios permitidos, el comando permanece en el sandbox y espera una decisión. En una sesión interactiva de terminal, la decisión depende de tu modo de permisos:

631

632| Modo de permisos | Qué sucede con la conexión |

633| :- | :- |

634| Modo `bypassPermissions`, y modo plan con [bypass de permisos disponible](/docs/es/permission-modes#skip-all-checks-with-bypasspermissions-mode) | Se permite sin solicitud |

635| Modo manual, modo `acceptEdits` y modo plan en otros casos | Recibes una solicitud |

636| Modo automático | Se rechaza a menos que el comando [haya listado el host](#per-command-allowed-domains-in-auto-mode) y el clasificador haya aprobado la lista |

637| Modo `dontAsk` | Se rechaza |

638

639Con [`strictAllowlist`](/docs/es/settings-reference#sandbox-network-strictallowlist) o [`allowManagedDomainsOnly`](/docs/es/settings-reference#sandbox-network-allowmanageddomainsonly) activado, el proxy integrado del sandbox rechaza la conexión en todos los modos de permisos. En el modo `bypassPermissions`, los hosts fuera de tus dominios permitidos se permiten a menos que uno de ellos esté activado. [La vía de escape de reintento sin sandbox](#the-unsandboxed-retry-escape-hatch) explica cuándo un comando puede salir del sandbox en ese modo. Una conexión a un host en [`deniedDomains`](/docs/es/settings-reference#sandbox-network-denieddomains) también se rechaza en todos los modos de permisos.

640

641<h4 id="hostnames-that-resolve-to-local-addresses">

642 Nombres de host que se resuelven en direcciones locales

643</h4>

644

645Después de que un nombre de host pasa la lista de permitidos, el proxy del sandbox lo resuelve y rechaza la conexión cuando el nombre se resuelve solo en direcciones locales. Las direcciones locales incluyen direcciones de loopback como `127.0.0.1`, direcciones de enlace local como el endpoint de metadatos en la nube `169.254.169.254`, y direcciones asignadas a tu propia máquina. Los nombres `localhost` y `*.localhost` pueden resolverse en loopback.

646

647Un nombre de host de intranet permitido que se resuelve en un rango privado como `10.0.0.0/8` se conecta. Para permitir que un nombre se resuelva en una dirección rechazada, agrega esa dirección IP a `allowedDomains`, como `"127.0.0.1:8080"`.

648

649La comprobación se aplica a nombres de host. Tus dominios permitidos y tu modo de permisos deciden una conexión a una dirección IP. El proxy también omite la comprobación para las conexiones que envía a través de un proxy corporativo upstream, porque ese proxy resuelve el nombre.

650

578<h4 id="per-command-allowed-domains-in-auto-mode">651<h4 id="per-command-allowed-domains-in-auto-mode">

579 Dominios permitidos por comando en modo automático652 Dominios permitidos por comando en el modo automático

580</h4>653</h4>

581 654

582En [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode) con sandboxing activado, Claude nombra los hosts que un comando necesita en el comando mismo en lugar de desencadenar una aprobación de red para cada conexión. Cada comando Bash, PowerShell o [Monitor](/docs/es/tools-reference#monitor-tool) que se ejecuta en el sandbox puede llevar una lista de hosts más allá de la lista de permitidos del sandbox: un dominio como `registry.npmjs.org`, un comodín como `*.pythonhosted.org`, o una dirección IP, cada uno con un `:port` opcional. El clasificador revisa los hosts junto con el comando. Requiere Claude Code v2.1.271 o posterior.655En el [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode) con el sandboxing activado, Claude indica en el propio comando los hosts que este necesita en lugar de activar una aprobación de red para cada conexión. Cada comando Bash, PowerShell o [Monitor](/docs/es/tools-reference#monitor-tool) que se ejecuta en el sandbox puede llevar una lista de hosts más allá de la lista de permitidos del sandbox: un dominio como `registry.npmjs.org`, un comodín como `*.pythonhosted.org` o una dirección IP, cada uno con un `:port` opcional. El clasificador revisa los hosts junto con el comando. Requiere Claude Code v2.1.271 o posterior.

583 656

584Una lista aprobada abre esos hosts solo para ese comando, mientras se ejecuta. Nada se agrega a los hosts permitidos de su sesión o su configuración; el siguiente comando nombra sus propios hosts.657Una lista aprobada abre esos hosts solo para ese comando, mientras se ejecute. No se agrega nada a los hosts permitidos de tu sesión ni a tu configuración; el siguiente comando indica sus propios hosts.

585 658

586Un comando que lleva hosts va al clasificador en lugar de ser aprobado por una regla de permiso o el [modo de auto-permitir](#sandbox-modes) del sandbox. Si una [regla ask](/docs/es/permissions#manage-permissions) fuerza una solicitud para el comando, el diálogo de permiso en su terminal enumera los hosts junto a él, y aprobar allí cubre ambos.659Un comando que lleva hosts pasa al clasificador en lugar de ser aprobado por una regla de permisos o por el [modo de permiso automático](#sandbox-modes) del sandbox. Si una [regla ask](/docs/es/permissions#manage-permissions) fuerza una solicitud para el comando, el diálogo de permisos en tu terminal enumera los hosts junto a él, y aprobar allí cubre ambos.

587 660

588Una lista por comando amplía solo lo que el sandbox deniega de forma predeterminada. Las entradas [`deniedDomains`](/docs/es/settings-reference#sandbox-network-denieddomains) aún bloquean. Cuando [`strictAllowlist`](/docs/es/settings-reference#sandbox-network-strictallowlist) o [`allowManagedDomainsOnly`](/docs/es/settings-reference#sandbox-network-allowmanageddomainsonly) bloquea la lista de permitidos, Claude Code rechaza listas por comando.661Una lista por comando amplía solo lo que el sandbox deniega de forma predeterminada. Las entradas de [`deniedDomains`](/docs/es/settings-reference#sandbox-network-denieddomains) siguen bloqueando. Cuando [`strictAllowlist`](/docs/es/settings-reference#sandbox-network-strictallowlist) o [`allowManagedDomainsOnly`](/docs/es/settings-reference#sandbox-network-allowmanageddomainsonly) bloquea la lista de permitidos, Claude Code rechaza las listas por comando.

589 662

590Mientras se aplican listas por comando, Claude Code rechaza una conexión a un host que ningún comando aprobado listó, sin una solicitud o una verificación del clasificador. El rechazo nombra el host en el resultado del comando, y Claude vuelve a ejecutar el comando con el host agregado.663Mientras se aplican las listas por comando, Claude Code rechaza una conexión a un host que ningún comando aprobado haya listado, sin solicitud ni comprobación del clasificador. El rechazo indica el host en el resultado del comando, y Claude vuelve a ejecutar el comando con el host agregado.

591 664

592<h4 id="ipv6-addresses-in-domain-lists">665<h4 id="ipv6-addresses-in-domain-lists">

593 Direcciones IPv6 en listas de dominios666 Direcciones IPv6 en listas de dominios

594</h4>667</h4>

595 668

596Las listas de dominios del sandbox son `allowedDomains`, `deniedDomains`, y las reglas `WebFetch(domain:...)` que las alimentan. Para coincidir con una dirección IPv6 en cualquiera de ellas, escriba el literal entre corchetes: `"[::1]"` coincide con esa dirección en cada puerto, y `"[::1]:443"` coincide con ella solo en el puerto 443. Escriba el puerto como un número del 1 al 65535 sin ceros iniciales. La forma entre corchetes requiere Claude Code v2.1.229 o posterior. Antes de v2.1.229, cuando el texto después de los dos puntos finales de una entrada sin corchetes era un número de puerto, Claude Code lo leía como uno, por lo que `::1:443` nombraba la dirección `::1` en el puerto 443.669Para que coincida una dirección IPv6 en `allowedDomains`, `deniedDomains` o una regla `WebFetch(domain:...)`, escribe la dirección entre corchetes: `"[::1]"` coincide con esa dirección en todos los puertos, y `"[::1]:443"` coincide con ella solo en el puerto 443. La forma entre corchetes requiere Claude Code v2.1.229 o posterior.

597 670

598Cuando elige "Sí, y no vuelvas a preguntar" en la solicitud de aprobación de red para una dirección IPv6, Claude Code guarda la regla `WebFetch(domain:...)` con la dirección entre corchetes, por lo que la regla sigue coincidiendo con la dirección en sesiones futuras.671Una entrada sin corchetes como `::1:443` es ambigua entre una dirección y una dirección con un puerto:

599 672

600Una entrada sin corchetes con dos o más dos puntos es ambigua: `::1:443` es tanto una dirección IPv6 completa como una dirección seguida de un puerto. Claude Code aplica deletreos ambiguos de forma conservadora en lugar de adivinar cuál lectura pretendía:673* **Listas de denegación**: Claude Code deniega todas las interpretaciones con las que se puede analizar la entrada, de modo que se bloquea la interpretación que hayas querido decir. Para una entrada sin ninguna interpretación analizable, Claude Code no bloquea nada

674* **Listas de permitidos**: Claude Code nunca permite más de lo que escribiste. Reescribe una entrada ambigua a su interpretación de host y puerto cuando esa interpretación se analiza correctamente, y puede descartar la entrada por completo en lugar de ampliar la lista de permitidos

601 675

602* **Listas de denegación**: Claude Code deniega cada lectura que la entrada analiza, por lo que cualquiera que sea la lectura que pretendía está bloqueada. Para una entrada sin lectura analizable, Claude Code no bloquea nada.676Para encontrar entradas ambiguas, ejecuta `claude doctor` en tu terminal y busca la advertencia `Sandbox network domain entries have unreliable spellings`. Reescribe cada entrada ambigua en la forma entre corchetes.

603* **Listas de permitidos**: Claude Code nunca permite más de lo que escribió. Reescribe una entrada ambigua a su lectura de host-y-puerto cuando esa lectura se analiza limpiamente, y puede descartar la entrada completamente en lugar de ampliar la lista de permitidos.

~~604~~

605Ejecute `claude doctor` en su terminal para encontrar las entradas afectadas: la advertencia `Sandbox network domain entries have unreliable spellings` nombra hasta tres de ellas y cuenta el resto. Reescriba cada una en la forma entre corchetes para borrar la advertencia. La advertencia también nombra entradas cuyo deletreo es poco confiable por otras razones, como `@`, caracteres de ruta o consulta, o comodines dentro de corchetes.

606 677

607<h3 id="os-level-enforcement">678<h3 id="os-level-enforcement">

608 Aplicación a nivel del sistema operativo679 Aplicación a nivel del sistema operativo

609</h3>680</h3>

610 681

611La herramienta Bash aislada utiliza primitivas de seguridad del sistema operativo:682La herramienta Bash en el sandbox usa primitivas de seguridad del sistema operativo:

~~612~~

613* **macOS**: utiliza Seatbelt para la aplicación del sandbox

614* **Linux**: utiliza [bubblewrap](https://github.com/containers/bubblewrap) para el aislamiento

615* **WSL2**: utiliza bubblewrap, igual que Linux

616 683

617WSL1 no es compatible porque bubblewrap requiere características del kernel solo disponibles en WSL2.684* **macOS**: usa Seatbelt para aplicar el sandbox

685* **Linux**: usa [bubblewrap](https://github.com/containers/bubblewrap) para el aislamiento

686* **WSL2**: usa bubblewrap, igual que Linux

618 687

619Estas mismas primitivas están disponibles como el paquete independiente [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropic-experimental/sandbox-runtime), que la página [Sandbox environments](/docs/es/sandbox-environments#sandbox-runtime) cubre como un enfoque separado para envolver todo el proceso de Claude Code.688También puedes ejecutar el paquete [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropics/sandbox-runtime) por sí solo para envolver el proceso de Claude Code. Consulta [Sandbox runtime](/docs/es/sandbox-environments#sandbox-runtime).

620 689

621<h2 id="how-sandboxing-relates-to-permissions-and-permission-modes">690<h2 id="how-sandboxing-relates-to-permissions-and-permission-modes">

622 Cómo se relaciona el sandboxing con los permisos y modos de permiso691 Cómo se relaciona el sandboxing con los permisos y modos de permiso

668El [modo auto-allow](#sandbox-modes) del sandbox es separado del [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode): auto-allow aprueba comandos Bash porque el límite del sandbox los contiene, mientras que el modo automático usa un clasificador para revisar acciones. Los dos funcionan independientemente y pueden combinarse, con las excepciones enumeradas en [Modos sandbox](#sandbox-modes). Para elegir un límite de aislamiento para ejecuciones desatendidas, consulte [Entornos sandbox](/docs/es/sandbox-environments#how-isolation-relates-to-permission-modes). Para una tabla de emparejamientos comunes de modo de permiso y sandbox con los indicadores que inician cada uno, consulte [Configuraciones comunes](/docs/es/permission-modes#common-setups).737El [modo auto-allow](#sandbox-modes) del sandbox es separado del [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode): auto-allow aprueba comandos Bash porque el límite del sandbox los contiene, mientras que el modo automático usa un clasificador para revisar acciones. Los dos funcionan independientemente y pueden combinarse, con las excepciones enumeradas en [Modos sandbox](#sandbox-modes). Para elegir un límite de aislamiento para ejecuciones desatendidas, consulte [Entornos sandbox](/docs/es/sandbox-environments#how-isolation-relates-to-permission-modes). Para una tabla de emparejamientos comunes de modo de permiso y sandbox con los indicadores que inician cada uno, consulte [Configuraciones comunes](/docs/es/permission-modes#common-setups).

669 738

670<h2 id="configure-the-sandbox-for-your-organization">739<h2 id="configure-the-sandbox-for-your-organization">

671 Configurar el sandbox para su organización740 Configurar el sandbox para tu organización

672</h2>741</h2>

673 742

674Los administradores pueden requerir sandboxing para cada usuario, evitar que los desarrolladores amplíen la política y enrutar el tráfico del sandbox a través de un proxy corporativo.743Los administradores pueden requerir sandboxing para cada usuario, evitar que los desarrolladores amplíen la política y enrutar el tráfico del sandbox a través de un proxy corporativo.

677 Aplicar sandboxing con configuración administrada746 Aplicar sandboxing con configuración administrada

678</h3>747</h3>

679 748

680Para requerir el sandbox para cada desarrollador, entregue las claves `sandbox` a través de [configuración administrada](/docs/es/managed-settings#delivery-mechanisms), ya sea como un archivo administrado por su MDM o a través de [configuración administrada por servidor](/docs/es/server-managed-settings) en claude.ai.749Para requerir el sandbox para cada desarrollador, entrega las claves `sandbox` a través de la [configuración administrada](/docs/es/managed-settings#delivery-mechanisms), ya sea como un archivo administrado por tu MDM o a través de la [configuración administrada por servidor](/docs/es/server-managed-settings) en claude.ai.

681 750

682La siguiente configuración de configuración administrada habilita el sandbox, se niega a iniciar Claude Code si el sandbox no puede inicializarse y evita que el modelo reintente comandos fuera del sandbox:751La siguiente configuración administrada habilita el sandbox, se niega a iniciar Claude Code cuando la plataforma no es compatible o falta una dependencia, y evita que el modelo reintente comandos fuera del sandbox:

683 752

684```json theme={null}753```json theme={null}

685{754{

693 762

694Las dos claves más allá de `enabled` controlan qué sucede cuando el sandbox no puede ejecutar un comando:763Las dos claves más allá de `enabled` controlan qué sucede cuando el sandbox no puede ejecutar un comando:

695 764

696* **`failIfUnavailable`**: una dependencia faltante como bubblewrap en Linux bloquea que Claude Code se inicie en lugar de mostrar una advertencia y volver a la ejecución sin aislar765* **`failIfUnavailable`**: una dependencia faltante como bubblewrap en Linux impide que Claude Code se inicie en lugar de volver a la ejecución sin aislar

697* **`allowUnsandboxedCommands: false`**: Claude Code ignora la salida de emergencia `dangerouslyDisableSandbox`, por lo que cuando un comando falla bajo el sandbox, Claude no puede reintentarlo sin aislar766* **`allowUnsandboxedCommands: false`**: Claude Code ignora la salida de emergencia `dangerouslyDisableSandbox`, por lo que cuando un comando falla bajo el sandbox, Claude no puede reintentarlo sin aislar

698 767

699Dos adiciones vale la pena considerar junto con ellas. Agregue `excludedCommands` para cualquier herramienta aprobada por la organización que deba ejecutarse sin aislamiento. Agregue entradas [`sandbox.credentials`](#protect-credentials) para directorios de credenciales como `~/.aws` y `~/.ssh` y para variables de entorno secretas, ya que la política de lectura predeterminada aún las permite.768Considera estas adiciones junto con ellas:

700 769

701Esta configuración aísla los comandos que ejecuta Claude. Un desarrollador aún puede escribir un comando en el [símbolo del sistema del modo shell `!`](/docs/es/interactive-mode#shell-mode-with-prefix) y ejecutarlo fuera del sandbox, con el mismo acceso que ya tienen en cualquier terminal fuera de Claude Code. Consulte [La salida de emergencia de reintento sin aislar](#the-unsandboxed-retry-escape-hatch) para las sesiones donde los comandos escritos se ejecutan aislados.770* Agrega `excludedCommands` para cualquier herramienta aprobada por la organización que deba ejecutarse sin aislamiento, porque esta configuración [impide que la configuración de un repositorio saque comandos del sandbox](#repository-settings-under-an-admin-required-sandbox)

771* Agrega entradas [`sandbox.credentials`](#protect-credentials) para directorios de credenciales como `~/.aws` y `~/.ssh` y para variables de entorno secretas, ya que la política de lectura predeterminada aún las permite

702 772

703El sandbox no se ejecuta en Windows nativo, por lo que si su flota incluye hosts de Windows, limite esta configuración a macOS y Linux o haga que esos usuarios ejecuten Claude Code dentro de WSL2 o un contenedor.773Esta configuración aísla los comandos que ejecuta Claude. Un desarrollador aún puede escribir un comando en el [prompt del modo shell `!`](/docs/es/interactive-mode#shell-mode-with-prefix) y ejecutarlo fuera del sandbox, con el mismo acceso que ya tiene en cualquier terminal fuera de Claude Code. Consulta el [modo de sandbox estricto](#turn-off-the-retry-with-strict-sandbox-mode) para las sesiones donde los comandos escritos se ejecutan aislados.

774

775El sandbox no se ejecuta en Windows nativo, por lo que con `failIfUnavailable` establecido, Claude Code se cierra al iniciar en esas máquinas. Si tu flota incluye hosts de Windows, puedes:

776

777* **Entregar la configuración por sistema operativo**: impleméntala a través de tu MDM o como un [archivo de configuración administrada](/docs/es/managed-settings#delivery-mechanisms) solo en máquinas macOS y Linux. La [configuración administrada por servidor](/docs/es/server-managed-settings#current-limitations) se aplica a todos los usuarios de la organización

778* **Mover a los usuarios de Windows a un entorno compatible**: haz que ejecuten Claude Code dentro de WSL2 o un contenedor

704 779

705<h3 id="keep-developers-from-widening-the-policy">780<h3 id="keep-developers-from-widening-the-policy">

706 Evitar que los desarrolladores amplíen la política781 Evitar que los desarrolladores amplíen la política

707</h3>782</h3>

708 783

709Para claves booleanas como `enabled` y `failIfUnavailable`, Claude Code usa el valor administrado e ignora cualquier cosa que un desarrollador establezca localmente. Para claves de array como `excludedCommands` y `allowRead`, Claude Code fusiona entradas de cada ámbito que carga la sesión, por lo que un desarrollador puede agregar entradas que amplíen la política.784Cuando la configuración administrada establece una clave booleana como `enabled` o `failIfUnavailable`, Claude Code usa el valor administrado e ignora cualquier cosa que un desarrollador establezca localmente. Para claves de array como `allowRead`, Claude Code combina las entradas de los alcances que carga la sesión, por lo que un desarrollador puede agregar entradas que amplíen la política, a menos que un bloqueo cubra esa clave.

785

786A menos que la configuración administrada las establezca, la configuración de usuario de un desarrollador o `--settings` pueden activar las siguientes claves. El `.claude/settings.json` de un repositorio también puede hacerlo, a menos que el sandbox sea [requerido por el administrador](#repository-settings-under-an-admin-required-sandbox). Cada una debilita el sandbox, así que establécela en `false` en la configuración administrada si no quieres que se use:

787

788* [`enableWeakerNestedSandbox`](/docs/es/settings-reference#sandbox-enableweakernestedsandbox)

789* [`enableWeakerNetworkIsolation`](/docs/es/settings-reference#sandbox-enableweakernetworkisolation)

790* [`network.allowAllUnixSockets`](/docs/es/settings-reference#sandbox-network-allowallunixsockets)

791* [`network.allowLocalBinding`](/docs/es/settings-reference#sandbox-network-allowlocalbinding)

792* [`allowAppleEvents`](/docs/es/settings-reference#sandbox-allowappleevents), que un repositorio no puede activar

710 793

711Establezca `allowManagedReadPathsOnly` en `true` en la configuración administrada para que solo se honren las entradas `allowRead` de la configuración administrada. Esto evita que los desarrolladores amplíen el acceso de lectura más allá de las rutas aprobadas por la organización. Para bloquear dominios de red a los valores administrados de la misma manera, establezca [`allowManagedDomainsOnly`](/docs/es/settings-reference#sandbox-network-allowmanageddomainsonly).794Establece `allowManagedReadPathsOnly` en `true` en la configuración administrada para que solo se respeten las entradas `allowRead` de la configuración administrada. Esto evita que los desarrolladores amplíen el acceso de lectura más allá de las rutas aprobadas por la organización.

712 795

713Cuando la configuración administrada configura `sandbox.filesystem` o enumera cualquier entrada `sandbox.credentials.files` con `"mode": "deny"`, solo la configuración administrada puede establecer [`filesystem.disabled`](#disable-filesystem-isolation), por lo que los desarrolladores no pueden desactivar las restricciones de aislamiento del sistema de archivos implementadas por el administrador. Si una entrada `mask` fija la clave depende de cómo se resuelva; la tabla bajo [Qué configuración puede desactivarla](#which-settings-can-disable-it) cubre los cuatro casos.796Para bloquear los dominios de red a los valores administrados de la misma manera, establece [`allowManagedDomainsOnly`](/docs/es/settings-reference#sandbox-network-allowmanageddomainsonly). Con el bloqueo activado, solo la configuración administrada puede establecer un [puerto de proxy](#custom-proxy-configuration).

714 797

715`excludedCommands` no tiene un bloqueo equivalente solo administrado, por lo que un desarrollador siempre puede agregar entradas que ejecuten comandos adicionales fuera del sandbox. Mantenga la lista administrada estrecha.798Cuando la configuración administrada configura `sandbox.filesystem` o enumera cualquier entrada `sandbox.credentials.files` con `"mode": "deny"`, solo la configuración administrada puede establecer [`filesystem.disabled`](#disable-filesystem-isolation), por lo que los desarrolladores no pueden desactivar las restricciones del sistema de archivos implementadas por el administrador. Una entrada `mask` [válida](/docs/es/settings-reference#invalid-credential-entries-in-managed-settings) no bloquea la clave. Consulta [Qué configuración puede desactivarla](#which-settings-can-disable-it).

799

800<h4 id="repository-settings-under-an-admin-required-sandbox">

801 Configuración del repositorio con un sandbox requerido por el administrador

802</h4>

803

804El sandbox es requerido por el administrador mientras uno de estos ajustes esté en vigor:

805

806* [`allowUnsandboxedCommands`](/docs/es/settings-reference#sandbox-allowunsandboxedcommands) establecido en `false` en la configuración administrada, o con el flag `--settings` a menos que la configuración administrada lo establezca en `true`

807* [`allowManagedDomainsOnly`](/docs/es/settings-reference#sandbox-network-allowmanageddomainsonly) establecido en `true` en la configuración administrada

808

809Estos ajustes no activan el sandbox, así que establece también `enabled`.

810

811Mientras el sandbox es requerido por el administrador, Claude Code toma los ajustes que lo flexibilizan solo de la configuración administrada, el flag `--settings` y el `~/.claude/settings.json` de cada desarrollador. Ignora estos ajustes en el `.claude/settings.json` y el `.claude/settings.local.json` de un repositorio:

812

813| Ajuste del repositorio | Lo que Claude Code ignora |

814| :- | :- |

815| `excludedCommands`, `ignoreViolations`, `network.allowedDomains`, `network.allowUnixSockets`, `network.allowMachLookup`, `network.httpProxyPort`, `network.socksProxyPort` | Todas las entradas |

816| `filesystem.allowWrite`, reglas de permiso `Edit(...)`, `permissions.additionalDirectories` | El acceso de escritura que cada entrada otorga a los comandos aislados. Las herramientas de archivos de Claude siguen respetando las reglas `Edit(...)` y los directorios adicionales |

817| Reglas de permiso `WebFetch(domain:...)` | El host que cada regla agrega a la lista de permitidos del sandbox. La herramienta WebFetch sigue respetando la regla |

818| `enableWeakerNestedSandbox`, `enableWeakerNetworkIsolation`, `network.allowAllUnixSockets`, `network.allowLocalBinding` | `true`. Un `false` sigue aplicándose |

819| `enabled`, `failIfUnavailable` | `false`, cuando el `~/.claude/settings.json` del desarrollador establece `true` |

820| `filesystem.allowRead` | Una entrada en o bajo una ruta cuya lectura deniegan la configuración administrada, `--settings` o la configuración de usuario, o un glob que podría coincidir con una |

821

822Estos ajustes siguen aplicándose mientras el sandbox es requerido por el administrador:

823

824* **En los archivos de un repositorio**: las entradas de denegación y el valor de `autoAllowBashIfSandboxed`. Establece la clave en la configuración administrada para evitar que un repositorio la cambie

825* **En la configuración propia de un desarrollador**: los ajustes de la tabla siguen aplicándose desde `~/.claude/settings.json` o `--settings`, a menos que un bloqueo solo administrado como `allowManagedDomainsOnly` los cubra. La mayoría de ellos, como `excludedCommands` y `filesystem.allowWrite`, no tienen un bloqueo solo administrado

826

827La configuración en [Aplicar sandboxing con configuración administrada](#enforce-sandboxing-with-managed-settings) hace que el sandbox sea requerido por el administrador. Agrega a la configuración administrada las entradas de `excludedCommands`, `allowWrite` y sockets que necesitan tus herramientas aprobadas, porque un repositorio no puede proporcionarlas.

828

829Requiere Claude Code v2.1.285 o posterior. De v2.1.282 a v2.1.284, los mismos ajustes hacían que Claude Code ignorara las entradas `excludedCommands` de un repositorio.

830

831<h4 id="locks-that-apply-without-an-admin-required-sandbox">

832 Bloqueos que se aplican sin un sandbox requerido por el administrador

833</h4>

834

835Algunos ajustes hacen que Claude Code ignore las claves del repositorio que sobrescriben directamente una restricción, incluso cuando el sandbox no es requerido por el administrador. Cada uno tiene este efecto solo cuando lo estableces en un archivo que nombra su fila, y los demás ajustes del sandbox del repositorio siguen aplicándose. Requiere Claude Code v2.1.285 o posterior.

836

837| Ajuste | Dónde lo estableces | Lo que Claude Code ignora en la configuración de un repositorio |

838| :- | :- | :- |

839| `network.deniedDomains` o una regla de denegación `WebFetch(domain:...)` | Configuración administrada, `--settings` | `httpProxyPort` y `socksProxyPort` |

840| `network.strictAllowlist` | Configuración administrada, `--settings`, configuración de usuario | Los puertos de proxy, `allowedDomains` y las reglas de permiso `WebFetch(domain:...)` |

841| `filesystem.denyRead`, una regla de denegación `Read(...)` o una entrada `credentials.files` | Configuración administrada, `--settings` | Una entrada `allowRead`, `allowWrite`, de permiso `Edit(...)` o `additionalDirectories` en o bajo una ruta cuya lectura deniegan la configuración administrada, `--settings` o la configuración de usuario, o un glob que podría coincidir con una |

842

843Estos bloqueos cambian lo que pueden alcanzar los comandos aislados. La herramienta WebFetch y las herramientas de archivos de Claude siguen respetando las reglas y los directorios adicionales de un repositorio.

716 844

717<h3 id="custom-proxy-configuration">845<h3 id="custom-proxy-configuration">

718 Configuración de proxy personalizado846 Configuración de proxy personalizado

719</h3>847</h3>

720 848

721Para organizaciones que requieren seguridad de red avanzada, puede implementar un proxy personalizado para:849Para inspeccionar, filtrar o registrar el tráfico del sandbox con tus propias herramientas, reemplaza el proxy integrado del sandbox por un proxy que ejecutes en la misma máquina.

722 850

723* Descifrar e inspeccionar tráfico HTTPS851Para enrutar el tráfico del sandbox a través de un proxy corporativo ubicado en otra parte de tu red, establece `HTTPS_PROXY` en su lugar, como describe la entrada **Proxy corporativo** en [Aislamiento de red](#network-isolation). De esa manera, la lista de permitidos de Claude Code sigue aplicándose.

724* Aplicar reglas de filtrado personalizadas

725* Registrar todas las solicitudes de red

726* Integrar con infraestructura de seguridad existente

727 852

728Para apuntar Claude Code a su proxy, establezca los puertos del proxy en [configuración de sandbox](/docs/es/settings-reference#sandbox-settings):853Para dirigir los comandos aislados a tu proxy, establece los puertos de localhost en los que escucha en la [configuración del sandbox](/docs/es/settings-reference#sandbox-settings):

729 854

730```json theme={null}855```json theme={null}

731{856{

738}863}

739```864```

740 865

866Si estableces un puerto y también estableces `HTTPS_PROXY` o `HTTP_PROXY`, Claude Code no reenvía lo que los comandos aislados envían a tu proxy hacia el proxy que nombran esas variables. Para llegar a un proxy corporativo, configura tu propio proxy para que reenvíe a él.

867

868Qué archivos pueden establecer un puerto depende de tus demás ajustes del sandbox:

869

870* **`allowManagedDomainsOnly` está activado**: solo la configuración administrada

871* **El sandbox es [requerido por el administrador](#repository-settings-under-an-admin-required-sandbox), o se aplica un [bloqueo de red más limitado](#locks-that-apply-without-an-admin-required-sandbox)**: la configuración administrada, `--settings` y la configuración de usuario

872* **En cualquier otro caso**: cualquier archivo de configuración

873

874Claude Code ignora un puerto establecido en cualquier otro lugar. Antes de v2.1.285, cualquier archivo de configuración podía establecer un puerto.

875

876<Warning>

877 Una vez que se aplica cualquiera de los puertos, tu proxy es responsable de filtrar todo lo que se le envía. Los controles de red propios de Claude Code, como `allowedDomains`, `deniedDomains`, `strictAllowlist`, las solicitudes de aprobación y la [verificación de direcciones locales](#hostnames-that-resolve-to-local-addresses), dejan de aplicarse a ese tráfico. Un comando aislado puede conectarse a cualquiera de los dos proxies, así que si estableces solo un puerto, las listas de dominios de Claude Code en el otro proxy no limitan lo que el comando alcanza a través del tuyo.

878</Warning>

879

741<h2 id="troubleshooting">880<h2 id="troubleshooting">

742 Solución de problemas881 Solución de problemas

743</h2>882</h2>

744 883

745Algunos comandos fallan dentro del sandbox aunque funcionen fuera de él. Las correcciones a continuación cubren los casos más comunes.884Algunos comandos fallan dentro del sandbox aunque funcionen fuera de él. Busca el encabezado que coincida con tu síntoma o mensaje de error.

885

886Si el sandbox de tu organización es [obligatorio por parte del administrador](#repository-settings-under-an-admin-required-sandbox), Claude Code ignora los ajustes que mencionan estas correcciones en los archivos de configuración de un proyecto, así que guárdalos en `~/.claude/settings.json`, donde se aplican en todos los proyectos. Si una corrección sigue sin tener efecto, es posible que la configuración administrada de tu organización establezca esa clave.

887

888Una corrección que agrega un patrón a `excludedCommands` quita el sandbox de los comandos que coinciden con el patrón. Consulta [qué puede hacer un comando excluido](#run-commands-outside-the-sandbox-with-excludedcommands).

746 889

747* **Los comandos fallan con un error de host no permitido**: muchas herramientas CLI necesitan alcanzar hosts específicos. Otorgar permiso cuando se solicita agrega el host a su lista de permitidos para que la herramienta se ejecute dentro del sandbox en el futuro.890<h3 id="commands-fail-with-a-host-not-allowed-error">

748* **`jest` se cuelga o falla**: `watchman` es incompatible con el sandbox. Ejecute `jest --no-watchman` en su lugar.891 Los comandos fallan con un error de host no permitido

749* **Las CLI basadas en Go fallan en la verificación de TLS en macOS**: herramientas como `gh`, `gcloud` y `terraform` pueden fallar en la verificación de TLS bajo Seatbelt. Liste estas herramientas en [`excludedCommands`](/docs/es/settings-reference#sandbox-excludedcommands). Si está usando `httpProxyPort` con un proxy MITM y CA personalizado, establezca [`enableWeakerNetworkIsolation`](/docs/es/settings-reference#sandbox-enableweakernetworkisolation) en `true` en su lugar.892</h3>

750* **`open`, `osascript` o los flujos de autenticación basados en navegador fallan con el error `-600` en macOS**: el sandbox bloquea Apple Events de forma predeterminada. Establezca [`allowAppleEvents`](/docs/es/settings-reference#sandbox-allowappleevents) en `true` en su configuración de usuario, administrada o CLI para permitirlos. La configuración del proyecto se ignora para esta clave. Habilitarlo elimina el aislamiento de ejecución de código, ya que los comandos aislados pueden entonces lanzar otras aplicaciones sin aislar sin solicitud del usuario y enviar comandos AppleScript a aplicaciones en ejecución, sujeto a la solicitud de consentimiento de automatización de macOS (TCC). Alternativamente, agregue el comando a [`excludedCommands`](/docs/es/settings-reference#sandbox-excludedcommands).893

751* **Los comandos `docker` fallan**: `docker` es incompatible con el sandbox. Agregue `docker *` a [`excludedCommands`](/docs/es/settings-reference#sandbox-excludedcommands).894Muchas herramientas CLI necesitan alcanzar hosts específicos. Aprueba el host cuando se te solicite, o agrégalo a [`allowedDomains`](/docs/es/settings-reference#sandbox-network-alloweddomains). Si tu organización bloquea la lista de dominios permitidos con `allowManagedDomainsOnly`, no hay solicitud, así que pide a tu administrador que agregue el host.

752* **`pbcopy`, `xclip` o `wl-copy` no actualiza el portapapeles**: estas utilidades de portapapeles pueden fallar al alcanzar el portapapeles del sistema desde dentro del sandbox, en cuyo caso el texto canalizado hacia ellas no llega.

753 895

754 Para poner la salida de Claude en su portapapeles, pida a Claude que la imprima en su respuesta, luego ejecute [`/copy`](/docs/es/commands). `/copy` escribe en el portapapeles desde el proceso Claude Code en lugar de desde un comando aislado.896<h3 id="jest-hangs-or-fails">

897 `jest` se cuelga o falla

898</h3>

755 899

756 Cuando Claude canaliza texto a una de estas herramientas, agregar la herramienta a [`excludedCommands`](/docs/es/settings-reference#sandbox-excludedcommands) no saca esa llamada del sandbox por sí sola.900`watchman` es incompatible con el sandbox. Ejecuta `jest --no-watchman` en su lugar.

757* **Un comando git falla con `unable to unlink old`**: `git merge`, `git checkout` y comandos similares fallan de esta manera cuando necesitan reemplazar un archivo al que el sandbox deniega escrituras, ya sea que ese archivo esté bajo una [ruta protegida](#protected-paths) como `.claude/skills`, bajo una de sus entradas `denyWrite`, o fuera de los directorios en los que el sandbox permite que los comandos escriban en absoluto. En Linux y WSL2 el error termina con `Read-only file system`.

758 901

759 Después de la falla, Claude puede [ofrecer ejecutar nuevamente el comando fuera del sandbox](#the-unsandboxed-retry-escape-hatch); apruebe ese reintento o ejecute el comando git usted mismo en otra terminal. Si ha establecido `allowUnsandboxedCommands` en `false`, Claude no puede ofrecer el reintento, así que ejecute el comando usted mismo. Si el mismo comando git falla a menudo, agréguelo a [`excludedCommands`](/docs/es/settings-reference#sandbox-excludedcommands).902<h3 id="go-based-clis-fail-tls-verification-on-macos">

760* **Bubblewrap falla al iniciarse dentro de un contenedor**: en un contenedor sin privilegios, bubblewrap no puede montar un sistema de archivos `/proc` nuevo, por lo que los comandos aislados fallan con un error `bwrap` como `Can't mount proc on /newroot/proc: Operation not permitted`. Establezca [`enableWeakerNestedSandbox`](/docs/es/settings-reference#sandbox-enableweakernestedsandbox) en `true` para que el sandbox interno monte el `/proc` existente del contenedor en su lugar. Solo use esta configuración cuando el contenedor externo ya proporcione el límite de aislamiento que necesita, ya que expone información de proceso a comandos aislados que un montaje `/proc` nuevo ocultaría.903 Las CLI basadas en Go fallan en la verificación de TLS en macOS

761* **Los archivos de solo lectura de 0 bytes aparecen en las rutas de configuración `.claude`, y "Sí, y no preguntar de nuevo" no guarda**: en Linux y WSL2, el sandbox mantiene una denegación de escritura en un archivo que aún no existe creando un marcador de posición de solo lectura de 0 bytes allí mientras se ejecuta un comando aislado. El sandbox elimina el marcador de posición después. Si una sesión se mata antes de que se ejecute esa limpieza, por ejemplo por SIGKILL, los marcadores de posición permanecen. Las sesiones posteriores los vinculan de solo lectura nuevamente en cada inicio, por lo que una escritura de configuración como guardar una opción de permiso falla donde se encuentra uno.904</h3>

905

906Herramientas como `gh`, `gcloud` y `terraform` pueden fallar en la verificación de TLS bajo [Seatbelt](#os-level-enforcement). Para ejecutar estas herramientas fuera del sandbox, agrega un patrón para cada herramienta, como `gh *`, a [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands). La herramienta se ejecuta entonces con tu acceso completo y sus credenciales almacenadas. Si estás usando `httpProxyPort` con un proxy MITM y CA personalizado, establece [`enableWeakerNetworkIsolation`](/docs/es/settings-reference#sandbox-enableweakernetworkisolation) en `true` en su lugar.

907

908<h3 id="open-osascript-or-browser-based-auth-flows-fail-with-error-600-on-macos">

909 `open`, `osascript` o los flujos de autenticación basados en navegador fallan con el error `-600` en macOS

910</h3>

911

912El sandbox bloquea Apple Events de forma predeterminada. Establece [`allowAppleEvents`](/docs/es/settings-reference#sandbox-allowappleevents) en `true` en tu configuración de usuario, administrada o CLI para permitirlos. Claude Code ignora esta clave en la configuración del proyecto.

913

914Habilitar `allowAppleEvents` elimina el aislamiento de ejecución de código, ya que los comandos aislados pueden entonces lanzar otras aplicaciones sin aislar sin solicitud del usuario, y pueden enviar comandos AppleScript a aplicaciones en ejecución, sujeto a la solicitud de consentimiento de automatización de macOS (TCC). Alternativamente, agrega un patrón como `open *` a [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands). Cada llamada a `open` pasa entonces por el flujo de permisos, y `open` puede lanzar cualquier archivo o aplicación, incluido uno que Claude haya escrito.

915

916<h3 id="docker-commands-fail">

917 Los comandos `docker` fallan

918</h3>

762 919

763 Ejecute `claude doctor` para enumerar los archivos de marcador de posición restantes. La advertencia [`Stale sandbox mask files left by a killed session`](/docs/es/errors#stale-sandbox-mask-files-left-by-a-killed-session) nombra hasta tres de ellos y cuenta el resto. Elimine cada archivo con `rm` mientras no se ejecute ninguna otra sesión de Claude Code en ese proyecto. Antes de v2.1.257, Claude Code dejaba los mismos marcadores de posición sin marcarlos.920`docker` es incompatible con el sandbox. Saca del sandbox los comandos `docker` que necesites con un patrón de `excludedCommands` como `docker compose *`. [Ejecutar comandos fuera del sandbox con `excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands) explica a qué puede acceder un comando `docker` excluido. Un patrón más específico saca menos comandos del sandbox.

764* **`--dangerously-skip-permissions` falla como root**: esta bandera se bloquea cuando se ejecuta como root o a través de sudo en Linux y macOS, porque el acceso root combinado sin solicitudes de permiso puede modificar cualquier archivo o servicio en el sistema. La verificación se omite automáticamente dentro de un sandbox reconocido. Para ejecutar de manera autónoma en un contenedor, use la configuración [contenedor de desarrollo](/docs/es/devcontainer), que ejecuta Claude Code como un usuario no root.921

922<h3 id="pbcopy-xclip-or-wl-copy-doesn’t-update-the-clipboard">

923 `pbcopy`, `xclip` o `wl-copy` no actualiza el portapapeles

924</h3>

925

926Las utilidades de portapapeles `pbcopy`, `xclip` y `wl-copy` pueden fallar al alcanzar el portapapeles del sistema desde dentro del sandbox, en cuyo caso el texto canalizado hacia ellas no llega.

927

928Para poner la salida de Claude en tu portapapeles, pide a Claude que la imprima en su respuesta, luego ejecuta [`/copy`](/docs/es/commands). `/copy` escribe en el portapapeles desde el proceso Claude Code en lugar de desde un comando aislado.

929

930Cuando Claude canaliza texto a una de estas herramientas, agregar la herramienta a [`excludedCommands`](/docs/es/settings-reference#sandbox-excludedcommands) no saca esa llamada del sandbox por sí sola.

931

932<h3 id="a-git-command-fails-with-unable-to-unlink-old">

933 Un comando git falla con `unable to unlink old`

934</h3>

935

936`git merge`, `git checkout` y comandos similares fallan con `unable to unlink old` cuando necesitan reemplazar un archivo al que el sandbox deniega escrituras. En Linux y WSL2 el error termina con `Read-only file system`. El archivo puede estar en uno de estos lugares:

937

938* Bajo una [ruta protegida](#protected-paths) como `.claude/skills`

939* Bajo una de tus entradas `denyWrite`

940* Fuera de los directorios en los que el sandbox permite que los comandos escriban en absoluto

941

942Después de la falla, Claude puede [ofrecer ejecutar nuevamente el comando fuera del sandbox](#the-unsandboxed-retry-escape-hatch). Aprueba ese reintento o ejecuta el comando git tú mismo en otra terminal. Si has establecido `allowUnsandboxedCommands` en `false`, Claude no puede ofrecer el reintento, así que ejecuta el comando tú mismo.

943

944<h3 id="bubblewrap-fails-to-start-inside-a-container">

945 Bubblewrap falla al iniciarse dentro de un contenedor

946</h3>

947

948En un contenedor sin privilegios, [bubblewrap](#os-level-enforcement) no puede montar un sistema de archivos `/proc` nuevo, por lo que los comandos aislados fallan con un error `bwrap` como `Can't mount proc on /newroot/proc: Operation not permitted`. Establece [`enableWeakerNestedSandbox`](/docs/es/settings-reference#sandbox-enableweakernestedsandbox) en `true` para que el sandbox monte mediante bind el `/proc` existente del contenedor en su lugar. Solo usa este ajuste cuando el contenedor externo ya proporcione el límite de aislamiento que necesitas, ya que el ajuste expone información de proceso a comandos aislados que un montaje `/proc` nuevo ocultaría.

949

950<h3 id="0-byte-read-only-files-appear-at-claude-settings-paths-and-yes-and-don’t-ask-again-doesn’t-save">

951 Los archivos de solo lectura de 0 bytes aparecen en las rutas de configuración `.claude`, y "Sí, y no preguntar de nuevo" no guarda

952</h3>

953

954En Linux y WSL2, el sandbox mantiene una denegación de escritura en un archivo que aún no existe creando un marcador de posición de solo lectura de 0 bytes allí mientras se ejecuta un comando aislado. El sandbox elimina el marcador de posición después. Si una sesión se mata antes de que se ejecute esa limpieza, por ejemplo por SIGKILL, los marcadores de posición permanecen. Las sesiones posteriores vuelven a vincular los marcadores de posición como de solo lectura en cada inicio, por lo que una escritura de configuración como guardar una opción de permiso falla en una ruta donde permanece un marcador de posición.

955

956Ejecuta `claude doctor` en tu terminal para enumerar los archivos de marcador de posición restantes. La advertencia [`Stale sandbox mask files left by a killed session`](/docs/es/errors#stale-sandbox-mask-files-left-by-a-killed-session) nombra algunos de ellos y cuenta el resto. Elimina cada archivo con `rm` mientras no se ejecute ninguna otra sesión de Claude Code en ese proyecto. Antes de v2.1.257, Claude Code dejaba los mismos marcadores de posición sin marcarlos.

957

958<h3 id="git-over-ssh-fails-with-the-sandbox-on">

959 `git` sobre SSH falla con el sandbox activado

960</h3>

961

962En macOS, `git fetch`, `git pull` y `git push` contra un remoto SSH fallan dentro del sandbox incluso cuando el host está permitido. En Linux y WSL2, funcionan una vez que el host está permitido. Claude Code canaliza la conexión SSH de git a través del [proxy del sandbox](#network-isolation), y el túnel de macOS no puede autenticarse ante ese proxy.

963

964En Linux y WSL2, revisa lo siguiente si la conexión sigue fallando:

965

966* **El host está permitido en el puerto 22**: una entrada de `allowedDomains` sin puerto, como `"git.example.com"`, lo cubre

967* **Tu proxy corporativo permite el puerto 22**: si tu red requiere un proxy ascendente, el túnel también pasa por él

968* **La clave se puede leer como archivo**: el sandbox puede bloquear el socket de `ssh-agent`, y una entrada `denyRead` o `credentials` para `~/.ssh` oculta tus archivos de clave

969

970En macOS, cambia el remoto a HTTPS, lo que requiere credenciales HTTPS como un token de acceso personal:

971

972```bash theme={null}

973git remote set-url origin https://git.example.com/example-org/example-repo.git

974```

975

976Si tienes que mantener el remoto SSH, saca los comandos de red de git del sandbox con [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands):

977

978```json theme={null}

979{

980 "sandbox": {

981 "excludedCommands": ["git fetch *", "git pull *", "git push *"]

982 }

983}

984```

985

986Estas entradas coinciden con `git push origin main`. Una llamada que agrega un `cd`, usa `git -C` o contiene una sustitución de comandos permanece en el sandbox. Los comandos git excluidos pueden alcanzar cualquier host, no solo los que están en `allowedDomains`.

987

988`ssh`, `scp` y `rsync` sobre SSH por sí solos fallan por la razón que indica [la entrada del cliente de base de datos](#a-database-client-or-other-non-http-tool-fails-to-reach-an-allowed-host).

989

990<h3 id="a-database-client-or-other-non-http-tool-fails-to-reach-an-allowed-host">

991 Un cliente de base de datos u otra herramienta no HTTP no logra alcanzar un host permitido

992</h3>

993

994Una herramienta que ignora las variables de entorno del proxy no puede conectarse desde dentro del sandbox, ni siquiera a un host que esté en `allowedDomains`. Un comando aislado [no tiene una ruta directa a la red](#network-isolation), por lo que una herramienta que abre su propia conexión falla. La mayoría de los controladores de bases de datos, `ssh` por sí solo y las herramientas que usan UDP se comportan de esta manera.

995

996La falla se ve como un error de red o de resolución de nombres:

997

998* **macOS**: `Operation not permitted`, o un error de resolución de nombres como `Could not resolve host`

999* **Linux y WSL2**: `Network is unreachable`, o un error de resolución de nombres como `Temporary failure in name resolution`

1000

1001Una herramienta que usa el proxy falla de otra manera cuando su host no está permitido. Recibes una solicitud de red, o la herramienta recibe una respuesta `403` del proxy.

1002

1003Para permitir que la herramienta se conecte, ejecuta el comando que la necesita fuera del sandbox con [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands). Este ejemplo excluye un script y agrega una [regla ask](/docs/es/permissions) para que apruebes cada ejecución:

1004

1005```json theme={null}

1006{

1007 "sandbox": {

1008 "excludedCommands": ["python scripts/load_orders.py *"]

1009 },

1010 "permissions": {

1011 "ask": ["Bash(python scripts/load_orders.py *)"]

1012 }

1013}

1014```

1015

1016El script se ejecuta con tu acceso completo, y Claude puede editar un script que esté dentro de tu directorio de trabajo, así que revísalo cuando aparezca la solicitud.

1017

1018<h3 id="a-command-fails-to-reach-a-server-on-localhost">

1019 Un comando no logra alcanzar un servidor en localhost

1020</h3>

1021

1022De forma predeterminada, un comando aislado no puede conectarse directamente a un servidor que se ejecuta en tu máquina fuera del sandbox, como un servidor de desarrollo o una base de datos en un contenedor. Lo que puedes cambiar depende de tu plataforma:

1023

1024* **macOS**: establece [`network.allowLocalBinding`](/docs/es/settings-reference#sandbox-network-allowlocalbinding) en `true`. Los comandos aislados pueden entonces escuchar en puertos de red y conectarse a cualquier puerto en localhost, lo que incluye todos los demás servicios que escuchan allí. Un servicio de localhost que no requiere autenticación, como un depurador, puede entonces actuar en nombre del comando fuera del sandbox, y un comando que escucha en una dirección que no es de loopback acepta conexiones de otras máquinas

1025* **Linux y WSL2**: el `localhost` de un comando aislado es privado para ese comando. El comando puede escuchar en un puerto y alcanzar servidores que él mismo inició. Una conexión directa a `localhost` o `127.0.0.1` no alcanza los servidores del host, y `allowLocalBinding` no tiene efecto. Ejecuta el comando que necesita el servidor del host fuera del sandbox con [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands), donde no tiene límites de sistema de archivos ni de red. Para conexiones que pasan por el proxy del sandbox, consulta [Nombres de host que se resuelven en direcciones locales](#hostnames-that-resolve-to-local-addresses)

1026

1027Este ejemplo activa el ajuste para macOS:

1028

1029```json theme={null}

1030{

1031 "sandbox": {

1032 "network": {

1033 "allowLocalBinding": true

1034 }

1035 }

1036}

1037```

1038

1039Una entrada de `allowedDomains` para `localhost` se aplica a las conexiones que pasan por el proxy, por lo que no cambia una conexión directa. Claude Code establece `NO_PROXY` para los comandos aislados de modo que se conecten a `localhost` directamente en lugar de a través del proxy. La entrada también expone todos los puertos del localhost de tu máquina a un comando que sí usa el proxy. Para un nombre de host de desarrollo que apunta a `127.0.0.1`, consulta [Un nombre de host permitido se rechaza con `resolved to a loopback address`](#an-allowed-hostname-is-refused-with-resolved-to-a-loopback-address).

1040

1041<h3 id="an-allowed-hostname-is-refused-with-resolved-to-a-loopback-address">

1042 Un nombre de host permitido se rechaza con `resolved to a loopback address`

1043</h3>

1044

1045El proxy del sandbox rechaza un nombre de host permitido que [se resuelve en una dirección local](#hostnames-that-resolve-to-local-addresses), lo que afecta a nombres de desarrollo como `myapp.test` que apuntan a `127.0.0.1`. El comando ve una respuesta `403` cuyo cuerpo indica el tipo de dirección, como `Connection to myapp.test blocked: resolved to a loopback address`.

1046

1047Agrega la dirección IP en la que se resuelve el nombre junto al nombre de host en `allowedDomains`, cada uno con el puerto en el que escucha tu servidor:

1048

1049```json theme={null}

1050{

1051 "sandbox": {

1052 "network": {

1053 "allowedDomains": ["myapp.test:3000", "127.0.0.1:3000"]

1054 }

1055 }

1056}

1057```

1058

1059Una entrada de dirección IP sin puerto permite que los comandos aislados alcancen todos los servicios que escuchan en esa dirección.

1060

1061Antes de v2.1.284, el proxy se conectaba a cualquier dirección en la que se resolviera un nombre de host permitido.

1062

1063<h3 id="/sandbox-fails-with-sandbox-settings-are-overridden-by-a-higher-priority-configuration">

1064 `/sandbox` falla con `Sandbox settings are overridden by a higher-priority configuration`

1065</h3>

1066

1067`/sandbox` imprime `Error: Sandbox settings are overridden by a higher-priority configuration and cannot be changed locally.` en lugar de abrir su panel cuando un [nivel de configuración](/docs/es/settings#settings-precedence) superior establece `sandbox.enabled`, `sandbox.autoAllowBashIfSandboxed` o `sandbox.allowUnsandboxedCommands`. El panel guarda tus elecciones en `.claude/settings.local.json`, y un valor guardado allí no puede sobrescribir esos niveles.

1068

1069La configuración administrada y `--settings` tienen prioridad sobre la configuración local. Para ver cuáles de ellas cargó esta sesión, ejecuta `/status` y lee la línea `Setting sources`:

1070

1071* **`Command line arguments`**: si iniciaste Claude Code con [`--settings`](/docs/es/settings#change-a-setting-for-one-session), comprueba si el archivo o JSON que pasaste establece una de esas claves. Si es así, cambia el valor allí, o inicia Claude Code de nuevo sin esas claves.

1072* **`Enterprise managed settings`**: la configuración administrada de tu organización está cargada. Si establece una de esas claves, no puedes cambiar esa clave desde `/sandbox` ni desde ningún archivo de configuración que controles, así que consulta a tu administrador.

765 1073

766<h2 id="limitations">1074<h2 id="limitations">

767 Limitaciones1075 Limitaciones

768</h2>1076</h2>

769 1077

770El sandboxing reduce el riesgo pero no es un límite de aislamiento completo. Revise las limitaciones a continuación antes de confiar en él como un control de seguridad duro.1078El sandboxing reduce el riesgo pero no es un límite de aislamiento completo. Revisa las limitaciones a continuación antes de confiar en él como un control de seguridad duro.

771 1079

772<h3 id="security-limitations">1080<h3 id="security-limitations">

773 Limitaciones de seguridad1081 Limitaciones de seguridad

774</h3>1082</h3>

775 1083

776* **Filtrado de red**: el sandbox restringe los dominios a los que se permite que se conecten los procesos. De forma predeterminada, el proxy integrado no termina ni inspecciona TLS en el tráfico saliente, por lo que el contenido de las conexiones cifradas no se examina. La configuración experimental [`network.tlsTerminate`](/docs/es/settings-reference#sandbox-network-tlsterminate) termina TLS en el proxy para [sustitución de credenciales `mask`](#mask-credentials) pero no añade filtrado de contenido. Usted es responsable de asegurarse de que solo se permitan dominios confiables en su política.1084* **Filtrado de red**: el sandbox restringe los dominios a los que se permite que se conecten los procesos. De forma predeterminada, el proxy integrado no termina ni inspecciona TLS en el tráfico saliente, por lo que el contenido de las conexiones cifradas no se examina. El ajuste experimental [`network.tlsTerminate`](/docs/es/settings-reference#sandbox-network-tlsterminate) termina TLS en el proxy para [sustitución de credenciales `mask`](#mask-credentials) pero no añade filtrado de contenido. Eres responsable de asegurarte de que solo se permitan dominios confiables en tu política.

777 1085

778<Warning>1086<Warning>

779 Permitir dominios amplios como `github.com` puede crear caminos para exfiltración de datos. Porque el proxy toma su decisión de permitir del nombre de host suministrado por el cliente sin inspeccionar TLS, el código que se ejecuta dentro del sandbox puede potencialmente usar [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) u técnicas similares para alcanzar hosts fuera de la lista de permitidos. Si su modelo de amenaza requiere garantías más fuertes, configure un [proxy personalizado](#custom-proxy-configuration) que termine TLS e inspeccione tráfico, e instale su certificado CA dentro del sandbox. El aislamiento de red consciente de TLS más fuerte es un área activa de desarrollo.1087 Permitir dominios amplios como `github.com` puede crear caminos para exfiltración de datos. Porque el proxy toma su decisión de permitir del nombre de host suministrado por el cliente sin inspeccionar TLS, el código que se ejecuta dentro del sandbox puede potencialmente usar [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) o técnicas similares para alcanzar hosts fuera de la lista de permitidos. Si tu modelo de amenaza requiere garantías más fuertes, configura un [proxy personalizado](#custom-proxy-configuration) que termine TLS e inspeccione tráfico, e instala su certificado CA dentro del sandbox. El aislamiento de red consciente de TLS más fuerte es un área activa de desarrollo.

780</Warning>1088</Warning>

781 1089

782* **Escalada de privilegios a través de sockets Unix**: la configuración `allowUnixSockets` puede otorgar inadvertidamente acceso a servicios del sistema que podrían llevar a omisiones del sandbox. Por ejemplo, permitir acceso a `/var/run/docker.sock` efectivamente otorga acceso al sistema host a través del socket de Docker. Considere cuidadosamente cualquier socket Unix que permita a través del sandbox.1090* **Escalada de privilegios a través de sockets Unix**: la configuración `allowUnixSockets` puede otorgar inadvertidamente acceso a servicios del sistema que podrían llevar a omisiones del sandbox. Por ejemplo, permitir acceso a `/var/run/docker.sock` efectivamente otorga acceso al sistema host a través del socket de Docker. Considera cuidadosamente cualquier socket Unix que permitas a través del sandbox.

783* **Escalada de permisos del sistema de archivos**: los permisos de escritura del sistema de archivos demasiado amplios pueden permitir ataques de escalada de privilegios. Permitir escrituras en directorios que contienen ejecutables en `$PATH`, directorios de configuración del sistema o archivos de configuración de shell del usuario como `.bashrc` o `.zshrc` puede llevar a ejecución de código en diferentes contextos de seguridad cuando otros usuarios o procesos del sistema acceden a estos archivos.1091* **Escalada de permisos del sistema de archivos**: los permisos de escritura del sistema de archivos demasiado amplios pueden permitir ataques de escalada de privilegios. Permitir escrituras en directorios que contienen ejecutables en `$PATH`, directorios de configuración del sistema o archivos de configuración de shell del usuario como `.bashrc` o `.zshrc` puede llevar a ejecución de código en diferentes contextos de seguridad cuando otros usuarios o procesos del sistema acceden a estos archivos.

784* **Fortaleza del sandbox de Linux**: la implementación de Linux proporciona un fuerte aislamiento del sistema de archivos y la red pero incluye un modo `enableWeakerNestedSandbox` que le permite funcionar dentro de entornos Docker sin espacios de nombres privilegiados, o en hosts Linux donde los espacios de nombres de usuario sin privilegios están deshabilitados por sysctl. Esta opción debilita considerablemente la seguridad y solo debe usarse cuando se aplica aislamiento adicional de otra manera.1092* **Fortaleza del sandbox de Linux**: la implementación de Linux proporciona un fuerte aislamiento del sistema de archivos y la red pero incluye un modo `enableWeakerNestedSandbox` que le permite funcionar dentro de entornos Docker sin espacios de nombres privilegiados. Esta opción debilita considerablemente la seguridad y solo debe usarse cuando se aplica aislamiento adicional de otra manera.

785* **Apple Events en macOS**: el sandbox de macOS bloquea Apple Events de forma predeterminada. La configuración `allowAppleEvents` levanta esta restricción para que herramientas como `open` y `osascript` funcionen, pero elimina el aislamiento de ejecución de código: los comandos aislados pueden lanzar otras aplicaciones sin aislar sin solicitud del usuario, y pueden enviar comandos AppleScript a aplicaciones en ejecución, sujeto al aviso de consentimiento de automatización por aplicación de macOS (TCC). Solo se honra desde configuración de usuario, administrada o CLI. La configuración del proyecto no puede habilitarla.1093* **Apple Events en macOS**: el sandbox de macOS bloquea Apple Events de forma predeterminada. El ajuste `allowAppleEvents` levanta esta restricción para que herramientas como `open` y `osascript` funcionen, pero elimina el aislamiento de ejecución de código: los comandos aislados pueden lanzar otras aplicaciones sin aislar sin solicitud del usuario, y pueden enviar comandos AppleScript a aplicaciones en ejecución, sujeto a la solicitud de consentimiento de automatización por aplicación de macOS (TCC). Solo se honra desde configuración de usuario, administrada o CLI. La configuración del proyecto no puede habilitarlo.

~~786~~

787<h3 id="platform-and-tool-compatibility">

788 Compatibilidad de plataforma y herramienta

789</h3>

~~790~~

791* **Soporte de plataforma**: admite macOS, Linux y WSL2. WSL1 y Windows nativo no son compatibles.

792* **Sobrecarga de rendimiento**: mínima, pero algunas operaciones del sistema de archivos pueden ser ligeramente más lentas.

793* **Compatibilidad de herramienta**: algunas herramientas que requieren patrones de acceso específicos del sistema pueden necesitar ajustes de configuración, o pueden necesitar ejecutarse fuera del sandbox.

794 1094

795<h3 id="scope">1095<h3 id="scope">

796 Alcance1096 Alcance

797</h3>1097</h3>

798 1098

799El sandbox aísla subprocesos Bash. Otras herramientas operan bajo límites diferentes:1099El sandbox aísla los comandos de shell y sus procesos hijos. [Qué se ejecuta fuera del sandbox](#what-runs-outside-the-sandbox) enumera las herramientas y los procesos auxiliares que no cubre. El uso de computadora y los subagentes se relacionan con el sandbox de la siguiente manera:

800 1100

801* **Herramientas de archivo integradas**: Read, Edit y Write usan el sistema de permisos directamente en lugar de ejecutarse a través del sandbox. Consulte [permisos](/docs/es/permissions).1101* **Uso de computadora**: cuando Claude abre aplicaciones y controla tu pantalla, se ejecuta en tu escritorio real en lugar de en un entorno aislado. Las solicitudes de permiso por aplicación controlan cada aplicación. Consulta [uso de computadora en la CLI](/docs/es/computer-use) o [uso de computadora en Desktop](/docs/es/desktop#let-claude-use-your-computer).

802* **Uso de computadora**: cuando Claude abre aplicaciones y controla su pantalla, se ejecuta en su escritorio real en lugar de en un entorno aislado. Las solicitudes de permiso por aplicación controlan cada aplicación. Consulte [uso de computadora en CLI](/docs/es/computer-use) o [uso de computadora en Desktop](/docs/es/desktop#let-claude-use-your-computer).

803* **Variables de entorno**: los comandos Bash aislados heredan el entorno del proceso padre de forma predeterminada, incluidas las credenciales establecidas allí. Use [`sandbox.credentials`](#protect-credentials) para desactivar o enmascarar variables específicas para comandos aislados, o establezca [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/es/env-vars) para eliminar credenciales de todos los subprocesos.

804* **Subagentes**: los [subagentes](/docs/es/sub-agents) se ejecutan en el mismo proceso que la sesión padre y usan la misma configuración de sandbox. Los comandos Bash dentro de un subagente están aislados cuando el sandboxing está habilitado en la sesión padre.1102* **Subagentes**: los [subagentes](/docs/es/sub-agents) se ejecutan en el mismo proceso que la sesión padre y usan la misma configuración de sandbox. Los comandos Bash dentro de un subagente están aislados cuando el sandboxing está habilitado en la sesión padre.

1103* **Mods**: un [mod](/docs/es/plugins/mods/overview) es un plugin que ejecuta su propio código dentro de Claude Code, y un proceso que inicia un mod se ejecuta fuera del sandbox. Consulta [Qué puede alcanzar un mod](/docs/es/plugins/mods/overview#what-a-mod-can-reach).

805 1104

806<Warning>1105<Warning>

807 El sandboxing efectivo requiere tanto aislamiento del sistema de archivos como de la red. Sin aislamiento de red, un agente comprometido podría exfiltrar archivos sensibles como claves SSH. Sin aislamiento del sistema de archivos, ya sea por una política permisiva o por [deshabilitar la capa del sistema de archivos](#disable-filesystem-isolation), un agente comprometido podría instalar una puerta trasera en recursos del sistema para obtener acceso a la red. Cuando amplíe los valores predeterminados, verifique que una ruta `allowWrite`, una entrada `allowedDomains` amplia o una excepción `excludedCommands` no deshaga una restricción en el otro lado.1106 El sandboxing efectivo requiere tanto aislamiento del sistema de archivos como de la red. Sin aislamiento de red, un agente comprometido podría exfiltrar archivos sensibles como claves SSH. Sin aislamiento del sistema de archivos, ya sea por una política permisiva o por [deshabilitar la capa del sistema de archivos](#disable-filesystem-isolation), un agente comprometido podría instalar una puerta trasera en recursos del sistema para obtener acceso a la red. Cuando amplíes los valores predeterminados, verifica que una ruta `allowWrite`, una entrada `allowedDomains` amplia o una excepción `excludedCommands` no deshaga una restricción en el otro lado.

808</Warning>1107</Warning>

809 1108

810<h2 id="see-also">1109<h2 id="see-also">

sandboxing.md 2026-10-01 23:59 UTC to 2026-10-02 13:58 UTC

Configura la herramienta Bash en el sandbox

Qué restringe el sandbox

Qué se ejecuta fuera del sandbox

Primeros pasos

Ejecuta /sandbox

Elige un modo

Ejecuta un comando de Bash

Confirmar que los comandos se ejecutan dentro del sandbox

Configurar Linux y WSL2

Modos del sandbox

Modo auto-allow

Modo de permisos regulares

La vía de escape del reintento fuera del sandbox

Desactivar el reintento con el modo estricto del sandbox

Directorios temporales

Configurar el sandboxing

Ejecutar comandos fuera del sandbox con `excludedCommands`

Desactivar el aislamiento del sistema de archivos

Qué configuraciones pueden desactivarlo

Qué cambia cuando el aislamiento del sistema de archivos está desactivado

Proteger credenciales

Enmascarar credenciales

Enmascarar variables de entorno

Volver a firmar solicitudes de AWS

Enmascarar archivos de credenciales

Cómo funciona el sandboxing

Aislamiento del sistema de archivos

Rutas protegidas

Aislamiento de red

Hosts fuera de tus dominios permitidos

Nombres de host que se resuelven en direcciones locales

Dominios permitidos por comando en el modo automático

Direcciones IPv6 en listas de dominios

Aplicación a nivel del sistema operativo

Cómo se relaciona el sandboxing con los permisos y modos de permiso

Reglas de permiso

Modos de permiso

Configurar el sandbox para tu organización

Aplicar sandboxing con configuración administrada

Evitar que los desarrolladores amplíen la política

Configuración del repositorio con un sandbox requerido por el administrador

Bloqueos que se aplican sin un sandbox requerido por el administrador

Configuración de proxy personalizado

Solución de problemas

Los comandos fallan con un error de host no permitido

`jest` se cuelga o falla

Las CLI basadas en Go fallan en la verificación de TLS en macOS

`open`, `osascript` o los flujos de autenticación basados en navegador fallan con el error `-600` en macOS

Los comandos `docker` fallan

`pbcopy`, `xclip` o `wl-copy` no actualiza el portapapeles

Un comando git falla con `unable to unlink old`

Bubblewrap falla al iniciarse dentro de un contenedor

Los archivos de solo lectura de 0 bytes aparecen en las rutas de configuración `.claude`, y "Sí, y no preguntar de nuevo" no guarda

`git` sobre SSH falla con el sandbox activado

Un cliente de base de datos u otra herramienta no HTTP no logra alcanzar un host permitido

Un comando no logra alcanzar un servidor en localhost

Un nombre de host permitido se rechaza con `resolved to a loopback address`

`/sandbox` falla con `Sandbox settings are overridden by a higher-priority configuration`

Limitaciones

Limitaciones de seguridad

Alcance

Ver también