Saltar al contenido
ai-jail
EnglishPortuguês (Brasil)Españolעברית日本語한국어
Menú
¿Lo necesito?Lo que un agente puede alcanzar en tu máquinaCómo funcionaLas capas entre el agente y tu sistemaCompararSandboxes integrados, Docker y VMsConfigurarAbre solo lo que la tarea necesitaSeguridadEl modelo de amenazas y sus límitesInstalar
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.

Elige cómo instalarloVersiones en GitHub

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.

terminal
brew tap akitaonrails/tap && brew install ai-jail

Funciona en macOS y en Linux.

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.

terminal
pacman -S bubblewrapapt install bubblewrapdnf install bubblewrap

macOS

No hay nada que instalar. ai-jail usa sandbox-exec, que viene con macOS. Apple marca esa interfaz como obsoleta.

Windows

No está soportado. Usa WSL2 y sigue dentro de él los pasos de Linux.

Tu primera ejecución

Tres comandos te llevan del plan a un vistazo por dentro y de ahí a un agente funcionando. ai-jail no abre nada hasta que lo pidas.

Tres paneles de izquierda a derecha. Dry run: la celda es solo un contorno punteado y el agente espera fuera. Echar un vistazo: la celda es sólida y contiene una terminal y la carpeta del proyecto. Ejecutar el agente: el agente y el proyecto están dentro, con dos aberturas en el muro, una para la red y otra para el login del agente. Tu carpeta home queda fuera, tras barrotes, en los tres.
Tu directorio home queda fuera en cada paso. Solo el último paso abre algo, y solo las dos cosas que un agente en la nube necesita.

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

    dry run
    cd ~/Projects/my-appai-jail --dry-run claude

  2. Echa 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 vacío, y los tokens de tu shell ya no están. Escribe exit para salir.

    una shell en la jaula
    ai-jail bash

  3. Ejecuta el agente con las dos cosas que necesita

    Un agente que habla con un modelo en la nube necesita la red para llegar a él, y su propio login guardado para demostrar quién eres. Ambos están apagados por defecto, así que los activas: --network y --agent-state. Desde la versión 1.22, si arrancas un agente conocido sin uno de ellos, ai-jail imprime una advertencia con el nombre del flag que falta.

    la ejecución real
    ai-jail --network --agent-state claude

  4. Déjalo como predeterminado para ese agente

    Pon los dos ajustes en ~/.ai-jail, tu propio archivo de configuración, bajo el nombre del agente. A partir de ahí basta con el comando corto. El archivo .ai-jail que puede aparecer en el proyecto solo puede endurecer la jaula. Nunca puede activar la red ni un login, así que un repositorio que clonas no puede abrirse la jaula a sí mismo.

    ~/.ai-jail
    [commands.claude]network = trueagent_state = true # from now on, in any project:# ai-jail claude

Lo que verás dentro

El prompt cambia a (jail) y el proyecto está donde siempre estuvo. Falta lo que vale la pena robar.

ai-jail bash, en Linux
$ 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-sandbox

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

La vista desde dentro de la celda. El agente está junto a una carpeta de proyecto grande y brillante, con un home vacío y las herramientas del sistema detrás. Fuera de las rejas, atenuados y tras barrotes: las claves SSH, los logins de la nube, otros proyectos y la red.

Desde dentro, el proyecto es lo único tuyo que existe. La red también queda fuera hasta que pases --network.

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:

terminal
echo 'kernel.apparmor_restrict_unprivileged_userns=0' \  | sudo tee /etc/sysctl.d/60-userns.confsudo sysctl --system

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

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

Faltan las herramientas de mise dentro

ai-jail activa mise cuando lo encuentra, pero el home nuevo no tiene ni la configuración de mise ni sus herramientas instaladas, así que omite la activación. Mapea ambas hacia dentro, en solo lectura, desde tu propia configuración:

~/.ai-jail
[commands.claude]ro_maps = ["~/.config/mise", "~/.local/share/mise"]

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.

terminal
ai-jail --no-mise claude

Por agente

ai-jail sabe dónde guarda su login cada agente. --agent-state monta solo las carpetas del agente que arrancas, y solo si existen.

Ejecutas--agent-state montaConviene saber
ai-jail claude~/.claude
~/.claude.json		Para un segundo perfil de Claude, apunta --claude-dir a su directorio.
ai-jail codex~/.codexDespués de redimensionar la ventana, ai-jail le envía a Codex una tecla de redibujado para que la pantalla se repinte.
ai-jail opencode~/.config/opencode
~/.local/share/opencode
ai-jail gemini~/.gemini
ai-jail ai-memory run claudeLas carpetas del agente lanzadoai-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 con crush, grok, jcode, pi, aider, soulforge, omp y los comandos de kimi. Cualquier otro comando también se ejecuta. Recibe la misma jaula y ninguna carpeta de login.

Sigue leyendo

Configurar

Cada flag y cada clave de configuración, y cómo abrir solo lo que la tarea necesita.

Cómo funciona

Las capas entre el agente y tu sistema, en Linux y en macOS.

Seguridad

Qué detiene ai-jail, qué no, y cómo se firman las versiones.

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.

terminal
brew tap akitaonrails/tap && brew install ai-jailai-jail claude
Instalar ai-jailVer en GitHub