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

Base	Ubuntu 24.04, SSH (só por chave), sudo sem senha, mosh, locales en_US e pt_BR
Agentes	Claude Code, Codex CLI, opencode — com as integrações do Herdr já configuradas
Multiplexador	Herdr (e tmux, se você preferir)
Editor	Neovim + LazyVim, com modo mobile automático
Tema	Vesper no Herdr e no Neovim
Runtimes	Node.js, Bun, uv, Python 3
Ferramentas	git, git-lfs, gh (GitHub CLI), ripgrep, fd, fzf, jq, build-essential
Docker	daemon próprio, instalado na primeira subida — o agentbox roda containers sozinho (docs/docker.md)
Espelhamento	agentbox-mirror mantém o projeto ao vivo no seu computador também, para o código que só roda em hardware de verdade (docs/mirror.md)

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.