Developer documentation
Architecture
The control, workspace, edge, and integration planes.
The architecture is organized around ownership boundaries. Each plane has a different job, privilege level, and failure shape. Keeping those planes separate is what lets the system combine SSH workspaces, public sites, edge caching, and integrations without turning one component into a privileged catch-all.
Quanta Workspaces is split into four planes.
| Plane | Responsibilities |
|---|---|
| Control | State, APIs, routes, assignments, policies, and audit events. |
| Workspace | SSH sessions, bwrap sandboxes, runit services, and workspace files. |
| Edge | OpenResty request serving, route lookup, cache hydration, CGI dispatch, and access logs. |
| Integration | LDAP, Forgejo, Nextcloud, Matomo, and CDN/static asset flows. |
Why The Planes Matter
The control plane should make decisions and persist durable state. Workspace nodes should run user runtime behavior. Edges should serve public traffic and route approved dynamic requests. Integrations should connect outside systems without becoming the owner of every decision.
This keeps the public hot path narrow and makes operational failures easier to reason about.
Main Components
quanta-control-plane
quanta-workspace-controller
quanta-workspace-agent
quanta-ssh-gateway
quanta-edge
quanta-edge-syncd
quanta-cgi-runner
quanta-service-bridge
quanta-deploy-worker
quanta-analytics-worker
quanta-nextcloud-integrator
Important Runtime Contracts
- The SSH gateway resolves sessions through the control plane.
- OpenResty route lookups are host-based.
- Published
sitesreleases are not SSH-accessible. - Assigned edge caches serve the hot path; workspace storage or release origins are authoritative, not the direct public serving path.
- Matomo analytics are imported from edge logs.
In current production the workspace-app control plane is private on vpsxl.
Public hosts are content routes. For example, code.henrysheehy.com serves the
henry/code workspace HTML and Forgejo remains code.quantalumin.com.
These contracts are the practical expression of the design principles: identity is authoritative, runtime behavior is isolated, releases are immutable, and public serving stays separate from writable workspace storage.