Architecture

The Minion system consists of three layers: HQ, Supabase, and Minion Servers.

Overall architecture

flowchart TD
    HQ["<b>HQ Server</b> — ECS Fargate<br/>Next.js + Custom Server<br/>WebSocket proxy: VNC / Terminal<br/>Google OAuth via Supabase Auth<br/>Stripe billing: Free / Pro / Enterprise<br/>API: Minion mgmt / Projects / Skills / Workflows"]
    SB["<b>Supabase</b><br/>PostgreSQL — RLS by user_id<br/>Auth — Google OAuth<br/>Storage — skill files<br/>Realtime — dashboard updates"]
    MS["<b>Minion Server</b> — Lightsail VPS<br/>@geekbeer/minion Fastify API :3001<br/>Claude Code CLI + MCP servers<br/>Xvfb + noVNC :6080<br/>ttyd terminal :7681<br/>Cloudflare Tunnel"]

    HQ -->|"HTTPS / WSS"| SB --> MS

HQ Server

HQ is a Next.js-based management server deployed on ECS Fargate.

• Custom server — Wraps Next.js and provides WebSocket proxying (VNC / Terminal)
• Authentication — Google OAuth via Supabase Auth
• API — Minion communication (API token auth) and dashboard operations (session auth)
• Billing — Stripe (Free / Pro / Enterprise plans)

Minion Server

Each minion runs as an isolated environment on a Lightsail VPS.

Port	Service	Purpose
3001	Fastify API	HQ communication, skill/workflow management
6080	noVNC (websockify)	VNC access from browser
7681	ttyd	Web terminal

Background jobs

The following jobs are executed via EventBridge Scheduler + Lambda.

Job	Description
expire-trials	Free tier trial expiration → snapshot + pause
cleanup-snapshots	Delete expired snapshots and minion records
track-usage	Report compute hours to Stripe Meters