agentbox

Sua VM pessoal de agentes de código, em um container. Ubuntu + Herdr +
Claude Code, Codex e opencode + Neovim configurado para caber na tela do
celular. Você sobe com um docker compose up, conecta por SSH de onde estiver,
e os agentes continuam trabalhando depois que você desconecta.

🇺🇸 English version

Por que isso existe

Eu queria deixar agentes de código rodando o tempo todo e conseguir acompanhar
de qualquer lugar — inclusive do celular, esperando em uma fila. Três coisas
estavam no caminho:

1. Fechar o notebook mata o agente. Uma sessão SSH normal morre junto com a
   conexão, e o agente vai junto.
2. Nem todo mundo tem uma VM dedicada. Mas muita gente já paga um VPS
   rodando Coolify ou Dokploy. Se o ambiente for um container, ele sobe ali do
   lado dos outros serviços, sem provisionar máquina nova.
3. Terminal em celular é hostil. Editor com barra de status, número
   relativo, sinal de coluna, animação de scroll — em 45 colunas isso não é
   ferramenta, é obstáculo.

O agentbox é a resposta que eu montei para os três. Ele não é um "devcontainer"
de projeto: é uma máquina de desenvolvimento que se comporta como uma VM
normal — você dá sudo apt install, clona repositórios, instala o que quiser —
só que descartável, versionada em um Dockerfile, e com todos os seus dados em
um volume que fica no seu servidor.

Como funciona

       seu celular / notebook
                │  ssh -p 2222 dev@servidor
                ▼
   ┌────────────────────────────────────────────┐
   │  container agentbox (Ubuntu 24.04)         │
   │                                            │
   │   sshd ──► herdr  (multiplexador)          │
   │              ├─ pane: claude               │
   │              ├─ pane: codex                │
   │              ├─ pane: opencode             │
   │              └─ pane: nvim / shell         │
   │                                            │
   │   /home/dev  ───────────────────────────┐  │
   └─────────────────────────────────────────┼──┘
                                             ▼
                            volume persistente no servidor
                  (repos, credenciais dos agentes, config, histórico)

O Herdr é a peça central: um multiplexador de terminal feito para agentes
de código. Ele mantém tudo rodando quando você desconecta, e mostra na sidebar
qual agente está trabalhando e qual está esperando resposta sua. É o que
transforma "abrir o terminal no celular" em algo que faz sentido.

O que vem instalado

Começando

Pré-requisitos: Docker e Docker Compose na máquina que vai hospedar (seu
servidor, seu VPS, ou seu próprio computador).

git clone https://github.com/pedrogiroldo/agentbox.git
cd agentbox

make init        # cria o .env já com a chave pública desta máquina
$EDITOR .env     # adicione a chave do celular, ajuste porta, fuso e identidade git

make up          # constrói a imagem e sobe o container

O primeiro build demora (ele compila os plugins do Neovim para o primeiro
nvim no celular abrir instantâneo). Depois:

ssh -p 2222 dev@seu-servidor
herdr

E é isso. Ctrl+b ? mostra os atalhos, Ctrl+b q desconecta deixando tudo
rodando.

Os comandos que você vai usar

make key       # mostra sua chave pública (cria uma se não existir)
make up        # sobe
make ssh       # conecta a partir desta máquina
make logs      # acompanha o boot e o provisionamento
make shell     # entra no container sem SSH (quando você se trancou do lado de fora)
make update    # reconstrói a imagem e recria o container, preservando o volume
make backup    # empacota o volume em ./backups

make sozinho lista tudo.

Do celular

Instale um cliente SSH (Termius,
Blink, Termux), gere a chave no próprio celular e
adicione a chave pública ao SSH_PUBLIC_KEY (uma por linha).

Conectou, rode herdr. Os dois atalhos que importam em tela pequena são
Ctrl+b z (deixa um pane em tela cheia) e Ctrl+b b (esconde a sidebar).

O Neovim entra em modo mobile sozinho quando o terminal tem menos de 90
colunas: sem barra de status, sem número relativo, sem coluna de sinais, com
quebra de linha, jk para sair do modo de inserção, explorador de arquivos em
tela cheia e todas as animações desligadas — cada célula redesenhada custa caro
em um link móvel. Em tela grande, nada disso muda.

O passo a passo completo, com as configurações do cliente que fazem diferença,
está em docs/mobile.md.

Seus dados ficam no seu servidor

São dois volumes:

/home/dev é seu — repositórios, credenciais dos agentes, configuração
do Neovim, plugins, histórico do shell, sessões do Herdr e até as chaves de
host do SSH ficam no volume agentbox-home. Recriar o container não perde
nada — nem o fingerprint que o seu celular já confiou.

