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.

This guide walks you from a bare Linux host to a running cohort of KVM-isolated microVM sandboxes. The one-command path (forkd quickstart) handles every step automatically; the manual path below gives you control over each verb when you need it.
1

Prerequisites

forkd requires a bare-metal or nested-virt x86_64 Linux host with KVM enabled.
  • Architecture: x86_64
  • OS: Ubuntu 22.04 or newer (other distros work; Ubuntu is tested)
  • Kernel: Linux 5.7 minimum; 5.20+ recommended for automatic RNG re-seeding via vmgenid
  • KVM: /dev/kvm must be present and readable by your user
  • cgroup v2: unified hierarchy must be mounted (mount -t cgroup2)
Managed Kubernetes (GKE, EKS, AKS) typically requires a bare-metal node SKU or explicit nested-virt enablement to expose /dev/kvm. See Host Setup for cloud-specific instructions and the full list of kernel modules and tuning parameters.
Verify your host is ready before installing:
# Quick manual check
ls -la /dev/kvm
grep -Ec '(vmx|svm)' /proc/cpuinfo   # should be > 0
mount | grep cgroup2
2

Install forkd

Download and install the pre-built tarball — no Rust toolchain required:
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/
This installs two binaries:
  • forkd — the CLI for snapshots, forking, packing, and the bench tool.
  • forkd-controller — the daemon that owns the registry, REST API, auth, and metrics.
Confirm the install:
forkd --version
# forkd 0.5.2
Optionally install the language SDKs for programmatic use:
pip install forkd                  # Python SDK — E2B-compatible Sandbox + Controller
npm install @deeplethe/forkd       # TypeScript SDK for Node.js 18+ agents
3

One-command quickstart

Run the automated quickstart. This is the fastest way to get a working sandbox:
sudo -E forkd quickstart
forkd quickstart does the following in order (nothing happens without your consent, or pass --yes to accept all prompts):
  1. Preflights the host — runs the same 16 checks as forkd doctor (KVM, hardware virt, cgroup v2, IP forwarding, tap device, netns provisioning, Firecracker binary + version, Docker daemon, snapshot directory + disk space, kernel image, controller reachability, and uffd_wp + memfd_create for the v0.4 live-fork path).
  2. Downloads a guest kernel if one is not already present.
  3. Provisions a tap device (forkd-tap0) and network namespaces for per-child isolation.
  4. Bakes a Python snapshot from python:3.12-slim with numpy pre-imported using your local Docker daemon — or pulls a prebaked pack from the Snapshot Hub if Docker is absent.
  5. Forks 10 microVM children from the snapshot and prints per-child timings.
The command is idempotent — re-running it skips completed steps and reuses existing snapshots and tap devices.
If the quickstart completes successfully, you’ll see per-child fork timings in the output. Expect ~10–65 ms per child on a modern host. If any check fails, forkd doctor will print specific fix hints for each non-passing check.
4

Verify latency with the bench tool

After quickstart completes, probe your install’s actual fork latency:
forkd bench --tag quickstart --n 5
Example output:
forkd bench against snapshot quickstart
  spawn (n=1)              61 ms  sb-...-0027
  exec round-trip          22 ms  exit=0
  branch (diff=true)      287 ms  pause_ms=234 diff_physical_bytes=393216
  fanout (n=5)             65 ms  13ms/child
  cleanup                 136 ms
                          -----
  total                   571 ms
Run this against any snapshot to measure how forkd performs on your hardware. The output is screenshot-friendly and covers single-spawn, exec round-trip, BRANCH, and fan-out timings in one pass.

​
Using the Python SDK

The Python SDK is E2B wire-compatible at the Sandbox class level — swap from e2b import Sandbox for from forkd import Sandbox and existing agent code continues to work. In-guest agent (exec and eval inside a running sandbox): 
from forkd import Sandbox

with Sandbox() as sb:
    print(sb.commands.run("uname -a").stdout)
    print(sb.eval("numpy.zeros(5).tolist()"))   # reuses the warmed PID 1 interpreter
sb.eval(...) costs ~1 ms because it reuses the already-running Python interpreter in the sandbox’s PID 1. sb.commands.run("python3 -c '...'") spawns a cold subprocess that re-imports numpy (~96 ms). Prefer eval for tight loops.
Controller daemon (lifecycle + branching): 
from forkd import Controller

c = Controller()                                  # connects to http://127.0.0.1:8889
children = c.spawn_sandboxes("quickstart", n=1, per_child_netns=True,
                              live_fork=True)     # v0.4: enables mode="live" on BRANCH
sb_id = children[0]["id"]

# Drive the sandbox, then BRANCH before a risky step.
# mode="live" collapses source pause to sub-50 ms; wait=False returns
# after ~10 ms while the background memory copy completes asynchronously.
branch = c.branch_sandbox(sb_id, tag="checkpoint-1", mode="live", wait=False)
grandchildren = c.spawn_sandboxes(branch["tag"], n=5)   # speculative fan-out

​
Using the TypeScript SDK

For Node.js 18+ agents (LangChain.js, AutoGen, OpenAI Swarm, or anything JS-side): 
import { Controller } from '@deeplethe/forkd';

const ctrl = new Controller();   // reads FORKD_URL, FORKD_TOKEN from env

const [parent] = await ctrl.spawnSandboxes({
  snapshotTag: 'quickstart',
  n: 1,
  perChildNetns: true,
  liveFork: true,               // v0.4: enables { mode: 'live' } on branchSandbox
});

// mode: 'live' + wait: false = source pauses sub-50 ms and the caller returns
// after ~10 ms; the background memory copy completes asynchronously.
const branch = await ctrl.branchSandbox(parent.id, { mode: 'live', wait: false });
const kids = await ctrl.spawnSandboxes({ snapshotTag: branch.tag, n: 5, perChildNetns: true });

​
Next steps

Building Snapshots

Build custom parent snapshots from Docker images or pre-built recipes (Jupyter, browser, Postgres).

Forking Sandboxes

Fork N children from a snapshot, set memory limits, and communicate via exec and eval.

Python SDK Reference

Full API reference for the Sandbox and Controller classes.

BRANCH: Fork a Live VM

Pause a running sandbox mid-thought, snapshot its state, and fan out to N children in ~56 ms.

Build docs developers (and LLMs) love

Get started for freeTalk to us