Instalaciones
En Linux funcionan tal cual: los registries y github.com están en la lista por defecto. En macOS añade uno, --allow-host registry.npmjs.org, o ábrelo todo con --network.
Instalar
Instálalo, mira dentro, ejecuta tu agente
ai-jail es un solo programa, sin daemon y sin root. Lo instalas, pones su nombre delante del comando que ya escribes y el agente arranca dentro de un sandbox.
Para la persona que está al teclado.
Instalar
Elige la forma en que ya instalas tus herramientas de línea de comandos. Todos los métodos te dan el mismo y único programa ai-jail.
brew tap akitaonrails/tap && brew install ai-jailFunciona en macOS y en Linux.
yay -S ai-jail-binyay -S ai-jailEl primer paquete es un binario precompilado para Linux x86_64. El segundo compila desde el código fuente.
cargo install --locked ai-jailNecesita una toolchain de Rust. --locked compila con las versiones de dependencias con las que se probó la versión publicada.
nix run github:akitaonrails/ai-jail -- claudenix profile install github:akitaonrails/ai-jailLa primera línea ejecuta un agente sin instalar nada. La segunda instala para tu usuario. El flake hace que ai-jail use su propia copia de bubblewrap.
ai-jail-linux-x86_64.tar.gzai-jail-macos-aarch64.tar.gzLos archivos comprimidos están firmados y traen sus checksums al lado. Descomprime uno y pon ai-jail en algún lugar de tu PATH. Cómo verificar la firma está en la página de Seguridad.
cargo build --release --lockedinstall -Dm755 target/release/ai-jail ~/.local/bin/ai-jailNecesita Rust 1.97.1.
Lo que necesita tu sistema
Linux
Instala bubblewrap, el pequeño programa que ai-jail usa para construir el sandbox. La mayoría de las distribuciones lo empaquetan como bubblewrap.
pacman -S bubblewrapapt install bubblewrapdnf install bubblewrapmacOS
No hay nada que instalar. ai-jail usa sandbox-exec, que viene con macOS. Apple marca esa interfaz como obsoleta. En macOS los registries de paquetes no son accesibles por defecto: añade uno con --allow-host, o abre la red con --network.
Windows
No está soportado. Usa WSL2 y sigue dentro de él los pasos de Linux.
Tu primera ejecución
Tres comandos: un plan, un vistazo dentro, un agente funcionando. El login ya está dentro, y ai-jail abre por ti la ruta al host de la API del agente.
↔ Desliza hacia un lado para ver el diagrama completo
Mira el plan sin ejecutar nada
Ve a tu proyecto y pide un dry run, una simulación. ai-jail imprime el comando de sandbox que usaría y termina. Un dry run nunca escribe un archivo.
cd ~/Projects/my-appai-jail --dry-run claudeEcha un vistazo dentro
Arranca una shell simple en la jaula. Tu proyecto está ahí, en su ruta real, y puedes editarlo. Tu directorio home es uno nuevo, y los tokens de tu shell ya no están. Escribe
exitpara salir.ai-jail bashEjecuta el agente
ai-jail monta por defecto la carpeta de estado del propio agente, así que ya tiene la sesión iniciada. Cuando conoce al agente, también deja pasar el host de la API del propio agente por su proxy filtrado:
api.anthropic.compara Claude Code,api.openai.comychatgpt.compara Codex,generativelanguage.googleapis.compara Gemini,api.x.aipara Grok,server.codeium.compara Devin, en Linux y en macOS. Los hosts de telemetría siguen cerrados. En Linux, las toolchains alcanzan por defecto registries de paquetes como crates.io, npm y PyPI, así que las compilaciones funcionan.--networkabre en cambio toda la red.ai-jail claude# o, con toda la red abierta:ai-jail --network claudeCuando necesites más
Pon una lista de hosts en
~/.ai-jail, tu propio archivo de configuración, bajo el nombre del agente. La lista se suma al host de la propia API del agente, que sigue permitido, y en Linuxgithub.comy los registries de paquetes ya están dentro. O usa--networkpara toda la red. Para una ejecución sin sesión, pasa--no-agent-state. Un archivo.ai-jaildentro del proyecto solo puede endurecer la jaula: puede recortar la lista de hosts o la listaforward_portsy apagar el login, nunca lo contrario, así que un repositorio que clones no puede abrir la jaula por su cuenta.[commands.claude]allow_hosts = ["api.example.com"]# se suma al host de la API y a los registries que ai-jail ya permite # o, para una sola ejecución:# ai-jail --network claude
Lo que verás dentro
El prompt cambia a (jail) y el proyecto está donde siempre estuvo. Tus toolchains también están ahí, en solo lectura. Falta lo que vale la pena robar, salvo el login del propio agente, que está ahí a propósito.
$ ai-jail bash# el proyecto está en su ruta real(jail) ~/Projects/my-app $ pwd/home/you/Projects/my-app# un token exportado en tu shell no vino contigo(jail) ~/Projects/my-app $ echo $GITHUB_TOKEN # tus claves no están en este home(jail) ~/Projects/my-app $ cat ~/.ssh/id_ed25519cat: /home/you/.ssh/id_ed25519: No such file or directory# la jaula tiene su propio hostname(jail) ~/Projects/my-app $ hostnameai-sandboxEsta es una sesión de Linux. macOS no tiene forma de construir un árbol de archivos aparte, así que ahí las mismas rutas existen y se deniega su lectura.
↔ Desliza hacia un lado para ver el diagrama completo
Desde dentro, el proyecto es lo único tuyo que puedes cambiar. Tus toolchains (mise, cargo, npm y otras) están ahí, en solo lectura, con una caché de dependencias propia de la jaula. La red se queda fuera, salvo el host de la API del propio agente conocido y, en Linux, los registries de paquetes de los que esas toolchains descargan, hasta que abras un host con --allow-host, un puerto local con --forward-port o toda la red con --network. Cómo se mapean las toolchains.
Cuando la jaula bloquea algo
Todo lo que el agente arranca corre dentro con él, así que lo bloqueado falla, y nada te pregunta. Así se ve, y así puedes comprobarlo.
- Un archivo fuera del proyecto no está. En Linux la ruta no existe; en macOS existe y se deniega su lectura.
- Un host fuera de la lista no se puede alcanzar: la conexión falla.
--allow-host HOSTlo añade para la siguiente ejecución. - Una variable de tu shell está vacía dentro, salvo que la pases con
--env NAMEo--env-from-file. - Para ver qué se denegó, añade
--audit-log: registra cada arranque y cada conexión que el proxy permitió o denegó.ai-jail --audit-showlo imprime. - Para mirar tú mismo,
ai-jail bashabre una shell dentro de la misma jaula.
Lo que abrirás el primer día
Servicios locales
Una base de datos, un servidor MCP local o el socket de un editor en el loopback de tu máquina: --forward-port 5432 reenvía ese único puerto en Linux. En macOS, --network.
Git push
Clonar y hacer pull desde GitHub funciona en Linux. Un push necesita una credencial: --github para tu token de gh por HTTPS (en macOS añade --allow-host github.com), o --network --ssh para tu clave SSH.
Servidores MCP
Arrancan dentro de la jaula con el agente. Uno que lee un token de tu shell no recibe nada hasta que se lo pases, --env GITHUB_TOKEN o --env-from-file. Uno remoto por HTTP necesita su host en --allow-host.
Si no arranca
Estos son los casos que cubre la sección de problemas del README, más las dos reglas de configuración con las que la gente tropieza.
bwrap: setting up uid map: Permission denied
Ubuntu 24.04 y posteriores y Debian 13 y posteriores traen una política de AppArmor que impide a los programas crear user namespaces sin root, que es como bubblewrap aísla la jaula. Afecta a todas las herramientas sin root de este tipo. Relájala para todo el sistema:
echo 'kernel.apparmor_restrict_unprivileged_userns=0' \ | sudo tee /etc/sysctl.d/60-userns.confsudo sysctl --systemO conserva la política y exime solo a bwrap. Guarda esto como /etc/apparmor.d/bwrap y luego ejecuta sudo apparmor_parser -r /etc/apparmor.d/bwrap.
abi <abi/4.0>,include <tunables/global>profile bwrap /usr/bin/bwrap flags=(unconfined) { userns,}Tu BWRAP_BIN es rechazado
Puedes apuntar ai-jail a un bubblewrap concreto con BWRAP_BIN. ai-jail lo acepta solo cuando resuelve a un programa propiedad de root que otros usuarios no pueden escribir, o a uno en un /nix/store multiusuario estándar. Rechaza una copia en tu propio home, porque quien pueda reemplazar ese archivo controla la jaula.
opencode se queda colgado en Starting background server
opencode 2.x habla con un servidor en segundo plano compartido. La jaula es un wrapper de un solo uso con un home nuevo, así que ese servidor no sobrevive entre ejecuciones. Arranca opencode de forma autónoma con --standalone, y fíjalo en tu configuración para no escribirlo cada vez. ai-jail avisa al arrancar cuando opencode se inicia sin él:
[commands.opencode]command = ["opencode", "--standalone"]Failed to create stream fd al arrancar
Viene de un script de inicio de sesión de Ubuntu desktop durante la preparación de mise. Es inofensivo y mise sigue funcionando. Pasa --no-mise para omitir la preparación de mise y, con ella, el mensaje.
ai-jail --no-mise claudePor agente
ai-jail sabe dónde guarda su login cada agente y lo monta por defecto: solo las carpetas del agente que arrancas, y solo si existen. --no-agent-state lo apaga. Si está definida en tu shell, la variable con la clave de API de ese agente también entra: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY o GOOGLE_API_KEY, XAI_API_KEY, MOONSHOT_API_KEY.
Mostrar la tabla por agente
| Ejecutas | Montado por defecto | Conviene saber |
|---|---|---|
ai-jail claude | ~/.claude~/.claude.json | Para un segundo perfil de Claude, apunta --claude-dir a su directorio. |
ai-jail codex | ~/.codex | Después de redimensionar la ventana, ai-jail envía a Codex una tecla de redibujado. En macOS, fuera de lockdown, Codex recibe un ps shim privado; con el estado del agente activado, recibe también los servicios limitados que necesita su app server. --no-agent-state elimina esos servicios, no el shim. |
ai-jail gemini | ~/.gemini | |
ai-jail opencode | ~/.config/opencode~/.local/share/opencode | Necesita --standalone. Mira el punto de arriba en "Si no arranca". |
ai-jail antigravity | ~/.gemini | Comparte su login de Google con Gemini, así que una sola sesión sirve para los dos. |
ai-jail kimi | ~/.kimi | ~/.kimi-code, la ubicación antigua, también se monta cuando existe. |
ai-jail kiro-cli | ~/.kiro~/.local/share/kiro-cli | En macOS la segunda carpeta es ~/Library/Application Support/kiro-cli en su lugar. |
ai-jail prime-agent | ~/.prime/agent | Solo la carpeta del propio agente, nunca todo ~/.prime. |
ai-jail devin | ~/.local/share/devin~/.config/devin | La instalación propia del CLI bajo devin/cli/_versions se queda en solo lectura. Actualiza Devin en el host y después abre una sesión nueva. |
ai-jail ai-memory run claude | Las carpetas del agente lanzado | ai-jail reconoce al agente que lanza ai-memory y aplica los ajustes de ese agente, con ambos programas en una sola jaula. |
Lo mismo funciona para crush, grok, jcode, pi, aider, soulforge y omp. Cualquier otro comando también corre, con la misma jaula y sin carpeta de login. ai-jail abre el host de la API por defecto para los cinco agentes del paso 03; los demás agentes necesitan --allow-host o --network.
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