Cerrada por defecto. Los interruptores son tuyos.
Sin opciones, el agente recibe solo tu proyecto, sin red, sin login y sin claves. Abres lo que la tarea necesita, un interruptor a la vez, y también puedes cerrar más la jaula.
Tres lugares de donde puede venir un ajuste
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.
.ai-jail del proyecto
ai-jail lo trata como no confiable: puede endurecer la jaula y nunca abrirla. ai-jail nunca lo sigue a través de un symlink, y el agente ve un archivo vacío en su lugar.
~/.ai-jail global
Es 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.
Flags 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 = trueagent_state = trueenv_pass = ["ANTHROPIC_BASE_URL"]mask = ["*.pem"]Los interruptores
Cada fila está apagada hasta que lo pidas, y 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.
Red y servicios
| Flag | Clave de configuración | Qué hace | Riesgo |
|---|---|---|---|
--network | network = true | Acceso a la red sin restricciones. Todo lo que el agente puede leer, lo puede enviar fuera. | 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 |
Agente y entorno
| Flag | Clave de configuración | Qué hace | Riesgo |
|---|---|---|---|
--agent-state | agent_state = true | El login y los ajustes del propio agente, como ~/.claude o ~/.codex. Cualquier cosa dentro de la jaula puede entonces usar esas credenciales. | Abre una cosa |
--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. Se puede repetir y nunca se guarda en disco. | 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 |
Escritorio y hardware
| 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 |
--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 |
Archivos
| 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. |
Capas que puedes apagar, y no deberías
| 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.
Utilidades
| 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.
Oculta los secretos dentro del proyecto
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.
--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.
--deny-path <PATH|GLOB>
Convierte cada coincidencia en un error de permisos.
--mask-except y --deny-path-except
Vuelven 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/"]Lockdown: que un agente lea código que no debe cambiar
--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.
Qué cambia
- El proyecto se monta en solo lectura
- En Linux solo
/tmpes escribible. En macOS, nada - Sin directorios ocultos de tu home, sin mapeos extra, sin overlays
- El entorno se limpia y
PATHqueda fijado a los directorios del sistema - Landlock es obligatorio: si no se puede aplicar, el arranque falla
- Límites más estrictos de procesos, archivos abiertos y tamaño de archivo
- Sin pantalla, audio, GPU, Docker, agente SSH ni mise, pases lo que pases
ai-jail --lockdown claudeRecetas
Copia una. Para ver qué construye, ejecútala primero con --dry-run.
Un agente en la nube, a diario
Un modelo alojado necesita la red para llegar a su API y su propio login para autenticarse. Pon ambos en el archivo global y el comando sigue siendo corto.
# una vez, en ~/.ai-jail[commands.claude]network = trueagent_state = true # después, en cualquier proyectoai-jail claudeGit push por SSH
--ssh monta ~/.ssh en solo lectura y reenvía el socket de tu agente SSH. Para hacer push también hace falta la red.
ai-jail --network --ssh --agent-state claudeToolchains de mise
El directorio home nuevo no tiene ninguna instalación de mise, así que ai-jail omite mise. Mapea hacia dentro los dos directorios de mise, en solo lectura.
[commands.claude]ro_maps = ["~/.config/mise", "~/.local/share/mise"]Un navegador para el agente
--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 chromiumPerfiles de Claude separados
Manté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 refactor arriesgado sobre una copia
Un 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 --agent-state --overlay-map ~/Projects/my-app/src claudeTus configs antiguas siguen sirviendo
La 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_landlock, no_seccomp, no_rlimits. Por eso --gpu se guarda como no_gpu = false. Los más nuevos usan nombres directos como network = true.
Pon a tu agente tras las rejas
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