O que você instala por cima da imagem é lembrado e reaplicado. Um
sudo apt install postgresql-client, um binário em /usr/local/bin, um
arquivo editado em /etc: tudo isso é registrado no volume agentbox-state
e volta no próximo boot.

A imagem nunca é sobreposta por um volume, então atualizar o agentbox continua
trazendo node, nvim, herdr e agentes novos. agentbox-persist status mostra o
que está sendo mantido; recomeçar do zero é apagar os dois volumes
(make destroy). Detalhes e backup em
docs/persistence.md.

Rodando em Coolify ou Dokploy

Foi para isso que ele nasceu. Crie um recurso do tipo Docker Compose,
aponte para este repositório (ou cole
deploy/docker-compose.ghcr.yml para usar a
imagem pronta, mais rápido em VPS pequeno), defina SSH_PUBLIC_KEY e publique
a porta 2222:22 — SSH é TCP puro, o proxy HTTP da plataforma não entra na
história.

Passo a passo em docs/deploy.md.

Código que precisa rodar no seu hardware

Os agentes escrevem o código dentro do agentbox, mas nem todo código roda lá.
Build de Android precisa do SDK e de um emulador com aceleração de hardware,
adb precisa de um celular no cabo USB, CUDA precisa de GPU — e um VPS não
tem nada disso.

Encaminhar porta não resolve esse caso: o problema não é alcançar um servidor
que já está rodando lá dentro, é que o build não tem como acontecer lá.

A saída é espelhar o projeto: os mesmos arquivos, ao vivo, dos dois lados,
pela mesma conexão SSH que você já usa.

# dentro do agentbox — imprime o comando para você colar na sua máquina
agentbox-mirror meuapp

# ou, se você clonou este repositório
make mirror PROJECT=meuapp LOCAL=~/src/meuapp

O agente edita no agentbox e a mudança chega no seu computador um segundo
depois. Você roda ./gradlew installDebug no aparelho de verdade, e a correção
que fizer localmente volta para o agentbox na mesma velocidade. Saída de build
(build/, .gradle/, node_modules/) fica de fora por padrão; o .git não,
senão a cópia deixa de ser o mesmo repositório.

O Mutagen você instala na sua máquina — dentro do
agentbox não precisa instalar nada.

O passo a passo do Android, os ignores padrão e o que acontece quando os dois
lados editam o mesmo arquivo estão em docs/mirror.md.

Segurança

O container se recusa a subir sem nenhuma chave configurada, aceita só
autenticação por chave e não permite login de root. Ainda assim, você está
colocando um servidor SSH na internet: a porta padrão é 2222, restrinja a
origem no firewall, e se puder, não exponha nada — coloque o host numa rede
Tailscale/WireGuard e publique a porta só no IP privado.

Duas coisas merecem leitura antes. O agentbox roda com privileged: true — é o
que o daemon de Docker de dentro exige — e isso dá acesso equivalente a root
no host; suba ele numa máquina que já é sua.
docs/docker.md mostra como abrir mão disso se você preferir.
A outra: as credenciais dos agentes ficam em texto claro no volume.
docs/security.md explica o resto.

Personalizando

• Configuração do Neovim: image/skel/.config/nvim. O que está no seu home
  vence sempre; a imagem só adiciona arquivos que ainda não existem.
• Configuração do Herdr: image/skel/.config/herdr/config.toml
  (herdr --default-config lista todas as opções).
• Banner de boas-vindas: AGENTBOX_BANNER no .env — always (padrão,
  em todo terminal e em cada pane do Herdr), login (só ao conectar) ou off;
  AGENTBOX_BANNER_BY troca a assinatura. O desenho tem três tamanhos e
  escolhe sozinho o que cabe na largura do terminal — as letras grandes só
  aparecem a partir de 90 colunas, para não encher a tela de um celular.
• Mais ferramentas na imagem: edite o Dockerfile e rode make update.
• Mais ferramentas sem rebuild: ~/.agentbox/provision.sh.
• Versões fixas: NODE_VERSION, NVIM_VERSION, CLAUDE_CODE_VERSION,
  CODEX_VERSION, OPENCODE_VERSION no .env.

Documentação

• Uso no celular — cliente SSH, Herdr, Neovim em tela pequena
• Persistência — o que sobrevive, provisionamento, backup
• Deploy — VPS, Coolify, Dokploy, várias instâncias
• Agentes — login, integrações, rodar vários em paralelo
• Docker — o daemon de dentro, o container privilegiado, as alternativas
• Espelhamento — o mesmo projeto no seu computador, builds de Android, ignores
• Segurança — exposição, Docker, raio de alcance

Créditos

Herdr · LazyVim ·
Claude Code ·
Codex ·
opencode

Licença

MIT — veja LICENSE.