O que acontece quando você digita ai-jail claude
O ai-jail monta uma cópia pequena e fechada do seu sistema, coloca o seu projeto nela e inicia o agente lá dentro. Os muros são recursos do próprio sistema operacional, então o agente roda em velocidade total e não consegue desligá-los.
O que acontece na inicialização
Leva um instante, toda vez, e depois nada fica rodando em segundo plano.
Ele lê as suas regras
O ai-jail confia no seu arquivo ~/.ai-jail. Um arquivo .ai-jail dentro do projeto é tratado como não confiável: ele pode apertar o sandbox, nunca abrir. As flags na linha de comando têm prioridade sobre os dois.
Ele monta o sandbox
O ai-jail prepara cada uma das camadas abaixo antes de o agente existir. Se um arquivo de configuração estiver ilegível ou inválido, o ai-jail para, em vez de iniciar com regras mais fracas.
Ele inicia o agente lá dentro
O agente herda os mesmos muros, assim como cada script, pacote e servidor MCP que ele inicia. Quando o agente termina, o ai-jail termina junto.
As camadas, de fora para dentro
O ai-jail não confia em nenhum muro para segurar tudo sozinho. No Linux o agente fica atrás de cinco deles, cada um imposto pelo kernel, mais dois filtros sobre o que entra e o que sai.
Namespaces
bubblewrap- O que é
- Um namespace é o kernel dando a um processo uma visão privada do sistema. O ai-jail pede ao bubblewrap para criá-los. É a mesma ferramenta pequena que o Flatpak usa para isolar apps de desktop, e ela não precisa de root.
- O que barra
- O agente ganha a própria lista de processos, o próprio hostname (
ai-sandbox), nenhum canal de comunicação com os programas do host e nenhuma rede, a menos que você passe--network. Se o ai-jail morrer, tudo lá dentro morre junto.
Sistema de arquivos
montagens- O que é
- Dentro do namespace só existe o que o ai-jail monta. O projeto fica com leitura e escrita no caminho real, diretórios do sistema como
/usrficam somente leitura, e o diretório home e o/tmpsão novos e ficam na memória. - O que barra
~/.ssh,~/.aws,~/.gnupg,~/.dockere os perfis de navegador estão numa lista embutida que nunca é montada. Tudo o que for escrito fora do projeto some quando a sessão termina.
Landlock
kernel 5.13+- O que é
- O Landlock é um recurso do kernel Linux que permite a um processo abrir mão do acesso a arquivos de forma definitiva. O ai-jail usa o Landlock para repetir as regras de sistema de arquivos como uma segunda allowlist dentro do kernel.
- O que barra
- Um erro ou um truque na camada de montagem não basta para alcançar um caminho fora da lista, e o que é somente leitura continua somente leitura. Em kernels antigos demais para o Landlock, o ai-jail avisa e segue com as outras camadas.
seccomp
chamadas de sistema- O que é
- Os programas pedem coisas ao kernel por meio de chamadas de sistema (syscalls). O seccomp é um filtro sobre essas chamadas, e o ai-jail usa esse filtro para recusar as que um agente de código nunca precisa.
- O que barra
- O filtro bloqueia
ptrace,mount,bpf, módulos do kernel,io_uring, o keyring do kernel, raw sockets eTIOCSTI, a chamada que digita teclas num terminal. É uma blocklist de propósito, para que compiladores e runtimes continuem funcionando.
Limites de recursos
rlimits- O que é
- Tetos que o kernel impõe sobre quanto uma árvore de processos pode usar: 4.096 processos e 65.536 arquivos abertos, com core dumps desligados. O modo lockdown baixa esses números para 1.024 e 4.096.
- O que barra
- Uma fork bomb ou um script fora de controle bate no teto dentro da jaula, em vez de travar a sua máquina. O agente não consegue aumentar os limites de volta.
Allowlist de ambiente
o que entra- O que é
- Seu shell está cheio de variáveis, e algumas delas são chaves de API. O ai-jail limpa o ambiente e repassa só uma lista curta:
PATH,HOME,TERM, locale e configurações de proxy e de certificados. - O que barra
- Tokens e credenciais de nuvem exportados no seu shell nunca chegam ao agente. Quando uma tarefa precisa de uma variável, você a repassa pelo nome com
--env.
Proxy de terminal
o que sai- O que é
- O agente roda atrás de um pseudoterminal próprio, e o que ele imprime passa por um parser de terminal antes de chegar à sua tela. O mesmo proxy desenha a barra de status do ai-jail na última linha.
- O que barra
- O proxy filtra as sequências de escape que mexem no seu clipboard ou consultam o seu terminal. Dentro do tmux ou do zellij ele se desliga sozinho, porque terminais aninhados brigam pelo redimensionamento.
No macOS o muro é mais fino
O macOS não tem namespaces, Landlock nem seccomp. O ai-jail transforma a mesma política num perfil para o sandbox-exec, o sandbox embutido da Apple. A documentação do ai-jail diz com todas as letras que isso não equivale ao isolamento do Linux.
| Linux | macOS | |
|---|---|---|
| Backend | bubblewrap, depois Landlock, seccomp e limites de recursos | sandbox-exec com um perfil gerado a cada inicialização. A Apple marcou a ferramenta como obsoleta, e não existe nada melhor sem extensões de kernel. |
| Diretório home | Um home novo, na memória. O seu home real não é montado. | O perfil começa sem nenhuma leitura global e depois libera só os caminhos de que o agente precisa, então o seu home real continua fechado. |
/tmp | Privado, descartado na saída | O /tmp do host, porque não existe mount namespace. TMPDIR aponta para uma pasta privada criada para aquela inicialização, e esse é o único caminho temporário liberado. |
| Mapeamentos copy-on-write | --overlay-map deixa o agente escrever numa cópia | Tratado como um mapeamento somente leitura |
| Rede | Desligada por padrão, num network namespace próprio | Desligada por padrão. No lockdown fica sempre bloqueada, mesmo com --network. |
| Outros programas | Invisíveis: lista de processos própria, sem IPC do host | Mach, IOKit e IPC do host são negados, a menos que você passe --macos-host-ipc |
Por que essas peças
O ai-jail escreve o mínimo possível de código de segurança próprio. Ele comanda o bubblewrap, que é pequeno, vem empacotado em todas as grandes distribuições e é exercitado todo dia pelo Flatpak, e acrescenta recursos do kernel por cima.
| Opção | Por que não |
|---|---|
| Firejail | Dá conta do trabalho, mas é um binário setuid root, e várias CVEs vêm desse design. O bubblewrap funciona sem root. |
| Reescrever o bubblewrap em Rust | Mais de 500 linhas de código sensível de segurança para manter e corrigir sozinho, tudo para evitar uma dependência de uns 50 KB que recebe correções do upstream. |
| nsjail | Capaz, mas feito para servidores, configurado por arquivos protobuf e empacotado em menos distribuições. |
| systemd-nspawn | Exige o systemd, então falha dentro de containers e em sistemas sem ele. |
Pequeno o bastante para ler
A ferramenta inteira é um único programa síncrono em Rust, sem runtime assíncrono, daemon ou imagem de container.
- 1
- binário para instalar
- 8
- dependências diretas
- 720
- testes unitários no código-fonte
- 19
- testes que tentam escapar de um sandbox real
Contado no repositório do ai-jail na versão 1.22.0.
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