https://cleanroom-docs.pages.dev/dev/Recent content on CleanroomHugoenhttps://cleanroom-docs.pages.dev/dev/docs/components/mcp/Mon, 01 Jan 0001 00:00:00 +0000https://cleanroom-docs.pages.dev/dev/docs/components/mcp/<h1 id="cleanroom-mcp">cleanroom-mcp<a class="anchor" href="#cleanroom-mcp">#</a></h1> <p>The MCP server is the AI integration layer. It exposes MCP tools that AI agents (Hermes, Claude, Codex) can call to request cleanroom environments, submit jobs, and retrieve results — without any knowledge of the underlying infrastructure.</p> <h2 id="responsibilities">Responsibilities<a class="anchor" href="#responsibilities">#</a></h2> <ul> <li>Expose MCP tools over the MCP protocol</li> <li>Translate tool calls into HTTP API requests against the controller</li> <li>Return structured results (logs, artifacts, status) to the caller</li> </ul> <h2 id="design-constraints">Design constraints<a class="anchor" href="#design-constraints">#</a></h2> <ul> <li>Stateless — all state lives in the controller</li> <li>No business logic — routing and validation belong in the controller</li> <li>Must not require the caller to understand PXE, Buildroot, PoE, or worker lifecycle</li> </ul> <h2 id="mcp-tools-planned">MCP tools (planned)<a class="anchor" href="#mcp-tools-planned">#</a></h2> <table> <thead> <tr> <th>Tool</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code>submit_job</code></td> <td>Submit a job script and return a job ID</td> </tr> <tr> <td><code>get_job_status</code></td> <td>Poll a job by ID for status and progress</td> </tr> <tr> <td><code>get_job_logs</code></td> <td>Retrieve stdout/stderr for a completed job</td> </tr> <tr> <td><code>list_workers</code></td> <td>List registered workers and their current state</td> </tr> </tbody> </table>https://cleanroom-docs.pages.dev/dev/docs/components/controller/Mon, 01 Jan 0001 00:00:00 +0000https://cleanroom-docs.pages.dev/dev/docs/components/controller/<h1 id="cleanroom-controller">cleanroom-controller<a class="anchor" href="#cleanroom-controller">#</a></h1> <p>The controller is the central authority for all cleanroom state. It is built on <a href="https://pocketbase.io/">PocketBase</a> with an embedded Go binary and a lightweight UI for manual operation.</p> <h2 id="responsibilities">Responsibilities<a class="anchor" href="#responsibilities">#</a></h2> <ul> <li>Node registry — track which workers are registered and their current state</li> <li>Job scheduler — assign jobs to idle workers, track execution</li> <li>Power provider abstraction — enable/disable PoE ports, request reboots</li> <li>Log and artifact storage — persist job outputs to the local filesystem</li> <li>HTTP API — serve the controller API consumed by the MCP server and the UI</li> </ul> <h2 id="subsystems">Subsystems<a class="anchor" href="#subsystems">#</a></h2> <h3 id="node-registry">Node registry<a class="anchor" href="#node-registry">#</a></h3> <p>Each worker registers itself with the controller on boot. The controller maintains current state (idle, busy, offline) and last-seen timestamps for each node.</p>https://cleanroom-docs.pages.dev/dev/docs/components/worker/Mon, 01 Jan 0001 00:00:00 +0000https://cleanroom-docs.pages.dev/dev/docs/components/worker/<h1 id="cleanroom-worker">cleanroom-worker<a class="anchor" href="#cleanroom-worker">#</a></h1> <p>The worker is a small Go binary baked into the Buildroot image. It runs on each cleanroom node and is responsible for executing jobs assigned by the controller.</p> <h2 id="responsibilities">Responsibilities<a class="anchor" href="#responsibilities">#</a></h2> <ul> <li>Register with the controller on boot</li> <li>Poll for assigned jobs</li> <li>Execute job scripts in an isolated environment</li> <li>Stream logs and upload artifacts to the controller</li> <li>Report completion status and exit cleanly</li> </ul> <h2 id="design-constraints">Design constraints<a class="anchor" href="#design-constraints">#</a></h2> <ul> <li><strong>No durable state.</strong> The worker writes nothing to persistent storage. All output goes to the controller.</li> <li><strong>No long-lived secrets.</strong> Job credentials are passed at assignment time and discarded after the job completes.</li> <li><strong>Stateless across reboots.</strong> A rebooted worker is indistinguishable from a freshly booted one.</li> <li><strong>Minimal dependencies.</strong> The worker binary must build with only the Go standard library.</li> </ul>