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