SpyBara
Go Premium

sandboxing.md 2026-10-01 23:59 UTC to 2026-10-02 16:57 UTC

This page contains 606 additions and 307 deletions.

2026
Fri 2 18:00

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:

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
1

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.

2

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.

3

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

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

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:

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 en lugar de reemplazar el arreglo de un alcance con el de otro. Claude Code deja una entrada fuera de la combinación cuando la cubre un bloqueo descrito en Evitar que los desarrolladores amplíen la política.

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:

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:

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:

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. Se aplica el primer caso que coincida:

  • 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.

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