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.
  • root — the daemon manages TAP devices, bridges, and /run/k7d/.
  • Optional: k3s, if you want pods scheduled as k7d microVMs via runtimeClassName: k7.

​
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:

​
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/ — run sudo ./install.sh from there, or start the daemon directly for a quick look:

​
Fork your first cluster

The repository 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.

GRPO / tree search

fork_batch, protect, prune, auto_evict under RAM budgets.

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.