Architecture#

System overview#

Hermes / Claude / Codex
        |
        | MCP tools
        v
cleanroom-mcp
        |
        | HTTP API
        v
cleanroom-controller  (PocketBase + embedded UI)
        |
        +-- filesystem logs/artifacts
        +-- node registry
        +-- power provider abstraction
        +-- job scheduler
        |
        v
cleanroom-worker  (embedded in Buildroot image, runs on cleanroom hosts)

Hardware lifecycle#

controller enables PoE
  -> Soekris PXE-boots Buildroot
  -> worker registers
  -> job runs from clean state
  -> logs/artifacts uploaded
  -> controller disables PoE or requests reboot

Design principles#

• Go-first. No Python or Node.js on the control plane unless absolutely required.
• No Docker or Kubernetes on workers. Workers run bare Buildroot.
• Workers own no durable state. Every boot is a clean slate.
• Controller owns scheduling and power. Workers are passive.
• Workers get no long-lived secrets. Credentials are job-scoped and ephemeral.
• Reboot/poweroff wipes worker state. The power cycle is the reset primitive.
• MCP is a thin adapter. It translates AI tool calls into controller API calls and nothing more.