Multi-Harness + Gbrain (Docker)

Instalador/ambiente para um VPS rodar vários coding agents (harnesses), cada um na sua própria imagem Docker, mais o Gbrain (camada de memória/MCP) num serviço separado, pronto para acesso externo a partir dos seus PCs de desenvolvimento.

Harness	Serviço	Comando interno
Claude Code	claude	claude
OpenAI Codex CLI	codex	codex
Google Antigravity	antigravity	agy
Cursor Agent	cursor-agent	cursor-agent
OpenCode (MiniMax)	opencode	opencode
Gbrain (servidor)	gbrain + gbrain-db + caddy	gbrain serve --http

Cada harness é independente: sobe sob demanda, tem volume próprio de config/auth, e todos compartilham um volume workspace (/workspace).

---

Pré-requisitos

• Docker Engine + Docker Compose v2 (no VPS).
• Node.js ≥ 18 no host — só para o launcher (harness). Opcional.
• Para o Gbrain externo: um domínio com registro DNS A apontando para o IP do VPS, e portas 80/443 livres.

Setup rápido

cp .env.example .env
# edite .env: OPENAI_API_KEY, MINIMAX_API_KEY, GBRAIN_DOMAIN, ACME_EMAIL, POSTGRES_PASSWORD...

# (opcional) launcher TUI no host:
cd launcher && npm install && npm link   # expõe o comando `harness`
cd ..

Instalador (local / remoto via SSH)

Há um instalador que provisiona o ambiente na máquina atual ou num VPS via SSH. O núcleo é o install.sh (bash puro, roda no alvo); o front-end é o launcher (harness install ou menu → Instalar).

Núcleo install.sh (roda no alvo — local ou, no modo remoto, dentro do VPS):

bash install.sh --provision-docker --server    # instala Docker se faltar, builda, sobe o Gbrain
bash install.sh --dry-run                       # só mostra o que faria
# flags: --provision-docker  --server  --no-build  --yes  --dry-run

Modo remoto (harness install → Remoto): você informa um perfil (label, IP, usuário, porta, caminho da chave SSH, diretório no VPS), e o launcher:

1. testa a conexão SSH;
2. pergunta como levar o .env — copiar o seu .env local pelo canal SSH ou criar do .env.example no VPS p/ editar lá;
3. mostra os comandos exatos (rsync/tar + ssh) e pede confirmação (ou --dry-run);
4. transfere o projeto (rsync, com fallback tar por SSH) e roda install.sh no VPS.

Os perfis ficam em .servers.json (gitignored; guarda só o caminho da chave, nunca o conteúdo). Depois, use o VPS assim:

ssh -t USER@IP 'cd multi-harness && docker compose run --rm claude'
ssh -t USER@IP 'cd multi-harness && docker compose --profile server up -d'

Segurança: o SSH usa a sua chave (-i <caminho>), que nunca é lida nem transmitida por nós; get.docker.com | sh só roda no VPS com sua confirmação; .env e .servers.json são gitignored e só trafegam pelo canal SSH cifrado.

Rodando os harnesses

São TUIs interativas — use docker compose run (sob demanda), não up:

docker compose run --rm claude          # Claude Code
docker compose run --rm codex           # Codex
docker compose run --rm antigravity     # agy
docker compose run --rm cursor-agent    # Cursor Agent
docker compose run --rm opencode        # OpenCode (MiniMax)

docker compose run --rm claude --version   # checagem rápida

Ou pelo launcher:

harness            # menu interativo
harness claude     # direto
harness --list

Autenticação (headless)

O login é por harness, no primeiro uso, e fica salvo no volume de config (persiste entre execuções):

• Claude Code — /login na sessão (fluxo por código/navegador).
• Codex — codex login (ou API key).
• Antigravity — abre URL de Google Sign-In; em sessão remota ele imprime a URL para você abrir no PC. (Sem keyring no container, cai no fallback em arquivo, persistido no volume.)
• Cursor Agent — cursor-agent login.
• OpenCode — não precisa login: usa a MiniMax via opencode.json. Defina MINIMAX_API_KEY no .env (injetada no 1º boot) ou edite depois ~/.config/opencode/opencode.json no volume opencode-config (campo apiKey).

Volumes (config e dados)

Volume	Conteúdo
claude-config, codex-config, antigravity-config, cursor-config, opencode-config	config + auth de cada harness (/home/dev)
workspace	código/dados compartilhados (/workspace)
gbrain-data	brain do Gbrain (system of record, ~/.gbrain)
gbrain-db-data	dados do Postgres/pgvector
caddy-data, caddy-config	certificados TLS do Caddy

