PLATINUM

Appearance

Architecture overview ​

Every sandbox is its own Cloud Hypervisor micro-VM on stock KVM. The control plane decides what runs where, the host agent makes it happen, and the guest agent runs your commands.

What runs where ​

CLIENTSSDKs · pt CLI · MCP · console · curlHTTPS · API key or session cookieCONTROL PLANEAPI SERVER · :3000REST API · auth · scheduler · reconcilerSQLPOSTGRES:5432polls commandshost dials outRPC :18048exec · filesroutelookupsSANDBOX HOST × NHOST AGENTGo · runs as rootVSOCK-RPC :18048in the host agentEDGE PROXYpreviews · :80CLOUD HYPERVISORone VM per sandboxlaunchesPT-BR0 BRIDGE10.42.0.0/16 · NATVM portMICRO-VM · OWN KERNELguest agent: PID 1, AF_VSOCK :18047your processes, files, portsvsock :18047vsock.sockTAP/var/platinum/data · disks, snapshots, chunk cachechunks in / outOBJECT STORAGEtemplates · snapshots · backups · volumes
Clients reach only the control plane. Host agents dial out to it for work, and the guest agent answers only on vsock. Dashed: optional.
ComponentRole
Control plane (server/)Owns all state in Postgres and serves the API. Never launches a VM.
Host agent (components/host-agent/)Runs as root on each sandbox host. Pulls work and launches one cloud-hypervisor per sandbox.
Guest agent (components/guest-agent/, invm-agent)PID 1 in each VM. Listens on AF_VSOCK port 18047, never TCP.
Edge proxy (components/edge-proxy/)Runs on each sandbox host on port 80. Turns a signed preview URL into a connection to a VM port.
Object storageOptional. Lets templates, stopped sandboxes and backups move between hosts.

Clients talk only to the control plane, previews included: it forwards them to the edge proxy on the sandbox's host. The one exception is a direct TCP exposure, reached on a host port. See Components.

Postgres is the queue ​

There is no message broker. Every change to a sandbox is a row in the host_commands table.

  • Hosts dial out for work. The host agent long-polls POST /internal/hosts/:id/commands/poll. The control plane still dials each host on :18048 (exec and files) and on the edge port (previews), and schedules nothing on a host it cannot reach.
  • Wake-up. When a command is queued, the control plane releases that host's open poll (server/src/commandWake.ts).
  • At-least-once. The host acks each command. One picked but not acked within 3 seconds is redelivered (server/src/hostCommandClaim.ts).
  • Heartbeats. Each host posts capacity and its running sandboxes every 5 seconds. No heartbeat for 5 minutes marks it lost.
  • Reconciler. Every 10 seconds it repairs drift between Postgres and what hosts report (server/src/reconciler.ts).
  • Leader lease. Singleton loops run on one process, chosen by a lease row in Postgres (server/src/leader.ts).

How the control plane reaches a guest ​

The control plane runs without KVM. For exec and files it dials the VM's vsock socket if that socket is on its own filesystem. Otherwise it calls the host agent's vsock-rpc proxy on :18048 (viaProxy in server/src/invmAgent.ts). The full path is in Networking.

Guarantees and non-guarantees ​

  • Each sandbox has its own kernel inside its own VMM process, launched with --seccomp true. There is no shared-kernel container mode.
  • Nothing on the bridge, including other sandboxes, can reach exec or files. The guest agent has no TCP listener.
  • A control-plane restart loses no queued work. Commands are rows, and hosts keep polling.
  • Restarting the host agent does not stop running VMs. The unit uses KillMode=process, and recoverRunningVMs re-adopts them.
  • Without object storage, a template, snapshot or stopped sandbox lives only on the host that made it.
  • The control plane does not push work to hosts. A host that cannot reach the control plane gets no commands.

See also: Sandbox lifecycle · Storage · Security model