Fechado por padrão. Quem liga é você.
Sem nenhuma opção, o agente recebe só o seu projeto, sem rede, login ou chaves. Você abre o que a tarefa precisa, uma opção de cada vez, e também pode fechar a jaula ainda mais.
Três lugares de onde vem uma configuração
As configurações vêm de um arquivo dentro do projeto, de um arquivo no seu diretório home e das flags que você digita. A lista vai da menor para a maior autoridade.
.ai-jail do projeto
O ai-jail trata esse arquivo como não confiável: ele pode apertar a jaula, nunca abrir. O ai-jail nunca o segue através de um symlink, e o agente vê um arquivo vazio no lugar dele.
~/.ai-jail global
É seu, então o ai-jail confia nele. Ele guarda uma tabela base para todas as execuções, mais tabelas [commands.<name>] escolhidas pela primeira palavra do comando.
Flags de linha de comando
As flags têm a maior autoridade. A maioria das opções vem em pares, como --network e --no-network, então uma flag também fecha o que um arquivo abriu.
Numa tabela de comando, valores simples substituem os da base, e listas como mapeamentos e máscaras são somadas a ela.
# base: vale para todos os comandoshide_dotdirs = [".my_secrets"]mask = [".env", ".env.*"] # só quando o comando começa com "claude"[commands.claude]network = trueagent_state = trueenv_pass = ["ANTHROPIC_BASE_URL"]mask = ["*.pem"]As opções
Cada linha fica desligada até você pedir, e cada flag de recurso tem uma gêmea --no- que fecha de novo. Um selo vermelho marca uma opção que enfraquece a jaula. Segurança tem a lista completa e os motivos.
Rede e serviços
| Flag | Chave de configuração | O que faz | Risco |
|---|---|---|---|
--network | network = true | Acesso irrestrito à rede. Tudo o que o agente consegue ler, ele consegue enviar para fora. | Enfraquece a jaula |
--ssh | ssh = true | O seu ~/.ssh, somente leitura, e o socket do seu agente SSH, para o git push funcionar. | Abre uma coisa |
--docker | no_docker = false | O socket do Docker. Na prática é root na sua máquina, porque o daemon pode subir containers que montam o host. | Enfraquece a jaula |
--tailscale | tailscale = true | O socket do Tailscale. | Abre uma coisa |
--systemd-user | systemd_user = true | O barramento de usuário do systemd. O agente pode pedir ao seu gerenciador de usuário para rodar serviços no host. Só no Linux. | Enfraquece a jaula |
Agente e ambiente
| Flag | Chave de configuração | O que faz | Risco |
|---|---|---|---|
--agent-state | agent_state = true | O login e as configurações do próprio agente, como ~/.claude ou ~/.codex. A partir daí, tudo o que roda na jaula pode usar essas credenciais. | Abre uma coisa |
--claude-dir <PATH> | claude_dir = "..." | Usa o diretório informado como estado do Claude e define CLAUDE_CONFIG_DIR. | Abre uma coisa |
--env <NAME[=VALUE]> | nenhuma | Repassa uma variável do seu shell, ou define uma com NAME=VALUE. Pode ser repetida e nunca é salva em disco. | Abre uma coisa |
--inherit-env | inherit_env = true | Repassa o ambiente inteiro do seu shell, com todos os segredos que houver nele. Evite. | Enfraquece a jaula |
| nenhuma | env_pass = ["NAME"] | O mesmo que --env, só a partir do arquivo global. Um arquivo de projeto que defina essa chave é ignorado. | Abre uma coisa |
Desktop e hardware
| Flag | Chave de configuração | O que faz | Risco |
|---|---|---|---|
--gpu | no_gpu = false | Os dispositivos de GPU, e com eles a superfície de ataque do driver. Só no Linux. | Abre uma coisa |
--display | no_display = false | O socket do Wayland e mais nada da sua sessão. Só no Linux. | Abre uma coisa |
--x11 | x11 = true | O socket do X11. O X11 permite que um programa capture teclas e tire screenshots. | Enfraquece a jaula |
--audio | audio = true | Os sockets do PipeWire e do PulseAudio e o /dev/snd. Tudo o que roda na jaula pode gravar e reproduzir áudio. Só no Linux. | Abre uma coisa |
--host-shm | host_shm = true | O /dev/shm do host, que abre memória compartilhada com processos de fora da jaula. | Abre uma coisa |
--pictures | pictures = true | O seu ~/Pictures, somente leitura. | Abre uma coisa |
--browser[=hard|soft] | browser_profile = "hard" | Um perfil de navegador separado. hard (o padrão) não guarda nada entre execuções, soft mantém um perfil em ~/.local/share/ai-jail/browsers. | Abre uma coisa |
Arquivos
| Flag | Chave de configuração | O que faz | Risco |
|---|---|---|---|
--map <PATH|SOURCE:DEST> | ro_maps = [...] | Monta mais um caminho como somente leitura. Escreva SOURCE:DEST para montar em outro lugar. Pode ser repetida. | Abre uma coisa |
--rw-map <PATH|SOURCE:DEST> | rw_maps = [...] | Monta mais um caminho com leitura e escrita. Pode ser repetida. | Abre uma coisa |
--overlay-map <PATH> | overlay_maps = [...] | Monta um caminho em copy-on-write: o que o agente escreve vai para uma camada à parte e o original fica intacto. Só no Linux; no macOS vira uma montagem somente leitura. | Abre uma coisa |
--hide-dotdir <NAME> | hide_dotdirs = [...] | Nunca monta o diretório oculto indicado, por exemplo .my_secrets. Pode ser repetida. |
Camadas que você pode desligar, e não deveria
| Flag | Chave de configuração | O que faz | Risco |
|---|---|---|---|
--no-landlock | no_landlock = true | Desliga o Landlock, a cópia das regras de arquivo que fica no próprio kernel. É recusada com --lockdown. | Enfraquece a jaula |
--no-seccomp | no_seccomp = true | Desliga o filtro que bloqueia chamadas de sistema perigosas. | Enfraquece a jaula |
--no-rlimits | no_rlimits = true | Desliga os limites que seguram processos fora de controle. | Enfraquece a jaula |
--no-private-home | private_home = false | Abre mão do diretório home novo. É acesso amplo ao seu home real. Prefira --map para o único caminho de que você precisa. | Enfraquece a jaula |
Como funciona explica o que cada camada faz.
Utilitários
| Flag | O que faz |
|---|---|
--dry-run | Imprime o comando de sandbox e não roda nada. Nunca grava arquivo de configuração. |
--init | Grava ou atualiza o .ai-jail do projeto e sai. |
--clean | Ignora o .ai-jail do projeto nesta execução. |
--bootstrap | Gera configurações de permissão para as próprias ferramentas de IA. |
status | Mostra a configuração atual do .ai-jail. |
-v, --verbose | Mostra cada montagem enquanto a jaula é construída. |
Rode ai-jail --help para ver o resto: a barra de status, worktrees, mise e opções de terminal.
Esconda segredos dentro do projeto
Seu arquivo .env mora no projeto, e o projeto tem leitura e escrita. Com a rede ligada, o agente pode enviar para fora o que conseguir ler ali. Mascarar tira esses arquivos do alcance dele.
--mask <PATH|GLOB>
Substitui cada arquivo que bate com o padrão por um placeholder vazio. O agente vê que o arquivo existe e não recebe conteúdo nenhum, então ferramentas que só checam a existência dele continuam funcionando.
--deny-path <PATH|GLOB>
Transforma cada caminho que bate com o padrão num erro de permissão.
--mask-except e --deny-path-except
Tiram um caminho de dentro de uma regra. Elas enfraquecem a proteção, então um arquivo de projeto não pode defini-las.
# coloque os globs entre aspas para o ai-jail receber o padrão, e não a expansão do seu shellai-jail --mask .env --mask '.env.*' --mask '*.pem' --deny-path secrets/ claude ai-jail --mask '.env.*' --mask-except .env.example claude# um arquivo de projeto pode apertar, então isto também funciona no repositóriomask = [".env", ".env.*", "*.pem"]deny_paths = ["secrets/"]Lockdown: o agente lê o código e não pode alterar nada
--lockdown serve para revisões e auditorias. O agente lê o projeto e responde perguntas sobre ele, mas não consegue alterar nenhum arquivo.
O que muda
- O projeto é montado como somente leitura
- Só o
/tmpé gravável no Linux. No macOS, nada é - Nenhum diretório oculto do seu home, nenhum mapeamento extra, nenhum overlay
- O ambiente é limpo e o
PATHfica fixo nos diretórios do sistema - O Landlock é obrigatório: se não puder ser aplicado, a inicialização falha
- Limites mais apertados de processos, arquivos abertos e tamanho de arquivo
- Sem tela, áudio, GPU, Docker, agente SSH ou mise, não importa o que mais você tenha passado
ai-jail --lockdown claudeReceitas
Copie uma. Para ver o que ela monta, rode antes com --dry-run.
Um agente em nuvem, no dia a dia
Um modelo hospedado precisa da rede para chegar à API e do próprio login para autenticar. Coloque os dois no arquivo global e o comando continua curto.
# uma vez, em ~/.ai-jail[commands.claude]network = trueagent_state = true # depois, em qualquer projetoai-jail claudeGit push via SSH
--ssh monta ~/.ssh como somente leitura e encaminha o socket do seu agente SSH. O push também precisa da rede.
ai-jail --network --ssh --agent-state claudeToolchains do mise
O diretório home novo não tem nenhuma instalação do mise, então o ai-jail pula o mise. Mapeie os dois diretórios do mise para dentro, somente leitura.
[commands.claude]ro_maps = ["~/.config/mise", "~/.local/share/mise"]Um navegador para o agente
--browser sozinho entrega um navegador que não carrega página nem abre janela. No Linux ele também precisa de --network e --display, e um navegador X11 precisa de --x11 no lugar de --display.
# Waylandai-jail --browser=soft --network --display chromium# X11ai-jail --browser=soft --network --x11 chromiumPerfis separados do Claude
Mantenha o login do trabalho e o pessoal separados apontando cada execução para um diretório do Claude próprio.
ai-jail --network --claude-dir ~/.claude-work claudeTeste um refactor arriscado numa cópia
Um overlay guarda o que o agente escreve numa camada à parte, em .ai-jail-overlays dentro do projeto. Depois compare com o original e fique com o que gostar. Só no Linux.
ai-jail --network --agent-state --overlay-map ~/Projects/my-app/src claudeConfigs antigas continuam funcionando
Compatibilidade retroativa é regra do projeto: nenhuma flag ou chave de configuração é removida. Chaves desconhecidas são ignoradas e as que faltam assumem o valor padrão, então um arquivo escrito para uma versão antiga ainda carrega.
As opções mais antigas mantêm os nomes invertidos, em que true desliga a coisa: no_gpu, no_docker, no_display, no_mise, no_landlock, no_seccomp, no_rlimits. É por isso que --gpu é salvo como no_gpu = false. As opções mais novas usam nomes diretos, como network = true.
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