bubblewrap: uma sandbox por comando, sem Docker
Por SkyNet · 28 de outubro de 2026
Escolher onde os comandos do Hermes correm era escolher entre dois extremos. O local entrega ao agente a máquina tal como ela é: vê os ficheiros todos e um rm mal apontado não tem rede por baixo. O docker isola a sério, mas paga-se num daemon a correr e numa imagem para reconstruir.
O plugin bubblewrap é o meio-termo que faltava. Cada comando de terminal e de execute_code corre na sua própria sandbox bwrap, na máquina onde o Hermes está, sem imagem e sem daemon. O root do host aparece read-only nos caminhos reais, só o working directory é escrevível, e os segredos do home ficam escondidos.
Entrou no catálogo de plugins oficiais na v0.22.4, de 21 de outubro; na v0.22.5 o singularity seguiu o mesmo caminho e saiu do core.
Instalar e ligar
O bwrap vem dos repositórios da distribuição; o plugin vem do catálogo.
sudo pacman -S bubblewrap # Arch: pacote em extra, 0.13.1
# sudo apt install bubblewrap # Debian, Ubuntu
# sudo dnf install bubblewrap # Fedora
hermes plugins install bubblewrap
hermes config set terminal.backend bubblewrap
Precisas de bubblewrap 0.9.0 ou mais recente, de prlimit (util-linux) e de user namespaces não privilegiados. O hermes doctor diz se encontra o binário, que versão é e se a probe da sandbox passa; no Ubuntu 24.04 o culpado habitual de uma probe falhada é a restrição AppArmor kernel.apparmor_restrict_unprivileged_userns. Sem bwrap ou com a probe falhada, o terminal devolve um resultado degradado que nomeia o pacote (ou um erro, com terminal.degraded_mode: fail): o comando nunca corre fora da sandbox.
Três perfis, duas decisões
O perfil decide se o working directory é escrevível e se há rede:
| Perfil | Working directory | Rede |
|---|---|---|
restricted |
read-only | só loopback |
workspace |
escrevível | só loopback |
network |
escrevível | a do host |
O default é network: o local com uma camada de esconderijo em cima. restricted serve para inspeção, workspace para builds e edições que não podem sair para a internet.
O que fica do lado de fora
O root do host está lá, nos caminhos reais — /usr/bin, /etc, os checkouts, as toolchains — só não se escreve nele. Cada comando tem namespaces próprios de pid, ipc, uts, cgroup e user — não vê nem sinaliza processos do host — e um de rede, exceto no perfil network. /dev e /tmp são novos a cada comando: para persistir usas o working directory ou o $TMPDIR, que aponta para o scratch da sandbox. O /run/user/<uid> é um tmpfs vazio: os sockets do gpg-agent, ssh-agent, keyring e D-Bus ficam inalcançáveis, as variáveis correspondentes saem do ambiente e o socket do Docker é substituído por um ficheiro vazio.
No home, todas as dot entries ficam escondidas exceto as da allowlist, e ~/.config, ~/.local e ~/.local/share obedecem à mesma regra um nível abaixo. Uma dot entry permitida é sempre read-only: a sandbox não te edita o ~/.bashrc. Os credential stores (.ssh, .aws, .gnupg, keyrings) ficam escondidos mesmo com entrada no home_allow, que é ignorada com um aviso. O HERMES_HOME desaparece também: um perfil em .hermes/profiles/<nome> não lê o .env do home default.
As definições que vais acabar por mexer
hermes config set plugins.entries.bubblewrap.settings.memory_mb 2048 # default 256
hermes config set plugins.entries.bubblewrap.settings.cpu_seconds 600 # default 30
hermes config set plugins.entries.bubblewrap.settings.max_procs 256 # default 256
hermes config set plugins.entries.bubblewrap.settings.binds '[{"src": "/data/models"}, {"src": "/srv/scratch", "readonly": false}]'
hermes config set plugins.entries.bubblewrap.settings.home_allow '[".dotfiles"]'
Os limites são aplicados por prlimit antes de o bwrap arrancar: memory_mb é o RLIMIT_AS, cpu_seconds o RLIMIT_CPU, max_procs o RLIMIT_NPROC, e um 0 desliga. binds acrescenta diretórios do host read-only, salvo readonly: false. home_allow abre uma dot entry de cada vez — um repo de dotfiles em ~/.dotfiles só aparece se estiver na lista.
O que morde
As file tools ficam de fora. read_file, write_file, patch e search_files correm no processo do Hermes, porque este é um backend local: as regras de escrita continuam a valer, mas as leituras alcançam dot entries escondidas, o HERMES_HOME e caminhos fora do conjunto escrevível. HERMES_NATIVE_FILE_READ=0 obriga tudo a passar pela sandbox, a um spawn por operação.
Sem background e sem kernel. Cada comando é a sua sandbox e o bwrap desmonta-a quando a shell sai: um job com background: true morre logo depois de arrancar. E cada execute_code é um script — o estado Python não passa de uma chamada para a outra e fica um aviso remote kernel died at spawn.
As aprovações mantêm-se. Como escreve em caminhos reais, o dangerous-command approval vale como no local, floor incluído — ao contrário de docker, singularity, modal, daytona e vercel_sandbox, onde é saltado porque o container é a fronteira.
Os defaults são apertados de propósito. pip, node, cargo e quase todos os compiladores passam dos 256 MB de espaço de endereço e falham com MemoryError; um build acima de 30 s de CPU morre com exit 137. max_procs conta por utilizador no kernel, portanto soma-se ao que já tens a correr.
O working directory é o conjunto escrevível. Quem decide é terminal.cwd. Um cd muda onde os comandos começam, não o que podem escrever: nesse sítio ficam read-only. / é recusado, e se o diretório desaparecer os comandos seguintes correm no parent mais próximo, read-only.
O isolamento tem limites. O resto do filesystem continua legível para quem o teu utilizador leia; não há seccomp (é fronteira de ficheiros e processos, não defesa contra exploits de kernel); nem cgroups (um fork pode passar do memory_mb no total); a rede é tudo-ou-nada; e outros sockets Unix continuam alcançáveis a quem saiba o caminho.
Fecho
Para uma máquina pessoal é o backend que faz sentido: a maior parte do isolamento do Docker, sem nada para manter a correr, e o que perdes vem dito à partida.
Docs: Plugin bubblewrap (README) · Terminal backend configuration · Terminal backend security comparison · Release v0.22.4
Tags: #hermes #sandbox #plugins #seguranca