Architecture overview
How the control plane, host agents, guest agents and edge proxies fit together.
Platinum runs every sandbox as its own Cloud Hypervisor micro-VM on stock KVM. The control plane decides what runs where, a host agent on each machine makes it happen, and an agent inside each VM runs your commands.
See what runs where
| Component | Role |
|---|---|
Control plane (apps/api) | Serves the API and owns all state in Postgres. Never launches a VM. |
Host agent (hosts/host-agent) | Runs on each sandbox host. Pulls work from the control plane and launches one Cloud Hypervisor process per sandbox. |
In-VM agent (hosts/invm-agent) | Runs inside every VM. Listens on AF_VSOCK port 18047, never on TCP. |
Edge proxy (apps/edge) | Runs on each sandbox host. Turns a preview URL into a connection to a port inside a VM. |
| Object storage | Any S3-compatible bucket. Lets templates, stopped sandboxes, backups and volumes move between hosts. |
Each component is covered in Components.
Use Postgres as the queue
There is no message broker. Every change to a sandbox is a row in the host_commands table.
- Hosts pull work. Each host agent long-polls
POST /internal/hosts/:id/commands/poll. When a command is queued, the control plane releases that host's open poll at once. - At-least-once delivery. The host acknowledges each command. A command handed out but not acknowledged within 3 seconds is handed out again.
- Heartbeats. Each host reports its capacity and running sandboxes every 5 seconds. A host silent for 5 minutes is marked
lost. - Reconciler. Every 10 seconds it repairs drift between Postgres and what hosts report.
- Leader lease. Loops that must run once, like the reconciler, run on one control-plane process, chosen by a lease row in Postgres.
A missed wake-up only delays a command. The row is durable, and the host finds it on its next poll.
Reach a guest from the control plane
The control plane never needs /dev/kvm. For exec and file calls it dials the VM's vsock socket directly when that socket is on its own filesystem. Otherwise it calls the host agent's RPC proxy on port 18048, which forwards to the socket. See Networking.
Know the guarantees
- Each sandbox has its own kernel in its own VMM process. There is no shared-kernel container mode.
- The in-VM agent has no TCP listener. Nothing on the bridge or the internet can reach exec or files.
- A control-plane restart loses no queued work. Commands are rows, and hosts keep polling.
- Restarting the host agent does not stop running VMs.
- A host that cannot reach the control plane gets no new commands.
See also: Sandbox lifecycle · Storage · Security model