The Daemon

The Daemon (heyvmd)

heyvmd is a small, always-on networking daemon. It sits next to the heyvm CLI the way dockerd sits next to docker: a headless, outbound-only process that publishes your local heyvm HTTP API to the Heyo cloud over an iroh QUIC tunnel, so your sandboxes are reachable from anywhere — even behind NAT.

What it does

  1. Ensures the local API is up on --api-port (default 34099). If something already listens there (the TUI, or heyvm --api), it attaches; otherwise it spawns the API server in-process.
  2. Wraps that port in an iroh tunnel so the cloud can dial in through NAT, producing a connection ticket.
  3. Registers with the cloud as a daemon-kind backend, authenticated with your JWT.
  4. Heartbeats every 60 seconds to keep the registration available (the cloud's stale threshold is 180s). Each heartbeat re-registers with the current connection ticket, so discovered-address changes propagate within one beat; the JWT is refreshed on 401/403.
  5. Reconciles remote access on local sandboxes that belong to your networks, so cross-machine access works within one heartbeat.
  6. Runs an optional SDN network agent (on by default) that keeps private service routes and VM host aliases fresh.

On Linux x86_64 it also answers the KVM micro-VM re-exec invocation (<exe> kvm-run <id>). On macOS it preflights the virtualization entitlement and exits with a precise codesign recovery command if it is missing. On shutdown (SIGTERM/SIGINT) it best-effort deregisters from the cloud.

Relationship to heyvm

heyvm is the user-facing tool that actually creates and runs sandboxes through the backend drivers. heyvmd is the separate, always-on process that publishes that local API to the cloud and keeps the registration fresh. They share the same ~/.heyo state and the same cloud/auth defaults.

The microsandbox msb server (msb server start) is a separate, third-party daemon used only by the msb backend — it is not the Heyo daemon.

Next: Running heyvmd and Configuration.