O report procedia, e a correção já está disponível na v1.16.0.

Atualize pra v1.16.0

Se você usa o ai-jail, o update é o de sempre:

# Arch Linux (AUR)
yay -Syu ai-jail-bin

# Homebrew (macOS / Linux)
brew update && brew upgrade ai-jail

# crates.io
cargo install ai-jail --force

# mise
mise cache clear && mise upgrade github:akitaonrails/ai-jail

O que mudou na v1.16.0

Até a v1.15.x, o ai-jail montava o socket do Docker dentro da jaula automaticamente, sempre que /var/run/docker.sock existia no host. Read-write. Sem aviso, sem flag, sem pedir opinião. Eu documentei isso no README como “favorece usabilidade”, e era verdade: agente de coding frequentemente precisa rodar um docker compose pra subir banco de testes, e o passthrough automático poupava configuração.

A partir da v1.16.0 o comportamento inverteu:

• O passthrough do socket ficou desligado por padrão. Só entra se você pedir explicitamente com a flag --docker ou com no_docker = false no .ai-jail.
• Quando você liga e existe um socket no host, o ai-jail imprime um aviso na largada deixando claro que aquilo equivale a dar root no host pro processo dentro da jaula.
• O ai-jail status agora mostra Docker como disabled (default), pra ninguém achar que ligou sem querer.
• Nos modos --lockdown e browser profile o socket nunca entra, como já era antes.

Mudança de comportamento, sim, e de propósito. Se o seu workflow depende de Docker dentro da jaula (o meu depende em alguns projetos), o opt-in é uma linha no .ai-jail do projeto:

no_docker = false

O nome do campo ficou feio (no_docker = false pra ligar, eu sei), mas configs antigas continuam parseando igual e o --no-docker / no_docker = true funcionam como antes. Só o default mudou. Os detalhes estão nas release notes da v1.16.0.

O que o issue #88 mostrou

O report do mdindoffer é daqueles que todo mantenedor quer receber: resumo preciso, repro em poucas linhas, proposta de correção. A essência:

O ai-jail montava o socket cru do Docker dentro da sandbox, read-write. O daemon do Docker roda como root no host. Logo, um agente dentro da jaula podia rodar isto:

docker run --rm -v /:/host alpine sh -c 'cat /host/etc/shadow'

E pronto. Leitura de qualquer arquivo do host, como root. Isso derrota de uma vez só o $HOME em tmpfs, o --mask, o --deny-path e o Landlock, porque a ação deixa de acontecer dentro da sandbox: acontece no daemon, que vive fora e acima de qualquer namespace que o bwrap criou. O agente nem precisa escapar da jaula quando a jaula tem uma porta que dá direto na sala de máquinas.

Em retrospecto, deixar isso ligado por padrão foi uma falha de design. Eu sabia que o passthrough era “perigoso” no abstrato, tanto que escrevi isso no README. O que eu não tinha internalizado: perigoso desse jeito, com esse default, já é vulnerabilidade.

O mdindoffer ainda propôs o caminho de hardening definitivo: em vez de montar o socket cru, interpor um proxy filtrado (estilo o wollomatic/socket-proxy) que só aceita bind mounts de caminhos que o agente já pode escrever dentro da jaula. Está no radar pra uma versão futura. Pra fechar o buraco agora, opt-in com aviso explícito resolve o default, que era onde o problema morava.

A classe de vulnerabilidade: docker.sock é root

Essa não é a primeira vez que eu esbarro nessa história, e aposto que também não é a sua. “Quem tem acesso ao socket do Docker tem root no host” é um dos clássicos da segurança de containers, documentado pela própria Docker na página de daemon attack surface: só usuários confiáveis devem controlar o daemon, porque o Docker permite compartilhar qualquer diretório do host com um container, sem restrição nenhuma de acesso.

O motivo técnico é simples. O dockerd é um daemon que roda como root e obedece comandos que chegam pela API no socket Unix /var/run/docker.sock. A CLI docker é só um cliente dessa API. Quando você pede docker run -v /:/host, quem cria o container e monta o filesystem inteiro do host dentro dele é o daemon, com privilégio total. E processo dentro de container roda como uid 0 por padrão, que o kernel enxerga como uid 0 de verdade (salvo user namespace remapping, que quase ninguém liga). A conta fecha: acesso de escrita no socket equivale a root no host. O grupo docker é sudo sem senha com outro nome.

A demonstração, na sua máquina

Se você tem Docker instalado e seu usuário no grupo docker, reproduz agora. Sem sudo, sem explorar bug nenhum:

# confirme que você é um usuário comum
$ id
uid=1000(akitaonrails) gid=1000(akitaonrails) groups=...,docker

# tente ler o /etc/shadow diretamente: negado, como esperado
$ cat /etc/shadow
cat: /etc/shadow: Permission denied

# agora peça pro daemon fazer isso por você
$ docker run --rm -v /:/host alpine sh -c 'head -3 /host/etc/shadow'
root:$6$...:...
bin:!:...
daemon:!:...

E se quiser o pacote completo, uma shell de root no seu próprio host:

$ docker run --rm -it -v /:/host alpine chroot /host /bin/bash
# id
uid=0(root) gid=0(root) groups=0(root)

Nenhum exploit, nenhum 0-day. Você usou a API oficial, do jeito documentado, e saiu de usuário comum pra root em um comando. Era exatamente isso que um agente dentro do ai-jail conseguia fazer até hoje, mesmo com todas as camadas (bwrap, Landlock, seccomp, rlimits) ligadas.

Por que isso ainda existe?

Se todo mundo sabe disso há mais de uma década, por que ninguém “consertou”? A resposta curta: isso é arquitetura, e arquitetura não se resolve com patch.

• O daemon root com API todo-poderosa foi o design que fez o Docker simples de operar. Autorização granular por requisição existe na forma de authorization plugins, mas é opt-in, chata de configurar, e eu conto nos dedos os setups que já vi usando.
• O userns-remap existe desde o Docker 1.10 e mapeia o root do container pra um usuário sem privilégio no host. Vem desligado de fábrica, porque quebra compatibilidade com imagens e volumes que assumem uid 0.
• O rootless mode roda o daemon inteiro como o seu usuário, com o socket em $XDG_RUNTIME_DIR/docker.sock. Funciona, mas tem restrições de rede e storage, e a internet inteira de tutoriais assume o daemon root no caminho clássico.
• O Podman nasceu rootless e sem daemon justamente por causa dessa crítica. Tem uma seção inteira sobre ele logo abaixo.

Resumindo: isso vai continuar existindo. Toda ferramenta que monta /var/run/docker.sock dentro de um ambiente “pra conveniência” abre o mesmo buraco, consciente ou não. CI que monta o socket pra build de imagem, IDE remota, code-server, sandbox de agente de IA (oi, eu), plugin de painel web. O ajuste fica sempre do lado de quem monta o ambiente.

Curiosidade: isso é tudo, menos novo

