> ## Documentation Index
> Fetch the complete documentation index at: https://docs.katakate.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Installation
> Five-minute quickstart, install from a release tarball or build from source, then fork your first cluster
## 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/guides/runtime-class).
* Optional: the pinned **Firecracker + jailer** (`utils/install-firecracker.sh`,
v1.16.2, sha-verified) if you want the [`k7-fc` backend](/k7d/concepts/backends).
`k7d doctor` runs exactly these checks without starting a daemon:
```bash theme={null}
k7d doctor
# ok kvm /dev/kvm
# ok vhost_vsock /dev/vhost-vsock
# ok tun /dev/net/tun
# ok cgroup_v2 ...
# doctor: ok — host can run k7d
```
Exit code is non-zero on any `FAIL`.
The same report is available on the socket as `{"op":"doctor"}` — see
the [Daemon API](/k7d/api/protocol).
## Five-minute quickstart
From a clone or a clean box:
```bash theme={null}
git clone https://github.com/Katakate/k7d && cd k7d
sudo ./scripts/quickstart.sh
```
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:
```bash theme={null}
k7d doctor # host checks; does not start a daemon
k7d quickstart # 3-node busybox tree + 4 forks (daemon must be up)
```
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, the guest
docker payload, and an installer.
```bash theme={null}
tar xzf k7d-v0.7.0-x86_64-linux.tar.gz
cd k7d-v0.7.0-x86_64-linux
sudo ./install.sh
```
The installer:
* copies `k7d` and `containerd-shim-k7-v1` to `/usr/local/bin`
(override with `--prefix DIR`) and the shim's static `runc.amd64` to
`/opt/k7d`,
* copies the guest kernel (`vmlinux`), initramfs, and docker payload
to `/usr/local/share/k7d` (payload under `docker/`),
* 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:
```bash theme={null}
systemctl status k7d
ls /run/k7d/k7d.sock
k7d --version
```
`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` (and `k7-fc`), add
`--with-k3s`:
```bash theme={null}
sudo ./install.sh --with-k3s
```
This registers the `k7` and `k7-fc` runtimes in the k3s containerd config
template (the latter through `ConfigPath = /etc/k7d/shim-k7-fc.toml`),
restarts k3s, and applies both RuntimeClasses (`k7-fc` with its
`32Mi` / `50m` PodOverhead). It refuses to continue if either block
carries `BinaryName`. The
[RuntimeClass guide](/k7d/guides/runtime-class) explains each step if you
prefer to do it by hand. `k7-fc` pods additionally need the pinned
Firecracker binaries:
```bash theme={null}
sudo bash utils/install-firecracker.sh # reads guest/fc/pins.env, verifies every sha256
```
k7d **0.8.0** is the current tarball: pre-copied cluster keyframes,
keyframe `refresh`, a per-tree dilation policy, opt-in KSM, adopted-VM
teardown, and the fake-GPU fixture extensions. 0.7.0 was privilege
separation, Intel warm-fork CET/XSS, and Firecracker jail integrity.
The Firecracker engine and in-guest Docker service first shipped in
0.6.0 — do not use 0.5.0. Intel hosts that installed the dilation patch
from 0.7.0 should rebuild it
([Time warp](/k7d/guides/time-warp#intel-hosts-rebuild-the-patch)).
## Build from source
You need Rust and Docker (the guest rootfs is built in a container).
```bash theme={null}
git clone https://github.com/Katakate/k7d && cd k7d
make release # daemon, shim, guest kernel, rootfs → dist/
```
`make release` produces the same tarball layout under
`dist/k7d-v-x86_64-linux/` (daemon, shim, `vmlinux`,
`initramfs.cpio.gz`, `runc.amd64`, `docker/`, `install.sh`,
`quickstart.sh`) plus the `.tar.gz` — run `sudo ./install.sh` from
there, or start the daemon directly for a quick look:
```bash theme={null}
cd dist/k7d-v0.7.0-x86_64-linux
sudo K7D_KERNEL=$PWD/vmlinux K7D_INITRD=$PWD/initramfs.cpio.gz RUST_LOG=info ./k7d &
```
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`](https://github.com/katakate/k7d/blob/main/HACKING.md)
covers the remote-node development loop, the verification suite, and the
kubectl integration tests.
### What else ships in the tree
Since 0.5.0 the public repository also carries `gym/` (the RL gym — lease,
fork, prepare, score, scenario packs with a scripted runtime; see
[GRPO](/k7d/guides/grpo)) and `utils/kvm-dilation/` (the carried KVM
continuous ×N dilation patch with install/revert scripts; see
[Time warp](/k7d/guides/time-warp)). `make helm-pin` installs the pinned
helm v3.16.4 used for Ubuntu Cilium/Tetragon bring-up.
### 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](/k7d/guides/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.
```bash theme={null}
cd examples/cluster-tree-search
python3 run_demo.py --mode busybox --branches 4
# the density claim — 50 cluster forks on one 64 GB box:
python3 run_demo.py --mode busybox --branches 50
```
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](/k7d/api/protocol) for the full verb list and the
[GRPO guide](/k7d/guides/grpo) for wiring it into a training loop.
## Next steps
Create or adopt an N-node k3s cluster and fork it without agent restarts.
Stock Ubuntu 24.04 guests with k3s, Cilium, Tetragon, Longhorn.
fork\_batch, protect, prune, auto\_evict under RAM budgets.
Compress idle guest time with lockstep jumps or ×N dilation.
Schedule Kubernetes pods as k7d microVMs — native engine or jailed Firecracker.
Native rust-vmm vs stock Firecracker under the jailer: selection, matrix, fork mechanics.
Why a fork costs \~5 ms and dirty pages, not full guest RAM.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.