Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/deeplethe/forkd/llms.txt

Use this file to discover all available pages before exploring further.

Before you can fork microVMs, your Linux host needs a handful of one-time configuration steps: KVM access for the current user, a Firecracker binary, a host-side tap device for the parent VM, per-child network namespaces for isolation, and cgroup v2 for per-sandbox memory limits. This guide walks through each step, explains what every script does, and shows how forkd doctor verifies the result.

​
Prerequisites

Architecture

x86_64 Linux (aarch64 builds exist but are not benchmarked)

Kernel

Linux kernel 5.10 or newer. 5.7+ required for v0.4 live-fork mode.

KVM

/dev/kvm must exist. Bare-metal or nested-virt with VT-x / AMD-V exposed.

Distro

Ubuntu 22.04+ recommended. Other systemd-based distros work; PRs welcome.
You also need sudo access to install packages, configure tap devices, and provision network namespaces.

​
One-shot setup

1

Install the forkd binaries

Download the pre-built release tarball — no Rust toolchain needed:
curl -sSL https://github.com/deeplethe/forkd/releases/download/v0.5.2/forkd-v0.5.2-x86_64-linux.tar.gz \
  | sudo tar -xz -C /usr/local/bin/
Alternatively, if you are building from source:
cargo build --release
sudo install -m 0755 target/release/{forkd,forkd-controller} /usr/local/bin/
2

Run setup-host.sh

scripts/setup-host.sh performs the following actions:
  • Checks that /dev/kvm exists and that the CPU advertises VT-x / AMD-V
  • Adds your user to the kvm group (requires log-out / log-in to take effect)
  • Installs apt dependencies: build-essential, pkg-config, libssl-dev, iproute2, bridge-utils, iptables, socat, jq, qemu-utils
  • Installs Rust via rustup (if missing)
  • Downloads and installs Firecracker v1.10.1 to ~/.local/bin/firecracker
  • Enables KSM (kernel same-page merging) for CoW page deduplication
  • Reserves 1 GiB of hugepages (512 × 2 MiB) for live-fork mode
sudo bash scripts/setup-host.sh
Pass --paranoid to download pinned rustup-init and Firecracker archives with SHA-256 verification before installing:
sudo bash scripts/setup-host.sh --paranoid
After the script adds you to the kvm group you must log out and back in (or run newgrp kvm) before /dev/kvm becomes writable without sudo.
3

Create the host tap device

scripts/host-tap.sh creates forkd-tap0 at 10.42.0.1/24 on the host. This tap is used by the parent VM during warmup (before any children are forked). It also enables ip_forward and installs a MASQUERADE iptables rule so the parent has outbound internet access during the snapshot build step.
sudo bash scripts/host-tap.sh
The script is idempotent — re-running it is safe. You can customise the device name and IP via environment variables:
TAP=forkd-tap0 TAP_IP=10.42.0.1 sudo bash scripts/host-tap.sh
4

Provision per-child network namespaces

Each forked child runs in its own network namespace (forkd-child-<N>) for multi-tenant isolation. scripts/netns-setup.sh N provisions N namespaces and wires them up to a host bridge (forkd-br0) with outbound NAT:
sudo bash scripts/netns-setup.sh 100
Each namespace receives:
  • A tap device forkd-tap0 at 10.42.0.1/24 (faces the guest VM)
  • A veth pair connected to forkd-br0 at 10.43.0.<i+1>/16 (faces the host bridge)
  • A default route via 10.43.0.1 (the bridge)
  • An SNAT rule so guest traffic carries a unique source IP the bridge can route back
The host bridge has a single MASQUERADE rule through your uplink. The script is idempotent.
The number you pass (100 above) must be at least as large as the --n value you plan to pass to forkd fork. Re-run the script with a larger N to add more namespaces.
5

Verify the setup with forkd doctor

forkd doctor runs 16 checks and prints a fix hint for each non-passing item:
forkd doctor
CheckWhat it verifies
platformx86_64 Linux
kvm_device/dev/kvm exists and is accessible
hw_virtCPU exposes VT-x or AMD-V in /proc/cpuinfo
kvm_accessCurrent user can open /dev/kvm without root
cgroup_v2Unified cgroup v2 hierarchy mounted at /sys/fs/cgroup
ip_forwardnet.ipv4.ip_forward = 1 on the host
tap_deviceforkd-tap0 exists and is up
netnsAt least one forkd-child-* namespace is provisioned
firecracker_binaryfirecracker is on $PATH or ~/.local/bin/
firecracker_versionFirecracker version is ≥ v1.10
docker_daemonDocker daemon reachable (optional — needed for forkd from-image)
snapshot_dir~/.local/share/forkd/snapshots/ exists and has ≥ 2 GiB free
kernel_imageA vmlinux-* kernel image found at a standard path
controllerController daemon reachable at FORKD_URL (or http://127.0.0.1:8889)
uffd_wpvm.unprivileged_userfaultfd = 1 or CAP_SYS_PTRACE (v0.4 live-fork)
memfd_creatememfd_create(2) available (v0.4 live-fork)
Run forkd doctor whenever something feels off — it surfaces the exact fix commands to run.

​
v0.4 live-fork prerequisites

The default snapshot/fork flow works on any kernel ≥ 5.10 with vanilla Firecracker. To use live BRANCH (--live / mode: "live") you need three additional prerequisites:
  1. Kernel ≥ 5.7 — required for UFFD_WP (userfaultfd write-protection)
  2. vm.unprivileged_userfaultfd = 1 — or CAP_SYS_PTRACE:
sudo sysctl -w vm.unprivileged_userfaultfd=1
# Make persistent:
echo 'vm.unprivileged_userfaultfd=1' | sudo tee /etc/sysctl.d/99-forkd.conf
  1. Vendored Firecracker fork — the mem_backend.backend_type: "Shared" feature is not yet upstream. Install the vendored build:
# Replace the standard Firecracker binary with the vendored fork:
curl -sSL https://github.com/deeplethe/firecracker/releases/download/forkd-v0.4-mem-backend-shared-v1.12/firecracker-x86_64 \
  -o ~/.local/bin/firecracker
chmod +x ~/.local/bin/firecracker
Live-fork mode (--live-fork on forkd fork, mode: "live" on POST /v1/sandboxes/:id/branch) silently falls back to file-backed RAM when the vendored Firecracker fork is not installed. Run forkd doctor to confirm both uffd_wp and memfd_create checks pass before relying on the sub-50 ms pause window.
forkd doctor probes both uffd_wp and memfd_create and emits specific fix hints if either is missing.

​
Kubernetes deployment

Running forkd inside Kubernetes is supported — one forkd-controller Pod hosts N sandbox children; the K8s scheduler runs once at Pod creation regardless of fan-out size. Nodes require /dev/kvm + cgroup v2. Managed K8s clusters (GKE, EKS, AKS) typically need a bare-metal node SKU or explicit nested-virt to qualify. See /operations/kubernetes for the starter manifest and node configuration guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us