Backends: native and Firecracker

k7d boots every VM through the same daemon and the same containerd shim. The backend is which VMM process owns the KVM fd:

native (default) — k7d’s in-process rust-vmm VMM. The VM lives in the daemon’s address space; warm fork is a MAP_PRIVATE CoW of guest memory (~5 ms). This is what every other k7d page describes.
firecracker — a stock, sha-pinned upstream Firecracker v1.16.1 process, launched under the stock jailer. Same guest kernel, initramfs, agent, protocol, fork/tree/pool verbs and Docker service; the VMM is the audited upstream binary and sits in its own uid, chroot, pid namespace, cgroup and seccomp filter.

The Firecracker engine ships in k7d 0.6.0 (install.sh --with-k3s registers RuntimeClass k7-fc and the ConfigPath runtime option). The 0.5.0 tarball does not.

Selecting a backend

Three knobs, one result (VmConfig.backend). The first one that yields a backend wins; a contradiction is a loud Create error.

Knob	Where	Native	Firecracker
`VmConfig.backend`	control socket `create_vm`	`native` (serde default)	`firecracker`
Pod annotation `k7d.katakate.org/backend`	forwarded into the OCI spec by `pod_annotations`	`native`	`firecracker`
RuntimeClass `k7` / `k7-fc`	containerd handler; `runtimes.k7-fc` sets `[options] ConfigPath = /etc/k7d/shim-k7-fc.toml` (`backend = "firecracker"`) because the k3s CRI does not stamp `io.kubernetes.cri.runtime-handler`	handler `k7`	handler `k7-fc`

Rules:

runtimeClassName: k7-fc ⇒ Firecracker, even with no pod annotation.
runtimeClassName: k7 ⇒ native unless the pod carries k7d.katakate.org/backend: firecracker (per-pod opt-in).
k7d.katakate.org/backend: native on a k7-fc pod is a Create error containing contradicts. The RuntimeClass is never silently overridden.
Any other annotation value fails Create — a typo must not boot a pod on the wrong engine.

Gate admission on runtimeClassName (k7 vs k7-fc); k7d does not ship a Kyverno/OPA policy. In K7 the two RuntimeClasses surface as the k7d and k7d-fc backends.

apiVersion: v1
kind: Pod
metadata:
  name: demo-fc
spec:
  runtimeClassName: k7-fc
  containers:
    - name: main
      image: alpine:3.20
      command: ["sleep", "infinity"]

Feature matrix

Feature	Native (`k7`)	Firecracker (`k7-fc`)
VMM	in-process rust-vmm	stock Firecracker v1.16.1 under the stock jailer (sha-pinned)
Guest → host boundary	KVM	KVM + jailer (uid, chroot, pid ns, cgroup) + Firecracker seccomp
Agent	vsock	vsock (Unix socket inside the jail, same protocol)
Rootfs	erofs on virtio-blk	erofs on virtio-blk (Firecracker drives)
Scratch / data disks / image slots	virtio-blk	virtio-blk, filled after boot with `PATCH /drives`
Network	daemon TAP + bridge	same TAPs, moved into the jail by name
Warm fork (CoW memory)	`MAP_PRIVATE`	Diff snapshot → `FICLONERANGE` onto a reflinked base → `LoadSnapshot`
Cluster fork / snapshot tree / warm pool	yes	yes (`K7D_POOL_BACKEND=firecracker` for the pool)
`k7d.katakate.org/docker` (in-guest dockerd)	yes	yes — same agent service
virtiofs / hostPath fallback	yes (or `K7D_DENY_VIRTIOFS_FALLBACK=1`)	unsupported — Create fails naming the backend
Time warp / dilation / autowarp	yes	unsupported
Fork latency (256 MiB busybox, warm)	~5–50 ms	~190 ms for one child, ~76 ms/child at n=8
PodOverhead	none	`32Mi` / `50m` on the RuntimeClass

Unsupported is a named error, never a silent downgrade: a pod that asked for virtiofs or time warp on k7-fc does not reach Running.

How a Firecracker fork works

A native tree forks by mapping the source’s memory MAP_PRIVATE. A Firecracker tree has no such mapping, so a point is:

