Project layout
A map of the monorepo — what each package is, which decide vs. act, and where the plans, runbooks, and authoritative docs live.
SpipCP is a pnpm monorepo. Most of it is TypeScript; the fleet agent is Go. This page is the map — what each package is and how they relate. For how to run it all, see Development setup.
The packages
| Package | What it is |
|---|---|
panel (@spipcp/panel) | The product: the React/TanStack Start web app and the worker (job queue + agent gateway). All the server logic, the database schema, and the oRPC API live here. The biggest package by far. |
protocol (@spipcp/protocol) | The shared contract between the panel and the agent — typed message shapes for what the panel dispatches and the agent returns. Generated/validated so the two sides can't drift. |
agent (Go) | The fleet agent installed on each managed node. A static Go binary that connects out to the worker over WebSocket and executes what it's told. The only thing that touches a node. |
rig (@spipcp/rig) | The automated test harness that proves provisioning flows against real infrastructure before the UI is trusted. Rig-first is a law, not a nicety. |
node-harness (@spipcp/node-harness) | Owns the full local end-to-end stack (a VM + worker + panel children driven together), so an e2e flow can stand the whole rig up without a panel↔rig cycle. |
spipcp-docs (@spipcp/docs) | This documentation site (Fumadocs + TanStack Start). Standalone; runs on port 3402. |
Decide vs. act
The single most important relationship: the panel decides, the agent acts.
agent (Go) ←WSS→ worker (panel) ←Postgres→ web (panel)- The panel computes desired state and dispatches typed commands over the
protocol. - The agent is the one executor on a node — it applies what it's handed and reports back. The panel never SSHes a node to configure it (SSH is used only for first enrollment and break-glass).
One stateful service
The panel stores everything — jobs, fleet state, audit — in a single Postgres database. No Redis, no message broker. The job queue is a table, so it survives restarts.
Where the docs and decisions live
Code is only half the repo. The rest is the record of why:
| Path | What's there |
|---|---|
plans/ | The architecture and the build plans — the authoritative spec for each chunk of work. |
runbooks/ | Operational procedures (enroll a node, the dev tunnel, migrate the panel). |
evidence/ | Captured proof from rig/e2e runs. |
AGENTS.md | The hard rules and the laws (rig-first, convergence-only, one-executor, budgets) — the authority for how to work here. |
spipcp-docs/content/docs/ | These pages. |
The plans are authoritative
When in doubt, AGENTS.md and the relevant plans/ file win over anything else — including this
site. These pages describe shipped behaviour for users; the plans are the source of truth for
builders.
Next steps
- Development setup — run the stack locally.
- Contributing — the workflow and the laws in one place.
Development setup
Bring SpipCP up on your own machine — dev services, the database, the panel and worker — plus the 34xx port convention, the green gate, the rig, and how to run this docs site.
Contributing
How work happens in SpipCP — the laws that don't bend, the green gate, the rig-first rule, and where docs and runbooks belong.