Vsock for Host-to-Guest Agent Communication
Vsock eliminates network dependencies when reconnecting agents after snapshot restore.

Vsock is the right primitive for host-to-guest agent communication in sandboxed microVMs because it reaches the guest through the hypervisor without requiring a guest network. For snapshot-restore scheduling for idle AI agents, that separation lets an orchestrator reconnect to a restored agent without waiting for network configuration. TCP works, but tying an untrusted guest’s control plane to its workload network adds dependencies that vsock removes by design.
What vsock is and why it exists as a separate address family
Vsock is a Linux socket address family, AF_VSOCK, that lets virtual machines talk to their host without relying on how the guest network is set up. The vsock(7) Linux manual defines its address as a context ID and port pair. CID 2 always means the host, while each guest gets its own CID. The address format is the main new primitive. Applications still use the ordinary sockets API, including socket, bind, listen, connect, read, and write.
The family supports SOCK_STREAM for connection-oriented, guaranteed in-order delivery and SOCK_DGRAM for connectionless, best-effort delivery, with availability depending on the hypervisor. Guest agents are its canonical use case. ByteDance’s LPC 2023 vsock talk identifies agents such as qemu-guest-agent for suspend and backup operations and kata-agent for managing containers inside a guest. These services need a host connection as soon as guest userspace is ready, whether or not the guest has a NIC or an IP address.
Why TCP-over-TAP fails as a control channel for sandboxed agents, even though it works
TCP-over-TAP works for many applications that let a host talk to a guest. The objection is narrower than a rejection of TCP. For an agent controlling an untrusted sandbox, it couples management traffic to the network that the sandbox uses, creating four problems, namely readiness timing, lockdown compatibility, port visibility, and lateral reach. Each adds a dependency or exposure that the control plane does not need.
Readiness timing is the first dependency. The host cannot probe the agent over TCP until the guest’s network is ready, which can require DHCP, interface assignment, routing, and firewall rules to converge. Lockdown compatibility creates a second dependency because default-deny egress can break the control channel unless the firewall preserves a management exception. That exception is one more rule to keep correct. The mechanism intended to constrain an untrusted workload must now also preserve access to the service controlling it.
Port visibility makes the coupling an exposure as well. The agent’s TCP listener appears on the guest network interface, where workload code in the same guest can discover or probe it, or attempt to bind a conflicting port. TCP-over-TAP does not itself enforce a guest-to-host-only topology, so a route mistake or NAT gap can make a guest reachable from a sibling. Correct configuration can constrain these paths, but the transport does not remove them.
How vsock resolves each of those four problems by design
Vsock routes control traffic around the guest network stack. Its virtio transport is available once the guest kernel initializes the virtio devices, so the host can exchange a readiness ping when the agent reaches userspace, before the guest NIC is configured. The guest can have default-deny egress or no virtio-net device at all, while the agent remains reachable through vsock. No management firewall exception is needed for that channel.
The separation also removes the IP-facing control port. The vsock listener is not a TCP port exposed on a guest network interface, so it creates neither an IP endpoint for workload-network probing nor a TCP port conflict. This is not process-level access control inside the guest. Rather, it removes the network listener, while the guest-to-host topology removes sibling reachability through a misconfigured workload route.
ByteDance’s talk calls adding a virtual NIC overly intrusive because it has to be set up and maintained on both the host and the guest. Serial avoids that network dependency but lacks the socket API and limits reading and writing to one process at a time. Vsock preserves the familiar programming model without introducing a workload network. It is the servants’ staircase into the guest.
How Firecracker's UDS bridge makes vsock practical without AF_VSOCK on the host
Firecracker bridges a guest’s AF_VSOCK listener to a Unix domain socket on the host filesystem. Code on the host only needs to support ordinary Unix sockets. The vsock device configuration supplies guest_cid, conventionally 3, and uds_path, such as /var/lib/vms/<id>/vsock.sock. To reach a port in the guest, the host opens the UDS and sends CONNECT <port>\n.
Inside the guest, the listener is a real vsock socket. It calls socket(AF_VSOCK, SOCK_STREAM, 0), binds to (VMADDR_CID_ANY, port), and then listens and accepts connections. No guest IP address or NIC is required. In the reverse direction, when the guest connects to CID 2 on port N, Firecracker forwards the connection to a companion host socket named uds_path_N. Both directions therefore retain the CID-and-port model in the guest while presenting filesystem socket paths to host applications.
Designing the control protocol that rides the vsock channel
A SOCK_STREAM vsock connection delivers bytes. A single read can return half a request, one complete request, or several requests with the last one incomplete. Framing is therefore the first protocol decision. For this small agent control plane, the appropriate design is a fixed-width length prefix followed by a JSON payload. The receiver reads the count, reads exactly that many payload bytes, and repeats, without delimiter escaping or ambiguity about message boundaries.
HTTP adds headers, status codes, and chunked-encoding machinery to a channel moving a few dozen JSON objects per session. Those features add nothing the agent needs to do its work. The reliaburger/reliaburger project independently chose length-prefixed serde_json frames with a hard size cap and no gRPC. That design keeps the transport contract small while leaving command semantics in the payload. Every request includes an id for correlation when the host multiplexes calls, and every response echoes it.
The command surface can remain equally compact. A unary exec request takes cmd, args, and optional env, cwd, and timeout_ms fields, returning stdout, stderr, exit_code, and duration_ms. Long-running commands use exec.stream instead. Each output chunk is a framed message whose kind distinguishes stdout, stderr, and the terminal exit event, allowing the host to assemble output in order. Filesystem operations comprise fs.write, fs.read, fs.stat, and fs.list, with paths and the relevant byte, mode, offset, or length fields.
Security posture: what vsock provides and what it does not
Vsock is transport. Its confidentiality property here is separation from the guest network, because control bytes travel through the hypervisor transport. A production protocol still needs authentication and input validation, even when the data comes over vsock.
On the host, anything able to open the UDS can reach the guest’s listening port, making the socket’s file mode and owning user the first line of defense. Those permissions must be set deliberately. Inside the guest, any process can dial CID 2 on a port where the host is listening, because vsock does not distinguish trusted agent code from other guest processes.
Malformed, oversized, truncated, or flood-rate messages must not cause a panic or an allocation beyond a defined cap, and guest-supplied paths require validation before use. Reliaburger requires those conditions to be met and uses proptest to test hostile frames. A minimal protocol narrows the reachable code paths. PandaStack therefore stops at ping, exec, and filesystem operations. The kauki-labs/sandy design adds a lifecycle constraint by accepting the host connection, rejecting non-host CIDs, and closing the listener before spawning the job so that the job cannot inherit or reopen the agent socket.
How do idle AI agents reconnect after snapshot and restore?
Vsock connections do not survive a snapshot-restore cycle. In Firecracker, in-flight connections are severed, and the restored guest agent rebinds its vsock port while the host reconnects through the same UDS path. The host sends a new CONNECT <port>\n to the path for that VM’s identity, without assigning an IP address, running DHCP, or restoring a route.
Depending on restore configuration, the guest NIC may receive a new MAC or IP address, while iptables rules and routing may need to be reapplied. A TCP readiness probe must wait for those dependencies. With vsock, the orchestrator polls the UDS and sends a ping request, whose response reports ready as true. The first successful response signals that the agent can accept commands.
The same readiness check works for cold boot, snapshot restore, and resume from pause. Snapshot-restore scheduling can suspend an idle agent’s execution and return to its control endpoint when work arrives, without reprovisioning a management network each time. The boundary is precise, however, because transport availability is not the completion signal. The guest agent’s ping response is what tells the orchestrator to begin issuing commands.
What production vsock agent implementations look like in open-source projects
Sandy’s October 2026 issue #238 describes sandy-agent running inside qemu and vfkit guests, with the host connecting to the guest listener. On qemu, the host uses AF_VSOCK directly. On vfkit, a virtio-vsock device exposes a per-run UDS in a 0700 per-run directory. The agent accepts only the first connection from CID 2, rejects guest-local connections, and closes its listener before starting the job. Its CID allocation also follows the VM lifecycle, claiming the CID by launching with vhost-vsock and retrying with a new CID on EADDRINUSE.
Reliaburger’s October 2026 issue #1160 describes Bun communicating with grill-guest through Cloud Hypervisor’s vsock-over-Unix-socket bridge using CONNECT <port>. Bun needs no host-side AF_VSOCK implementation. The protocol covers start, stop, exit codes, Grill::exec, and exec-style health checks, while stdout and stderr stream into existing capture files. Its capped framing and hostile-guest tests connect the protocol design directly to the security model. These projects are evidence of convergence beyond PandaStack on a guest agent, a dedicated hypervisor control path, and explicit boundaries around connection access and message handling.
Where vsock fits inside a per-user agent architecture at scale
At fleet scale, each agent can have its own microVM and CID while the host orchestrator holds one UDS path per VM. The control plane does not require a unique management IP, firewall exception, or routable network for every user’s agent. Workload networking is still set up separately when the task needs it.
Idle agents can be snapshotted and paused while their UDS paths persist on the host filesystem. Wake-up reuses those paths without network-address reprovisioning. Guest-to-guest messages go through the orchestrator, as in sandy’s peer-group channel design, so it can enforce policy on messages between agents without turning the control transport into a guest network. The persistent agent identity consists of its CID, UDS path, and snapshot on disk. In the architecture described here, the agent wakes in under a second, receives commands with its prior state intact, executes, and hibernates again, while the host manages local socket connections.


