Fork AI 工作流

Source must boot with live_fork=True (memfd-backed RAM, the prereq

Build a 3-layer chain off a python:3.12-slim base

forkd snapshot-diff --from py-base --tag py-numpy --exec "pip install numpy==2.0.2" forkd snapshot-diff --from py-numpy --tag py-pandas --exec "pip install pandas==2.2.3"

sudo bash scripts/setup-host.sh --paranoid

sudo bash scripts/netns-setup.sh 3 # per-child network namespaces

2-3 min the first time (Docker pull + ext4 + warmup); cached after that.

sudo -E forkd fork --tag py-numpy -n 5 --per-child-netns ```

Probe your install's latency

```bash forkd bench --tag py-numpy --n 5

1. Host setup: KVM, Firecracker, Rust, KSM, hugepages, tap device.

sudo bash scripts/setup-host.sh sudo bash scripts/host-tap.sh cargo build --release sudo install -m 0755 target/release/{forkd,forkd-controller} /usr/local/bin/

2. Build a warmed rootfs from a Docker image.

sudo bash scripts/build-rootfs.sh python:3.12-slim python-rootfs.ext4 1536 python3-numpy

Framework integration recipes (host-side, no rootfs build)

Drop-in patterns for the four agent frameworks most often used with forkd. Each is ~150-250 lines of Python with a --dry-run mode that exercises the forkd plumbing without an LLM key:

Snapshot Hub (skip the rootfs build entirely)

Once a parent snapshot is built (yours or someone else's), forkd pack ships it as a single .tar.zst file with a manifest + per-file sha256. Other hosts pull and resume forking in seconds, no Docker round-trip:

```bash

Quick start

Requires: x86_64 Linux with KVM, Ubuntu 22.04 or newer.

Demo: branch a thinking agent

A 24-second walkthrough of the LangGraph branch-and-fan-out demo — source agent runs a ReAct loop, gets BRANCHed mid-thought, three grandchildren each receive a different steering hint, all three produce divergent itineraries while inheriting the same prior reasoning state.

Headline divergence: the source (no hint) picks Nishiki Market for Day 1; all three hinted children independently substitute Arashiyama Bamboo Grove. The cost-focused child also adds "may be pricey" annotations the others don't. The model wasn't told to swap places — each hint perturbed the next LLM call, the rest of the prior reasoning came along unchanged.

Full mechanism + numbers + raw transcripts in recipes/langgraph-react/ and recipes/langgraph-react/DEMO.md.

4. (Optional) language clients for programmatic use:

pip install forkd # Python SDK — calls the daemon over HTTP npm install @deeplethe/forkd # TypeScript SDK ```

forkd doctor runs 17 checks (KVM, hardware virt, cgroup v2, IP forward, tap, netns, Firecracker binary + version, Docker daemon, snapshot dir + disk space, kernel image, controller reachability, platform, plus uffd_wp + memfd_create + hugepages for the v0.4 live-fork path) and emits specific fix hints for each non-pass. Run this first whenever something feels off.

then add to claude_desktop_config.json:

spawn from the CLI is the next gap (see issue #209 for status).

sudo -E forkd fork --tag pyagent -n 1 --per-child-netns --live-fork sudo -E forkd snapshot --from-sandbox <sb-id> --live --no-wait ```

Requires Linux ≥ 5.7, vm.unprivileged_userfaultfd=1 (or CAP_SYS_PTRACE), and the vendored Firecracker fork from deeplethe/firecracker:forkd-v0.4-mem-backend-shared-v1.12 — forkd doctor probes both. Full design: DESIGN-v0.4.md. Empirical PoC data: experiments/v0.4-*-poc/. Tracking issue #101.

<br/>

CLI + daemon binaries (pre-built tarball, no Rust toolchain needed):

curl -sSL https://github.com/deeplethe/forkd/releases/download/v0.5.3/forkd-v0.5.3-x86_64-linux.tar.gz \ | sudo tar -xz -C /usr/local/bin/

sudo -E forkd quickstart ```

quickstart preflights the host (KVM, Firecracker, kernel image), tells you what it wants to set up (guest kernel download, tap device, per-child netns — nothing happens without your consent or --yes), bakes a Python snapshot from python:3.12-slim with your local Firecracker (or pulls a prebaked one from the hub when Docker is absent), then forks 10 microVM children from it and prints per-child timings. Idempotent — re-running reuses the snapshot and skips completed setup.

The sections below are the same flow broken into individual verbs, for when you want control over each step.

1. CLI + daemon binaries (pre-built tarball, no Rust toolchain needed):

curl -sSL https://github.com/deeplethe/forkd/releases/download/v0.5.3/forkd-v0.5.3-x86_64-linux.tar.gz \ | sudo tar -xz -C /usr/local/bin/

Python SDK

In-guest agent (E2B-compatible):

from forkd import Sandbox   # drop-in for `from e2b import Sandbox`

with Sandbox() as sb:
    print(sb.commands.run("uname -a").stdout)
    print(sb.eval("numpy.zeros(5).tolist()"))    # reuses warmed PID 1

Controller daemon (lifecycle + branching):

```python from forkd import Controller

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

TypeScript SDK

For Node.js 18+ agents (LangChain.js, agent-twins, anything JS-side):

npm install @deeplethe/forkd

import { Controller } from '@deeplethe/forkd';

const ctrl = new Controller();   // reads FORKD_URL, FORKD_TOKEN from env
const [parent] = await ctrl.spawnSandboxes({
  snapshotTag: 'pyagent', n: 1, perChildNetns: true,
  liveFork: true,             // v0.4: enables { mode: 'live' } later
});

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

Surface parity with the Python SDK: spawnSandboxes / branchSandbox take the same prewarm / liveFork / mode / wait / measure_diff options. See sdk/typescript/.

How forkd compares

The sandbox-runtime space has a wide spread of designs. The table below summarises positioning of forkd against the most-cited open-source projects. Numbers in quotes are as advertised by the upstream project unless they match a row in our benchmark chart above. forkd does not measure other projects on workloads they were not designed for.

¹ Wall-clock at N=100 concurrent on this bare-metal host (systemd-detect-virt: none, i7-12700, 20 vCPU, no nested virt). This is the fast-path number — pool_default_format_size_list was extended to include the template's writable-layer size, so each sandbox reuses a pre-formatted pool entry rather than going through a live mkfs.ext4 + reflink-copy. 1056 ± 14 ms over five runs, 100 % success every run, measured with a bench script that pre-warms Python's ThreadPoolExecutor to keep client-side lazy-init out of the timing. Host runs cube v0.2.0, which carries a ~50 ms latency regression that PR #234 fixes in v0.2.1 — the figure above is the v0.2.0 baseline. An earlier slow-path measurement on the same host (writable-layer size that didn't match the default pool) returned 20.3 s with 77/100 success — that mismatch was on our side and the maintainer corrected it at #235. Cube advertises <60 ms single-instance cold-start (P99 200 ms at N=100 concurrent) under the fast-path configuration on a 96 vCPU host — that figure isn't disputed and we did not retest it here. Note also that this row compares fork-from-warm (forkd) with cold-start (every other project); they're different operating points by design, not equivalent primitives. See bench/CUBESANDBOX.md for the full methodology, both rows, and the upstream cmdTimeout race we filed PRs #236 / #237 against. ² Daytona's advertised number; we did not measure it (workspace runtime, not a fan-out-comparable shape).

[cs]: https://github.com/TencentCloud/CubeSandbox [dy]: https://github.com/daytonaio/daytona [os]: https://github.com/alibaba/OpenSandbox [e2b]: https://github.com/e2b-dev/E2B [e2b-infra]: https://github.com/e2b-dev/infra [bl]: https://github.com/boxlite-ai/boxlite

Where forkd fits.

- Code interpreters and Jupyter-kernel sandboxes. Each conversation turn or tool call spawns a fresh kernel; the warmed parent carries the SciPy / ML runtime, so per-request import numpy / import torch collapses to zero. This is the design point — the workload shape Anthropic / OpenAI / Modal code-interpreter products are all on. - Evaluation harnesses. Hundreds of repository checkouts or test rollouts in parallel — SWE-bench-style — without paying Docker cold-start per task. - Per-user code execution at fan-out scale. Many short-lived sandboxes sharing one warmed parent, each child KVM-isolated by construction. - Untrusted-code execution in CI. git clone, pip install, pytest inside a real Linux VM, not a container namespace. - Self-hosted alternative to managed sandbox SaaS. One Linux box with KVM, single-binary daemon, Apache 2.0 — no per-second cloud fees, no vendor lock-in.

Where the others fit better. CubeSandbox: faster pure cold-start (<60 ms advertised). Daytona: workspace runtimes where each user owns one long-lived sandbox. OpenSandbox: one orchestration API across multiple isolation backends. BoxLite: embeddable, daemon-less, cross-platform (macOS via Hypervisor.framework). Modal: the closed- source managed system with the same primitive.

Where forkd is wrong. Function-level snapshot runtimes that give up real Linux (single-vCPU, serial I/O only) beat forkd's ~100 ms by an order of magnitude — at the cost of not running real Python servers, apt install, or outbound HTTPS.

<br/>

Alternative: build from a Docker image

forkd from-image wraps Docker pull → ext4 → boot + warmup → pause → register tag into a single verb. Use this when you need a recipe that isn't on the Hub yet:

```bash sudo -E forkd from-image python:3.12-slim \ --tag py-numpy \ --extra python3-numpy

Alternative: build from source (advanced)

```bash

`mode="live"` collapses source pause to sub-50 ms (vs ~200 ms for diff);

Enterprise deployment FAQ

Skim answers for platform / procurement teams scoping forkd:

Can we deploy on Kubernetes? Yes — one forkd-controller Pod hosts N sandbox children; the K8s scheduler runs once at Pod creation regardless of fan-out (vs one Pod-per-sandbox in Kata / Firecracker-on-K8s designs). A starter manifest ships at packaging/k8s/. Requires nodes with /dev/kvm + cgroup v2; managed K8s (GKE / EKS / AKS) typically needs a metal SKU or explicit nested-virt to qualify.

How many sandboxes fit in one Pod? With a 512 MiB warmed Python+numpy parent, rough sizing:

• ~1 actively-running agent per vCPU (compute-bound bottleneck)
• ~50 idle-pooled agents per 8 GiB Pod RAM (process-state bottleneck, not memory)

Measured CoW overhead at N=100 is 0.12 MiB / child on top of the parent (bench/), so memory rarely caps fan-out — vCPU + process count dominate. Heavier parents (browser, ML inference) hit the ceiling sooner; measure with yours.

How do existing agents connect?

• REST — POST /v1/sandboxes n=100, language-agnostic, bearer-token auth
• Python SDK — from forkd import Sandbox (drop-in for from e2b import Sandbox)
• LangGraph / AutoGen / CrewAI — through the Python SDK, no special glue
• MCP — pip install forkd-mcp ships an MCP server for Claude Desktop / Claude Code / Cursor / Cline. See sdk/mcp/

Production case shapes (from production users + this repo's recipes):

• AI code interpreter — one warmed parent (SciPy / torch pre-imported), fork-per-conversation-turn. Recipe: e2b-codeinterpreter/
• SWE-bench-style parallel evals — N parallel repo checkouts, each child runs pytest isolated. Recipe: coding-agent/
• Per-user code exec at scale — shared warmed parent, child KVM-isolated per user
• Untrusted CI — git clone + pip install + pytest inside a real Linux VM, not a container namespace
• Fork-per-test isolated databases — recipe: postgres-fixture/ — ready-to-query postgres at ~10 ms per child instead of ~2 s of fresh initdb

Which kernels does forkd run on? Two kernels are in play, and only one is yours to worry about:

The host kernel is where Firecracker's own version sensitivity lives (KVM ABI, snapshot compatibility) — see Firecracker's kernel support policy for the authoritative host-kernel matrix rather than a copy that can drift. Snapshots are not portable across Firecracker versions or host CPU microarchitectures (a separate concern from kernel version); forkd doctor reports both your FC version and guest kernel so a fleet can assert they match.

<br/>