cleanroom-controller#

The controller is the central authority for all cleanroom state. It is built on PocketBase with an embedded Go binary and a lightweight UI for manual operation.

Responsibilities#

• Node registry — track which workers are registered and their current state
• Job scheduler — assign jobs to idle workers, track execution
• Power provider abstraction — enable/disable PoE ports, request reboots
• Log and artifact storage — persist job outputs to the local filesystem
• HTTP API — serve the controller API consumed by the MCP server and the UI

Subsystems#

Node registry#

Each worker registers itself with the controller on boot. The controller maintains current state (idle, busy, offline) and last-seen timestamps for each node.

Job scheduler#

Jobs are queued and assigned to idle workers in FIFO order. The scheduler is responsible for detecting stuck or failed workers and requeueing jobs.

Power provider abstraction#

The controller interfaces with PoE switches to cycle power on worker nodes. The abstraction allows multiple switch vendors to be supported without changing the scheduler.

Log and artifact storage#

Logs and artifacts are written to the local filesystem under a per-job directory. The controller API exposes endpoints for the MCP server to retrieve them.