Components
The four binaries that make up Platinum, what each one owns, and where it runs.
Platinum is four binaries plus Postgres and an S3-compatible bucket. Only the control plane talks to clients. Only the host agent touches KVM.
| Component | Path | Stack | Runs on | Service |
|---|---|---|---|---|
| Control plane | apps/api | TypeScript, Bun, Hono, Drizzle | Control-plane machine | platinum-control-plane |
| Host agent | hosts/host-agent | Go | Each sandbox host | platinum-host-agent |
| In-VM agent | hosts/invm-agent | Go, static binary | Inside each VM | None. PID 1 in the guest. |
| Edge proxy | apps/edge | Bun | Each sandbox host | platinum-edge-proxy |
Control plane
The control plane serves the public API and owns all state. It never launches a VM, so it runs on a machine without /dev/kvm.
| Job | Where |
|---|---|
Public API under /v1/* | apps/api/src/server.ts, apps/api/src/api/ |
| Placement by capacity, region and host health | apps/api/src/scheduler.ts |
The host_commands queue under /internal/hosts/* | apps/api/src/api/hosts.ts, apps/api/src/hostCommandClaim.ts |
| Drift repair and auto-stop, auto-archive and auto-delete | apps/api/src/reconciler.ts |
| Exec, file and process calls into a guest | apps/api/src/invmAgent.ts |
| Leader election for singleton loops | apps/api/src/leader.ts |
The listener sets SO_REUSEPORT. A new process can bind the port before the old one drains, so a deploy does not drop requests.
Host agent
The host agent is the only component that touches KVM. It runs as root under platinum-host-agent, with its settings in /etc/platinum/host.env.
- Registration. It trades a one-time
htok_bootstrap token for a host API key, stored in/var/lib/platinum/host-api-key. - Commands. It long-polls the control plane, acknowledges and runs each command, and reports the result. It heartbeats every 5 seconds.
- VMs. It clones the template disk, creates the VM's TAP device and launches
cloud-hypervisorin its own scope underpt-vms.slice. - Templates. It builds template images with
podman, chunks them into object storage and keeps a local chunk cache. - Network. It installs each sandbox's isolation and egress rules and runs the egress proxy.
- RPC proxy. When
PT_VSOCK_RPC_LISTENis set, it serves port18048and forwards control-plane calls to a VM's vsock socket.
The host installer's fleet profile runs Cloud Hypervisor as the unprivileged platinum-vmm user (PT_CH_UID), with all capabilities dropped (PT_CH_PRIVDROP=1). The unit uses KillMode=process, so restarting the host agent leaves VMs running, and the agent re-adopts them on start.
In-VM agent
The in-VM agent runs inside every VM, as PID 1 or started by /sbin/pt-init. It is a static Go binary baked into every template.
On boot it configures eth0 from the pt_ip, pt_gw and pt_mask kernel arguments. There is no DHCP. It then listens on AF_VSOCK port 18047 and opens no TCP listener. Each message is a 4-byte big-endian length followed by a JSON body.
Its operations cover:
| Area | Operations |
|---|---|
| Commands | exec, PTY sessions, managed processes (proc_start, proc_wait, proc_kill, …) |
| Files | stat_file, list_dir, mkdir, rename, symlink, delete_path, reads and writes |
| Volumes | vol_mount, vol_unmount, vol_sync, vol_freeze, vol_thaw |
| Snapshots | fs_freeze, fs_thaw, prep_snapshot, reconfigure_net |
Edge proxy
The edge proxy serves preview URLs. It runs on each sandbox host because a VM's address on the host bridge is reachable only from that host.
It runs as user platinum with only CAP_NET_BIND_SERVICE, and listens on port 80 (EDGE_PORT). For each request it checks the preview token, looks up the sandbox's internal address in Postgres and forwards HTTP or WebSocket traffic. A request for a stopped sandbox resumes it and waits up to AUTO_RESUME_MS (default 30000), unless the sandbox was created with auto_resume: false.
Postgres
Postgres holds organizations, keys, sandboxes, templates, hosts, the host_commands queue, leases and the audit log. Each edge proxy also reads routes from it.
Two migration sets must both be applied. bun run db:migrate applies apps/api/drizzle/migrations. The idempotent SQL files in apps/api/migrations are applied with psql -f.
Object storage
Object storage is any S3-compatible bucket, configured with the PT_S3_* settings on the control plane and every host. With it, templates, stop snapshots, archives, backups and volumes can move between hosts. Details are in Storage.
Know the guarantees
- The control plane never needs KVM.
- The in-VM agent opens no TCP listener. Every connection to it starts on the host.
- The edge proxy runs unprivileged and cannot reach a VM on another host.
- Restarting the host agent does not stop running VMs.
See also: Architecture overview · Networking · Security model