Sin opciones, el agente recibe tu proyecto, tus herramientas de compilación en Linux, su propio login y el host de su propia API, y ninguna red más allá de eso y de una lista corta de registries de paquetes. Vas apagando cosas interruptor por interruptor, y lockdown cierra la mayoría de golpe.
Para la persona que está al teclado.
Los ajustes vienen de un archivo dentro del proyecto, de un archivo en tu directorio home y de los flags que escribes. Están ordenados de menor a mayor autoridad.
↔ Desliza hacia un lado para ver el diagrama completo
.ai-jail del proyectoai-jail lo trata como no confiable: puede endurecer la jaula y nunca abrirla. Puede recortar una lista allow_hosts o forward_ports y nunca añadirle nada. ai-jail nunca lo sigue a través de un symlink, y el agente ve un archivo vacío en su lugar.
~/.ai-jail globalEs tuyo, así que ai-jail confía en él. Contiene una tabla base para todas las ejecuciones, más tablas [commands.<name>] que se eligen por la primera palabra del comando.
Los flags tienen la mayor autoridad. La mayoría de los interruptores vienen en pares, como --network y --no-network, así que un flag también puede cerrar lo que un archivo abrió.
En una tabla de comando, los valores simples reemplazan a los de la base y las listas, como los mapeos y las máscaras, se suman a ella.
# base: se aplica a todos los comandoshide_dotdirs = [".my_secrets"]mask = [".env", ".env.*"] # solo cuando el comando empieza con "claude"[commands.claude]network = trueenv_pass = ["ANTHROPIC_BASE_URL"]mask = ["*.pem"]Cada fila está apagada hasta que lo pidas, salvo las dos filas cian, que vienen activadas por defecto. Cada flag de capacidad tiene un gemelo --no- que la vuelve a cerrar. Una etiqueta roja marca un interruptor que debilita la jaula. Seguridad tiene la lista completa y los motivos.
| Flag | Clave de configuración | Qué hace | Riesgo |
|---|---|---|---|
--network | network = true | Toda la red. Todo lo que el agente pueda leer, puede enviarlo fuera. Si el agente solo necesita unos pocos hosts, --allow-host es más estricto. Sin ninguno de los dos flags, el sandbox alcanza solo el host de la API de un agente conocido y, en Linux, los registries de paquetes que las toolchains abren a través del proxy; --no-network cierra ambas cosas. | Debilita la jaula |
--allow-host <HOST> | allow_hosts = [...] | El sandbox alcanza solo el host de la lista y sus subdominios, por TCP a través del proxy integrado de ai-jail. Puedes repetir el flag. Desde 2.8.1 la lista se suma al valor por defecto, así que un agente conocido conserva el host de su propia API. No se puede combinar con --network ni con --browser, y un archivo de proyecto solo puede recortar la lista. | Abre una cosa |
--forward-port <PORT> | forward_ports = [...] | Un puerto del loopback del host, reenviado al loopback propio del sandbox. Un servidor MCP local, un socket del editor o una base de datos de desarrollo en el 127.0.0.1 del host responde en el mismo puerto dentro, y todos los demás puertos del host siguen cerrados. Repite el flag para más puertos. Solo Linux, y se rechaza con --network y para puertos por debajo de 1024. Funciona con --allow-host y bajo --lockdown. El servicio detrás del puerto es de confianza por completo, sin lista de permitidos ni registro de auditoría. Un archivo de proyecto solo puede recortar la lista. Dónde va forward_ports en el archivo de configuración. | Debilita la jaula |
--ssh | ssh = true | Tu ~/.ssh, en solo lectura, y el socket de tu agente SSH, para que git push funcione. | Abre una cosa |
--docker | no_docker = false | El socket de Docker. En la práctica es root en tu máquina, porque el daemon puede arrancar contenedores que montan el host. | Debilita la jaula |
--tailscale | tailscale = true | El socket de Tailscale. | Abre una cosa |
--systemd-user | systemd_user = true | El bus de usuario de systemd. El agente puede pedirle a tu gestor de usuario que ejecute servicios en el host. Solo Linux. | Debilita la jaula |
| Flag | Clave de configuración | Qué hace | Riesgo |
|---|---|---|---|
--agent-state | agent_state = true | El login del propio agente. El estado del harness que arrancas, como ~/.claude, ~/.codex o los ~/.local/share/devin y ~/.config/devin de Devin, se monta en lectura y escritura, y su clave de API se copia de tu shell si está definida: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY o GOOGLE_API_KEY, XAI_API_KEY, MOONSHOT_API_KEY. El agente arranca con la sesión iniciada, y cualquier cosa dentro de la jaula puede usar ese login. --no-agent-state da una ejecución sin sesión. Apagado bajo lockdown, y un archivo de proyecto solo puede apagarlo. | Activado por defecto |
--claude-dir <PATH> | claude_dir = "..." | Usa el directorio indicado como estado de Claude y define CLAUDE_CONFIG_DIR. | Abre una cosa |
--env <NAME[=VALUE]> | ninguna | Pasa una variable de tu shell, o define una con NAME=VALUE. Repetible y nunca se guarda en disco. En Linux los valores viajan al sandbox por un archivo en memoria y nunca aparecen en la línea de comandos del lanzador, pero un NAME=VALUE literal sigue siendo visible en la línea de comandos del propio ai-jail, así que para un secreto prefiere --env NAME o --env-from-file. | Abre una cosa |
--env-from-file <PATH> | env_from_file = [...] | Lee líneas KEY=VALUE estrictas de un archivo y las pasa como --env, que gana si hay conflicto. El archivo tiene que ser tuyo, un archivo regular, con modo 0600 o más estricto y fuera del proyecto, o el arranque falla. ai-jail nunca guarda los valores en disco, y la clave de configuración solo funciona desde el archivo global. | Abre una cosa |
--secret <KEY=host> | secret_hosts = { ... } | Mantiene el valor real de KEY fuera del sandbox. El agente ve un marcador de posición (placeholder), y el proxy pone el valor real solo en las peticiones a ese único host. Necesita --allow-host, y la clave tiene que entrar ya por --env o --env-from-file. Solo en el archivo global, nunca se guarda. Cubre a los clientes que pueden hablar HTTP plano con el proxy para ese host; los túneles HTTPS no se tocan. | Abre una cosa |
--inherit-env | inherit_env = true | Pasa todo el entorno de tu shell, con cada secreto que contenga. Evítalo. | Debilita la jaula |
| ninguna | env_pass = ["NAME"] | Lo mismo que --env, solo desde el archivo global. Si un archivo de proyecto la define, se ignora. | Abre una cosa |
| Flag | Clave de configuración | Qué hace | Riesgo |
|---|---|---|---|
--toolchains | no_toolchains = false | Tus compiladores y gestores de paquetes en solo lectura, sus cachés de dependencias en un almacén propio de la jaula, y los registries de paquetes accesibles a través del proxy filtrado. Solo en Linux, y allí activado por defecto; en macOS no se mapea nada y ningún registry es accesible. Lockdown lo apaga, y un archivo de proyecto solo puede apagarlo. Detalles más abajo. | Activado por defecto |
--github | github = true | Tu directorio de configuración de gh, en solo lectura, más tu token activo de github.com reenviado como GH_TOKEN para ese arranque, así que gh tiene la sesión iniciada aunque el token viva en el llavero del sistema. ai-jail ejecuta gh auth token en el host y pasa el resultado por un archivo en memoria, nunca por una línea de comandos ni por disco; --dry-run nunca lo obtiene, y un GH_TOKEN que pases con --env se salta la consulta. Solo github.com y solo la cuenta activa. Cualquier cosa dentro de la jaula puede seguir actuando como tú en GitHub. | Abre una cosa |
--aws | aws = true | Tu ~/.aws, en solo lectura. Cualquier cosa dentro de la jaula puede actuar como tú en AWS mientras la credencial siga siendo válida. | Abre una cosa |
--kube | kube = true | Tu ~/.kube, en solo lectura. Cualquier cosa dentro de la jaula puede hablar con tus clústeres como tú. | Abre una cosa |
--gcloud | gcloud = true | Tu ~/.config/gcloud, en solo lectura. Cualquier cosa dentro de la jaula puede actuar como tú en Google Cloud. | Abre una cosa |
--docker-config | docker_config = true | Tu ~/.docker/config.json, en solo lectura, que guarda tus logins de registries. Cualquier cosa dentro de la jaula puede usarlos. | Abre una cosa |
| Flag | Clave de configuración | Qué hace | Riesgo |
|---|---|---|---|
--gpu | no_gpu = false | Los dispositivos de GPU y, con ellos, la superficie de ataque del driver. Solo Linux. | Abre una cosa |
--kvm | kvm = true | /dev/kvm, para máquinas virtuales con aceleración por hardware como QEMU o un emulador de Android. Expone la interfaz KVM del kernel del host. Los guests solo tienen la red del sandbox, y ningún dispositivo tun ni vhost. Solo Linux. | Abre una cosa |
--display | no_display = false | El socket de Wayland y nada más de tu sesión. Solo Linux. | Abre una cosa |
--x11 | x11 = true | El socket de X11. X11 permite que un programa registre pulsaciones de teclas y tome capturas de pantalla. | Debilita la jaula |
--audio | audio = true | Los sockets de PipeWire y PulseAudio y /dev/snd. Cualquier cosa dentro de la jaula puede grabar y reproducir audio. Solo Linux. | Abre una cosa |
--host-shm | host_shm = true | El /dev/shm del host, que abre memoria compartida con procesos de fuera de la jaula. | Abre una cosa |
--pictures | pictures = true | Tu ~/Pictures, en solo lectura. | Abre una cosa |
--browser[=hard|soft] | browser_profile = "hard" | Un perfil de navegador aparte. hard (el valor por defecto) no conserva nada entre ejecuciones, soft conserva un perfil en ~/.local/share/ai-jail/browsers. | Abre una cosa |
| Flag | Clave de configuración | Qué hace | Riesgo |
|---|---|---|---|
--map <PATH|SOURCE:DEST> | ro_maps = [...] | Monta una ruta más en solo lectura. Escribe SOURCE:DEST para montarla en otro lugar. Se puede repetir. | Abre una cosa |
--rw-map <PATH|SOURCE:DEST> | rw_maps = [...] | Monta una ruta más en lectura y escritura. Se puede repetir. | Abre una cosa |
--overlay-map <PATH> | overlay_maps = [...] | Monta una ruta en copy-on-write: las escrituras del agente van a una capa aparte y el original queda intacto. Solo Linux; en macOS pasa a ser un montaje de solo lectura. | Abre una cosa |
--hide-dotdir <NAME> | hide_dotdirs = [...] | Nunca monta el directorio oculto indicado, por ejemplo .my_secrets. Se puede repetir. |
| Flag | Clave de configuración | Qué hace | Riesgo |
|---|---|---|---|
--no-landlock | no_landlock = true | Apaga Landlock, la copia de las reglas de archivos que tiene el propio kernel. Con --lockdown se rechaza. | Debilita la jaula |
--no-seccomp | no_seccomp = true | Apaga el filtro que bloquea las llamadas al sistema peligrosas. | Debilita la jaula |
--no-rlimits | no_rlimits = true | Apaga los límites que frenan los procesos desbocados. | Debilita la jaula |
--no-private-home | private_home = false | Renuncia al directorio home nuevo. Es un acceso amplio a tu home real. Mejor usa --map para la única ruta que necesitas. | Debilita la jaula |
Cómo funciona explica qué hace cada capa.
| Flag | Clave de configuración | Qué hace | Riesgo |
|---|---|---|---|
--audit-log | audit_log = true | Añade un registro por arranque a ~/.local/share/ai-jail/history.jsonl (directorio 0700, archivo 0600): hora, comando, capacidades efectivas, fuentes de configuración, código de salida y duración. Con --allow-host, también registra cada conexión permitida o denegada, y con --secret, cada inyección. Cada línea lleva el hash de la anterior. Está apagado por defecto, y un archivo de proyecto puede apagarlo pero no activarlo. | Abre una cosa |
--audit-show | ninguna | Imprime un resumen legible del registro y termina: arranques, decisiones de la red filtrada y sustituciones de secretos. No comprueba la cadena. Sale con 0 tras mostrarlo, 1 si hay registros malformados o un error de lectura, 2 si no hay registro. Los registros por arranque pueden incluir los argumentos del comando, así que deja los secretos fuera de ellos. | |
--audit-verify | ninguna | Recorre la cadena de hashes del registro de auditoría y termina: 0 si está intacta, 1 en el primer eslabón roto, 2 si no hay registro. Los registros escritos antes de la 2.2 se reportan como legacy, lo cual no es un error. |
| Flag | Qué hace |
|---|---|
--dry-run | Imprime el comando de sandbox y no ejecuta nada. Nunca escribe un archivo de configuración. |
--init | Escribe o actualiza el .ai-jail del proyecto y termina. |
--clean | Ignora el .ai-jail del proyecto en esta ejecución. |
--bootstrap | Genera configuraciones de permisos para las propias herramientas de IA. |
status | Muestra la configuración actual de .ai-jail. |
-v, --verbose | Muestra cada montaje mientras se construye la jaula. |
Ejecuta ai-jail --help para ver el resto: la barra de estado, los worktrees, mise y las opciones de terminal. La clave de las toolchains está invertida como las más antiguas: no_toolchains = true las apaga.
Tu archivo .env vive en el proyecto, y el proyecto se puede leer y escribir. Con la red activada, el agente puede enviar fuera todo lo que pueda leer ahí. Enmascarar le quita esos archivos.
↔ Desliza hacia un lado para ver el diagrama completo
--mask <PATH|GLOB>Reemplaza cada coincidencia por un marcador vacío. El agente ve que el archivo existe y no recibe contenido, así que las herramientas que solo comprueban su existencia siguen funcionando. La máscara cambia solo lo que ve el sandbox. Un ayudante en el host que actúa por el agente, como el daemon de Docker o un servidor MCP, sigue leyendo el archivo real.
--deny-path <PATH|GLOB>Convierte cada coincidencia en un error de permisos.
--mask-except y --deny-path-exceptVuelven a sacar una ruta de una regla. Debilitan la protección, así que un archivo de proyecto no puede definirlos.
# pon los globs entre comillas para que ai-jail reciba el patrón y no la expansión de tu shellai-jail --mask .env --mask '.env.*' --mask '*.pem' --deny-path secrets/ claude ai-jail --mask '.env.*' --mask-except .env.example claude# un archivo de proyecto puede endurecer, así que esto también funciona en el repositoriomask = [".env", ".env.*", "*.pem"]deny_paths = ["secrets/"]Enmascarar cubre los archivos del proyecto. Para la clave del propio agente, pásala desde tu shell con --env NAME, o desde un archivo que solo tú puedes leer con --env-from-file. Ninguna de las dos se escribe nunca en un archivo .ai-jail, y un archivo de proyecto no puede definirlas. Con la salida filtrada activada, --secret KEY=host además mantiene el valor real fuera del sandbox; la receta de abajo lo muestra.
# el archivo tiene que ser tuyo, con modo 0600 y fuera del proyectochmod 600 ~/.secrets/claude.envai-jail --env-from-file ~/.secrets/claude.env claude# solo en el archivo global; si un archivo de proyecto lo define, se ignora[commands.claude]env_from_file = ["~/.secrets/claude.env"]Un build necesita compiladores, gestores de paquetes y sus cachés. En Linux, ai-jail los trae por defecto: las herramientas en solo lectura, las cachés en un almacén propio de la jaula, y los registries de paquetes accesibles a través del proxy filtrado.
↔ Desliza hacia un lado para ver el diagrama completo
Desde la 2.4.1, ai-jail mapea las instalaciones y la configuración de mise en solo lectura. Para Rust mapea ~/.cargo/bin y ~/.rustup del mismo modo, para que cargo y rustc se resuelvan. Las credenciales de Cargo y su config.toml se quedan fuera. Como mise no puede instalar nada en un mapeo de solo lectura, ai-jail define MISE_NOT_FOUND_AUTO_INSTALL=false dentro, así que una herramienta que falta falla una sola vez y no en cada llamada.
Las cachés de dependencias viven en ~/.local/share/ai-jail/cache/ y sobreviven entre sesiones. Ahí van las cachés de registry y de git de Cargo. También la caché por defecto de pip, uv, Go, npm, yarn, pnpm, bun, deno, Maven, Gradle, Coursier, Composer, Crystal y Zig, cuando el directorio de esa herramienta existe en tu máquina.
Con las toolchains activadas y sin ningún flag de red, el sandbox alcanza crates.io, npm, PyPI, el proxy de Go, Maven Central, Clojars, Packagist y github.com, cada uno con sus subdominios, a través del mismo proxy que --allow-host. El host de la API de un agente conocido pasa por la misma vía, también en macOS; los registries son solo para Linux.
# el valor por defecto en Linuxai-jail claude # cachés activadas, sin red de ningún tipoai-jail --no-network claude # nada mapeado, nada accesibleai-jail --no-toolchains --no-network claudeEl valor por defecto está pensado para trabajar. Cada paso de abajo cierra una cosa más, y --lockdown cierra la mayoría de golpe. Seguridad explica de qué protege cada uno.
--no-network: completamente sin conexión. Junto con una lista de --allow-host, el sandbox alcanza solo los hosts que nombres, sin los valores por defecto automáticos.--no-agent-state: sin login. El estado del harness se queda fuera y su clave de API no se copia.--no-toolchains: sin cachés de dependencias y sin registries de paquetes.--mask, --deny-path y --hide-dotdir quitan rutas sueltas, y un --map o --rw-map estrecho sustituye a un permiso amplio. Cambian lo que ve el sandbox; un ayudante en el host, como el daemon de Docker o un servicio detrás de --forward-port, sigue leyendo los archivos reales.--lockdown: el proyecto en solo lectura, sin login, sin toolchains, sin registries, Landlock y seccomp estrictos, y sigue sin ser una VM.--lockdown es para revisiones y auditorías. El agente puede leer el proyecto y responder preguntas sobre él, pero no puede cambiar ni un archivo.
↔ Desliza hacia un lado para ver el diagrama completo
/tmp es escribible. En macOS, nadaPATH queda fijado a los directorios del sistemaai-jail --lockdown claudeCopia una. Para ver qué construye, ejecútala primero con --dry-run.
Un agente conocido arranca con la sesión iniciada y alcanza el host de su propia API a través del proxy filtrado, más los registries de paquetes en Linux. Cuando una tarea necesite más, pon allow_hosts en el archivo global con los hosts extra, o abre toda la red con network = true.
# nada que añadir: el login y api.anthropic.com vienen por defectoai-jail claude # cuando una tarea necesite más, una vez en ~/.ai-jail (se suma al host de la API y, en Linux, a los registries)[commands.claude]allow_hosts = ["api.example.com"]# o abre toda la red: network = trueai-jail permite el host de la API por sí solo para cinco agentes. Cualquier otro agente recibe su host de ti con --allow-host. Si el host falta en la lista, el aviso de arranque lo nombra.
ai-jail --allow-host api.example.com myagent# un agente conocido no necesita flag: ai-jail permite su host de la API por sí soloCuando el agente no debe tener ninguna credencial, --no-agent-state deja fuera su directorio de estado y su clave de API. Arranca sin sesión, y cualquier login que haga dentro del home nuevo desaparece cuando termina la ejecución.
ai-jail --no-agent-state claudeLa lista se aplica a cada ejecución de ese comando, además del host de la propia API del agente. En Linux, github.com y los registries de paquetes ya son accesibles, así que solo los listas en macOS. Un host permitido es de confianza por completo: el agente puede pedirle cualquier cosa que tus credenciales ahí permitan.
[commands.claude]allow_hosts = ["api.example.com"]Sin --network el sandbox tiene su propio loopback, así que un servidor en el 127.0.0.1 de tu host queda fuera de alcance. --forward-port reenvía ese único puerto y nada más, en Linux. En el archivo global, pon forward_ports bajo la tabla del comando y nunca en la tabla base: el flag se rechaza con --network, que --browser normalmente implica, y en macOS, así que una entrada en la base haría fallar esos arranques.
ai-jail --forward-port 49374 claude # o una vez en ~/.ai-jail, bajo la tabla del comando[commands.claude]forward_ports = [49374]El sandbox recibe un marcador de posición en ANTHROPIC_API_KEY, y el proxy de ai-jail pone la clave real solo en las peticiones a api.anthropic.com. El cliente tiene que enviar HTTP plano al proxy para ese host, y la URL base http:// hace justo eso; ai-jail lleva después la petición al host real por TLS. Un cliente que solo abre túneles HTTPS sigue funcionando, sin sustitución.
# la clave vive en el archivo 0600; el sandbox solo ve AIJAIL-PHANTOM-...ai-jail --allow-host api.anthropic.com \ --env-from-file ~/.secrets/claude.env \ --secret ANTHROPIC_API_KEY=api.anthropic.com \ --env ANTHROPIC_BASE_URL=http://api.anthropic.com claude--ssh monta ~/.ssh en solo lectura y reenvía el socket de tu agente SSH. No abre la red, por eso la receta lo combina con --network. Para hacer push por HTTPS con tu token de gh, mira la receta del CLI de GitHub.
ai-jail --network --ssh claudeNada que añadir en Linux. cargo build, npm install o go get descargan de los registries a través del proxy y guardan en el almacén propio de la jaula, y las instalaciones de mise vienen en solo lectura. Para una ejecución que no toque nada ni llegue a nada, apaga ambas cosas.
# por defecto en Linux: cachés activadas, registries accesibles a través del proxyai-jail claude # nada mapeado, nada accesibleai-jail --no-toolchains --no-network claude--github monta tu directorio de configuración de gh en solo lectura y reenvía tu token activo de github.com como GH_TOKEN, así que gh y git push por HTTPS tienen la sesión iniciada, con llavero o sin él. En Linux, github.com y sus subdominios ya están en la lista por defecto, así que no añades ningún host; en macOS añade --allow-host github.com. Cualquier cosa dentro de la jaula puede entonces actuar en GitHub como tú.
ai-jail --github claude # macOS: ahí github.com no está en la lista por defectoai-jail --github --allow-host github.com claude--browser por sí solo da un navegador que no puede cargar una página ni abrir una ventana. En Linux también necesita --network y --display, y un navegador X11 necesita --x11 en lugar de --display.
# Waylandai-jail --browser=soft --network --display chromium# X11ai-jail --browser=soft --network --x11 chromiumMantén separados el login del trabajo y el personal apuntando cada ejecución a su propio directorio de Claude.
ai-jail --network --claude-dir ~/.claude-work claudeUn overlay guarda las escrituras del agente en una capa aparte, bajo .ai-jail-overlays en el proyecto. Después compárala con el original y quédate con lo que te guste. Solo Linux.
ai-jail --network --overlay-map ~/Projects/my-app/src claudeLa compatibilidad hacia atrás es una regla del proyecto: nunca se elimina un flag ni una clave de configuración. Las claves desconocidas se ignoran y las que faltan toman su valor por defecto, así que un archivo escrito para una versión antigua todavía carga.
Los interruptores más antiguos conservan sus nombres invertidos, donde true apaga la cosa: no_gpu, no_docker, no_display, no_mise, no_toolchains, no_landlock, no_seccomp, no_rlimits. Por eso --gpu se guarda como no_gpu = false. Los más nuevos usan nombres directos como network = true. --allow-tcp-port todavía se parsea y todavía se niega a arrancar, porque no puede vallar UDP. Su error apunta a --allow-host.
ai-jail es un único binario que no necesita daemon ni root. Añades una palabra delante del comando que ya usas.
brew tap akitaonrails/tap && brew install ai-jailai-jail claude