forkd

forkd is an open-source microVM sandbox runtime built on Firecracker, designed specifically for AI agent fan-out workloads. It lets a warmed parent VM be snapshotted once and then forked into hundreds of isolated children in milliseconds, with each child inheriting the parent's address space copy-on-write rather than cold-booting its own kernel. The project is written in Rust, licensed under Apache 2.0, and hosted at github.com/deeplethe/forkd.

What It Is

forkd sits in the category of sandbox runtimes for AI code execution and agent orchestration. Its core job is collapsing the per-request startup cost of spawning isolated execution environments — the kind of cost that shows up when an AI code interpreter needs a fresh Python kernel with NumPy and PyTorch already imported for every conversation turn. Instead of cold-booting a new VM each time, forkd boots the parent once, warms it (imports, JIT compilation, model weights), pauses it to disk, and then restores N children from that snapshot using mmap MAP_PRIVATE so the kernel handles copy-on-write at the page level. The result is hardware-level KVM isolation per child with a spawn cost closer to fork(2) than to a VM boot.

Architecture and How It Works

The system has three main components: a Firecracker VMM wrapper (forkd-vmm), a CLI binary (forkd), and a controller daemon (forkd-controller) that owns the snapshot registry, exposes a REST API with bearer-token auth, writes append-only JSON audit logs, and emits Prometheus /metrics. Children each get their own network namespace, cgroup v2 memory limit, and an independently re-seeded /dev/urandom via vmgenid. The controller can be deployed as a single Pod on Kubernetes — one daemon hosts N sandbox children, so the K8s scheduler runs once at Pod creation regardless of fan-out scale. A starter manifest ships at packaging/k8s/.

The BRANCH primitive extends fork-on-write to running VMs: pause a live sandbox, snapshot its in-flight state, and resume — all in roughly 150 ms — so an agent can fork mid-thought. The v0.4 live BRANCH mode uses UFFD_WP to capture dirty pages out-of-band, collapsing the source-pause window to 56 ms p50 / 64 ms p90 on a 1.5 GiB source. With wait: false, the caller returns after ~70 ms while the background memory copy completes asynchronously.

SDK and Integration Surface

forkd ships four client surfaces:

• Python SDK (pip install forkd) — drop-in compatible with the E2B Sandbox API
• TypeScript SDK (npm install @deeplethe/forkd) — surface parity with Python, targets Node.js 18+
• REST API — language-agnostic, bearer-token auth, documented in docs/API.md
• MCP server (pip install forkd-mcp) — exposes spawn_sandboxes, exec_command, eval_code, and other tools for Claude Desktop, Claude Code, Cursor, and Cline

Framework integration recipes ship for LangGraph, CrewAI, AutoGen, and OpenAI Swarm/Agents SDK. Pre-built rootfs recipes cover Python+NumPy, E2B-compatible code interpreter, Jupyter kernel, coding agents, Node.js, Playwright browser automation, and PostgreSQL fixture isolation.

Design Point and Tradeoffs

The README positions forkd for four workload shapes: AI code interpreters where per-request import numpy/import torch cost collapses to zero; SWE-bench-style parallel evaluation harnesses; per-user code execution at fan-out scale; and untrusted-code execution in CI inside a real Linux VM. Each child gets multi-vCPU, full TCP networking, and apt install — unlike function-level snapshot runtimes that trade single-vCPU and serial I/O for faster raw spawn. The tradeoff is that function-level runtimes beat forkd's ~100 ms by an order of magnitude when real Linux is not needed.

The benchmark table in the README (measured on Ubuntu 24.04, Linux 6.14, 20 vCPU, 30 GiB, KVM) shows forkd spawning 100 sandboxes in 101 ms wall-clock with 0.12 MiB memory delta per sandbox, compared to 1.06 s for CubeSandbox's fast path, 759 ms for raw Firecracker cold-boot, and 335 s for Docker (runc). These numbers compare fork-from-warm against cold-start, which the README explicitly notes are different operating points.

Update: v0.4 Live BRANCH

The latest release series culminates in v0.4 live BRANCH, wired end-to-end across REST (mode: "live"), CLI (--live), and all three SDKs. The mechanism requires spawning with live_fork: true to back guest RAM with a memfd shared between Firecracker and the controller; a vendored Firecracker fork (deeplethe/firecracker:forkd-v0.4-mem-backend-shared-v1.12) is required until an upstream mem_backend proposal lands. Earlier in the v0.3 series, diff-snapshot BRANCH cut the source-pause window from 29.3 s to 205 ms (143×) on a 4 GiB SSD source; v0.3.4 fixed a multi-BRANCH pause anomaly where repeated BRANCHes on the same parent climbed from 150 ms to 2.7 s, restoring flat ~150 ms behavior (17.6× faster on the 6th consecutive BRANCH). The project self-describes as Alpha, with on-disk formats and API shapes subject to change before 1.0.

Current Status

The project reports Alpha status as of the latest README. The fork-on-write primitive, controller daemon, REST API, auth, audit logging, cgroup memory limits, Prometheus metrics, and Python + TypeScript SDKs are exercised by 25 unit and integration tests in CI. Noted production-readiness gaps include: multi-node scheduling (one daemon per host), default-deny egress on per-child netns, cpu/io/pids quotas beyond memory.max, and no third-party security audit. A security advisory in the README notes that versions 0.1.0–0.1.3 contained HIGH-class validation gaps (path-traversal and placeholder bearer token) that were fixed in 0.1.4.