Daemon API

The k7d daemon exposes its control plane on a Unix socket, by default /run/k7d/k7d.sock (override with --socket or the K7D_SOCKET env var).

Protocol: one JSON request object per line, one JSON response object per line. A connection may carry multiple request/response pairs. Requests are tagged with "op", responses with "status". Errors are always an explicit {"status": "error", "message": "..."} response — never a silent success.

echo '{"op":"ping"}' | socat - UNIX-CONNECT:/run/k7d/k7d.sock# {"status":"pong","version":"0.9.0"}

Reference clients: a thin Python client covering the tree verbs in examples/cluster-tree-search/k7d_client.py, an MCP server wrapping the tree for a frontier agent in examples/k7d-mcp/, and a read-only SSE dashboard in examples/k7view/.

Host operations#

VM lifecycle operations#

VmConfig#

The config object accepted by create_vm (and the tree-create operations):

vm_created responses carry vm_id, guest_cid, vm_index (determines the guest IP 10.200.0.{2 + vm_index}), pod_netns_attached, and pooled (whether the VM was served from the warm pool instead of cold-booted). vm_list entries carry backend and, for Firecracker VMs, jail — {pid, uid, chroot} of the jailed VMM process, the only handles an operator has on it (k7d doctor prints them too).

Tree operations#

Snapshot-tree semantics (budgets, LRU eviction, protect/prune, keyframes) are explained in Snapshot tree; cluster specifics in Cluster mode.

TreeBudget#

TreeUsage#

Carried on tree_nodes, tree_list, and tree_watching: live_vm_count, live_ram_bytes, disk_bytes, total_nodes, live_node_count.

EgressPolicy#

Per-tree posture for traffic leaving the tree’s bridge, enforced by the tree network jail. Forks inherit the source’s policy.

{"mode": "open"}{"mode": "deny"}{"mode": "whitelist", "allow": [{"cidr": "140.82.112.0/20", "port": 443}], "allow_dns": "10.200.0.1"}

169.254.0.0/16 (cloud metadata) is dropped in every mode unless a whitelist entry names it. RoCEv2 leaves as UDP/4791 — a whitelist that needs RDMA out of the tree must name that port.

Dilation policy fields#

These fields opt a tree node into the daemon’s adaptive dilation loop.

dilation_config sets the loop’s knobs. Omitted fields take the defaults below:

A fork that omits either field inherits the source node’s mode and knobs. down / track need the native backend and a factor that sits on the ladder (config.dilation at create, or the child’s factor at fork). Anything else is refused before a VM boots. fixed still validates dilation_config, so a child can inherit it later. The loop is not persisted, so a tree reopened with tree_open has no modes recorded.

KSM flag#

ksm: true on tree_create_cluster or tree_adopt_cluster marks every native member’s MAP_PRIVATE guest RAM MADV_MERGEABLE once the guest is running. Forks inherit it. The default is off. Firecracker members and members with virtiofs shares, whose RAM is MAP_SHARED, are refused with a named error. k7d never writes /sys/kernel/mm/ksm: an operator has to start ksmd, and doctor reports its state in ksm_run. Merged pages show up per member in tree_nodes.live_ksm. A tree that did not opt in reports zeros.

Fork responses#

tree_created, tree_forked, and tree_resumed responses carry guest_cids — one vsock CID per payload member, ordered by vm_index (a single entry for single-VM trees). Fork responses additionally carry:

• fork_memory_full_copy (per member): false means the CoW MAP_PRIVATE fast path; true means a full memory copy (only virtiofs-backed sources — e.g. read-write hostPath — take that fallback).
• latency_ns: the daemon’s own wall time for the fork (or the whole batch). Budgets are asserted on this figure, not on the client’s round trip.
• dilation: the child’s clock factor after the fork.

{"op": "tree_fork_batch", "tree_id": "t1", "source_id": "root", "labels": ["b0", "b1"]}{"status": "tree_fork_batch", "latency_ns": 104000000, "forks": [  {"node_id": "b0", "guest_cids": [41, 42, 43], "fork_memory_full_copy": [false, false, false], "latency_ns": 104000000, "dilation": 1},  {"node_id": "b1", "guest_cids": [44, 45, 46], "fork_memory_full_copy": [false, false, false], "latency_ns": 104000000, "dilation": 1}]}

tree_created for a native cluster tree also carries pause_ns (0.8.0), one entry per member: the host time that member’s guest did not run while the root keyframe was cut (pause, residual write, restore-swap). It also carries max_pause_ns. Both are measured values, not budgets, and are empty or zero for single-VM and Firecracker trees.

Keep the CIDs from these replies. Guest exec is vsock straight to a CID, and the vm_id from create_vm does not reach a tree fork. To get them back later, read tree_nodes.live_guest_cids[node_id] (or live_agent_endpoints on Firecracker). list_vms will not show them.

tree_prepared carries wrote_base (a new keyframe was written), wrote_base_incremental (it was a reflink clone of the nearest ancestor plus this node’s dirty pages, O(divergence) instead of O(guest RAM); a refresh is incremental against the node’s own previous keyframe), base_disk_bytes (the physical bytes it actually added — stat cannot tell you this on a reflinked file), latency_ns, and guest_cids.

Clock operations#

All clock ops act on every live VM of one cluster at once: the whole cluster is paused for the write and resumed after it. Concepts, numbers, and caveats: Time warp.

cluster_id is the NetConfig.cluster_id given to create_vm, or for tree-owned clusters {tree_id}-{node_id} (tree_id alone for the root).

The auto_warp reply carries mode, holders, and stats: cycles, warps, guest_ns_added, wall_ns_paused, plus a breakdown of where the pause went (pause_ns, freeze_ns, stop_vcpus_ns, quiesce_ns, decide_ns, …).

Daemon environment#

Every unknown value above is a hard error rather than a silent fallback.

On-disk locations#