Instalações
Funcionam no Linux como estão: os registries e github.com estão na lista padrão. No macOS, libere um, --allow-host registry.npmjs.org, ou abra tudo com --network.
Instalar
Instale, olhe lá dentro, rode o seu agente
O ai-jail é um programa só, sem daemon e sem root. Você instala, coloca o nome dele na frente do comando que já digita, e o agente inicia dentro de um sandbox.
Para quem está no teclado.
Instalar
Escolha o jeito como você já instala ferramentas de linha de comando. Todos os métodos entregam o mesmo programa único, o ai-jail.
brew tap akitaonrails/tap && brew install ai-jailFunciona no macOS e no Linux.
yay -S ai-jail-binyay -S ai-jailO primeiro pacote é um binário pré-compilado para Linux x86_64. O segundo compila a partir do código-fonte.
cargo install --locked ai-jailPrecisa de uma toolchain de Rust. --locked compila com as versões das dependências com que a release foi testada.
nix run github:akitaonrails/ai-jail -- claudenix profile install github:akitaonrails/ai-jailA primeira linha roda um agente sem instalar nada. A segunda instala para o seu usuário. O flake aponta o ai-jail para a cópia de bubblewrap que ele mesmo traz.
ai-jail-linux-x86_64.tar.gzai-jail-macos-aarch64.tar.gzOs arquivos compactados são assinados, com os checksums ao lado. Descompacte um deles e coloque o ai-jail em algum lugar do seu PATH. Como verificar a assinatura está na página de Segurança.
cargo build --release --lockedinstall -Dm755 target/release/ai-jail ~/.local/bin/ai-jailPrecisa do Rust 1.97.1.
O que o seu sistema precisa ter
Linux
Instale o bubblewrap, o programa pequeno que o ai-jail usa para montar o sandbox. A maioria das distribuições empacota como bubblewrap.
pacman -S bubblewrapapt install bubblewrapdnf install bubblewrapmacOS
Nada para instalar. O ai-jail usa o sandbox-exec, que já vem com o macOS. A Apple marca essa interface como obsoleta. Os registries de pacotes não ficam alcançáveis por padrão no macOS: libere um com --allow-host, ou abra a rede com --network.
Windows
Não é suportado. Use o WSL2 e siga os passos de Linux dentro dele.
Sua primeira execução
Três comandos: um plano, uma olhada lá dentro, um agente funcionando. O login já está lá, e o ai-jail abre para você o caminho até o host da API do agente.
↔ Deslize para o lado para ver o diagrama inteiro
Veja o plano sem rodar nada
Vá até o seu projeto e peça um dry run. O ai-jail imprime o comando de sandbox que usaria e sai. Um dry run nunca grava arquivo nenhum.
cd ~/Projects/my-appai-jail --dry-run claudeDê uma olhada lá dentro
Abra um shell comum na jaula. Seu projeto está lá, no caminho real, e você pode editá-lo. Seu diretório home é um novo, e os tokens do seu shell sumiram. Digite
exitpara sair.ai-jail bashRode o agente
O ai-jail monta a pasta de estado do próprio agente por padrão, então ele já está logado. Quando conhece o agente, ele também deixa passar o host da API do próprio agente pelo proxy filtrado:
api.anthropic.compara o Claude Code,api.openai.comechatgpt.compara o Codex,generativelanguage.googleapis.compara o Gemini,api.x.aipara o Grok,server.codeium.compara o Devin, no Linux e no macOS. Os hosts de telemetria continuam fechados. No Linux, as toolchains alcançam por padrão registries de pacotes como crates.io, npm e PyPI, para os builds funcionarem.--networkabre a rede inteira.ai-jail claude# ou, com a rede inteira aberta:ai-jail --network claudeQuando você precisa de mais
Coloque uma lista de hosts em
~/.ai-jail, o seu arquivo de configuração, embaixo do nome do agente. A lista soma ao host da API do próprio agente, que continua liberado, e no Linuxgithub.come os registries de pacotes já estão dentro. Ou use--networkpara a rede inteira. Para uma execução sem login, passe--no-agent-state. O arquivo.ai-jaildentro do projeto só consegue apertar a jaula: pode encurtar a lista de hosts ou a listaforward_portse desligar o login, nunca o contrário, então um repositório que você clona não consegue abrir a jaula para si mesmo.[commands.claude]allow_hosts = ["api.example.com"]# somado ao host da API e aos registries que o ai-jail já libera # ou, só para uma execução:# ai-jail --network claude
O que você vai ver lá dentro
O prompt muda para (jail) e o projeto está onde sempre esteve. Suas toolchains também estão lá, somente leitura. O que valeria a pena roubar não está, menos o login do próprio agente, que está lá de propósito.
$ ai-jail bash# o projeto está no caminho real(jail) ~/Projects/my-app $ pwd/home/you/Projects/my-app# um token exportado no seu shell não veio junto(jail) ~/Projects/my-app $ echo $GITHUB_TOKEN # suas chaves não estão neste home(jail) ~/Projects/my-app $ cat ~/.ssh/id_ed25519cat: /home/you/.ssh/id_ed25519: No such file or directory# a jaula tem hostname próprio(jail) ~/Projects/my-app $ hostnameai-sandboxEsta é uma sessão no Linux. O macOS não tem como montar uma árvore de arquivos separada, então lá os mesmos caminhos existem e a leitura deles é recusada.
↔ Deslize para o lado para ver o diagrama inteiro
Visto de dentro, o projeto é a única coisa sua que você pode alterar. Suas toolchains (mise, cargo, npm e outras) estão lá, somente leitura, com um cache de dependências da própria jaula. A rede fica de fora, exceto o host da API de um agente conhecido e, no Linux, os registries de pacotes de onde essas toolchains baixam, até você liberar um host com --allow-host, uma porta local com --forward-port ou tudo com --network. Como as toolchains são mapeadas.
Quando a jaula bloqueia alguma coisa
Tudo o que o agente inicia roda lá dentro com ele, então o que é bloqueado falha, e nada pergunta a você. É assim que isso aparece, e como enxergar.
- Um arquivo fora do projeto não está lá. No Linux o caminho não existe, no macOS ele existe e a leitura é recusada.
- Um host fora da lista não é alcançado: a conexão falha.
--allow-host HOSTacrescenta o host para a próxima execução. - Uma variável do seu shell chega vazia lá dentro, a menos que você a passe com
--env NAMEou--env-from-file. - Para ver o que foi recusado, adicione
--audit-log: ele registra cada inicialização e cada conexão que o proxy liberou ou negou.ai-jail --audit-showimprime o log. - Para olhar com os próprios olhos,
ai-jail bashabre um shell dentro da mesma jaula.
O que você vai abrir no primeiro dia
Serviços locais
Um banco de dados, um servidor MCP local ou o socket de um editor no loopback da sua máquina: --forward-port 5432 repassa essa única porta no Linux. No macOS, --network.
Git push
Clone e pull do GitHub funcionam no Linux. Um push precisa de uma credencial: --github para o seu token do gh por HTTPS (no macOS, acrescente --allow-host github.com), ou --network --ssh para a sua chave SSH.
Servidores MCP
Eles iniciam dentro da jaula, junto com o agente. Um que lê um token do seu shell não recebe nada até você passar o token, com --env GITHUB_TOKEN ou --env-from-file. Um servidor remoto por HTTP precisa do host dele em --allow-host.
Se ele não iniciar
Estes são os casos cobertos pela seção de troubleshooting do README, mais as duas regras de instalação em que o pessoal costuma tropeçar.
bwrap: setting up uid map: Permission denied
O Ubuntu, a partir do 24.04, e o Debian, a partir do 13, vêm com uma política do AppArmor que impede programas de criar user namespaces sem root, e é assim que o bubblewrap isola a jaula. Isso afeta toda ferramenta rootless desse tipo. Para afrouxar a política no sistema inteiro:
echo 'kernel.apparmor_restrict_unprivileged_userns=0' \ | sudo tee /etc/sysctl.d/60-userns.confsudo sysctl --systemOu mantenha a política e abra exceção só para o bwrap. Salve isto como /etc/apparmor.d/bwrap e depois rode sudo apparmor_parser -r /etc/apparmor.d/bwrap.
abi <abi/4.0>,include <tunables/global>profile bwrap /usr/bin/bwrap flags=(unconfined) { userns,}Seu BWRAP_BIN é recusado
Você pode apontar o ai-jail para um bubblewrap específico com BWRAP_BIN. O ai-jail só aceita quando ele resolve para um programa que pertence ao root e em que outros usuários não podem escrever, ou para um programa num /nix/store multiusuário padrão. Ele recusa uma cópia no seu próprio home, porque quem consegue trocar esse arquivo controla a jaula.
O opencode trava em Starting background server
O opencode 2.x conversa com um servidor compartilhado em segundo plano. A jaula é um wrapper de uma execução só, com um home novo, então esse servidor não sobrevive entre execuções. Inicie o opencode de forma autônoma com --standalone, e fixe isso na sua configuração para não digitar toda vez. O ai-jail avisa na inicialização quando o opencode sobe sem a flag:
[commands.opencode]command = ["opencode", "--standalone"]Failed to create stream fd na inicialização
Isso vem de um script de login do Ubuntu desktop durante a preparação do mise. É inofensivo e o mise continua funcionando. Passe --no-mise para pular a preparação do mise, e a mensagem vai junto.
ai-jail --no-mise claudePor agente
O ai-jail sabe onde cada agente guarda o login e monta por padrão: só as pastas do agente que você inicia, e só se elas existirem. --no-agent-state desliga isso. Quando estiver definida no seu shell, a variável da chave de API desse agente vai junto: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY ou GOOGLE_API_KEY, XAI_API_KEY, MOONSHOT_API_KEY.
Mostrar a tabela por agente
| Você roda | Montado por padrão | Bom saber |
|---|---|---|
ai-jail claude | ~/.claude~/.claude.json | Para um segundo perfil do Claude, aponte --claude-dir para o diretório dele. |
ai-jail codex | ~/.codex | Depois que você redimensiona a janela, o ai-jail envia ao Codex uma tecla de redesenho. No macOS, fora do lockdown, o Codex recebe um ps shim privado; com o estado do agente ligado, recebe também os serviços restritos de que o app server precisa. --no-agent-state remove esses serviços, não o shim. |
ai-jail gemini | ~/.gemini | |
ai-jail opencode | ~/.config/opencode~/.local/share/opencode | Precisa de --standalone. Veja o item de troubleshooting acima. |
ai-jail antigravity | ~/.gemini | Compartilha o login do Google com o Gemini, então um único login serve para os dois. |
ai-jail kimi | ~/.kimi | ~/.kimi-code, o local antigo, também é montado quando existe. |
ai-jail kiro-cli | ~/.kiro~/.local/share/kiro-cli | No macOS, a segunda pasta é ~/Library/Application Support/kiro-cli. |
ai-jail prime-agent | ~/.prime/agent | Só a pasta do próprio agente, nunca o ~/.prime inteiro. |
ai-jail devin | ~/.local/share/devin~/.config/devin | A instalação do próprio CLI, em devin/cli/_versions, continua somente leitura. Atualize o Devin no host e depois inicie uma sessão nova. |
ai-jail ai-memory run claude | As pastas do agente iniciado | O ai-jail reconhece o agente que o ai-memory inicia e aplica as configurações desse agente, com os dois programas na mesma jaula. |
O mesmo vale para crush, grok, jcode, pi, aider, soulforge e omp. Qualquer outro comando também roda, com a mesma jaula e nenhuma pasta de login. O ai-jail abre o host da API por padrão para os cinco agentes do passo 03; os outros agentes precisam de --allow-host ou --network.
Coloque seu agente atrás das grades
O ai-jail é um binário único que não precisa de daemon nem de root. Você acrescenta uma palavra na frente do comando que já usa.
brew tap akitaonrails/tap && brew install ai-jailai-jail claude