PUT /snapshot/create on the paused source — a Diff snapshot by default (only pages dirtied since the previous point; K7D_FC_FORK_SNAPSHOT=full writes all of RAM and exists for cross-checking, not as a fallback).
The Diff extents are FICLONERANGEd onto a root-owned base.mem; restore-N.mem is a FICLONE of the result — the point costs its dirty set, the base costs O(1).
Each child is a fresh jailed Firecracker LoadSnapshoted from its own reflink of restore-N.mem (mem_backend: File, clock_realtime), with writable disks reflinked from clones taken at the same paused instant. Every child extent reports FIEMAP_EXTENT_SHARED — CoW is proven, not assumed.

Cluster fork runs that primitive on every member after a parallel PATCH /vm Paused (pause skew p99 ≈ 125 µs across 20 runs). Suspend exports a Full point out of the jail and drops the process; resume re-stages a jail and LoadSnapshots with network_overrides so the member keeps its TAP identity. Measured on an exclusive Hetzner node (2026-09-08, 256 MiB / 1 vCPU busybox guests, 500 ms per-child ceiling asserted in tests):

Operation	Typical
Root point at `tree_create` (first Diff, 43 MiB)	169 ms
`prepare_fork_source` (Diff, ~1–2 MiB dirtied)	140–157 ms
`fork_batch` n=1	190 ms, child answers `ping` 5 ms later
`fork_batch` n=8	607 ms = 76 ms per child
`rollback` (load the existing point)	75–90 ms
Cluster `fork_batch`, 3 members	~0.67 s (debug build)
Cluster suspend / resume (2 members)	~2.1 s / ~512 ms (debug build)
Warm pool acquire (`K7D_POOL_BACKEND=firecracker`)	~100 ms

Most of the per-child cost is staging a chroot, leasing a uid, spawning jailer (new namespaces, pivot_root, cgroup) and waiting for its API socket — the warm pool of pre-staged jails is what recovers it. See LATENCY_BUDGETS.md for the native rows.

What the jail buys, and what it does not


Gained	The VMM is out of the daemon’s address space. A guest → VMM escape lands in a per-VM uid, chroot, pid namespace, cgroup and Firecracker’s seccomp filter — not in `k7d`.
Unchanged	The daemon is still host root and still one process (control socket, TAP/bridge, vsock proxy, tree bookkeeping). The shim still rewrites the OCI spec, and the guest-controlled path rules are the floor for both backends. The guest agent is the same binary. Sibling forks of one tree still share the daemon.
Lost	Time warp, dilation, autowarp. virtiofs / hostPath (`backend firecracker has no virtiofs`). Native `MAP_PRIVATE` fork latency.

Multi-tenant --docker should use k7-fc: the guest side is identical, so it is a RuntimeClass switch, not a rewrite. The VMM jail is the extra boundary; the in-guest docker.sock is still guest root. See Security.

Installing

packaging/install.sh --with-k3s registers both k7 and k7-fc (containerd blocks without BinaryName, /etc/k7d/shim-k7-fc.toml, RuntimeClass k7-fc with overhead.podFixed 32Mi / 50m).
utils/install-firecracker.sh puts the pinned firecracker and jailer in /usr/local/bin, verifying every sha256 from guest/fc/pins.env. A digest mismatch is fatal. k7d doctor reports the version and sha it finds.
Daemon knobs: K7D_FC_CHROOT_BASE (jail root; default /var/lib/k7d/fc, a link onto the reflink XFS that holds the writable disks so they can be hard-linked into a jail), K7D_FC_UID_BASE (first uid of the per-VM lease range; default 60000, 1024 live VMs per daemon, exhaustion is an error rather than a wrap-around), K7D_FC_FORK_SNAPSHOT (diff default, full), K7D_POOL_BACKEND (native | firecracker for the warm pool).

Known issue: K7 observed CRI exec into a k7-fc pod hanging after a k7 pause / k7 resume cycle (readiness probe timeout, K7 PERFORMANCE.md). Native k7 is unaffected.

Reference

docs/backends.md — selection matrix, source of truth
OVERHEAD.md — how the k7-fc PodOverhead was measured
RuntimeClass k7 — installing the runtime, annotation reference

Getting started

Concepts

Guides

API

Deep dives

Backends: native and Firecracker

Selecting a backend

Feature matrix

How a Firecracker fork works

What the jail buys, and what it does not

Installing

Reference

​Selecting a backend

​Feature matrix

​How a Firecracker fork works

​What the jail buys, and what it does not

​Installing

​Reference

Selecting a backend

Feature matrix

How a Firecracker fork works

What the jail buys, and what it does not

Installing

Reference