Wire Protocol

Host-Guest Communication

Host and guest communicate over AF_VSOCK (port 1234) using the void-box-protocol crate. The protocol uses a simple length-prefixed binary framing with JSON payloads.

Frame Format

Binary frame layout

+---------------+-----------+--------------------+
| length (4 B)  | type (1B) | payload (N bytes)  |
+---------------+-----------+--------------------+

Field	Size	Description
`length`	4 bytes	`u32` little-endian, payload size only (excludes the 5-byte header)
`type`	1 byte	Message type discriminant
`payload`	N bytes	JSON-encoded body

Message Types

Type Byte	Direction	Message	Description
`0x01`	host → guest	ExecRequest	Execute a command (program, args, env, timeout)
`0x02`	guest → host	ExecResponse	Command result (stdout, stderr, exit_code)
`0x03`	both	Ping	Session authentication handshake
`0x04`	guest → host	Pong	Authentication reply with protocol version
`0x05`	host → guest	Shutdown	Request guest shutdown
`0x0A`	host → guest	SubscribeTelemetry	Start telemetry stream
`0x0B`	host → guest	WriteFile	Write file to guest filesystem
`0x0C`	guest → host	WriteFileResponse	Write file acknowledgement
`0x0D`	host → guest	MkdirP	Create directory tree
`0x0E`	guest → host	MkdirPResponse	Mkdir acknowledgement
`0x0F`	guest → host	ExecOutputChunk	Streaming output chunk (stream, data, seq)
`0x10`	host → guest	ExecOutputAck	Flow control ack (optional)
`0x11`	both	SnapshotReady	Guest signals readiness for live snapshot

Security

MAX_MESSAGE_SIZE

64 MB — prevents OOM from untrusted length fields. Messages exceeding this limit are rejected before allocation.

Session Secret

32-byte hex token injected as voidbox.secret=<hex> in kernel cmdline. The guest-agent reads it from /proc/cmdline at boot and requires it in every ExecRequest.

ExecRequest Debug Redaction

The Debug impl for ExecRequest redacts environment variables matching KEY, SECRET, TOKEN, PASSWORD patterns — preventing accidental credential exposure in logs.

Network Layout (SLIRP)

VoidBox uses smoltcp-based usermode networking (SLIRP) — no root, no TAP devices, no bridge configuration.

Network topology

Guest VM                                    Host
+---------------------+                    +------------------+
| eth0: 10.0.2.15/24  |                    |                  |
| gw:   10.0.2.2      |-- virtio-net ------| SLIRP stack      |
| dns:  10.0.2.3      |   (MMIO)           | (smoltcp)        |
+---------------------+                    |                  |
                                           | 10.0.2.2 -> NAT  |
                                           |   -> 127.0.0.1   |
                                           +------------------+

Guest/Host IP Details

Endpoint	Address	Description
Guest IP	`10.0.2.15/24`	Static IP assigned to guest `eth0`
Gateway	`10.0.2.2`	Mapped to host `127.0.0.1` — guest reaches host services via this address
DNS	`10.0.2.3`	Forwarded to host resolver

Outbound TCP/UDP is NATed through the host. The guest reaches host services (e.g. Ollama on :11434) via 10.0.2.2.