Quer ver o workspace direto no host? Troque o volume nomeado por um bind, ex.: - ./workspace:/workspace.

---

Gbrain (memória compartilhável, acesso externo)

gbrain serve --http é Postgres-only (por isso o serviço gbrain-db com pgvector). O Caddy publica o servidor no seu domínio com HTTPS automático (Let's Encrypt). Auth: bearer token e OAuth 2.1 (dashboard /admin).

Subir

docker compose --profile server up -d        # gbrain-db -> gbrain -> caddy
docker compose logs -f gbrain                 # veja "listening :3131" + admin bootstrap token (OAuth)

Verifique o TLS/descoberta OAuth:

curl https://SEU_DOMINIO/.well-known/oauth-authorization-server

Conectar seus PCs de desenvolvimento

Crie um token e conecte (precisa do CLI gbrain no seu PC):

docker compose exec gbrain gbrain auth create "laptop"      # imprime gbrain_xxxxx
# no seu PC:
gbrain connect https://SEU_DOMINIO/mcp --token gbrain_xxx --install                # Claude Code
gbrain connect https://SEU_DOMINIO/mcp --token gbrain_xxx --agent codex --install  # Codex

Pelo launcher: Gbrain: criar token / connect (gera o token e monta o comando pronto).

Embeddings: o Gbrain indexa com a OpenAI (text-embedding-3-large). Sem OPENAI_API_KEY, ele sobe sem embeddings (--no-embedding) e você habilita depois colocando a key no .env e reiniciando o serviço.

---

Plugins / Skills (prontos pra adicionar)

Os harnesses já trazem os pré-requisitos (node, npm, npx, git, agent-skills). Tudo que você instalar persiste no volume de config do harness. Use o helper ou o launcher:

plugins/install.sh --list                     # combinações disponíveis
plugins/install.sh claude superpowers          # imprime comandos p/ colar na sessão do Claude
plugins/install.sh claude gstack               # executa no container (git clone + setup)
plugins/install.sh opencode openspec           # roda openspec init em /workspace

Plugin	O que é	Harnesses
Gstack	23 skills opinativas (CEO/PM/QA/Eng)	Claude
Agent Skills	catálogo multi-agente (wizard)	Claude, Codex, Cursor, OpenCode, Antigravity
Headroom	compressão de contexto (skill/MCP/hook)	Claude, Codex, Cursor, OpenCode
Superpowers	framework de skills (brainstorm/plan/TDD)	Claude (+ demais manual)
Ponytail	persona "lazy senior dev" (código mínimo)	Claude, Codex, OpenCode, Antigravity, Cursor
OpenSpec	spec-driven dev (gera AGENTS.md)	todos (por-projeto em /workspace)

Modos: run (executa no container), session (cole na sessão do Claude/Codex, ex. /plugin …), manual (passo de edição/cópia). Veja plugins/manifest.json.

---

Atualização

• Harnesses: docker compose build --no-cache <serviço> (puxa a versão mais nova do instalador).
• Gbrain: ele não tem tag semver estável; o gbrain/Dockerfile fixa um commit SHA (GBRAIN_REF). Para subir de versão, atualize o SHA e rebuild: docker compose build gbrain.

Notas / limitações honestas

• Gbrain + Postgres self-hosted: validado — o Gbrain seleciona o engine Postgres automaticamente quando DATABASE_URL está no ambiente (o compose monta a partir dos POSTGRES_*). Não precisa de Supabase nem de passo de migrate. Postgres é obrigatório para o servidor HTTP e para bearer tokens.
• Gbrain é jovem (mudanças frequentes) — por isso o pin por commit (GBRAIN_REF no gbrain/Dockerfile). Versão validada aqui: 0.42.53.0.
• Comandos /plugin … (Superpowers/Ponytail no Claude/Codex) exigem a sessão interativa do harness; o helper imprime o que colar.
• Os builds baixam instaladores externos (Anthropic, OpenAI, Google, Cursor, OpenCode, Gbrain) — exigem rede e podem mudar.

Estrutura

docker-compose.yml          # harnesses (profile harness) + gbrain/db/caddy (profile server)
.env.example                # placeholders
harnesses/<x>/Dockerfile     # 1 imagem por harness
gbrain/                      # Dockerfile + entrypoint (bun + gbrain)
caddy/Caddyfile              # reverse proxy + TLS
plugins/manifest.json        # catálogo plugin -> comando por harness
plugins/install.sh           # helper de instalação
launcher/bin/harness.js      # TUI no host