Pular para o conteúdo
Linux para todos os rolês
  1. Rolês e receitas
  2. Receitas
  3. Caixa de areia para os agentes

Caixa de areia para os agentes

O comando caixa roda um agente de IA com o bubblewrap, escrevendo só na pasta do projeto, sem ver as suas chaves SSH e sem sudo, e liga a caixa de areia do próprio Claude Code.

ia/caixa-de-areia Risco médio Pede a senha de administrador Testada em máquina virtual no Ubuntu e no Debian
O agente dentro de uma caixa: escreve na pasta do projeto, lê o sistema sem mudar nada, e não alcança as chaves SSH, o login do GitHub nem o sudo. caixa opencode ~/projetos/site escreve o resto do sistema só lê sem sudo · sem /run · com internet, para falar com o modelo ~/.ssh invisível ~/.config/gh invisível chaves.env invisível
Ilustração. Um comando errado do agente estraga, no máximo, a pasta do projeto, que está no Git.

Em resumo

O que faz e o que não faz

O que faz

  • Instala o comando caixa, que roda qualquer agente dentro de uma caixa de areia do bubblewrap.
  • Dentro dela, o agente escreve só na pasta do projeto e nas pastas dele, e lê o resto sem mudar nada.
  • Esconde as suas chaves SSH, o GnuPG, o login do GitHub CLI e o arquivo de chaves de API, e não deixa usar sudo.
  • Liga a caixa de areia do próprio Claude Code, se ele estiver instalado, e deixa a do Claude Code e a do Codex funcionarem no Ubuntu 24.04.

O que não faz

  • Não corta a internet: o agente precisa dela para falar com o modelo.
  • Não abre na pasta pessoal inteira nem fora dela.
  • Não usa o distrobox nem o toolbox, que montam a pasta pessoal inteira e não isolam.
  • Não é uma máquina virtual: um defeito no kernel ainda alcançaria o sistema.

Passo a passo

Como o bora aplica esta receita

As mesmas quatro etapas de toda receita, com o que esta confere em cada uma.

  1. Verificar já está aplicada?

    Confere se o bubblewrap e o socat estão instalados, se o comando caixa é o da receita, se o perfil do AppArmor está lá (quando o sistema restringe os user namespaces) e se a caixa de areia do Claude Code está ligada (quando ele está instalado).

  2. Aplicar faz a mudança

    • Instala os pacotes e escreve /usr/local/bin/caixa.
    • Se o bubblewrap não abrir por causa do AppArmor, como no Ubuntu 24.04, escreve e carrega o perfil /etc/apparmor.d/bora-bwrap.
    • Liga sandbox.enabled em ~/.claude/settings.json, sem mexer no resto.
  3. Testar funcionou?

    Como a pessoa, numa pasta de teste: dentro da caixa, escreve no projeto, não escreve fora, não lê um arquivo de mentira em ~/.ssh, não usa sudo, e a caixa recusa abrir na pasta pessoal.

  4. Desfazer quando você pedir

    Apaga o comando e o perfil, volta o settings.json do Claude Code e remove os pacotes que a receita instalou.

No terminal

Uma aplicação de verdade

A saída de um teste no Ubuntu 24.04.

Os porquês

Por que assim

Por que isolar um agente?

Um modelo erra, entende mal, ou lê num arquivo do projeto uma instrução escondida para apagar algo ou mandar as suas chaves para fora. Na caixa, o estrago fica na pasta do projeto, que está no Git.

Por que o bubblewrap, e não um contêiner?

O distrobox e o toolbox montam a pasta pessoal inteira e o sistema dentro do contêiner, então não isolam. O bubblewrap é a peça que o Flatpak usa para isolar os aplicativos, e a mesma que o Claude Code e o Codex usam no Linux.

E o git push?

Dentro da caixa, o agente não vê a sua chave SSH. Faça o push fora, depois de conferir o que ele fez. É de propósito.

O que é o perfil do AppArmor?

Do Ubuntu 24.04 em diante, só programas com um perfil podem criar o espaço isolado que a caixa usa. O Ubuntu 26.04 já traz um para o bubblewrap; no 24.04, a receita escreve um, como o Ubuntu faz com o Flatpak.

Como

O que muda no sistema

Parâmetros

O que dá para escolher

ParâmetroPadrãoO que é
usuarioautoA conta que vai programar. "auto" é quem rodou o bora com sudo.

No menu, o bora pergunta o que precisa. Num script ou num agente, passe os parâmetros na linha de comando:
bora plano --receitas ia/caixa-de-areia -p ia/caixa-de-areia.usuario=auto

Confira você mesmo

Os comandos para conferir

caixa --helpMostra o que fica dentro e fora da caixa.
cd ~/projetos/site && caixa opencodeRoda o OpenCode isolado na pasta do projeto.
caixa bashAbre um terminal dentro da caixa, para ver com os próprios olhos.

Onde funciona

Distros e testes

UbuntuTestada em VMUbuntu, Mint, Pop!_OS, Zorin
DebianTestada em VMDebian 13
FedoraPlanejadaFedora, Nobara
ArchPlanejadaArch, CachyOS, EndeavourOS, Manjaro
Fedora imutávelPlanejadaBazzite, Silverblue, Kinoite
openSUSEPlanejadaTumbleweed, Leap

Registro de testes

DistroOndeDataResultado
Debian 13Contêiner (teste automático)09/11/2026Passou
Ubuntu 24.04Contêiner (teste automático)09/11/2026Passou
Ubuntu 26.04Contêiner (teste automático)09/11/2026Passou
Debian 13Máquina virtual09/11/2026Passou
Ubuntu 24.04Máquina virtual09/11/2026Passou
Ubuntu 26.04Máquina virtual09/11/2026Passou

Testada em contêiner: passou nos testes automáticos dessa família, que rodam num contêiner a cada pull request, sem kernel, disco nem tela de login de verdade. Testada em VM: além disso, foi aplicada, conferida e desfeita numa máquina virtual (VM) de verdade, o que o CI faz toda semana. O registro acima mostra a última vez de cada distro. Enquanto uma receita só tem o teste em contêiner, o bora avisa quando monta o plano. Testar numa máquina sua é uma das ajudas mais valiosas.

Onde ela entra

Rolês que usam esta receita

Fontes

Para ler mais

Bora melhorar

Falta alguma coisa?

Os pedidos viram issues no GitHub, onde qualquer pessoa pode comentar, votar com um 👍 ou se oferecer para fazer.