Se você me acompanha há algum tempo, essa história toda deve ter dado déjà vu. Em 2023 eu gravei o [Akitando #139] - Entendendo Como Containers Funcionam, onde eu explico o que um container realmente é: um processo comum do Linux, limitado por cgroups, enganado por namespaces, com as capabilities cortadas. Sem mágica e sem máquina virtual. E olha o que já estava na lista de links daquele episódio: um walkthrough de privilege escalation via Docker, demonstrando exatamente o truque do docker run -v /:/host. O buraco que o issue #88 explorou dentro do ai-jail é o mesmo que eu já apontava num video de 2023, e que já era manjado muito antes disso.

Ninguém sabe disso melhor que a Red Hat. O Podman nasceu lá em 2018 como resposta direta a essa arquitetura: sem daemon central, rootless por padrão. Cada container vira filho direto do seu usuário, via fork-exec, sem um processo todo-poderoso rodando como root intermediando nada. O “docker.sock é root” simplesmente não existe nesse modelo, porque não existe nem docker.sock, nem daemon, nem root.

E antes que você pergunte: sim, eu uso Podman em algumas coisas e recomendo. Mas ele também não é solução perfeita, e vale entender o porquê.

O que o Podman faz bem:

• A arquitetura certa. Daemonless e rootless desde o dia zero. A classe inteira de vulnerabilidade deste artigo perde o sentido.
• Compatibilidade de CLI. alias docker=podman cobre a maioria esmagadora dos comandos do dia a dia. Build, run, push, pull: mesmos comandos, mesmas flags.
• Integração com systemd. Os Quadlets são, na minha opinião, o jeito mais limpo de rodar container como serviço no Linux. O Docker nunca chegou perto disso.

E onde ele tropeça:

• O socket de compatibilidade não é 100%. O Podman oferece um socket compatível com a API do Docker (o podman.socket), e muita ferramenta funciona em cima dele. Mas “muita” não é “toda”: Testcontainers, alguns plugins de IDE, ferramentas de CI mais exóticas tropeçam em diferenças de comportamento. Funciona até o dia em que não funciona, e aí você perde uma tarde debugando.
• Compose é cidadão de segunda classe. O docker compose oficial até conversa com o socket do Podman, e existe o podman-compose, mas nenhum dos dois tem a mesma redondeza do par original. Projeto com compose complicado é onde a migração costuma enroscar.
• Rootless tem preço. A rede rootless (slirp4netns, e hoje o pasta) tem limitações: sem ping por padrão, IP de origem esquisito, throughput menor. Imagem que assume uid 0 e volume com permissão errada pedem ajuste. Nada grave, mas é atrito.
• Docker Desktop é um produto. No macOS e no Windows, o Docker Desktop entrega uma experiência polida que o Podman Desktop ainda está alcançando. Pra muita gente, esse é o único contato com containers que existe.

Somando tudo, você chega na resposta de por que o mundo continua no Docker: inércia de ecossistema. Todo tutorial, todo CI, toda imagem de exemplo, todo docker run colado de Stack Overflow assume o daemon root no caminho clássico. O Docker virou o nome da categoria, tipo Bombril. Migrar pro Podman é tecnicamente fácil e politicamente caro: é você contra o conhecimento acumulado da internet inteira.

Um detalhe que importa pra quem usa sandbox: montar o socket do Podman rootless dentro de uma jaula é bem menos catastrófico que montar o do Docker. O “daemon” equivalente roda como o seu usuário, então um agente mal-intencionado ganharia os seus privilégios, não root. Continua ruim (dá pra sobrescrever o seu ~/.ssh com eles, por exemplo), mas é outro campeonato. Mesmo assim, o default do ai-jail continua valendo: não montar socket nenhum, de runtime nenhum. Opt-in é opt-in.

Boas práticas pra isso não morder você

A lista que eu aplico e recomendo:

1. Trate o grupo docker como sudo sem senha. Antes de adicionar qualquer usuário ou serviço nele, pergunte se você daria sudo irrestrito pra aquilo. É a mesma coisa.
2. Nunca monte /var/run/docker.sock em ambientes não confiáveis. Agente de IA, job de CI que roda código de pull request de estranho, container de terceiro. Faça um grep -r docker.sock nos seus docker-compose, manifests de CI e configs de ferramentas. Aparece em mais lugares do que você lembra.
3. Precisou expor pra algo semiconfiável? Use um socket proxy. O wollomatic/socket-proxy e o docker-socket-proxy da Tecnativa ficam entre o cliente e o daemon com allowlist de endpoints e bloqueio de bind mounts arbitrários. Read-only por padrão, você liga só o que precisa.
4. Prefira rootless sempre que possível. Podman rootless no Linux é o caminho mais limpo; o rootless mode do próprio Docker é a segunda opção. O daemon deixa de ser root e essa classe inteira de problema perde a mordida.
5. Em CI, construa imagem sem daemon privilegiado. Kaniko e Buildah constroem imagens rootless, sem precisar montar socket nenhum no job.
6. Não conseguiu rootless? Ligue o userns-remap. Custa uma tarde de testes com seus volumes e compra isolamento real entre o root do container e o root do host.
7. No ai-jail, deixe o default trabalhar por você. Docker desligado, e --docker só nos projetos onde você confia no workload como confiaria num sudo. Regra prática: se você não daria sudo cego pro agente naquele diretório, também não dê --docker.

Conclusão

Uma sandbox bem construída perde boa parte do valor se tiver uma porta dos fundos aberta por conveniência. O bwrap, o Landlock, o seccomp e os rlimits do ai-jail continuam fazendo o trabalho deles, mas nenhum deles enxerga o que acontece quando o processo lá dentro pede gentilmente pro daemon root do host montar o filesystem inteiro num container. Camada de segurança que você não audita vira decoração.

Meu agradecimento público ao @mdindoffer: report limpo, repro mínima, severidade correta e ainda por cima proposta de solução. É assim que se reporta vulnerabilidade em projeto open source.

Se você quer o contexto completo de como eu uso sandbox no dia a dia, escrevi sobre isso em Como me precaver pros meus agentes não apagarem minhas coisas?. A história do ai-jail está em AI Agents: Garantindo a Proteção do seu Sistema e na reescrita em Rust.

Agora vai lá e roda o upgrade.

No mesmo dia saiu a versão 1.1.0. Hoje, 20 de julho, estamos na 1.17.1.

Versão sozinha não quer dizer grande coisa, então fui contar o que aconteceu de verdade desde o horário daquele post. Foram 31 releases, 55 pull requests mergeados e 46 issues fechadas. Eu contei 24 grupos de funcionalidades novas voltadas ao usuário no CHANGELOG, ignorando correções, documentação e detalhes internos da mesma entrega. Se eu quebrasse a nova família ai-memory run em auto-seleção, adoção de sessão, suporte a Crush, --yolo, busca e recuperação, passava disso fácil.

Quinze pessoas tiveram PRs mergeados nesse período, quatorze além de mim. Preciso agradecer em especial ao Djalma Júnior, que sozinho teve 24 PRs mergeados, Matheus Rodrigues, com cinco, lhzapata, com quatro, Thiago Silva e Cristiano Dewes, com dois cada. Mais nove contribuidores tiveram PR mergeado. Faz tempo que isso deixou de ser “um programinha que eu fiz num fim de semana”.

Não vou despejar 55 PRs aqui. Quero falar da mudança que mais afeta meu uso diário: o novo ai-memory run.

A sessão também faz parte do projeto

Código é o resultado que sobreviveu. Ele não guarda a investigação inteira.

O Git mostra que você trocou Redis por SQLite. Talvez o commit explique uma parte. Mas onde ficou o experimento com Redis? Onde está o bug intermitente que só aparecia com dois workers? Quem lembrou que a primeira solução quebrava no Windows? Por que o time mudou de ideia depois de três horas? Qual workaround era temporário e qual virou decisão?

Boa parte disso só existe na sessão do agente.

Quando programo com Claude Code ou Codex, a sessão acumula o raciocínio operacional do projeto: perguntas, correções, tentativas descartadas, resultados de testes, surpresas, decisões e mudanças de direção. O código final mostra o que ficou. A sessão explica por que chegamos ali.

E sessão de LLM, no fim das contas, é texto. Claude Code grava JSONL. Codex também. OpenCode usa SQLite. Pi, OMP e Crush têm seus próprios formatos e diretórios. Cada harness empacota a conversa de um jeito, mas o conteúdo visível continua sendo mensagens e resultados de ferramentas.

Por que eu deveria deixar a parte mais cara do trabalho presa ao harness?

Anthropic pode mudar limite, preço, modelo ou formato amanhã. OpenAI também. Um agente pode estar excelente esta semana e insuportável na próxima. Eu quero trocar o motor sem jogar fora a viagem inteira.

Essa é a tese do ai-memory desde o começo: o programador tem que continuar independente das vontades dos providers. Modelo e harness são substituíveis. A memória do projeto é minha.

O handoff resolvia só metade

O ai-memory já fazia passagem de bastão. Eu encerrava Claude Code, os hooks consolidavam a sessão e o Codex seguinte recebia um resumo curto com o que foi feito, perguntas abertas e próximos passos.

Isso continua existindo e continua útil. Quem abre claude, codex ou opencode diretamente mantém o comportamento anterior. O launcher novo é opt-in.

Mas handoff é uma compressão deliberadamente lossy. Ele preserva o que parece mais importante naquele momento. Não pretende transportar a sessão inteira, nem retomar a sessão nativa de cada harness. Se o resumo omitiu uma tentativa antiga que voltou a ser relevante duas horas depois, você precisa procurar na wiki ou nos registros.

O ai-memory run acrescenta outra camada: uma workstream gerenciada, uma linha de trabalho que atravessa os harnesses.

Claude hoje, Codex daqui a pouco

O uso básico é esse:

cd ~/Projects/meu-projeto

ai-memory run claude
# trabalha, encerra o Claude Code normalmente

ai-memory run codex --yolo
# Codex continua a mesma linha de trabalho

ai-memory run claude --model opus
# volta pra sessão nativa anterior do Claude

ai-memory run
# ou deixa o ai-memory escolher o harness certo pra continuar

Não precisa de -- pra separar os argumentos. Tudo depois do nome do harness segue pra ele, com uma exceção proposital: o --yolo pertence ao wrapper e é traduzido pra opção perigosa nativa de Claude Code, Codex, OpenCode, Pi ou Crush.

Por baixo, o ai-memory não tenta converter um arquivo do Codex num arquivo do Claude. Isso seria frágil e provavelmente quebraria na próxima atualização. Cada harness mantém sua própria sessão nativa. A workstream liga essas sessões a um ledger portátil com a parte visível da conversa.

Pensa assim:

sessão nativa do Claude ─┐
sessão nativa do Codex  ─┼─ workstream ─ contexto portátil
sessão do OpenCode      ─┤                 + busca completa
sessão nativa do Pi     ─┘

Na primeira vez que Claude entra naquela workstream, ele ganha uma sessão nativa. Quando você troca pra Codex, o Codex ganha a sessão nativa dele e recebe o delta portátil que ainda não viu. Ao voltar pro Claude, o launcher usa o --resume do próprio Claude Code e entrega apenas o que aconteceu nos outros harnesses desde a última vez.

Isso é bem diferente de começar um chat novo com um resumo colado no prompt. O Claude volta pra sessão real dele. O Codex volta pra sessão real dele. O ai-memory cuida da continuidade entre os dois.

Hoje o modo gerenciado suporta Claude Code, Codex, OpenCode, Pi, Crush e OMP. O suporte geral do ai-memory é maior, com MCP e hooks pra outros clientes, mas isso não quer dizer que todo cliente já tenha adapter de sessão nativa pro run. São contratos diferentes e eu prefiro deixar isso explícito.

O que entra na workstream

Quando o harness encerra, o ai-memory lê o final da sessão nativa sem modificar o store original. Entram mensagens visíveis de usuário e assistente, tool calls concluídas com seus resultados, resumos de compaction e um checkpoint não mutante do Git. Cada evento mantém a origem: veio do Claude, Codex, OpenCode, Pi, Crush ou OMP.

Credenciais do provider, registros criptografados, system/developer prompts e hidden reasoning ficam de fora. Formatos privados que o adapter não entende também ficam de fora e geram uma anotação de perda, em vez de o sistema fingir que importou tudo.

Os registros passam pelo sanitizer antes de entrar no ledger pesquisável e nos segmentos JSONL imutáveis do ai-memory. Os stores nativos são abertos read-only pelo adapter; quem continua escrevendo neles é o próprio harness.

Também não enfio a sessão inteira no próximo prompt. Isso recriaria o problema que o projeto tenta resolver: contexto bruto demais, caro demais e cheio de ruído. O próximo agente recebe um delta recente com tamanho limitado. Se uma decisão velha voltar a importar, o ledger completo continua pesquisável:

ai-memory workstream-search "por que desistimos do Redis"
ai-memory workstream-search --limit 50 --json "migration que falhou"

Dentro de um ai-memory run, o ID da workstream já entra no ambiente. O agente não precisa descobrir UUID nenhum.

E o ledger não substitui a wiki. Ele resolve continuidade operacional. Decisões, regras, procedimentos e gotchas que precisam sobreviver por meses continuam merecendo páginas Markdown consolidadas. Sessão bruta é evidência. Wiki é conhecimento organizado.

Posso manter mais de uma linha de trabalho?

Sim. A workstream padrão se chama default, selecionada por repositório e worktree. Se eu quiser abrir uma linha independente pra uma investigação sem contaminar o trabalho principal:

ai-memory run --new investigar-race claude

# depois continuo aquela linha com outro harness
ai-memory run --workstream investigar-race codex

Uma lease impede duas janelas de escreverem ao mesmo tempo na mesma workstream. Em encerramento normal, o launcher importa o final da sessão e libera imediatamente. Se alguém matar o processo sem cleanup, a lease expira em até 90 segundos e a próxima execução retoma do último cursor confirmado, sem duplicar os eventos já importados.

Uma irritação besta que eu tinha o tempo todo: voltava pra um projeto depois de alguns dias e não lembrava se a sessão mais recente estava no Claude ou no Codex. Eu chutava um, abria, percebia que o contexto estava no outro, fechava e tentava de novo.

Agora só rodo:

ai-memory run

# ou com a mesma seleção automática em YOLO mode
ai-memory run --yolo

Numa workstream vazia, o ai-memory procura sessões locais daquele checkout em Claude Code, Codex, OpenCode, Pi e Crush, descobre qual é a mais recente e abre o harness certo pra mim. Numa workstream já estabelecida, a memória do servidor vence o timestamp de arquivo: ele volta ao último harness ligado àquele trabalho, em vez de adotar por engano uma sessão velha que só recebeu uma gravação mais recente. OMP continua disponível quando escolhido explicitamente, mas ainda não participa da seleção automática.

Na primeira execução explícita, o launcher também pode oferecer sessões existentes do mesmo checkout pra adoção. Dá pra começar a usar sem abandonar o chat que já estava aberto antes de atualizar o ai-memory.

Outras novidades que eu realmente uso

Eu prometi não ler o changelog inteiro em voz alta, mas algumas mudanças desse mês merecem menção porque reduzem trabalho do programador.

Briefing antes da primeira pergunta

Um projeto pode pedir um briefing automático no início de cada sessão:

[briefing]
inject_on_session_start = "true"
max_chars = 4000

O ai-memory recompõe um pacote com páginas pinned, _rules/, _slots/ e títulos recentes. O agente começa sabendo as regras e o estado básico do projeto, em vez de gastar a primeira conversa redescobrindo a arquitetura. É opt-in porque consome contexto em todo SessionStart, inclusive depois de um /clear do Claude.

Preferências globais e busca entre projetos

Preferências que valem pra todo meu trabalho agora podem viver no escopo reservado _global: estilo de código, ferramentas que prefiro, regras pessoais e convenções que não pertencem a um repositório específico. Consultas normais já fazem union desse escopo com o projeto atual.

Pra meta-repos que precisam consultar vários projetos irmãos o tempo todo, existe outro opt-in:

[recall]
default_global = "true"

Assim memory_query e memory_recent sem escopo explícito procuram em todos os projetos. Não ligo isso em qualquer repo porque busca global à toa só traz ruído.

Menos instrução fixa, mais Agent Skills

O bloco de routing em CLAUDE.md ou AGENTS.md ficou pequeno. As instruções detalhadas de quando buscar memória, consolidar, guardar decisão ou criar handoff foram movidas pra Agent Skills gerenciadas. Um comando instala ou atualiza os dois sem atropelar o resto do arquivo:

ai-memory install-instructions

Isso também reduz drift. Quando o protocolo muda, atualizo o pacote gerenciado em vez de caçar um prompt velho copiado em quarenta repositórios.

Privacidade antes da rede

Agora cada repo pode excluir caminhos da captura:

[capture]
ignore_paths = ["private/**", "~/personal-notes/**"]

Quando uma integração reconhece uma file tool e o caminho bate, o evento é descartado localmente antes de spool, fila, rede ou servidor. Isso tem limites claros: não é DLP mágico, não interpreta qualquer shell command e não rastreia conteúdo citado em texto livre. Mas resolve o caso verificável sem vender uma garantia falsa.

Também entraram integrações com Kimi Code, Grok Build CLI, Devin e Zero, um provider OpenCode Zen/Go, finalize-session pro Codex e melhorias na administração de workspaces. Reforço: ter MCP e hook não significa automaticamente ter ai-memory run. O README separa esses níveis.

Bônus: ai-jail por fora, YOLO por dentro

Há pouco mais de uma semana escrevi como me protejo pra agentes não apagarem minhas coisas. Minha recomendação continua a mesma: YOLO mode dá a melhor experiência, desde que o sistema limite o estrago possível.

O ai-jail chegou à versão 1.15.0 e agora entende o launcher do ai-memory. O jeito que mais estou gostando de trabalhar virou:

ai-jail ai-memory run codex --yolo

Ou, se quero que o ai-memory escolha qual harness deve continuar:

ai-jail ai-memory run --yolo

A ordem importa. ai-jail fica por fora para manter tanto o launcher quanto o processo filho na mesma sandbox. ai-memory run sozinho gerencia a sessão, mas não cria sandbox.

O --yolo desliga a cerimônia de aprovação do harness. O ai-jail faz a contenção: projeto atual read-write, home substituído por tmpfs, partes necessárias do estado dos agentes montadas seletivamente e diretórios sensíveis como .ssh, .gnupg e .aws fora da jaula. O suporte novo também deixa o estado local do ai-memory gravável pros hooks manterem spool e cursores entre execuções.

ai-jail reconhece tanto a camada ai-memory quanto o harness selecionado. Se você tem configuração global específica pra Codex, por exemplo, ela continua sendo aplicada quando o comando real é ai-memory run codex. Até o ajuste de redraw da status bar entende que o filho é Codex.

Essa combinação resolve as duas irritações ao mesmo tempo: o agente para de pedir confirmação a cada comando e a sessão para de pertencer ao agente. Fluidez sem dar o home inteiro de presente.

One more thing: ai-usagebar também cresceu

Quando publiquei o ai-usagebar original, ele monitorava Claude, Codex, Z.AI e OpenRouter num widget da Waybar ou numa TUI. A versão 0.14.0 já cobre onze integrações de uso, gasto ou saldo.

Kimi ganhou as duas informações que realmente importam pra coding: quota semanal da assinatura e janela móvel de cinco horas. Kilo, Novita, Moonshot e Grok mostram saldo restante. Uma integração separada da Anthropic Console mostra gasto de API no mês, sem confundir isso com a assinatura do Claude Code. Ela deixa explícito que o Cost API não inclui Priority Tier.

Também dá pra cadastrar várias contas da Anthropic, ver limites semanais específicos de modelos como Fable e enxergar um marcador de ritmo. A barra não fica vermelha só porque chegou em 40%; ela compara o percentual gasto com quanto da janela já passou. Se usei 40% em 20% da semana, estou rápido demais. Essa é a informação útil.

O projeto deixou de ser só Waybar. Tem app nativo de menu bar no macOS, extensão do GNOME e a TUI standalone. E a novidade mais recente é um monitor local de contexto do Claude Code: aperto c, escolho uma das sessões recentes e vejo quanto da janela já foi consumido. Ele lê caudas limitadas dos JSONL locais e não inventa porcentagem quando não consegue determinar o tamanho da janela.

No meu fluxo, o trio acaba se encontrando naturalmente. ai-usagebar mostra qual assinatura ainda tem espaço. ai-memory run troca de harness sem jogar fora o trabalho. ai-jail deixa o escolhido trabalhar em YOLO sem acesso irrestrito à máquina.

Atualizando

As páginas de instalação dos três projetos têm todos os métodos, incluindo AUR, Homebrew e binários de release:

• ai-memory
• ai-jail
• ai-usagebar

Depois de atualizar o ai-memory, reinstale os hooks dos harnesses que pretende usar no modo gerenciado. Os três principais no meu caso:

ai-memory install-hooks --agent claude-code --apply
ai-memory install-hooks --agent codex --apply
ai-memory install-hooks --agent opencode --apply

Crush não precisa de hook no modo gerenciado; ele recebe o contexto por um arquivo temporário configurado só pro processo lançado. A documentação de managed workstreams tem os detalhes de instalação, privacidade, recuperação e os argumentos nativos de cada adapter.

Conclusão

Um mês atrás, o ai-memory já conseguia transformar sessão em wiki e entregar um handoff pro próximo agente. Agora ele consegue gerenciar a própria linha de trabalho: adota uma sessão existente, mantém uma sessão nativa por harness, transporta o histórico visível, retoma cada cliente no formato dele e deixa o ledger inteiro pesquisável.

Pra mim, é aí que está o valor. O código contém a implementação que venceu. A sessão contém as decisões, experimentos que falharam, gotchas, bugs inesperados e mudanças de ideia que produziram aquela implementação. Jogar isso fora toda vez que muda de provider é desperdício.

Raw transcript também não resolve sozinho. É grande, repetitivo e caro pra enfiar em qualquer contexto. O ai-memory mantém a evidência, entrega só o delta recente e usa consolidação pra transformar o que merece sobreviver em páginas Markdown curtas.

Ainda há formatos novos pra suportar, arestas de plataforma e muito teste pela frente. A diferença é que agora existe uma base real, com acceptance test chamando harness de verdade, 14 contribuidores externos com PR mergeado em pouco mais de um mês e uso diário empurrando o desenho.

LLM e assinatura eu alugo de quem estiver entregando melhor hoje. A sessão do meu projeto fica comigo.

No dia seguinte o goodalexander reproduziu o mesmo comportamento num devnet descartável: um rsync --delete-delay contra / varreu /var, /etc e o estado dos validators dele, corrompendo o filesystem a ponto de precisar reinstalar o sistema operacional. A conclusão dele: “you can’t use this thing in prod”.

Casos assim aparecem de tempos em tempos desde que agentes de coding viraram mainstream. E toda vez a discussão descamba pros mesmos dois extremos: de um lado “viu? IA é perigosa, nunca deixe rodar nada sozinha”, do outro “quem deixa um agente solto no sistema merece o que acontece”. Eu acho os dois lados preguiçosos. Deixa eu contar minha experiência real e o que eu faço a respeito.

Cinco meses de maratona, zero acidentes

Desde fevereiro eu estou maratonando Claude Code, Codex e OpenCode. Quase todos os dias, quase o tempo todo, em sessões muito longas que às vezes atravessam dias. Estourando o limite do meu plano Max da Anthropic e do meu plano Plus da OpenAI com folga. O resultado concreto até agora: quase 40 repositórios novos no meu GitHub e mais de 500 mil linhas de código produzidas.

E nos últimos dois meses eu rodo tudo exclusivamente em “YOLO mode”. Pra quem não conhece o jargão: por padrão, esses agentes pedem permissão antes de cada comando que vão executar no seu terminal. O YOLO mode desliga essa trava. No Claude Code é a flag --dangerously-skip-permissions, no Codex é o --yolo, no OpenCode você configura as permissões pra aprovar tudo. O agente roda o que quiser, quando quiser, sem me perguntar nada.

Em cinco meses nesse regime, nem uma vez um agente apagou um arquivo que eu não pedi. Nem uma vez rodou um comando destrutivo fora do escopo. As frustrações que eu tenho com agentes são de outra natureza (teimosia, solução preguiçosa, contexto que se perde), coisas irritantes mas a quilômetros de distância de um rm -rf no meu home.

Então quando eu vejo esses relatos, minha primeira hipótese sempre vai pro mesmo lugar: o prompt. Pra um agente “enlouquecer” desse jeito, em geral o usuário escreveu instruções muito ruins. Vagas, ambíguas, pedindo limpeza sem definir o que é lixo, mandando o agente “resolver” sem dar contexto. Falta de habilidade de comunicação combinada com falta de conhecimento técnico pra perceber que o pedido estava mal formulado. O agente executa a instrução que você escreveu, com todas as ambiguidades que você deixou nela.

Dito isso, eu NÃO confio completamente em LLMs. Ninguém deveria.

A diferença é que a minha desconfiança vira engenharia em vez de virar tweet.

Camada por camada, é assim que eu durmo tranquilo.

Camada 1: sandbox com ai-jail

Quando eu realmente suspeito que uma sessão pode fazer besteira (vou mexer em scripts de sistema, vou deixar o agente rodar por horas sem supervisão num código que toca no filesystem), eu abro o harness dentro do ai-jail, uma ferramenta minha, open source, escrita em Rust.

O ai-jail é um wrapper de sandbox pra agentes de coding. No Linux ele usa o bwrap (bubblewrap, a mesma base do Flatpak), no macOS usa o sandbox-exec. A ideia: o processo enxerga um filesystem que parece normal, mas só o diretório do projeto atual é real e persistente. O resto do $HOME, os diretórios vizinhos, o /tmp, tudo vive em tmpfs e evapora quando a sessão termina. O estado do agente (~/.claude, ~/.codex etc) é montado de verdade pra ele continuar logado e configurado, mas ~/.ssh, ~/.gnupg, ~/.aws e perfis de browser nunca entram na jaula.

Instalar é um comando:

# Arch Linux
yay -S ai-jail-bin

# macOS / Linux via Homebrew
brew tap akitaonrails/tap && brew install ai-jail

# ou direto do crates.io
cargo install ai-jail

E usar é mais simples ainda:

cd ~/Projects/meu-app
ai-jail claude       # Claude Code na jaula
ai-jail codex        # Codex na jaula
ai-jail --dry-run claude  # mostra a política sem rodar

Se o agente resolver rodar rm -rf ~ lá dentro, ele apaga um tmpfs que ia sumir de qualquer jeito. Meu home real nem foi montado. Pra quem está começando com YOLO mode e ainda não tem calo, é o jeito mais barato de errar sem consequência.

Camada 2: BTRFS e snapshots (a rede de segurança de verdade)

Agora o ponto principal desse post. Eu advogo há ANOS que usuário de Linux deveria usar BTRFS em vez de EXT4. Fiz um episódio inteiro do Akitando sobre isso em 2023, muito antes de existir agente de coding pra levar a culpa. O argumento era o mesmo: seus dados precisam sobreviver a erro humano. Um LLM rodando rm -rf no lugar errado é só uma categoria nova de erro humano, terceirizado.

Por que BTRFS é superior pra desktop? Copy-on-write (CoW): o filesystem nunca sobrescreve um bloco no lugar, ele escreve a versão nova em outro bloco e atualiza os ponteiros. Checksum de dados e metadados, então bitrot silencioso é detectado em vez de corromper seu arquivo caladinho. Compressão transparente. Subvolumes, que funcionam como partições flexíveis sem tamanho fixo. E a consequência mais valiosa do CoW: snapshots leves.

Um snapshot BTRFS é instantâneo e custa perto de zero espaço no momento em que é criado. Ele congela os ponteiros dos blocos atuais em vez de copiar dados. Só o que divergir a partir dali (blocos novos ou modificados) passa a ocupar espaço extra. Na prática você pode tirar dezenas de snapshots por dia sem sentir. Neste exato momento minha máquina mantém 23 snapshots do sistema, e o custo é a diferença entre eles, alguns poucos gigas.

Agendando snapshots

As duas ferramentas clássicas são o Timeshift e o snapper. O Timeshift é o mais amigável: interface gráfica, você marca “quantos snapshots manter” por hora/dia/semana/mês e ele cuida do resto. Ele espera o layout de subvolumes @ (raiz) e @home, que é o padrão da maioria das distros que instalam em BTRFS hoje. O snapper (nascido no openSUSE) é mais granular: configs por subvolume, timeline automática, integração com o gerenciador de pacotes pra tirar snapshot antes e depois de cada instalação.

# Timeshift: snapshot manual antes de uma sessão suspeita
sudo timeshift --create --comments "antes de soltar o agente"

# snapper: criar config pro /home e ligar a timeline
sudo snapper -c home create-config /home
sudo systemctl enable --now snapper-timeline.timer

Meu setup roda Timeshift agendado, mais o grub-btrfsd de plantão (já explico por quê).

Recuperando arquivos apagados

Aqui está a mágica que todo mundo que perdeu arquivo pra um agente gostaria de ter tido. Snapshot BTRFS é navegável como um diretório comum. O agente apagou seu projeto às 15h? O snapshot das 14h ainda tem tudo:

# com Timeshift, os snapshots ficam montados em /run/timeshift
sudo ls /run/timeshift/backup/timeshift-btrfs/snapshots/

# achou o snapshot de antes do estrago? copia de volta e pronto
sudo cp -a /run/timeshift/backup/timeshift-btrfs/snapshots/2026-07-11_14-00-01/@home/akitaonrails/Projects/meu-app ~/Projects/

Com snapper é a mesma coisa via .snapshots dentro do subvolume, e ele ainda tem o snapper undochange pra reverter mudanças específicas entre dois snapshots. Recuperação em segundos, sem drama, sem ferramenta forense.

E se o sistema nem ligar mais?

O caso do goodalexander foi além de perder arquivos: o agente varreu /var e /etc e o sistema ficou imprestável, precisou reinstalar o OS. Com BTRFS nem isso seria necessário. É pra esse cenário que existe o grub-btrfs: um daemon que observa seus snapshots e regenera o menu do GRUB com uma entrada de boot pra cada um.

Sistema não sobe mais? Reinicia, segura o menu do GRUB, escolhe “snapshots” e dá boot direto num snapshot de ontem, read-only. De dentro dele, roda timeshift --restore, escolhe o snapshot bom, reinicia de novo. Sistema inteiro de volta ao estado de antes do desastre, em menos tempo do que você levaria pra achar o pendrive de instalação. No pior caso absoluto (o próprio GRUB foi junto), um live USB qualquer monta a partição BTRFS, aponta o subvolume padrão de volta pro snapshot bom e resolve.

E no macOS? E no Windows?

Usuário de Mac tem o equivalente direto: o APFS, filesystem padrão desde o High Sierra (2017), também é copy-on-write e também tem snapshots leves. Quem gerencia é o Time Machine: com ele ativado, o macOS tira snapshots locais automáticos de hora em hora e guarda as últimas 24 horas no próprio disco, independente do backup externo. E dá pra criar um na mão antes de soltar o agente:

# criar um snapshot local do APFS agora
tmutil localsnapshot

# listar os snapshots existentes
tmutil listlocalsnapshots /

Pra recuperar, abre o próprio Time Machine (“Browse Time Machine Backups” na barra de menu): ele navega pelos snapshots locais mesmo sem nenhum disco externo plugado, e você restaura o arquivo dali. Quem prefere terminal monta o snapshot read-only com mount_apfs -s e copia de volta. Ou seja, o caso do Matt Shumer lá do começo tinha solução nativa no próprio Mac dele: um snapshot de uma hora antes teria devolvido quase tudo.

No Windows a história é mais fraca. O NTFS tem o Volume Shadow Copy (VSS), que alimenta os restore points e a aba “Versões Anteriores”, mas é voltado pra arquivos de sistema e raramente está cobrindo seus dados na hora que você precisa. Nada com a leveza e a previsibilidade de um snapshot CoW agendado. Se você desenvolve no Windows, trate backup externo como obrigatório, sem discussão (e o restic da próxima seção roda em Windows numa boa).

Camada 3: backup externo com restic

Snapshot mora no mesmo disco que os dados. Se o NVMe morrer, morrem os dois juntos. Por isso a outra coisa que eu repito há anos: todo mundo precisa de backup externo, seja num HD externo, seja num NAS. Eu uso um Synology na rede local, montado via NFS, e documentei o setup completo aqui.

Em cima dele roda o restic, que na minha opinião é a melhor ferramenta de backup pra essa finalidade: deduplicação, criptografia, snapshots incrementais e restore simples. Minha configuração real é um script disparado por um timer do systemd todo dia às 3 da manhã. Ele confere se o NAS está montado, faz o backup do /home e do /mnt/data/Projects pulando caches (node_modules, target/ do Rust, __pycache__ e afins, tudo num arquivo de excludes), e depois aplica a política de retenção: 7 diários, 4 semanais, 6 mensais, 1 anual.

Reproduzir o essencial é isso aqui:

# uma vez: criar o repositório no NAS
restic init --repo /mnt/nas/desktop-backup

# todo dia (via cron ou systemd timer):
restic -r /mnt/nas/desktop-backup backup ~ /mnt/data/Projects \
    --exclude-file=~/.config/restic/excludes --exclude-caches

restic -r /mnt/nas/desktop-backup forget \
    --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --keep-yearly 1 --prune

E se o dia ruim chegar de verdade (agente destrutivo, disco morto, ransomware, tanto faz a causa):

# listar os snapshots disponíveis
restic -r /mnt/nas/desktop-backup snapshots

# restaurar um arquivo ou diretório específico
restic -r /mnt/nas/desktop-backup restore latest \
    --target /tmp/recuperado --include /home/akitaonrails/Projects/meu-app

# ou montar o repositório inteiro como filesystem e navegar com calma
restic -r /mnt/nas/desktop-backup mount /mnt/restic

Repara na arquitetura em camadas: o snapshot BTRFS resolve o acidente de minutos atrás em segundos. O restic resolve o desastre de dias atrás, incluindo hardware morto. Um agente de IA teria que ser muito dedicado pra atravessar as duas camadas, e mesmo assim ainda existiria a cópia de ontem no NAS, que ele nem alcança.

E nas empresas? Profissionalismo

Tudo acima é sobre a minha máquina pessoal. Agora sobe o sarrafo: ambiente corporativo.

A regra número um é simples e inegociável: nenhum agente de IA deve ter acesso a produção. Nunca. Nem SSH direto em servidor de produção, nem credencial de banco de produção, nem token de admin de serviço em produção. Se o seu agente consegue rodar um DELETE na base que atende clientes, o problema deixou de ser a IA faz tempo: qualquer estagiário com o mesmo acesso é a mesma bomba-relógio, só com menos velocidade de digitação.

Agente em staging, por outro lado, eu defendo. É pra isso que staging existe. Mas mesmo em staging tem jeito certo: você resiste à tentação de pedir ações one-shot (“roda um apt install aí”, “dá um systemctl restart”, “conecta no postgres e executa isso”). Comando avulso executado na mão é conhecimento que evapora. Sua infraestrutura precisa ser automatizada e reproduzível: Ansible, Kubernetes, Terraform, o que fizer sentido pro seu stack. O papel do agente passa a ser escrever e refinar essas receitas, que ficam versionadas em git.

Um exemplo pequeno, aqui da minha mesa

Eu tenho um ambiente de jogos no meu PC principal, mas eu me recuso a misturar pacote de emulador com meu ambiente de desenvolvimento. Então isolei os jogos dentro de um distrobox. Pra quem não conhece: o distrobox cria containers (via podman ou docker) que se integram com seu desktop como se fossem nativos. Compartilham seu home (ou um home dedicado), acesso a GPU, Wayland, áudio. Na prática é uma distro completa dentro da sua distro, com espaço de pacotes separado.

O distrobox-gaming é um repositório de playbooks Ansible que constrói uma box Arch chamada gaming do zero: ES-DE de frontend, emuladores standalone (shadPS4, RPCS3, PCSX2, Dolphin, DuckStation, Eden e mais uma dúzia), cores do RetroArch, configs otimizadas por jogo, atalhos no launcher do host. E o distrobox-llm faz o mesmo pra uma box de trabalho com LLMs locais: CUDA, cuDNN, Ollama, whisper.cpp e LM Studio isolados numa box com --nvidia, enquanto o host só carrega o driver. Upgrade de versão maior do CUDA deixa de chacoalhar meu ambiente de desenvolvimento.

Quem escreveu a esmagadora maioria desses playbooks? Os agentes. Em vez de pedir “instala o RPCS3 pra mim”, meu prompt é “escreve a receita Ansible idempotente que instala e configura o RPCS3, roda ela, verifica o resultado e corrige até passar”. Olha um trecho real do role que cria a box do LLM:

- name: Check if distrobox exists
  ansible.builtin.shell: "distrobox list 2>/dev/null | awk '{print $3}' | grep -qx {{ dl_box_name }}"
  register: _box_exists
  changed_when: false
  failed_when: false

- name: Create distrobox
  ansible.builtin.command: >-
    distrobox create
    --name {{ dl_box_name }}
    --image {{ dl_image }}
    --home {{ dl_box_home }}
    {{ '--nvidia' if dl_nvidia_enabled else '' }}
  when: _box_exists.rc != 0

Idempotente: confere se a box existe antes de criar, rodar duas vezes dá no mesmo. Se meu PC pegar fogo amanhã, eu recrio os dois ambientes inteiros com um ansible-playbook site.yml em cada repo. O conhecimento está na receita, versionado, auditável. Zero comando perdido no histórico do shell.

Escalando o mesmo princípio pra produção

Numa empresa, troca distrobox por Kubernetes e o princípio é idêntico. O agente escreve o manifesto, testa no cluster de staging, você promove pra produção manualmente:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: minha-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: minha-api
  template:
    metadata:
      labels:
        app: minha-api
    spec:
      containers:
        - name: minha-api
          image: registry.exemplo.com/minha-api:v42
          readinessProbe:
            httpGet:
              path: /healthz
              port: 8080
          resources:
            limits:
              memory: 512Mi

O fluxo profissional: o agente produz e ajusta o manifesto (ou o chart do Helm, ou o módulo do Terraform), aplica em staging (kubectl apply -n staging), roda os testes, observa efeitos colaterais, bugs, comportamento não intencional, e itera até você estar satisfeito. Aí VOCÊ, humano, promove pra produção (via PR revisado num fluxo GitOps, ou um kubectl apply manual e consciente), monitorando cada passo. O agente fez todo o trabalho pesado: os artefatos, os procedimentos, os checklists. Dá até pra pedir pra ele gerar a documentação de auditoria no final. Mas o dedo que aperta o botão de produção tem CPF.

Até o SQL “simples” de manutenção

Um caso que parece inofensivo e me incomoda muito: comando SQL de manutenção em produção. Muita gente sempre rodou esses comandos na mão, direto no client de produção, e agora está pedindo pro agente escrever E executar. Isso é inaceitável, com ou sem IA. Seu sistema deve ter um fluxo de migrations: a mudança vira código versionado, roda em staging primeiro, é validada, e só então executa em produção dentro do processo normal de deploy.

E “produção”, por definição, significa duas coisas que muita empresa finge ter. Primeiro: backups de verdade, testados, com restore ensaiado.

Jamais rode em produção qualquer coisa da qual você não consegue se recuperar.

Segundo: monitoramento. Se você não tem visibilidade do estado do sistema, você não tem produção, tem um servidor ligado na tomada e reza.

Monitoramento: até no meu humilde PC

E monitoramento é tão parte da disciplina que eu aplico até na minha máquina pessoal. Recentemente eu desenvolvi um widget de system health pro meu clock-tui (meu fork mantido do clock-tui original, com widgets de comando no modo relógio). Ele fica aberto num canto mostrando isso aqui:

Uma linha de veredito (“all systems healthy”) e o estado de tudo que este post descreveu: o backup do restic rodou há 19 horas e o próximo é às 03:03; o Timeshift mantém 23 snapshots; a limpeza de caches de desenvolvimento rodou há 32 horas; o scrub do BTRFS está em dia em cada filesystem, com trim recente, alocação saudável e zero erros de I/O; mais zumbis, load, memória e ocupação de cada disco. O widget (tclock-system-health) vem junto no repositório e no pacote do AUR, e detecta a maior parte disso sozinho.

Por trás dele estão as manutenções automatizadas, todas em timers do systemd: o restic diário às 3h; o dev-cache-clean (dia 1 e dia 15) varrendo target/ órfãos de Rust e cache do yay, que juntos devolvem dezenas de gigas; o btrfs-scrub mensal por filesystem validando checksums; o fstrim semanal. Nada disso exige que eu lembre de nada. Quando algum atrasar ou falhar, o widget muda de cor na minha cara.

Esse é o nível caseiro, proporcional a um PC pessoal. Numa empresa você vai de full-blown: Prometheus coletando métricas, Grafana desenhando os dashboards, Alertmanager acordando o plantonista às 3 da manhã. A escala muda, o princípio é o mesmo: o estado do sistema visível o tempo todo, e alguém (ou alguma coisa) sendo avisado quando sai do trilho.

Conclusão: disciplina

Volta nos dois tweets do começo. Em ambos os casos, um único comando errado causou perda real, e a discussão pública virou “em quem eu confio mais”. A pergunta certa é outra: por que um único comando errado, de qualquer origem, tem o poder de causar perda irrecuperável na sua máquina?

Ser profissional é ser disciplinado, e a disciplina começa em casa. Meu PC pessoal opera com o mesmo rigor que eu cobraria de um ambiente corporativo: filesystem com snapshots leves e agendados, boot recuperável via GRUB, backup externo diário com política de retenção, sandbox pra sessões suspeitas, ambientes isolados e reconstruíveis por receitas versionadas, manutenção automatizada e um monitor que me avisa quando qualquer peça atrasa. Custo de manutenção mensal disso tudo: perto de zero. Foi montado uma vez (em boa parte pelos próprios agentes) e funciona sozinho.

Com essas camadas, a pergunta do título quase perde o sentido. O agente apagou um diretório? Snapshot de uma hora atrás, dois minutos de recuperação. Destruiu o sistema? Boot num snapshot pelo GRUB, restore, dez minutos. Fritou o disco junto? Restic no NAS, backup de ontem. Em cinco meses de YOLO mode eu nunca precisei de nenhuma dessas redes pra acidente de IA. Mas eu durmo tranquilo justamente porque elas estão lá.

LLM rodando solto no seu sistema é só o teste de estresse mais recente da sua disciplina. Se um agente descontrolado consegue causar perda permanente nos seus dados, a vulnerabilidade sempre esteve aí, esperando um erro seu, um disco ruim ou um ransomware. O agente foi só o mensageiro que chegou primeiro.

Vou repetir uma coisa importante antes que alguém saia clonando todos os meus repositórios achando que virou produto 1.0: a maior parte dos projetos frank-* no meu GitHub são provas de conceito. São experimentos. Alguns funcionam bem pra mim, no meu ambiente, no meu fluxo. Isso não quer dizer que estão prontos pra virar dependência crítica da sua empresa amanhã de manhã. Quer brincar, contribuir, estudar, ótimo. Só não confunda “publiquei no GitHub” com “está production ready”.

Existem exceções. O FrankMD, por exemplo, recebeu uma quantidade decente de contribuições, testes, lapidação, correções de bugs reais, uso real. Hoje ele já é bem mais estável do que era no primeiro post. Ainda assim, o ponto continua: esses projetos nasceram como laboratório de vibe coding, não como plano de produto de 3 anos com roadmap, suporte enterprise e SLA.

Este post é um apanhado do que aprendi nesse laboratório. Algumas ferramentas minhas, alguns hábitos, algumas recomendações. Nada místico. Nenhuma “nova forma revolucionária de programar”. É engenharia velha com ferramenta nova.

Primeiro: pare de colecionar agente

Se você é desenvolvedor normal, você não precisa de 12 agentes, 40 wrappers, 7 orquestradores e um diagrama de Kubernetes pra escolher quem vai escrever um if.

Na prática, foque em Claude Code, Codex ou opencode. Só isso.

Sim, existe Gemini CLI. Sim, existe Cursor. Sim, existe Windsurf, Crush, OpenClaw, Pi, Aider, e amanhã vai aparecer mais meia dúzia. Eu testei um monte. Leia meus posts de benchmark de LLMs, especialmente o “LLM Benchmarks Parte 3: DeepSeek, Kimi, MiMo”. A conclusão é chata e óbvia: hoje, as melhores opções de custo-benefício pra programação pesada são Opus 4.7 e GPT 5.5 nos planos Pro/Plus/Max subsidiados. Nada chega perto quando o assunto é trabalhar várias horas por dia com agente de código de verdade.

Pagar token direto é caro. Pagar plano mensal subsidiado sai muito mais barato. É por isso que eu vivo alternando entre Claude Code e Codex: não porque eu quero “multi-agent architecture”, mas porque os planos têm limites e eu trabalho muitas horas seguidas.

DeepSeek v4 e Kimi 2.6 são mais baratos? Sim. São usáveis? Sim. Eu gosto deles pra vários casos. Mas pra Agile Vibe Coding do jeito que venho defendendo desde o post “Do Zero à Pós-Produção em 1 Semana”, ainda falta. Eles tropeçam mais em continuidade, em refatoração longa, em testes, em entender o projeto inteiro. Dá pra usar? Dá. Mas se o objetivo é produtividade consistente, Opus e GPT ainda são a régua.

Rodar modelo open source local é legal. Eu mesmo brinquei bastante com isso no review do Minisforum MS-S1 Max com AMD AI Max+ 395. Pra one-shot, pra estudar, pra brincar com inferência local, é divertido. Pra Agile Vibe Coding o dia inteiro, todo dia, ainda não é prático. Latência, contexto, qualidade, manutenção do setup, VRAM, tudo cobra imposto.

Também não é prático ficar rodando múltiplos LLMs em paralelo, tipo “planner + executor + reviewer + juiz”. Eu testei isso no post “LLM Benchmarks: Vale a Pena Misturar 2 Modelos?”. A ideia é bonita no papel. Na prática, aumenta custo, aumenta latência, aumenta superfície de erro, e o ganho não paga a complexidade.

O segredo não é ter um monte de agentes. Esquece OpenClaw ou Pi pra programação do dia a dia. O segredo é processo de engenharia. XP. Testes. Clean Code pra agentes de IA. CI. Pair programming. Refatoração constante. Código pequeno. Deploy automatizado. Feedback rápido.

Ferramenta ajuda. Engenharia ganha.

ai-jail: autonomia com cerca

O primeiro projeto que quero destacar é o ai-jail. Ele é um wrapper de sandbox pra rodar agentes de IA com acesso restrito ao sistema. No Linux usa bubblewrap (bwrap) e Landlock. No macOS usa sandbox-exec. A ideia é simples: o agente enxerga o ambiente que precisa pra trabalhar, mas não sai fuçando seu sistema inteiro.

Uso todo dia? Sim. Uso sempre? Não.

Quando sei que não vou fazer nada arriscado, abro claude ou codex direto. Se vou mexer num projeto simples, só rodar testes, editar markdown, refatorar coisa local, muitas vezes nem me preocupo. Em mais de 600 horas de Agile Vibe Coding intenso, mais de meio milhão de linhas de código e documentação, nunca tive um caso desses folclóricos de LLM destruindo meu sistema host de um jeito irrecuperável.

E olha que eu usei agentes explicitamente pra configurar meu Omarchy. ZSH, Hyprland, Waybar, configs de terminal, scripts de login, tudo. Nunca fizeram nada que eu não pedi.

Essas histórias de “o agente deletou meu home inteiro sozinho” eu leio com um pé atrás. Na minha experiência, quando você pede pra deletar algo perigoso, Claude e Codex perguntam confirmação. Você precisa dizer sim. Se você disse sim sem ler, a culpa não é mágica negra do LLM. É usuário no modo zumbi.

Dito isso: nada é garantido. Daí o ai-jail.

Meu uso preferido é combinar ai-jail com o modo sem freio do harness:

ai-jail claude --dangerously-allow-permissions
ai-jail codex --dangerously-bypass-approvals-and-sandbox

Parece contraditório, mas faz sentido. Eu tiro a fricção de confirmação dentro do agente, mas coloco uma cerca no nível do sistema operacional. O agente pode trabalhar rápido dentro do projeto, mas o filesystem do host fica essencialmente read-only. O diretório atual fica read-write. O que eu mapear explicitamente com --rw-map também fica read-write. O resto não é pra tocar.

O README do ai-jail resume bem: é um sandbox wrapper pra agentes como Claude Code, GPT Codex, OpenCode e Crush. No primeiro run ele cria um .ai-jail no projeto, que pode ser commitado. Suporta --dry-run pra ver os mounts antes de executar, --lockdown pra modo mais restritivo, --private-home pra esconder dotfiles reais, --mask .env pra esconder arquivos sensíveis dentro do próprio projeto, e perfis de navegador isolado pra Chromium/Firefox.

O ponto importante: não venda isso como segurança absoluta. Processo sandbox não é VM. Kernel bug existe. Side channel existe. macOS tem limitações. O próprio README é claro: se você precisa isolar workload hostil de verdade, use uma VM descartável. Eu não uso ai-jail como “blindagem militar”. Uso como mais uma camada, boa o suficiente pro fluxo de desenvolvimento.

E mesmo dentro do projeto, tudo é Git. Eu faço push frequente pro GitHub ou pro meu Gitea privado. Então o pior caso realista é o agente destruir o diretório do projeto. Chato? Sim. Catastrófico? Não. Clono de novo. Volto do remote. Refaço o que estava local. Se o .git corromper, apago tudo e clono de novo.

Secrets também têm cópia fora. .env, tokens, keys, tudo que importa fica no Bitwarden. Self-hosted em Vaultwarden, claro. Então se eu perder o diretório local, não perdi a chave do reino.

O risco mais comum não é o agente deletar tudo. É você vazar segredo no Git. Isso aconteceu comigo mais de uma vez. Você dá git add ., esquece um .env, empurra pro remote, parabéns. Acontece. Por isso tem que olhar git status, git diff --cached, e pensar antes de dar push.

Mesmo quando acontece, os LLMs são muito competentes pra ajudar a reescrever histórico. Peço pra limpar o segredo do Git, forçar push, revisar se sumiu, e depois eu rotaciono a key. Não é bonito, mas é administrável.

Então sim, recomendo usar Claude/Codex com permissões perigosas dentro do ai-jail. Existe a chance de 0,001% de acidente irrecuperável? Existe. Mas se você é bom engenheiro, isso não deveria te matar. Eu tenho camadas: snapshots automáticos em Btrfs, restic pro NAS, NAS arquivando offsite em AWS Glacier, Git remoto, Bitwarden. Ferramenta nenhuma substitui backup.

ai-memory: contexto que sobrevive ao harness

O segundo é o ai-memory, que expliquei em detalhes no post “Criei um Sistema de Memória pra Agentes de Código: ai-memory”.

A motivação é simples: harnesses perdem contexto. Claude Code compacta. Codex compacta. opencode compacta. Sessão acaba. Você abre outro agente e ele não sabe o que aconteceu nas últimas 4 horas. Se você usa só um harness, talvez isso não incomode tanto. Se você alterna entre Claude e Codex como eu, incomoda rápido.

Eu queria um consolidador de memória de longo prazo que funcionasse atravessando harnesses diferentes. Algo que permitisse handoff entre Claude, Codex e opencode sem eu ficar escrevendo HANDOFF.md manual toda vez. Algo que capturasse prompts, tool calls e eventos de sessão via hooks, consolidasse em páginas markdown, indexasse com SQLite/FTS5, e expusesse tudo via MCP quando o agente precisasse consultar.

Outro motivador foi o que expliquei no post “RAG Está Morto? Contexto Longo, Grep e o Fim do Vector DB Obrigatório”. Pra projeto de código, quase sempre texto simples resolve mais do que arquitetura afetada de vector DB. Markdown, grep, SQLite FTS5, contexto longo e bons arquivos em docs/ já levam você longe. O ai-memory segue essa linha: compila memória em texto, deixa no disco, indexa simples, e só chama LLM quando vale consolidar.

O ai-memory não foi feito pra ser uma knowledge base navegável por usuário final. Ele tem uma UI web read-only, sim, mas isso é pra auditoria e inspeção. A memória é otimizada pra LLM consumir. É um wiki interno que o harness pode consultar quando acha que precisa. É um lugar onde posso pedir explicitamente “salva isso pra próxima sessão” e esperar que sobreviva mais do que a compactação padrão do Claude ou do Codex.

O README resume bem: agentes de código perdem todo contexto quando a sessão termina; o ai-memory dá a eles um wiki persistente compartilhado. Cada prompt, tool call e decisão pode ser capturado automaticamente. No fim da sessão, páginas relevantes são reescritas como narrativa coerente. Na próxima sessão, outro agente pode receber um handoff já prepended no contexto.

Isso é útil quando você fecha Claude às 18h, abre Codex no dia seguinte no mesmo diretório, e quer que ele saiba que você estava testando session cookies porque rotação de JWT tinha dado problema. Ou quando você volta a um projeto seis semanas depois e não lembra por que descartou Redis.

Mas não confunda com documentação canônica. Se você fez uma pesquisa importante que não quer perder, peça pro agente escrever um markdown em docs/ dentro do projeto. Decisão arquitetural, benchmark, análise de biblioteca, runbook de deploy, tudo que precisa sobreviver com garantia deve virar arquivo explícito no repo. Isso é mais simples, auditável e versionado.

O ai-memory cobre a faixa intermediária: informação transitória que talvez importe depois. Um bug estranho que apareceu. Um raciocínio que levou a uma decisão. Um gotcha de ambiente. Um resumo de sessão. Coisas que você não quer transformar em doc oficial ainda, mas também não quer jogar fora.

Ele ainda é beta. Eu uso em produção pessoal, mas precisa de muito mais gente batendo nele. Tem integração com Claude Code, Codex e opencode mais polida. Gemini CLI, OpenClaw e clientes MCP exóticos ainda precisam de mais teste. PRs são bem-vindos. Bug report também. “Instalei e quebrou no meu setup” é exatamente o tipo de feedback que revela suposição errada.

ai-usagebar: saber quando trocar de cavalo

Como falei acima, eu prefiro usar os planos subsidiados da Anthropic e da OpenAI. O problema é que, se você faz Agile Vibe Coding de verdade, você bate limite. Limite diário. Limite semanal. Limite de sessão. Limite que muda. Limite que não aparece direito em lugar nenhum.

Eu usava o claudebar, que é bom, mas só cobre Claude. Eu queria ver os principais vendors num lugar só. Daí nasceu o ai-usagebar, que apresentei no post “Criei um Widget de Waybar pra Omarchy pra Monitorar Uso de Planos de LLM: ai-usagebar”.

É um widget de Waybar e uma TUI em Rust pra monitorar uso de Anthropic Claude, OpenAI Codex/ChatGPT, Z.AI GLM e OpenRouter. Pra Claude e OpenAI, ele lê as credenciais OAuth que os CLIs oficiais já gravaram. Pra Z.AI e OpenRouter, usa API key. Mostra porcentagem da sessão, reset, limites, saldo, e permite trocar o vendor principal.

O valor disso é banal e por isso mesmo útil: bato o olho na barra e sei se devo continuar no Claude, fazer handoff pro Codex, ou recarregar crédito no OpenRouter. Não quero descobrir que cheguei no limite semanal no meio de uma refatoração grande.

Também tem a TUI standalone:

Se você não usa Omarchy, Hyprland ou Waybar, ainda dá pra rodar ai-usagebar-tui em qualquer terminal. SSH, tmux, terminal normal, tanto faz. A barra é conveniência. A TUI é a forma universal.

ghpending: pendência de GitHub sem ritual

Depois da maratona, fiquei com dezenas de ai-* e frank-* no GitHub. Isso cria um problema chato: issues e pull requests começam a aparecer. Contribuidor abre PR. Alguém reporta bug. Outro manda sugestão. Se eu tiver que abrir o navegador, entrar repo por repo, filtrar aba por aba, eu vou adiar. E se eu adiar, fico semanas sem responder.

Sim, eu poderia usar gh, a CLI oficial do GitHub. Aliás, uso. Mas eu queria uma coisa mais burra e mais rápida: um comando curto pra imprimir um digest de tudo que está pendente nos repos que eu escolhi monitorar. Nasceu o ghpending, que descrevi no post “Criei um CLI pra Checar Pendências no Meu GitHub: ghpending”.

É só isso: ghpending add pra escolher repos, ghpending pra ver o digest, ghpending list, ghpending rm. Sem autenticação funciona com limite de 60 req/h do GitHub. Com GITHUB_TOKEN=$(gh auth token) ghpending, sobe pra 5.000 req/h.

O ponto não é substituir o GitHub. É reduzir atrito. Se eu consigo rodar um comando no terminal e ver “tem 3 PRs e 2 issues pra olhar”, eu olho. Se depende de ritual de navegador, notificações e abas, fica pra depois.

E Claude/Codex são muito bons nesse tipo de trabalho. Dá pra pedir:

“Checa os pull requests abertos, revisa o código, vê se compila, roda os testes, adiciona teste se faltar, faz rebase de master se precisar, mergeia e fecha.”

Ou:

“Checa as issues abertas, avalia se tem bug real, reproduz se der, propõe correção, responde o usuário.”

Eles leem o PR, entendem o diff, rodam teste, fazem rebase, resolvem conflito simples, escrevem resposta pro contribuidor. Não é pra desligar o cérebro. É pra terceirizar o trabalho mecânico que você já sabe fazer.

Refatoração: peça explicitamente, várias vezes

Claude e Codex são muito bons em refatorar, mas não presuma que vão fazer isso automaticamente do jeito que você faria. Eu costumo começar projetos ou features com instruções explícitas:

“Use as melhores práticas de Rust. Evite duplicação desnecessária. Modularize só onde fizer sentido. Adicione unit tests pra toda feature nova. Siga princípios de Clean Code. Não crie abstração antes de precisar.”

Depois de uma feature grande, uma correção grande, ou algumas horas de desenvolvimento, paro e peço:

“Agora que mexemos bastante no código, reavalie com calma. Delete código morto. Refatore duplicações óbvias. Adicione testes faltantes. Remova magic numbers. Veja se tem módulos grandes demais. Não mude comportamento sem teste.”

Antes de release:

“Antes de publicar essa versão, faça uma auditoria de sanidade. Procure vazamento de secrets, permissões perigosas, comandos destrutivos, path traversal, unwraps desnecessários, falta de validação, e qualquer coisa que pareça vulnerabilidade óbvia.”

Isso garante segurança? Claro que não. Nem perto. Mas remove muito erro besta. É mais uma camada. Eu gosto de rodar essa auditoria com Claude e depois com Codex, porque cada um acha coisas diferentes. Mesmo assim, bug passa. Segurança é processo, não ritual mágico.

Experimentos descartáveis: código ficou barato

Antes de escolher biblioteca, framework, arquitetura, modelo ou serviço, eu gosto de criar experiments/.

Exemplo:

“Antes de escolher entre Qwen e DeepSeek, cria um protótipo descartável em experiments/ pra A/B test. Documenta a análise em docs/ com resultado, custo, latência, qualidade e recomendação.”

Isso mudou meu jeito de decidir. Antes, muita decisão de engenharia virava opinião, feeling, fé em benchmark dos outros. Agora código é barato. Peço pro agente fazer duas ou três versões, rodar teste, medir, documentar, jogar fora o que não presta.

Prototipar ficou rápido de verdade. O Frank Karaoke é um bom exemplo: transformar YouTube num app de karaokê era o tipo de ideia que antes eu talvez deixasse numa lista mental por meses, esperando “um fim de semana livre” que nunca chega. Agora dá pra abrir um experiments/, pedir um protótipo tosco, testar o caminho técnico, e decidir se vale virar projeto. Olha meus outros posts de 2026 sobre os projetos frank-* e ai-*: quase todos começaram assim, como código descartável que provou alguma coisa antes de merecer nome.

Mas protótipo barato não significa one-shot. Já escrevi em “Por que as LLMs não te dão o resultado esperado”: prompt bom é conversa iterativa. Você dá contexto, mostra referência, aponta restrição, lê o resultado, corrige direção, manda refazer. Se você joga uma frase vaga e espera produto pronto, o erro é seu.

Também aprendi isso apanhando. No post do Frank Yomik contei meu primeiro fracasso real com vibe coding: quando a direção está errada, insistir no mesmo prompt só cava o buraco. Tem hora que precisa reduzir escopo, isolar o problema, criar teste, trocar estratégia. LLM não transforma plano ruim em engenharia boa.

E tem domínio onde você precisa estudar junto. No post de Driveclub e shadPS4, a IA quase me levou pra todo lado errado porque o problema exigia entender renderização, gamma, shaders, buffers. A ferramenta ajuda a explorar, mas quem decide se a explicação faz sentido ainda é você. Se você não entende o suficiente pra verificar, está só aceitando chute bonito.

Por isso também repito a ideia de “Software Nunca Está Pronto”: deploy não é linha de chegada. O protótipo vira produto quando aguenta bug report, manutenção, refatoração, docs, release, rollback, usuário reclamando. LLM ajuda muito nesse ciclo chato. Mas o ciclo continua existindo.

Se é testável, teste. Se dá pra medir, meça. Se não dá pra medir, pelo menos escreva as premissas. O importante é não escolher só porque “parece melhor”.

Código barato também significa desapego. Faça código pra jogar fora. Faça protótipo feio. Faça benchmark descartável. Peça pro agente documentar o que aprendeu em docs/decision-qwen-vs-deepseek.md, depois apague experiments/ se quiser. O documento fica. O aprendizado fica.

LLMs também são muito bons em documentação. Use isso. Peça pra documentar tudo. Por que escolhemos PostgreSQL em vez de SQLite nesse caso. Por que o deploy usa Docker image multi-stage. Por que o serviço roda atrás de Cloudflare Tunnel. Por que aquele sysctl existe. Mesmo que depois você delete metade, o custo de escrever caiu perto de zero.

Deploy automatizado ou você vai parar de manter

Todo projeto meu que importa tem build automatizado. Muitos rodam no meu homelab, como descrevi em “Migrando meu Home Server com Claude Code”. Quase todo projeto tem um bin/deploy que builda imagem Docker, faz push, rotaciona no servidor, aplica migração se precisar, e valida healthcheck.

Claude e Codex são excelentes em deploy. Eles leem o bin/deploy, entendem Dockerfile, editam GitHub Actions, ajustam release workflow, corrigem assinatura de binário, atualizam Homebrew tap, geram checksum. E sim, eu peço pra Claude/Codex dar SSH no meu homelab e redeployar container Docker. Eles são muito bons nisso. O ai-jail, por exemplo, tem GitHub Actions pra buildar binários assinados pra Linux e macOS.

Se você tem dezenas de projetos, quanto mais automatizado melhor. Eu raramente digito comando administrativo no terminal sozinho. Peço pro LLM fazer, observo, aprovo o que for perigoso, e depois peço:

“Documente o que foi feito e por que foi feito.”

Isso vale pro homelab e pra minha workstation. Meu Omarchy é customizado via Claude: ZSH, Hyprland, Waybar, scripts, atalhos, temas, integrações. Até meus setups de gaming/emulação entram nessa, como mostrei no post dos retrogames de corrida rodando no Distrobox. Esse é um caso onde normalmente não uso ai-jail, porque justamente quero mexer no host. Então olho comandos, leio diffs, aprovo devagar. Mesmo assim, nunca tive o agente quebrando meu sistema de um jeito irrecuperável. Pelo contrário. Meu PC nunca esteve tão estável e documentado.

Dias depois, quando esqueço por que configurei alguma coisa daquele jeito, o contexto está em markdown, Git, ai-memory, ou no próprio histórico do projeto. Eu posso perguntar e o agente tem de onde puxar.

Até este post foi escrito assim

Inclusive, é assim que escrevo estes posts agora. Eu jogo um bloco enorme e bagunçado do meu cérebro no Claude. Peço pra ler posts recentes pra calibrar estilo. Peço pra checar os projetos diretamente e elaborar as partes técnicas. Peço pra usar as screenshots mais recentes, subir pro S3 quando precisa, linkar os posts anteriores, revisar o tom.

Depois eu leio e edito. Corto o que ficou genérico. Troco frase que parece release note. Coloco minhas broncas de volta. O resultado ainda é meu texto, só que agora eu gasto energia no que importa: decidir o que dizer, corrigir nuance, cortar besteira.

“Mas você testou o Pi?”

Toda vez que falo de LLM ou ferramenta de LLM, aparece alguém nos comentários com a mesma pergunta: “mas você testou Pi?”, “mas você testou DeepSeek?”, “mas e o Qwen?”, “mas e o modelo novo que saiu ontem?”. Toda. Santa. Vez.

É irritante pra cacete. E quase sempre vem de três tipos de pessoa: quem não testou nada e quer terceirizar o trabalho, quem já escolheu uma ferramenta e quer que eu valide a escolha dela, ou fanboy que trata vendor de LLM como time de futebol. Todos soam iguais. NPC repetindo diálogo de tutorial.

Engenheiro de software não deveria decidir baseado em opinião dos outros. Nem na minha. Se você escolhe ferramenta porque “o Akita falou”, você entendeu errado. Eu defendo Claude Code e Codex porque usei centenas de horas, em projetos reais, publicando código e post-mortem do que funcionou e do que falhou. E mesmo assim eu não parei em opinião.

Eu criei meu próprio benchmark automatizado: llm-coding-benchmark. Atualizo quando vendor popular solta versão nova. Rodo cenários comparáveis. Publico resultado. Depois ajusto minha opinião baseado nos dados. É por isso que eu tenho segurança pra dizer que, no meu fluxo, Opus e GPT continuam vencendo. Não porque acordei com vontade de defender logo de empresa bilionária.

Se sua primeira reação foi “mas você testou Qwen?”, ótimo. Testa você. Roda o benchmark. Cria cenário melhor. Manda PR. Mostra número. Mostra custo. Mostra latência. Mostra onde falhou. Mostra onde ganhou. Traga dado novo.

Opinião solta é irrelevante. “Pra mim funciona” não escala. “Eu gosto mais” não interessa. “No meu prompt one-shot ele foi melhor” é anedota. Engenharia começa quando dá pra reproduzir, comparar e agir em cima.

Então fica simples: traga dado acionável ou fique quieto. Eu não preciso de torcida organizada de vendor nos comentários. Preciso de gente testando, medindo e contribuindo resultado novo.

Checklist final

Resumo curto, porque este post já ficou grande:

• Foque em Claude Code, Codex ou opencode. Pare de colecionar agente.
• Use Opus 4.7 e GPT 5.5 via planos Pro/Plus/Max quando produtividade diária importa.
• DeepSeek, Kimi e modelos locais são úteis, mas ainda não substituem o fluxo principal.
• Agile Vibe Coding é XP com LLM: testes, Clean Code, CI, pair programming e deploy.
• Use ai-jail quando quiser autonomia do agente com cerca no filesystem.
• Combine ai-jail com permissões perigosas do Claude/Codex quando o projeto estiver protegido por Git.
• Tenha backup de verdade: Btrfs snapshots, restic, NAS, offsite, Git, Bitwarden.
• Revise git add, git diff --cached e pushes pra não vazar secrets.
• Use ai-memory pra contexto transitório e handoff entre agentes.
• Escreva documentação canônica em docs/ quando a informação precisa sobreviver com garantia.
• Use ai-usagebar pra saber quando trocar de Claude pra Codex, ou quando recarregar OpenRouter.
• Use ghpending pra não abandonar issues e PRs.
• Peça refatoração explicitamente depois de features grandes.
• Rode auditoria de segurança antes de release, de preferência com mais de um modelo.
• Crie protótipos descartáveis em experiments/ antes de decidir por fé.
• Se discordar de benchmark, rode o llm-coding-benchmark e traga dado novo.
• Documente decisões em markdown. Código ficou barato. Documentação também.
• Automatize deploy. Se depender de ritual manual, você vai parar de fazer.

No fim, é o mesmo conselho de sempre: ferramenta muda, engenharia não. LLM aumenta a alavanca. Se você já tinha bons hábitos, vai produzir mais. Se não tinha, vai só produzir bagunça mais rápido.

E sim, isso muda a interface do trabalho. Já escrevi sobre isso em “VS Code é o novo Cartão Perfurado”: ficar polindo pixel em editor virou nostalgia de programador velho. A parte difícil agora é escrever intenção direito, revisar execução sem preguiça, medir resultado, jogar fora código barato, e não confundir opinião com dado.

–

Em janeiro publiquei um shell script de ~170 linhas que montava um sandbox com bubblewrap pra rodar Claude Code, OpenCode, Crush e qualquer outro agente de IA. Funcionava. Resolvia o problema. Mas era um script bash jogado em ~/.local/bin/ que você tinha que copiar, colar, e rezar pra não precisar customizar demais.

Dois meses usando aquele script todo dia me mostraram os limites. Queria configuração por projeto. Queria suporte a macOS pros devs do meu time. Queria parar de editar arrays em bash toda vez que precisava de um diretório extra. E queria algo que alguém pudesse instalar com brew install ou cargo install em 10 segundos, sem ler 170 linhas de script.

Resultado: ai-jail. Uma ferramenta em Rust, ~880KB, 4 dependências, 124 testes, que faz exatamente o que aquele script fazia e mais. Vou explicar o que mudou e por que você deveria estar usando.

O Problema (de novo, pra quem pulou o post anterior)

Agentes de IA pra programação precisam de acesso ao seu filesystem. Precisam rodar compiladores, linters, grep, ls, make, cargo, npm. O mínimo pra serem úteis. O problema é que junto com esse acesso vem a capacidade de ler ~/.aws/credentials, exportar suas chaves SSH, ou rodar um rm -rf fora do diretório do projeto.

Não é paranoia. Supply-chain attacks são reais. Toda hora uma lib de NPM, PyPI, ou RubyGems é comprometida. Se o agente rodar npm install e um post-install script malicioso tentar exfiltrar seus dados, a única coisa entre o atacante e suas credenciais é o que você montou de barreira antes.

A resposta é um sandbox. Especificamente, um que permita o agente trabalhar no diretório do projeto com as ferramentas que precisa, mas que torne invisível todo o resto do sistema.

De Script pra Ferramenta

O shell script do post anterior já resolvia isso com bubblewrap. O ai-jail resolve o mesmo problema, mas trata as limitações que dois meses de uso diário revelaram:

A lógica core é a mesma: bubblewrap cria namespaces isolados de PID, UTS, IPC, monta o $HOME como tmpfs efêmero, e só monta o diretório do projeto com escrita. A diferença é que agora tudo isso é configurável sem editar código.

Instalação

Quatro formas:

# Homebrew (macOS e Linux)
brew tap akitaonrails/tap && brew install ai-jail

# Cargo
cargo install ai-jail

# Mise
mise use -g ubi:akitaonrails/ai-jail

# Binário direto do GitHub Releases
curl -fsSL https://github.com/akitaonrails/ai-jail/releases/latest/download/ai-jail-linux-x86_64.tar.gz | tar xz
sudo mv ai-jail /usr/local/bin/

No Linux, bubblewrap precisa estar instalado separadamente: pacman -S bubblewrap (Arch), apt install bubblewrap (Debian/Ubuntu), dnf install bubblewrap (Fedora). No macOS não precisa de nada extra.

Uso Básico

cd ~/Projects/meu-app

# Roda Claude Code dentro do sandbox
ai-jail claude

# Roda Codex
ai-jail codex

# Roda OpenCode
ai-jail opencode

# Bash puro pra debug
ai-jail bash

# Qualquer comando
ai-jail -- python script.py

Na primeira execução, ele cria um arquivo .ai-jail no diretório do projeto:

# ai-jail sandbox configuration
# Edit freely. Regenerate with: ai-jail --clean --init

command = ["claude"]
rw_maps = []
ro_maps = []

Esse arquivo é commitável no repo. Quando outro dev do seu time clona o projeto e roda ai-jail, a mesma configuração se aplica.

Se quiser adicionar diretórios extras, pode fazer pela CLI ou direto no TOML:

# Diretório extra com escrita
ai-jail --rw-map ~/Projects/shared-lib claude

# Diretório extra somente leitura
ai-jail --map /opt/datasets claude

Quer ver o que o sandbox vai fazer sem executar nada?

ai-jail --dry-run --verbose claude

Isso mostra cada mount point, cada flag de isolamento, o comando completo do bubblewrap. Sem surpresas.

Por Que Bubblewrap no Linux

Avaliei as alternativas antes de decidir. O documento completo de análise tá no repositório, mas o resumo é:

Bubblewrap (bwrap) é o sandbox que o Flatpak usa pra isolar todo app desktop. ~50KB de binário, ~4000 linhas de C, mantido pelo time do GNOME. Roda sem root usando CLONE_NEWUSER pra criar namespaces sem privilégio elevado. Tá empacotado em toda distro Linux relevante e testado em escala por milhões de instalações Flatpak.

Considerei e descartei as alternativas. Firejail requer setuid root, e confiar em setuid pra proteger contra agentes que já rodam no seu sistema é contraditório. nsjail e minijail são projetados pra ambientes de produção (Google os usa internamente), complexos demais pra workstation de dev. systemd-nspawn requer root e é pra containers de sistema, não pra isolar um processo.

Landlock é um caso diferente. Ele não substitui bubblewrap — não tem nada a ver com namespaces ou mount isolation. Mas complementa. Landlock é um LSM (Linux Security Module) que controla acesso no nível do VFS, independente dos mount namespaces. Isso fecha vetores que o bwrap sozinho não cobre: rotas de escape pelo /proc, tricks com symlinks dentro de mounts permitidos, e serve como seguro contra bugs no próprio mecanismo de namespaces. A partir da v0.4.0, o ai-jail aplica Landlock automaticamente em kernels 5.13+ como defense-in-depth. Usa ABI V3 (Linux 6.2+) com degradação graceful pra V1 em kernels mais antigos, e vira no-op silencioso se o kernel não suportar. Se causar problema com alguma ferramenta específica, --no-landlock desativa.

Bubblewrap acerta no ponto exato: isolamento real sem root, em toda distro, e simples o suficiente pra wrappear num binário de 880KB.

O Que o Sandbox Faz no Linux

Quando você roda ai-jail claude, o seguinte acontece:

O agente roda em namespaces isolados de PID, UTS e IPC, com hostname ai-sandbox, e morre automaticamente se o pai morrer (--die-with-parent).

O filesystem é montado numa sequência específica (bubblewrap é order-dependent). /usr, /etc, /opt, /sys entram read-only pras ferramentas do sistema. /dev e /proc montados pra acesso a devices e processos. /tmp e /run como tmpfs frescos. GPUs auto-detectadas (/dev/nvidia*, /dev/dri). Docker socket, X11/Wayland, /dev/shm, tudo auto-detectado e montado se existir.

A parte mais importante é o tratamento do home directory. $HOME é montado como tmpfs vazio. Depois, seletivamente, dotfiles são layered por cima. .gnupg, .aws, .ssh, .mozilla, .sparrow nunca são montados (dados sensíveis). .claude, .crush, .codex, .aider, .config, .cargo, .cache, .docker entram como read-write porque os agentes precisam escrever aqui. Todo o resto entra read-only. Dentro de ~/.config, subdiretórios de browser são escondidos atrás de tmpfs: BraveSoftware, Bitwarden. Mesma coisa em ~/.cache: BraveSoftware, chromium, spotify, nvidia. O agente não consegue nem ver que esses diretórios existem.

O diretório corrente do projeto é o único lugar com permissão de escrita (além dos dotdirs de ferramentas). O agente modifica o código, mas não toca no resto.

macOS: sandbox-exec

No macOS, o backend é o sandbox-exec com profiles SBPL (Sandbox Profile Language). É uma API legada da Apple, depreciada oficialmente mas sem substituto público. Funciona hoje, mas a Apple pode remover no futuro.

O ai-jail gera um profile SBPL em runtime que replica a mesma lógica do Linux:

• Default deny em tudo
• Permite operações de processo (exec, fork, signal)
• Permite rede (exceto em lockdown)
• Permite leitura global, nega paths sensíveis (.gnupg, .aws, .ssh, ~/Library/Keychains, ~/Library/Mail)
• Permite escrita só em diretório do projeto, dotfiles de ferramentas, e /tmp

As limitações são reais. GPU (Metal) e Display (Cocoa) são system-level no macOS, sandbox-exec não consegue restringir. As flags --no-gpu e --no-display simplesmente não têm efeito no macOS. A paridade entre plataformas é aproximada, não exata.

Mesmo com essas limitações, é melhor do que rodar o agente completamente aberto. O sandbox-exec protege contra acesso a filesystem sensível e, em lockdown, remove permissões de escrita e rede.

Windows: Não Suportado (E Provavelmente Nunca Será)

Não é falta de vontade, é falta de primitivas. Windows não tem equivalente userspace a Linux namespaces. Não tem mount API como bubblewrap. AppContainers existem mas usam um modelo de segurança completamente diferente, requerem privilégios de admin, e mapear a funcionalidade do bwrap pra AppContainers seria efetivamente escrever outro projeto do zero.

A solução pra Windows é WSL 2:

# No WSL 2 (kernel Linux real)
sudo apt install bubblewrap
cargo install ai-jail
# ou: mise use -g ubi:akitaonrails/ai-jail

cd /mnt/c/Users/voce/Projects/meu-app
ai-jail claude

WSL 2 roda um kernel Linux de verdade. Bubblewrap funciona normalmente. Os arquivos do Windows ficam acessíveis em /mnt/c/. Performance de I/O é mais lenta pelo mount de 9p, mas funciona. Pra projetos grandes, clonar dentro de ~/Projects/ no lado Linux melhora a performance consideravelmente.

Lockdown Mode

Pra workloads que você realmente não confia, existe --lockdown:

ai-jail --lockdown bash

Lockdown faz tudo que o modo normal faz, mas vai além. O projeto é montado read-only (não read-write). GPU, Docker, Display e mise são desabilitados. Flags --rw-map e --map são ignoradas. $HOME vira tmpfs puro, sem dotfiles do host. No Linux, a rede é cortada com --unshare-net e o ambiente é limpo com --clearenv. No macOS, as variáveis de ambiente são limpas e as regras de escrita e rede são removidas do SBPL.

É o sandbox mais restritivo que dá pra fazer sem usar uma VM. Útil pra auditar código de terceiros ou rodar agentes em projetos que você não conhece.

Bootstrap: Configuração Automática de Permissões

ai-jail --bootstrap gera configurações de permissão pras ferramentas que você usa:

ai-jail --bootstrap

Pro Claude Code, gera ~/.claude/settings.json com listas de allow/deny/ask. Permite git status, diff, log, ls, grep, cargo, npm, python, docker compose. Bloqueia rm -rf, sudo, chmod 777, git push –force. Pergunta antes de git push, rm, docker run.

Pro Codex, gera ~/.codex/config.toml com approval_policy = "on-request".

Pro OpenCode, gera ~/.config/opencode/opencode.json com permissões de bash, edit, write.

Antes de sobrescrever qualquer arquivo, faz backup automático (settings.json.bak). E rejeita operações se o alvo for um symlink, pra evitar path traversal.

É exatamente o conteúdo que eu coloquei manualmente no post anterior, mas automatizado e testado.

Mas o Claude Code Já Tem Sandbox Próprio

Tem. Desde outubro de 2025, o Claude Code oferece um sandbox runtime via o comando /sandbox. E adivinhe o que ele usa por baixo? Bubblewrap no Linux e sandbox-exec no macOS. O mesmo stack.

Mas as diferenças importam.

ai-jail é agnóstico de ferramenta. Funciona com Claude, Codex, OpenCode, Crush, e qualquer comando. O sandbox do Claude só protege o Claude. Se amanhã você trocar de agente, o ai-jail continua funcionando igual.

O ponto que mais me incomoda é o escape hatch. Quando um comando falha por restrição de sandbox, o Claude pode tentar novamente com dangerouslyDisableSandbox, caindo de volta no fluxo normal de permissões. Dá pra desabilitar isso ("allowUnsandboxedCommands": false), mas é opt-out, não opt-in. No ai-jail, não existe escape hatch. O processo roda dentro do bwrap ou do sandbox-exec, ponto. Não tem como o agente decidir sozinho sair do sandbox.

Outra diferença prática: o .ai-jail vive no diretório do projeto e pode ser commitado no repositório. Qualquer dev que clona o projeto herda a mesma política de sandbox. O sandbox do Claude depende de settings.json global.

Quando roda dentro de Docker, o sandbox do Claude cai pra um modo enableWeakerNestedSandbox que, nas palavras da própria documentação, “considerably weakens security”. O ai-jail não foi projetado pra rodar dentro de Docker (ele roda diretamente na workstation do dev), então esse problema não existe.

Sobre rede: o sandbox do Claude roteia tráfego por um proxy e permite/bloqueia por domínio. ai-jail no modo normal herda a rede do host; no lockdown, corta a rede inteira com --unshare-net. A abordagem do Claude é mais granular; a do ai-jail é mais simples e mais difícil de contornar.

Os dois não são mutuamente exclusivos. Dá pra rodar o sandbox do Claude dentro do ai-jail. O ai-jail cuida do isolamento de filesystem; o sandbox do Claude adiciona filtragem de rede por domínio. Layers de segurança se somam.

Por Que Não Usar –dangerously-skip-permissions Sem Jail

Vou ser direto: se você roda Claude Code com --dangerously-skip-permissions sem nenhum sandbox, tá confiando cegamente que a LLM nunca vai executar algo destrutivo. E tá confiando que nenhuma dependência do seu projeto foi comprometida num supply-chain attack.

Toda flag --dangerously tem esse nome por um motivo. O Claude Code é explícito: esse modo existe pra CI/CD e automação em ambientes já isolados (containers, VMs descartáveis). Não pra sua workstation pessoal com ~/.aws/credentials, ~/.gnupg/, SSH keys, e o banco de senhas do seu browser.

Com ai-jail, o agente tem autonomia total dentro do sandbox. Faz o que quiser no diretório do projeto, usa as ferramentas que precisa, e não consegue acessar nada fora do que foi explicitamente permitido.

ai-jail + Git: A Rede de Segurança que Você Já Tem

Tem uma coisa que eu não mencionei ainda e que muda o cálculo de risco: se o seu projeto tá num repositório Git, com remote no GitHub/GitLab, e o agente não tem permissão de git push, o dano que ele consegue causar é limitado ao diretório local.

Pense assim. O pior cenário dentro do ai-jail é o agente corromper todos os arquivos do projeto. Irritante? Sim. Catastrófico? Não. Você faz git checkout . e volta ao último commit. Se ele corromper o .git de alguma forma (improvável, mas possível), você deleta o diretório e clona de novo. O remote não foi tocado.

Por isso o --bootstrap do ai-jail coloca git push na lista de “ask” (perguntar antes), não na lista de “allow”. E git push --force vai direto pra “deny”. O agente pode commitar à vontade localmente, pode criar branches, pode fazer rebase. Nada disso afeta o remote. Quando chega na hora de push, você revisa o que ele fez e decide se vai pro ar.

Essa combinação, sandbox pra filesystem + Git pro código + push manual, já te dá um nível de segurança muito razoável pro dia a dia. O ai-jail protege seus dados pessoais e o sistema. O Git protege seu código. E a decisão de publicar continua sendo sua.

Se quiser ir além, as próximas duas seções cobrem camadas adicionais.

ai-jail vs Dev Containers

Desde que escrevi o ai-jail, a pergunta mais frequente é: “por que não usar Dev Containers?”. A resposta curta é que um não substitui o outro. Resolvem problemas diferentes.

Dev Containers (a spec do containers.dev) define um ambiente de desenvolvimento completo num devcontainer.json. Você especifica imagem base, ferramentas, extensões do VS Code, variáveis de ambiente, e o editor monta tudo pra você num container Docker. O Docker também lançou recentemente os Docker Sandboxes, que vão além e rodam cada agente numa microVM com Firecracker, com isolamento de hardware.

ai-jail não faz nada disso. Ele não define ambiente. Não instala ferramentas. Não roda imagem Docker. Ele pega o ambiente que já existe na sua máquina e restringe o que o processo pode acessar.

Na prática, a diferença é:

Dev Container faz mais sentido quando você precisa que todo o time tenha exatamente o mesmo ambiente, ou quando o projeto tem dependências que ninguém quer instalar no host, ou pra rodar agentes não-interativos em CI/CD. Docker Sandboxes com microVM são o isolamento mais forte que existe fora de uma VM dedicada.

ai-jail faz mais sentido quando você já tem o ambiente configurado e quer startup instantâneo sem Docker daemon. Ou quando usa ferramentas que são chatas de rodar dentro de container (CUDA, Wayland, mise). Ou simplesmente quando quer a mesma proteção pra qualquer agente, não só os que têm integração com devcontainer.

E dá pra combinar. Eu conheço gente que roda ai-jail dentro de um Dev Container pra ter reprodutibilidade de ambiente + restrição de filesystem. Layers de segurança se somam.

Sistemas Operacionais Imutáveis: A Última Camada

Se você quer levar a segurança a sério, a terceira camada é o sistema operacional em si.

Sistemas imutáveis como Fedora Silverblue, NixOS, e openSUSE Aeon têm o filesystem raiz read-only. O sistema base não pode ser modificado por nenhum processo, nem com root. Atualizações são atômicas: ou aplicam completamente ou não aplicam. E se algo der errado, você faz rollback pra imagem anterior em um reboot.

Na prática, isso significa que mesmo se um agente de IA escapasse do sandbox (exploiting uma vulnerabilidade no kernel, por exemplo), ele não conseguiria modificar o sistema de forma persistente. No próximo reboot, o sistema volta ao estado declarado. No NixOS, o sistema inteiro é definido por um arquivo de configuração (configuration.nix). No Silverblue, o base é uma imagem OSTree que recebe updates atômicos via rpm-ostree.

Pra desenvolvedores, a pegada é: suas ferramentas de dev rodam em containers (Toolbox/Distrobox no Silverblue, nix-shell no NixOS). O sistema base fica intocado. Apps desktop vêm via Flatpak, que já roda em sandbox. O resultado é que a superfície de ataque do host é mínima.

Fedora Silverblue é provavelmente a entrada mais acessível. Já é Fedora por baixo, com GNOME, funciona com hardware que Fedora suporta, e o Toolbox te dá um Fedora Server containerizado onde você instala o que quiser sem tocar no host. NixOS é mais poderoso (reprodutibilidade total, rollback declarativo), mas a curva de aprendizado é real.

A combinação completa fica assim: o OS imutável cuida do sistema (filesystem read-only, updates atômicos, rollback em um reboot). O ai-jail cuida da sessão (namespace isolado, home efêmero, dados sensíveis invisíveis). E o Git cuida do código (remote intocado enquanto o agente não tiver push).

Nenhuma dessas camadas é perfeita sozinha. Mas o ataque que fura as três ao mesmo tempo — escapar do namespace, persistir num filesystem read-only, e corromper um remote Git — é um cenário que eu ficaria confortável chamando de improvável.

O melhor é que nenhuma exige mudar como você trabalha. O ai-jail é um comando antes do seu agente. Git você já usa. E um OS imutável é uma instalação, não uma mudança de workflow.

Detalhes Técnicos (Pra Quem Se Importa)

Escrito em Rust com 124 testes e 4 dependências: lexopt (parsing de CLI sem clap), serde + toml (config), nix (syscalls Unix). Sem runtime async, sem framework de cores (ANSI direto), binary de ~880KB com LTO e strip.

O signal handling é feito corretamente: SIGINT, SIGTERM, e SIGHUP são forwarded pro processo filho. O handler só chama libc::kill, que é async-signal-safe. O reaping do processo usa waitpid em loop com retry em EINTR.

Arquivos temporários (como o /etc/hosts customizado que o sandbox monta) usam RAII: um SandboxGuard que implementa Drop em Rust. Se o processo pai morrer por qualquer razão, o cleanup acontece.

A compatibilidade de configuração é garantida por política de desenvolvimento: nunca remover campos, nunca renomear, campos novos sempre com #[serde(default)], campos desconhecidos são silenciosamente ignorados. Testes de regressão pra formatos antigos de .ai-jail garantem que atualizar o binário nunca quebra configs existentes. São 32 testes só de config.

Roadmap

O que falta:

• Mais backends de ferramentas no bootstrap: Aider, Cursor, Windsurf. Conforme mais agentes padronizarem arquivos de configuração de permissão.
• Profile sharing pra monorepos, pra não ter que configurar cada serviço separadamente.

Instalação e Primeiro Uso (Resumo Rápido)

# 1. Instalar
brew tap akitaonrails/tap && brew install ai-jail
# ou: cargo install ai-jail

# 2. No Linux, instalar bubblewrap
sudo pacman -S bubblewrap  # Arch
# sudo apt install bubblewrap  # Debian/Ubuntu

# 3. Entrar no projeto e rodar
cd ~/Projects/meu-app
ai-jail claude

# 4. (Opcional) Gerar configs de permissão
ai-jail --bootstrap

# 5. (Opcional) Ver o que o sandbox faz
ai-jail --dry-run --verbose claude

O .ai-jail criado pode ser commitado no seu repo. A partir daí, qualquer dev que clonar o projeto roda ai-jail claude e tem o mesmo sandbox.

Conclusão

O shell script de janeiro resolveu o problema. O ai-jail resolve o problema direito. Config por projeto, suporte a macOS, lockdown mode, bootstrap de permissões, dry-run pra auditar, e um binário de 880KB que instala em 10 segundos.

Se você usa agentes de IA pra programar, rode eles num sandbox. A boa vontade da LLM não é garantia de nada, e supply-chain attacks não escolhem vítima. Isolamento de processo é a barreira que funciona.

O projeto é GPL-3.0 e tá no GitHub: github.com/akitaonrails/ai-jail

Issues e PRs são bem-vindos.

O problema é que pra serem eficientes, essas ferramentas precisam ter acesso ao seu sistema de arquivos pra vasculhar os arquivos do seu projeto, pra analizar o código. E mais: conseguir rodar ferramentas como compiladores, linters, e coisas mundanas como grep, sed, awk, ls, e outros comandos do seu sistema.

Eventualmente, uma LLM pode mandar executar um rm -Rf / aleatório e apagar coisas no seu sistema, por exemplo. O código em si, se por acidente apagar o que não devia, teoricamente você deveria estar seguro porque seu código já deveria estar, no mínimo, num repositório de Git (GitHub, GitLab, etc), então seria só reverter a mudança. Mas se o agente rodar um rm fora do diretório do seu projeto, pode criar todo tipo de problema.

Não é comum isso acontecer e todas as ferramentas costumam ter checagens pra isso, incluindo perguntar se você quer realmente executar o comando. Ao mesmo tempo, eles também tem a opção de permitir rodar qualquer comando durante a sessão, sem perguntar - porque uma hora começa a ficar tedioso dar “ok” pra cada comando individual. Todo mundo acaba ficando com preguiça e diz “foda-se, roda o que quiser”.

E vocês devem estar pensando “ah, minha ferramenta X é bem comportada, ele sempre pergunta antes de rodar qualquer coisa, então eu controlo”. Não esqueçam: ATAQUES DE SUPPLY-CHAIN existem. Toda hora alguma biblioteca open source é invadida com malware e os programas que usam essas libs acabam sendo infectados sem saber. Isso já aconteceu várias vezes, em várias libs de NPM por exemplo. Não tem como garantir que mesmo um software open source seja confiável. Sempre parta do princípio que tudo é inseguro até prova em contrário e trate esses programas dessa forma: com restrição máxima.

Pra garantir que esses agentes realmente não vão fazer nada fora do diretório do projeto, o melhor é criar um JAIL. E aqui vai o comando pra isso:

bwrap --ro-bind /usr /usr \
      --ro-bind /bin /bin \
      --ro-bind /lib /lib \
      --ro-bind /lib64 /lib64 \
      --dev /dev \
      --proc /proc \
      --bind $(pwd) $(pwd) \
      --chdir $(pwd) \
      --unshare-all \
      --share-net \
      bash

bwrap é o Bubblewrap um dos componentes que permitem a existência de coisas como Flatpak. Ele cria um sandbox. O Bash que vai rodar ao executar o comando acima está essencialmente em “jail”, ou seja, “preso”. Nele damos acesso somente de leitura a alguns diretórios do sistema caso precise de bibliotecas e ferramentas. Pra isso serve o --ro-bind.

Mas somente o diretório corrente pwd vai ter permissão de escrita. Qualquer comando que rodar dentro desse jail não tem permissão de escrever em nenhum outro lugar o seu sistema. Veja o exemplo na foto abaixo onde eu tento apagar um arquivo na minha $HOME:

Ele não consegue nem listar os arquivos na minha home. É tudo invisível dentro do sandbox. Essa é uma das vantagens de apps rodando com Flatpak: eles são muito mais isolados do que apps instalados direto.

Dentro desse bash em sandbox podemos agora executar opencode, crush, cursor ou qualquer outro agente e ter certeza que eles não vão fazer nenhuma besteira no seu sistema.

Pra facilitar, recomendo criar um script como ~/.local/bin/ai-jail:

#!/bin/bash

# ai-jail — bubblewrap sandbox for AI coding agents
# Mounts the project dir read-write, auto-discovers home dotfiles with a
# deny-list for sensitive dirs, and isolates namespaces.
#
# Usage: ai-jail [--map PATH]... COMMAND [ARGS...]
#        ai-jail claude
#        ai-jail bash

PROJECT_DIR=$(pwd)
TEMP_HOSTS=$(mktemp /tmp/bwrap-hosts.XXXXXX)

trap 'rm -f "$TEMP_HOSTS"' EXIT

# ── Mise discovery ─────────────────────────────────────────────
REAL_MISE_BIN=$(type -p mise 2>/dev/null || echo "")

# ── Localhost fix (Go resolver needs /etc/hosts) ───────────────
printf '127.0.0.1 localhost ai-sandbox\n::1       localhost ai-sandbox\n' > "$TEMP_HOSTS"

# ── Parse --map / --rw-map arguments ─────────────────────────
EXTRA_MOUNTS=()
while [[ "${1:-}" == --map || "${1:-}" == --rw-map ]]; do
    FLAG="$1"
    MAP_PATH="$2"
    if [ -e "$MAP_PATH" ]; then
        if [[ "$FLAG" == "--rw-map" ]]; then
            EXTRA_MOUNTS+=("--bind" "$MAP_PATH" "$MAP_PATH")
        else
            EXTRA_MOUNTS+=("--ro-bind" "$MAP_PATH" "$MAP_PATH")
        fi
    else
        echo "Warning: Path $MAP_PATH not found, skipping." >&2
    fi
    shift 2
done

# ── Mise init command ──────────────────────────────────────────
if [ -n "$REAL_MISE_BIN" ]; then
    MISE_INIT="$REAL_MISE_BIN trust && eval \"\$($REAL_MISE_BIN activate bash)\" && eval \"\$($REAL_MISE_BIN env)\""
else
    MISE_INIT="true"
fi

# ── Dotfile deny-list (never mounted — sensitive data) ─────────
DOTDIR_DENY=(.gnupg .aws .mozilla .basilisk-dev .sparrow)

# Subdirs of ~/.config to hide (tmpfs over rw config mount)
CONFIG_DENY=(BraveSoftware Bitwarden)

# Subdirs of ~/.cache to hide (sensitive browser/app caches)
CACHE_DENY=(BraveSoftware basilisk-dev chromium spotify nvidia mesa_shader_cache)

# Dotdirs requiring read-write access
DOTDIR_RW=(.claude .crush .codex .aider .config .cargo .cache .docker)

# ── Helper functions ───────────────────────────────────────────
is_denied() {
    local name="$1"
    for d in "${DOTDIR_DENY[@]}"; do [[ "$name" == "$d" ]] && return 0; done
    return 1
}

is_rw() {
    local name="$1"
    for d in "${DOTDIR_RW[@]}"; do [[ "$name" == "$d" ]] && return 0; done
    return 1
}

# ── Auto-discover dot-directories in $HOME ─────────────────────
# Only directories — regular dotfiles (e.g. .claude.json) are NOT mounted.
# The tmpfs $HOME is writable so tools can create dotfiles as needed.
DOTFILE_MOUNTS=()
for entry in "$HOME"/.*; do
    [ -d "$entry" ] || continue
    name=$(basename "$entry")
    [[ "$name" == "." || "$name" == ".." ]] && continue
    is_denied "$name" && continue

    if is_rw "$name"; then
        DOTFILE_MOUNTS+=("--bind" "$entry" "$HOME/$name")
    else
        DOTFILE_MOUNTS+=("--ro-bind" "$entry" "$HOME/$name")
    fi
done

# ── Explicit dotfile mounts (regular files) ────────────────────
[ -f "$HOME/.gitconfig" ] && DOTFILE_MOUNTS+=("--ro-bind" "$HOME/.gitconfig" "$HOME/.gitconfig")
[ -f "$HOME/.claude.json" ] && DOTFILE_MOUNTS+=("--bind" "$HOME/.claude.json" "$HOME/.claude.json")

# ── Hide sensitive subdirs inside ~/.config (after rw mount) ───
CONFIG_HIDE_MOUNTS=()
for denied in "${CONFIG_DENY[@]}"; do
    [ -d "$HOME/.config/$denied" ] && CONFIG_HIDE_MOUNTS+=("--tmpfs" "$HOME/.config/$denied")
done

# ── Hide sensitive subdirs inside ~/.cache (after rw mount) ──
CACHE_HIDE_MOUNTS=()
for denied in "${CACHE_DENY[@]}"; do
    [ -d "$HOME/.cache/$denied" ] && CACHE_HIDE_MOUNTS+=("--tmpfs" "$HOME/.cache/$denied")
done

# ── Override ~/.local subdirs as rw (parent .local is ro) ──────
LOCAL_OVERRIDES=()
[ -d "$HOME/.local/state" ] && LOCAL_OVERRIDES+=("--bind" "$HOME/.local/state" "$HOME/.local/state")
for rw_share in zoxide crush opencode atuin mise yarn flutter kotlin NuGet pipx ruby-advisory-db uv; do
    [ -d "$HOME/.local/share/$rw_share" ] && LOCAL_OVERRIDES+=("--bind" "$HOME/.local/share/$rw_share" "$HOME/.local/share/$rw_share")
done

# ── GPU device mounts (NVIDIA + DRM) ─────────────────────────
GPU_MOUNTS=()
for dev in /dev/nvidia* /dev/dri; do
    [ -e "$dev" ] && GPU_MOUNTS+=("--dev-bind" "$dev" "$dev")
done

# ── Docker socket ────────────────────────────────────────────
DOCKER_MOUNT=()
[ -S /var/run/docker.sock ] && DOCKER_MOUNT+=("--bind" "/var/run/docker.sock" "/var/run/docker.sock")

# ── Shared memory (Chromium needs large /dev/shm) ───────────
SHM_MOUNT=()
[ -d /dev/shm ] && SHM_MOUNT+=("--dev-bind" "/dev/shm" "/dev/shm")

# ── Display passthrough (X11 + Wayland) ─────────────────────
DISPLAY_MOUNTS=()
DISPLAY_ENV=()

# X11 / XWayland socket
[ -d /tmp/.X11-unix ] && DISPLAY_MOUNTS+=("--bind" "/tmp/.X11-unix" "/tmp/.X11-unix")
[ -n "${DISPLAY:-}" ] && DISPLAY_ENV+=("--setenv" "DISPLAY" "$DISPLAY")
[ -n "${XAUTHORITY:-}" ] && {
    DISPLAY_MOUNTS+=("--ro-bind" "$XAUTHORITY" "$XAUTHORITY")
    DISPLAY_ENV+=("--setenv" "XAUTHORITY" "$XAUTHORITY")
}

# Wayland socket (lives in XDG_RUNTIME_DIR, typically /run/user/UID)
if [ -n "${XDG_RUNTIME_DIR:-}" ] && [ -d "$XDG_RUNTIME_DIR" ]; then
    DISPLAY_MOUNTS+=("--bind" "$XDG_RUNTIME_DIR" "$XDG_RUNTIME_DIR")
    DISPLAY_ENV+=("--setenv" "XDG_RUNTIME_DIR" "$XDG_RUNTIME_DIR")
    [ -n "${WAYLAND_DISPLAY:-}" ] && DISPLAY_ENV+=("--setenv" "WAYLAND_DISPLAY" "$WAYLAND_DISPLAY")
fi

# ── Assemble and launch ───────────────────────────────────────
echo "Jail Active: $PROJECT_DIR"

bwrap \
  --ro-bind /usr /usr \
  --symlink usr/bin /bin \
  --symlink usr/lib /lib \
  --symlink usr/lib /lib64 \
  --ro-bind /etc /etc \
  --ro-bind "$TEMP_HOSTS" /etc/hosts \
  --ro-bind /opt /opt \
  --ro-bind /sys /sys \
  --dev /dev \
  "${GPU_MOUNTS[@]}" \
  "${SHM_MOUNT[@]}" \
  --proc /proc \
  --tmpfs /tmp \
  --tmpfs /run \
  "${DOCKER_MOUNT[@]}" \
  "${DISPLAY_MOUNTS[@]}" \
  --tmpfs "$HOME" \
  "${DOTFILE_MOUNTS[@]}" \
  "${CONFIG_HIDE_MOUNTS[@]}" \
  "${CACHE_HIDE_MOUNTS[@]}" \
  "${LOCAL_OVERRIDES[@]}" \
  "${EXTRA_MOUNTS[@]}" \
  --bind "$PROJECT_DIR" "$PROJECT_DIR" \
  --chdir "$PROJECT_DIR" \
  --die-with-parent \
  --unshare-pid \
  --unshare-uts \
  --unshare-ipc \
  --hostname "ai-sandbox" \
  "${DISPLAY_ENV[@]}" \
  --setenv PS1 "(jail) \w \$ " \
  --setenv _ZO_DOCTOR 0 \
  bash -c "$MISE_INIT && ${*:-bash}"

Esta versão é bem customizada, deem uma boa lida porque tem deny-list pra que só diretórios de que você realmente precisa dentro do Jail estejam disponíveis. Alguns são read-write porque um Claude precisa conseguir escrever em ~/.claude ou Codex precisa do ~/.codex; vários diretórios nunca devem ir pra dentro do Jail como repositório de senhas de um Brave ou BitWarden. O resto de que pode precisar deve ser tudo read-only. Esse script cuida de tudo isso.

Só fazer chmod +x ~/.local/bin/ai-jail. Agora podemos executar ele direto ou já passar o comando que queremos rodar no sandbox:

~/.local/bin/ai-jail crush

Nesta versão ele vai criar um diretório $HOME temporário, caso ele precise gravar algo temporário lá. E também mandei mapear o seu ~/.config pros agentes terem acesso às suas configurações. Se precisar de mais coisas como variáveis de ambiente e coisas assim, modifique pra mapear essas coisas também, mas isso é o mínimo pra conseguir montar um sandbox seguro.

Tome muito cuidado com programas que rodam comandos aleatórios no seu sistema. Nada é 100% seguro, especialmente uma LLM que pode halucinar a qualquer momento e decidir apagar coisas, ou ferramentas suspeitas que você baixou sem ter certeza da origem e pode ser um malware disfarçado. Sempre rode coisas realmente suspeitas somente numa VM ou, no mínimo, dentro de um jail como esse.

Isso não serve só pra agentes de IA, lógico. Toda vez que for rodar qualquer comando que tem dúvidas ou ache suspeito, rode dentro desse jail.

De bônus, note que eu também mapeio o Mise pra dentro do container. Se você usa Omarchy, deve estar usando Mise também.

Especificamente pra Claude Code, que eu mais uso, prefiro não deixar tudo autorizado no modo automático --allow-dangerously-skip-permissions, mas também não gosto de ter que ficar autorizando coisa besta como cada domínio que ele quer pesquisar na web (só pesquisar não tem problema nenhum) ou qualquer comando que só lista coisas como ls ou grep então dá pra melhorar configurando direto em ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git branch *)",
      "Bash(git checkout *)",
      "Bash(git switch *)",
      "Bash(git stash *)",
      "Bash(git show *)",
      "Bash(git fetch *)",
      "Bash(git pull *)",
      "Bash(git merge *)",
      "Bash(git tag *)",
      "Bash(git remote -v*)",
      "Bash(git rev-parse *)",
      "Bash(git ls-files *)",
      "Bash(ls *)",
      "Bash(find *)",
      "Bash(grep *)",
      "Bash(wc *)",
      "Bash(cat *)",
      "Bash(head *)",
      "Bash(tail *)",
      "Bash(file *)",
      "Bash(which *)",
      "Bash(echo *)",
      "Bash(pwd)",
      "Bash(cd *)",
      "Bash(ps *)",
      "Bash(env *)",
      "Bash(printenv *)",
      "Bash(mkdir *)",
      "Bash(cp *)",
      "Bash(mv *)",
      "Bash(touch *)",
      "Bash(npm *)",
      "Bash(npx *)",
      "Bash(yarn *)",
      "Bash(pnpm *)",
      "Bash(bun *)",
      "Bash(node *)",
      "Bash(ruby *)",
      "Bash(bundle *)",
      "Bash(rails *)",
      "Bash(rake *)",
      "Bash(go *)",
      "Bash(cargo *)",
      "Bash(rustc *)",
      "Bash(python *)",
      "Bash(pip *)",
      "Bash(docker compose *)",
      "Bash(docker ps *)",
      "Bash(docker logs *)",
      "Bash(docker images *)",
      "Bash(make *)",
      "Bash(gh *)",
      "Bash(curl *)",
      "Bash(jq *)",
      "Bash(sed *)",
      "Bash(awk *)",
      "Bash(sort *)",
      "Bash(uniq *)",
      "Bash(diff *)",
      "Bash(* --version)",
      "Bash(* --help)",
      "WebSearch",
      "WebFetch"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(rm -r *)",
      "Bash(sudo *)",
      "Bash(chmod 777 *)",
      "Bash(git reset --hard *)",
      "Bash(git clean *)",
      "Bash(git push --force *)",
      "Bash(git push -f *)",
      "Bash(docker rm *)",
      "Bash(docker rmi *)",
      "Bash(docker system prune *)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(git rebase *)",
      "Bash(git branch -D *)",
      "Bash(git branch -d *)",
      "Bash(rm *)",
      "Bash(kamal *)",
      "Bash(docker run *)",
      "Bash(docker exec *)",
      "Bash(docker stop *)"
    ],
    "defaultMode": "acceptEdits"
  },
  "enabledPlugins": {
    "gopls-lsp@claude-plugins-official": true,
    "typescript-lsp@claude-plugins-official": true,
    "pyright-lsp@claude-plugins-official": true,
    "rust-analyzer-lsp@claude-plugins-official": true,
    "github@claude-plugins-official": true,
    "pr-review-toolkit@claude-plugins-official": true,
    "frontend-design@claude-plugins-official": true
  },
  "alwaysThinkingEnabled": true
}

Pesquise a documentação (ou pergunte direto pro próprio Claude) sobre mais customizações que dá pra fazer nesse arquivo pra servir melhor pro seu tipo de projeto de fluxo de trabalho.

É basicamente assim que um container de Docker ou Podman funciona também. Eu expliquei isso no meu video sobre Docker. Se não assistiu ainda, recomendo ver.