Skip to main content

​
Requirements

  • Linux amd64 / x86_64 host with KVM — same ISA (amd64 is the Debian name; release tarballs use x86_64). /dev/kvm must exist. Bare metal or a cloud instance with nested virtualization both work. k7d does not build or run on macOS / Windows / ARM.
  • /dev/vhost-vsock, /dev/net/tun, and cgroup v2 — the daemon talks to guest agents over vsock, gives each VM a TAP, and jails each tree in a cgroup.
  • root — the daemon manages TAP devices, bridges, nftables, and /run/k7d/.
  • Optional: k3s, if you want pods scheduled as k7d microVMs via runtimeClassName: k7.
k7d doctor runs exactly these checks without starting a daemon:
Exit code is non-zero on any FAIL. The same report is available on the socket as {"op":"doctor"} — see the Daemon API.

​
Five-minute quickstart

From a clone or a clean box:
The script doctor-checks the host, fetches the release tarball and guest artifacts if they are not already present, starts k7d, boots a busybox 3-node tree, forks 4 branches, and prints the wall-clocks next to both rows of the two-clocks table. k7d doctor and k7d quickstart are the same verbs on an already-installed binary:
Overrides: K7D_RELEASE_URL (tarball), K7D_PREFIX (default /usr/local), K7D_SOCKET (default /run/k7d/k7d.sock).

​
Install from a release tarball

Each release ships a self-contained tarball with the daemon, the containerd shim, the guest kernel, the guest initramfs, and an installer.
The installer:
  • copies k7d and containerd-shim-k7-v1 to /usr/local/bin (override with --prefix DIR),
  • copies the guest kernel (vmlinux) and initramfs to /usr/local/share/k7d,
  • writes a k7d.service systemd unit that points K7D_KERNEL / K7D_INITRD at those assets, sets RUST_LOG=info, and raises LimitNOFILE to 524288 (the 1024 soft default is far too low for multi-cluster forks),
  • starts the daemon and waits for the control socket.
Verify:
k7d --version and k7d --help answer and exit without touching the running daemon. The daemon also refuses to start if a live listener already owns the socket path — it never displaces a running instance.

​
Registering with k3s

If the host runs k3s and you want runtimeClassName: k7, add --with-k3s:
This registers the k7 runtime in the k3s containerd config template, restarts k3s, and applies the RuntimeClass. The RuntimeClass guide explains each step if you prefer to do it by hand — or need to know why the config must not set BinaryName.

​
Build from source

You need Rust and Docker (the guest rootfs is built in a container).
make release produces the same tarball layout under dist/k7d-v<version>-x86_64-linux/ (daemon, shim, vmlinux, initramfs.cpio.gz, runc.amd64, install.sh, quickstart.sh) plus the .tar.gz — run sudo ./install.sh from there, or start the daemon directly for a quick look:
The daemon is the only process that chooses a guest kernel and initramfs. Without K7D_KERNEL / K7D_INITRD it refuses to create a VM rather than guessing. HACKING.md covers the remote-node development loop, the verification suite, and the kubectl integration tests.

​
Ubuntu node images

The tarball’s guest is the minimal busybox initramfs. To run stock Ubuntu 24.04 guests (k3s + Cilium + Tetragon + Longhorn, the ~1.1 s fork clock), build a node image once with guest/ubuntu/build-node-image.sh — see Ubuntu nodes.

​
Fork your first cluster

k7d quickstart is the shortest path. The repository also ships a demo that boots a live 3-VM k3s cluster once, then forks it into parallel branches, scores them, keeps the winner, and prunes the rest — printing the fork wall-clock as it goes.
Everything the demo does goes through the JSON-lines protocol on /run/k7d/k7d.sock — the same verbs your own trainer would call. See the daemon API for the full verb list and the GRPO guide for wiring it into a training loop.

​
Next steps

Cluster mode

Create or adopt an N-node k3s cluster and fork it without agent restarts.

Ubuntu nodes

Stock Ubuntu 24.04 guests with k3s, Cilium, Tetragon, Longhorn.

GRPO / tree search

fork_batch, protect, prune, auto_evict under RAM budgets.

Time warp

Compress idle guest time with lockstep jumps or ×N dilation.

RuntimeClass k7

Schedule Kubernetes pods as k7d microVMs.

How CoW fork works

Why a fork costs ~5 ms and dirty pages, not full guest RAM.