Networking

How sandboxes reach the internet, how they are kept apart, and how the control plane reaches a guest.

Each sandbox host has one private bridge, and every VM gets its own TAP device on it with NAT to the internet. Exec and file calls never use that network. They travel over vsock.

Set up the host bridge

infra/03-network.sh creates the bridge and NAT at install. The platinum-network unit recreates them at every boot.

Piece	Value
Bridge	`pt-br0`
Guest subnet	`10.42.0.0/16`
Gateway	`10.42.0.1` on the bridge
NAT	`table inet platinum_nat`, masquerade on the default-route interface

Give each VM a TAP

The host agent picks a free address in 10.42.0.0/16. Addresses held by stopped sandboxes on the host are skipped.
It derives the guest's MAC from that address.
It creates pt-tap-<vsock cid> and attaches it to pt-br0.
It applies the sandbox's egress policy to the TAP.
Cloud Hypervisor boots with pt_ip, pt_gw and pt_mask on the kernel command line. The in-VM agent configures eth0 from them.

Keep sandboxes apart

The host agent installs these nftables rules (hosts/host-agent/internal/l2iso).

Rule	What it stops
`table bridge pt_l2_v1`, cross-tenant drop	Frames switched from one VM's TAP to another's. Always on.
`pt_xtenant` in `inet platinum_filter`	Traffic a guest routes back through the gateway to another VM. Always on.
Per-TAP anti-spoof sets	A VM sending from an IP or MAC that is not its own. Drops when `PT_L2_ISOLATION=enforce`, which the host installer sets.
`pt_guest_in` on the input hook	Guests reaching host services outside a short allowlist.

The guard chain in inet platinum_filter matches guest traffic to link-local and loopback ranges, including 169.254.0.0/16, fe80::/10 and 127.0.0.0/8. infra/03-network.sh installs it, and the host agent re-applies it while it runs.

`PT_EGRESS_GUARD_MODE`	Effect
`counter` (default)	Counts matches. Traffic passes.
`drop`	Drops matches.
`reject`	Rejects matches at once, so a probe fails fast.

Control egress per sandbox

Set a policy at create time or with POST /v1/sandboxes/:id/network. The control plane validates it (apps/api/src/api/network.ts), and the host enforces it per TAP.

Field	Meaning
`allow_internet_access`	`false` cuts the sandbox off from the internet.
`allow_out`	CIDRs or domains the sandbox may reach.
`deny_out`	CIDRs or domains it may not reach.
`rules`	Per-host transforms on outbound requests.

CIDR rules stay in nftables. No proxy is in the path.
Domain rules redirect TCP 80 and 443 to the host's egress proxy on port 18050. The proxy reads the TLS SNI or the Host header and splices the bytes through without decrypting them.
Transforms are the one case where the proxy terminates TLS, and only for the destination that has a transform. This is how secrets are injected.

A sandbox with an egress policy gets no IPv6. Every policy rule is IPv4.

Reach the guest for exec and files

The in-VM agent listens only on AF_VSOCK port 18047. Cloud Hypervisor exposes it on the host as /var/platinum/data/vms/<sandbox id>/vsock.sock. A client sends CONNECT 18047, then length-prefixed JSON.

The control plane picks the path per call (apps/api/src/invmAgent.ts):

Local socket. If the socket is on the control plane's own filesystem, it dials it.
Remote host. Otherwise it calls https://<host>:18048/v1/vsock-rpc/<sandbox id>. The host agent forwards the call to the socket.

The :18048 listener (hosts/host-agent/cmd/host-agent/vsockrpc.go) is protected in layers:

Layer	What it checks
nftables	Only the control plane's address may connect. `infra/scripts/setup-vsock-rpc.sh` installs the rule.
TLS	The host's self-signed certificate. The control plane trusts only certificates in its bundle, `PT_VSOCK_PROXY_CA` (default `/etc/platinum/vsock-ca.pem`).
Client certificate	Required only when `PT_VSOCK_RPC_CLIENT_CA` is set on the host.
Bearer token	`PT_VSOCK_RPC_TOKEN` on the host must match `PT_VSOCK_PROXY_TOKEN` on the control plane.

Each host publishes its certificate to POST /internal/hosts/:id/vsock-cert at install and again every time the host agent starts. The control plane adds it to the bundle without a restart.

Serve preview URLs

An exposed port is served by the edge proxy on the sandbox's host, at a hostname of the form <port>-<short sandbox id>.<preview domain>.

Token. Private ports need an HMAC token signed with EDGE_HMAC_SECRET. It is sent as ?t=, or in the x-pt-preview-token or x-pt-token header.
Route hint. The control plane can attach a route hint signed with EDGE_HINT_SECRET, which lets the edge skip a database lookup.
Revocation. The edge proxy polls revoked tokens from Postgres every 30 seconds.
Peer gate. EDGE_PEER_GATE=enforce refuses peers outside EDGE_TRUSTED_PEERS. Unset, any peer may reach port 80.

EDGE_HMAC_SECRET and EDGE_HINT_SECRET must match on the control plane and every edge proxy.

Ports

Port	Where	Purpose	Reachable from
`80`	Each sandbox host	Edge proxy	Preview traffic
`18048`	Each sandbox host	RPC proxy, TLS	The control plane only
`18050`	`10.42.0.1`	Egress proxy	Guests, by redirect
`18047` (vsock)	Inside each VM	In-VM agent	The host, through the VM's socket

Know the guarantees

Two VMs on one host cannot reach each other over the bridge, even in the same organization.
No exec or file path exists over TCP, from the bridge or from the internet.
Domain filtering does not decrypt traffic. Only a destination with a transform rule is terminated.
Metadata endpoints are not blocked until you set PT_EGRESS_GUARD_MODE.