2. 主机初始化:

May 31, 2026 · View on GitHub

101 毫秒 fork 100 个 microVM,56 毫秒 BRANCH 一个运行中的 VM(v0.4 live 模式)。

面向 AI Agent 扇出(fan-out)场景的 microVM 沙箱运行时。子 VM 从一个已"暖启动"的父快照 fork 而来,通过写时复制(CoW)继承父进程的地址空间,而不是冷启动一个新内核。

forkd 基于 Firecracker 构建。父 VM 启动一次,把运行时(Python + 依赖,JIT 已暖的 JVM,已加载的 ML 模型)导入内存,然后暂停并落盘。每个子 VM 是一个独立的 Firecracker 进程,通过 MAP_PRIVATE 方式 mmap 父快照的内存镜像;内核在页面级别实现写时复制,因此在子 VM 发生写入分歧之前,它们共享父 VM 的常驻内存。

由此同时获得两个特性:每个子 VM 都是独立的 KVM 隔离, 同时单个子 VM 的启动成本接近 fork(2),而非冷启动 VM。

forkd 同时支持 BRANCH:把正在运行的沙箱暂停,把它当下的 in-flight 状态做成快照,再恢复 —— 整套 ~150 ms —— 让 agent 能在"思考过程中"叉出多条路径,而不只在暖启动时刻 fork。 v0.3.4 修复了一个慢路径回归:在同一个父 VM 上反复 BRANCH 时, pause 时间会从 150 ms 涨到 2.7 s (#146);修复后连续 BRANCH 保持平直(第 6 次 BRANCH 快了 17.6×)。

v0.4 live BRANCH 把源 VM 卡顿窗口从 ~200 ms(Diff)压到 56 ms p50 / 64 ms p90(1.5 GiB 源 VM,实测, bench/live-fork-pause-window/RESULTS-v0.4.md)。 p50 比 v0.3 Diff 快 3.6 倍,而且在慢盘上这个比值变得更大—— 因为 Live 的 pause 是 disk-independent 的(内存拷贝跑在 resume 之后,不占临界区)。加 wait: false 让调用方 ~70 ms 就返回,背景拷贝异步完成——对于 agent 代码的 fire-and-forget BRANCH 是 200× 的 RT 改进。CLI 用 --live / --no-wait,REST 用 mode: "live" / wait: false,Python / TypeScript / MCP SDK 同名。

from forkd import Controller
c = Controller()
# 源 VM 必须用 live_fork=True 启动(memfd 后端 RAM,UFFD_WP 看到
# 运行中父 VM 写的前提条件)。
parent = c.spawn_sandboxes("pyagent", n=1, live_fork=True)[0]
# ... 驱动 parent ... 然后 live BRANCH + fire-and-forget:
branch = c.branch_sandbox(parent["id"], mode="live", wait=False)
# ~10 ms 返回,status="writing";poll list_snapshots 等到
# status="ready" 即背景拷贝完成。

# CLI:本地 fork live-fork-capable 子 VM,然后对 daemon 追踪的那个
# 做 live BRANCH。两条路径暂时还不组合 ——daemon 侧 spawn 走 CLI
# 是下一个缺口(状态见 issue #209)。
sudo -E forkd fork --tag pyagent -n 1 --per-child-netns --live-fork
sudo -E forkd snapshot --from-sandbox <sb-id> --live --no-wait

需要 Linux ≥ 5.7、vm.unprivileged_userfaultfd=1(或 CAP_SYS_PTRACE),以及 vendored Firecracker 分支 deeplethe/firecracker:forkd-v0.4-mem-backend-shared-v1.12 ——forkd doctor 会探测这两项。完整设计: DESIGN-v0.4.md。PoC 实证数据: experiments/v0.4-*-poc/。跟踪 issue #101。

Demo:让一个思考中的 agent 分裂

一个 24 秒的演示 —— 源 agent 在 LangGraph ReAct loop 中跑到一半, 被 BRANCH,3 个子沙箱继承同一份认知状态,各自收到不同的引导 ("深度文化派"、"极简派"、"省钱派"),输出三条显著不同的 第一天行程。

forkd 分裂思考中的 agent

最关键的分裂证据:源 agent(无引导)第一天下午选 Nishiki Market (锦市场, $);3 个被引导的子沙箱**各自独立地都换成了 Arashiyama Bamboo Grove**(岚山竹林,free);"省钱派" 还在$ 餐厅那里加上了 "may be pricey" 的警告语,其他两个没有。模型并没有被告知"换景点" —— 是 hint 影响了下一次 LLM 调用,前置推理整套都没变。

完整机制 + 数据 + 原始 transcript 在 recipes/langgraph-react/ 和 recipes/langgraph-react/DEMO.md。

不仅是推理状态,文件系统状态也继承

针对"难道你不能直接并行调 3 次 LLM 吗"这个常见反驳,看 recipes/coding-agent-fork/ —— 50 MiB 的二进制 blob 通过一次 BRANCH 字节完全一致地传到 4 个沙箱里。3 个孙沙箱各自对同一个有 bug 的 Python 包应用不同的修复; 它们的 __pycache__/ 和编辑互不影响,但那 50 MiB 的继承是共享的。字节是塞不进 prompt 的。BRANCH 操作的 pause 时间 3.3 秒。

关键特性

硬件级隔离。 每个子 VM 都是独立的 Firecracker microVM, 基于 KVM。要逃逸出来需要 hypervisor 或内核漏洞,而不是 runc 的一个回归 bug。
暖启动的运行时免费继承。 导入、JIT 编译、模型权重、预取的缓存——只要父 VM 做过的事,子 VM 直接拿到。
每个子 VM 都是真 Linux。 多 vCPU、完整 TCP 网络、apt install、出站 HTTPS。和那些为了极致启动速度牺牲掉单 vCPU + 串行 I/O 的函数级快照运行时不同,forkd 的子 VM 可以跑真实的 Python 服务、模型推理或任何需要完整内核的负载。
从设计上就是多租户。 每个子 VM 独立 network namespace、独立 cgroup v2 内存限制、独立 /dev/urandom(Linux 5.20+ 通过 vmgenid 重新播种)。
为 Agent 扇出而生。 单次请求扇出到大量短生命周期沙箱的 AI Agent 负载——代码解释器、工具调用、评估 rollout——是设计目标。暖启动的父 VM 把每次请求的 import numpy / import torch 开销在整个 cohort 间分摊到接近零。
可运维。 守护进程持有状态、REST API(Unix 或 TCP)、 Prometheus /metrics、append-only JSON 审计日志、systemd 单元。
开源。 Apache 2.0,没有厂商 SDK 锁定。

基准测试

同一台 Linux 主机(Ubuntu 24.04,Linux 6.14,20 vCPU,30 GiB,KVM)。负载:启动 100 个沙箱,每个执行 import numpy; numpy.zeros(5).tolist()。

Spawn time at N=100

Host memory per sandbox

后端	N=100 总耗时	每个沙箱内存增量	说明
forkd	101 ms	0.12 MiB	从暖启动快照 CoW fork
CubeSandbox¹	1.06 s	5 MiB	RustVMM microVM,冷启动(池 fast path)
BoxLite²	113.2 s	—	KVM microVM,冷启动 OCI rootfs
OpenSandbox³	122.0 s	—	经抽象层调用 Docker 运行时
Firecracker 冷启动	759 ms	84 MiB	裸 VM 启动,无编排
gVisor (runsc)	288.6 s	—	用户态内核容器
Docker (runc)	335.3 s	4 MiB	标准容器运行时

¹ CubeSandbox:1.06 s 是本机的 fast-path N=100 数字(1056 ± 14 ms, 五次连跑,每次 100 % 成功),用 pre-warm Python ThreadPoolExecutor 的改进 bench 脚本测,避免 client 侧懒初始化污染测量。之前在同一台机器上跑的 slow-path 是 20.3 s / 77 成功 —— 那次模板的 writable layer 是 2 GiB,与默认 1 GiB 池不匹配,每个沙箱都走了一遍 mkfs.ext4 + reflink-copy;维护者在 #235 澄清后,我们把 2Gi 加进 pool_default_format_size_list 重测。机器跑的是 cube v0.2.0,这版有一个 ~50 ms 延迟回归, PR #234 在 v0.2.1 中修复 —— 上面的数字是 v0.2.0 baseline。CubeSandbox 公布单实例冷启动 <60 ms(96 vCPU 主机,N=100 并发 P99 200 ms), 我们没在此处复测那个形态。详见 bench/CUBESANDBOX.md、以及两个上游 PR #236 / #237。

² BoxLite 的设计目标是每个负载一个长生命周期、有状态的 Box, 而不是 100 个并发的全新 microVM。冷启动扇出数据放在这里仅为直接对比。详见 bench/BOXLITE.md。

³ OpenSandbox 是 Docker / K8s / gVisor / Kata / Firecracker 上层的抽象层;此处数字是它默认的 Docker 运行时。详见 bench/OPENSANDBOX.md。

复现:bench/bench-spawn-100.sh 然后 bench/generate_charts.py。

对单个沙箱执行同一个 numpy 表达式的两种方式:

调用	耗时	做了什么
`sandbox.eval("numpy.zeros(5).tolist()")`	1 ms	复用 PID 1 里已暖的 Python
`sandbox.commands.run("python3 -c '...'")`	96 ms	冷子进程重新 import numpy

工作原理

flowchart TB
    %% ─── parent ───────────────────────────────────────────────
    subgraph PARENT["父 VM(启动一次并暖启动)"]
        direction TB
        runtime["PID 1<br/>Python + numpy + 你的依赖<br/>已导入 RAM"]
    end

    PARENT -- "暂停 + 快照" --> SNAP["磁盘上的快照<br/>memory.bin(CoW 源)<br/>vmstate(vCPU + 设备)"]

    %% ─── controller ───────────────────────────────────────────
    CLIENT["客户端(CLI / Python SDK)"] -- "POST /v1/sandboxes n=100" --> CTL["forkd-controller<br/>REST · 鉴权 · 审计 · /metrics"]
    CTL -- "restore_many_with(...)" --> SNAP

    %% ─── children ─────────────────────────────────────────────
    subgraph CHILDREN["100 个子 Firecracker 进程(内核每页 CoW)"]
        direction LR
        subgraph NS1["netns forkd-child-1"]
            C1["子 VM 1<br/>mmap MAP_PRIVATE<br/>cgroup memory.max"]
        end
        subgraph NS2["netns forkd-child-2"]
            C2["子 VM 2<br/>mmap MAP_PRIVATE<br/>cgroup memory.max"]
        end
        subgraph NSN["netns forkd-child-100"]
            CN["子 VM 100<br/>mmap MAP_PRIVATE<br/>cgroup memory.max"]
        end
    end

    SNAP -. "共享文件<br/>(基本只读)" .-> C1
    SNAP -. "共享文件" .-> C2
    SNAP -. "共享文件" .-> CN

    %% ─── network ──────────────────────────────────────────────
    C1 -- "veth" --> BR["宿主机桥 forkd-br0<br/>MASQUERADE"]
    C2 -- "veth" --> BR
    CN -- "veth" --> BR
    BR --> UPLINK(("uplink → 公网"))

    %% styling
    classDef parent fill:#e8f3ec,stroke:#4c956c,color:#1f2933;
    classDef snap   fill:#fff3df,stroke:#d4a259,color:#1f2933;
    classDef ctl    fill:#e6efff,stroke:#5b7dba,color:#1f2933;
    classDef child  fill:#ffffff,stroke:#52606d,color:#1f2933;
    classDef net    fill:#f1f3f5,stroke:#8d99ae,color:#1f2933;
    class PARENT,runtime parent;
    class SNAP snap;
    class CTL,CLIENT ctl;
    class NS1,NS2,NSN,C1,C2,CN child;
    class BR,UPLINK net;

完整设计、以及当前架构留下的开放问题,见 DESIGN.md。

forkd 与其他方案对比

沙箱运行时这个领域的设计差异很大。下表把 forkd 和最常被提及的开源项目放在一起对比。引号内的数字是上游项目自己公布的数字, 除非已经在上面我们的基准图里。forkd 不会去测别的项目在它们本来就不为之设计的负载形态。

项目	隔离原语	冷启动 (N=100)	Fork 自暖快照	配额	鉴权 / TLS	协议
forkd	Firecracker + 快照 CoW	101 ms	✓	cgroup `memory.max`	bearer + rustls	Apache 2.0
CubeSandbox	RustVMM + KVM microVM	1.06 s¹	"coming soon"	<5 MiB / 实例	闭源不开放	Apache 2.0
Daytona	OCI workspace	<90 ms²	✗	每 workspace	平台 API key	AGPL-3.0
OpenSandbox	Docker / K8s + gVisor / Kata / FC	122 s	✗	取决于底层	k8s 网关	Apache 2.0
E2B	Firecracker(在 infra 中)	开源不含	✗	平台侧	云 API key	Apache 2.0
BoxLite	KVM / Hypervisor.framework + OCI	113 s	✗ 有状态 Box	KVM + seccomp	仅出站策略	Apache 2.0
Modal	闭源快照 fork	不公开	✓	✓	✓	闭源
Firecracker 裸用	只有 microVM	759 ms	手工	n/a	n/a	Apache 2.0
Docker (runc)	OCI 容器	335 s	✗	cgroups	n/a	Apache 2.0
gVisor (runsc)	用户态内核	289 s	✗	cgroups	n/a	Apache 2.0

¹ N=100 并发,本机裸金属(systemd-detect-virt: none,i7-12700, 20 vCPU,无嵌套虚拟化)。这是 fast path 的数字 —— pool_default_format_size_list 已包含模板的 writable-layer 尺寸, 每个沙箱复用预格式化的池条目,不走 mkfs.ext4 + reflink-copy。五次连跑均值 1056 ± 14 ms,每次 100 % 成功,bench 脚本会先 pre-warm Python 的 ThreadPoolExecutor,把 client 侧懒初始化排除在测量外。机器跑的是 cube v0.2.0,这版有 ~50 ms 延迟回归, PR #234 在 v0.2.1 修 —— 上面的数字是 v0.2.0 baseline。之前在同一台机器上的 slow-path 测得 20.3 s / 77 成功 —— 那是我们模板配错的结果,维护者在 #235 指出后修正。Cube 自称单实例冷启动 <60 ms(96 vCPU 主机, N=100 并发 P99 200 ms),我们没复测。注意这行是把 forkd 的 fork-from-warm 跟其他项目的 冷启动 放在一起 —— 它们是不同的工作点,不是等价原语。详见 bench/CUBESANDBOX.md,以及为上游 cmdTimeout race 提的两个 PR #236 / #237。

² Daytona 自己公布的数字,我们没测它(workspace 运行时,不属于可对比的扇出形态)。

forkd 适合什么场景。

代码解释器和 Jupyter kernel 沙箱。 每一次对话或工具调用都开一个全新 kernel;暖启动的父 VM 带着 SciPy / ML 运行时, 所以每次请求的 import numpy / import torch 直接降到零开销。这就是设计目标——Anthropic / OpenAI / Modal 的代码解释器产品全是这种负载形态。
评估测试集 harness。 几百个仓库 checkout 或测试 rollout 并行跑——SWE-bench 那种形状——又不用每个 task 付 Docker 冷启动的代价。
大规模扇出的多用户代码执行。 大量短生命周期沙箱共享同一个暖启动父 VM,每个子 VM 都是 KVM 隔离。
CI 里执行不可信代码。 git clone、pip install、 pytest 跑在真实的 Linux VM 里,而不是一个容器 namespace。
托管沙箱 SaaS 的自托管替代品。 一台 Linux + KVM,单二进制守护进程,Apache 2.0——没有按秒计费的云账单,也没有厂商锁定。

别的项目更合适什么。 CubeSandbox:更快的纯冷启动(自称 <60 ms)。Daytona:每个用户拥有一个长生命周期沙箱的 workspace 形态。OpenSandbox:用一套编排 API 适配多种隔离后端。BoxLite: 可嵌入、不需要守护进程、跨平台(macOS 走 Hypervisor.framework)。 Modal:同一种原语的闭源托管版本。

forkd 的不适用场景。 函数级快照运行时为了极致启动速度放弃了真实 Linux(单 vCPU、只有串行 I/O),它们能在 forkd 的 ~100 ms 基础上再快一个数量级——代价是跑不了真实的 Python 服务、apt install、出站 HTTPS。

企业部署 FAQ

给平台 / 采购团队的速查答案:

能直接上 Kubernetes 吗? 可以——一个 forkd-controller Pod 承载 N 个沙箱子 VM,K8s 调度器只在 Pod 创建时跑一次,跟扇出数量无关(对比 Kata / Firecracker-on-K8s 那种"每个沙箱一个 Pod"的设计)。起步 manifest 在 packaging/k8s/。节点要有 /dev/kvm + cgroup v2;托管 K8s(GKE / EKS / AKS)通常得选裸金属 SKU 或显式开嵌套虚拟化才行。

一个 Pod 能塞多少沙箱? 用 512 MiB 暖好的 Python+numpy 父 VM,大致定容:

每 vCPU 跑 ~1 个活跃 agent(算力瓶颈)
每 8 GiB Pod RAM 装 ~50 个空闲池里的 agent(进程状态瓶颈,不是内存)

N=100 实测 CoW 开销是 每个 child 0.12 MiB(详见 bench/),内存几乎从来不是扇出的天花板,真正卡住的是 vCPU 和进程数。父 VM 更重的负载(浏览器、ML 推理)更快撞顶,具体定容请用自家父 VM 实测。

现有 agent 怎么接入?

REST —— POST /v1/sandboxes n=100,跟语言无关,bearer-token 鉴权
Python SDK —— pip install forkd(from forkd import Sandbox 可替 from e2b import Sandbox)
TypeScript SDK —— npm install @deeplethe/forkd,Node.js 18+,与 Python SDK surface 对齐
LangGraph / AutoGen / CrewAI / Swarm —— 通过 SDK,无需特殊适配。完整示例见 recipes/ 下的 crewai-fanout/、autogen-branch/、openai-swarm/
MCP —— pip install forkd-mcp 提供 MCP server,可接入 Claude Desktop / Claude Code / Cursor / Cline,详见 sdk/mcp/

生产场景形态(对应仓内 recipe):

AI 代码解释器 —— 一个暖好的父 VM(SciPy / torch 已 import),每个对话回合 fork 一个 child。Recipe:e2b-codeinterpreter/
SWE-bench 风格并行评测 —— N 个并行 repo checkout,每个 child 独立跑 pytest。Recipe:coding-agent/
多用户代码执行规模化 —— 共享暖父 VM,每个用户的 child 由 KVM 隔离
CI 跑不可信代码 —— git clone + pip install + pytest 在真 Linux VM 里跑,不是容器 namespace
每测试隔离数据库 —— Recipe:postgres-fixture/ —— 每个 child ~10 ms 拿到 ready-to-query postgres,跳过 ~2 s 的 fresh initdb

快速开始

要求:x86_64 Linux,带 KVM,Ubuntu 22.04 或更新。两步跑出一个真 fork:主机准备(一次性),然后 forkd pull + fork(~30 秒)。下面再后面的章节是不在 Hub 上的自定义 recipe 的备选路径。

一. 确认主机环境就绪

# 1. CLI + 守护进程二进制(预编译 tarball,不需要 Rust 工具链):
curl -sSL https://github.com/deeplethe/forkd/releases/download/v0.3.4/forkd-v0.3.4-x86_64-linux.tar.gz \
  | sudo tar -xz -C /usr/local/bin/

# 2. 主机初始化:
sudo bash scripts/setup-host.sh           # KVM + tap 设备,一次性
sudo bash scripts/netns-setup.sh 3        # 每子 VM 的网络 namespace

# 3. 一键自检:
forkd doctor                              # 检查上面这些是否到位

# 4. (可选)给程序用的语言客户端:
pip install forkd                         # Python SDK —— 通过 HTTP 调守护进程
npm install @deeplethe/forkd              # TypeScript SDK

forkd doctor 跑 16 项检查(KVM、硬件虚拟化、cgroup v2、IP 转发、 tap、netns、Firecracker 二进制 + 版本、Docker daemon、快照目录 + 磁盘空间、内核镜像、controller 可达性、平台,以及 v0.4 live-fork 所需的 uffd_wp 和 memfd_create),每一项不通过都附带具体修复提示。任何东西觉得不对就先跑它。

forkd doctor —— 配置好的宿主机 14 项全过

二. 第一次 fork(推荐)

# 14.5 MiB 的预热快照(Python 3.12 + LangGraph) → ~15 秒下载,自动 sha256 校验。
forkd pull deeplethe/langgraph-react

# 3 个共享父 VM 内存的子 VM,每个 ~10 ms。
sudo -E forkd fork --tag langgraph -n 3 --per-child-netns

参见 docs/HUB.md 了解 registry 模型 + 如何发布自己的 snapshot pack。

三. 备选:从 Docker 镜像构建

forkd from-image 把 Docker pull → ext4 → 启动 + 暖启动 → pause → 注册 tag 串成一条命令。Hub 里还没有的 recipe 用这个:

sudo -E forkd from-image python:3.12-slim \
    --tag py-numpy \
    --extra python3-numpy
# 第一次 2-3 分钟(Docker pull + ext4 + warmup),之后走缓存。

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

四. 探测你装的 forkd 实际有多快

forkd bench --tag py-numpy --n 5
# forkd bench against snapshot py-numpy
#   spawn (n=1)              61 ms
#   exec round-trip          22 ms
#   branch (diff=true)      287 ms  pause_ms=234 ...
#   fanout (n=5)             65 ms  13ms/child
#   cleanup                 136 ms
#                           -----
#   total                   571 ms

screenshot 友好,跑一遍能知道 v0.3 在你机器上是不是真有那个速度。

五. 备选:从源码构建你自己的暖启动父 VM(进阶)

# 1. 主机准备:KVM、Firecracker、Rust、KSM、大页、tap 设备。
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. 从一个 Docker 镜像构建暖启动 rootfs。
sudo bash scripts/build-rootfs.sh python:3.12-slim python-rootfs.ext4 1536 python3-numpy

# 3. 拉一个内核。
curl -O https://s3.amazonaws.com/spec.ccfc.min/firecracker-ci/v1.10/x86_64/vmlinux-6.1.141

# 4. 跑一个一次性沙箱。
sudo -E forkd run --image python:3.12-slim --kernel ./vmlinux-6.1.141 \
    -- python3 -c "import numpy; print(numpy.zeros(5).sum())"
# 0.0

多子 VM 扇出

# 一次性给 N 个子 VM 准备好网络 namespace。
sudo bash scripts/netns-setup.sh 100

# 创建一个带 tag 的父快照。
sudo forkd snapshot --tag pyagent \
    --kernel ./vmlinux-6.1.141 \
    --rootfs ./python-rootfs.ext4 \
    --tap forkd-tap0

# Fork 100 个共享父 VM 内存的子 VM。
sudo -E forkd fork --tag pyagent -n 100 --per-child-netns --memory-limit-mib 256

# 和其中一个子 VM 通信。
sudo forkd eval --child forkd-child-42 -- "numpy.zeros(100).sum()"

Python SDK

from forkd import Sandbox   # 可直接替换 `from e2b import Sandbox`

with Sandbox() as sb:
    print(sb.commands.run("uname -a").stdout)
    print(sb.eval("numpy.zeros(5).tolist()"))    # 复用暖启动的 PID 1

TypeScript SDK

给 Node.js 18+ 的 agent 用(LangChain.js、agent-twins、任何 JS 侧的工具):

npm install @deeplethe/forkd

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

const ctrl = new Controller();   // 从 env 读 FORKD_URL、FORKD_TOKEN
const [parent] = await ctrl.spawnSandboxes({
  snapshotTag: 'pyagent', n: 1, perChildNetns: true,
  liveFork: true,             // v0.4:打开后,后续 BRANCH 可以用 mode: 'live'
});

// ... 驱动 parent ...
// `mode: 'live'` + `wait: false` 让源 VM 卡顿 sub-50 ms,~10 ms 返回。
// 背景内存拷贝异步完成,完成后快照 status 从 "writing" 变 "ready"。
const branch = await ctrl.branchSandbox(parent.id, { mode: 'live', wait: false });
const kids = await ctrl.spawnSandboxes({ snapshotTag: branch.tag, n: 5, perChildNetns: true });

Surface 与 Python SDK 对齐:spawnSandboxes / branchSandbox 都接受 prewarm / liveFork / mode / wait / measure_diff。详见 sdk/typescript/。

MCP server

用 Claude Desktop / Claude Code / Cursor 等任意 MCP 客户端接入:

pip install forkd-mcp
# 然后在 claude_desktop_config.json 里加:
#   "mcpServers": { "forkd": { "command": "forkd-mcp" } }

Server 暴露 spawn_sandboxes、exec_command、eval_code 等 8 个工具,agent 可以直接驱动 forkd 微 VM。详见 sdk/mcp/README.md。

Framework 集成 recipe(宿主机侧,不需要 rootfs 构建)

四个最常被问到的 agent framework 的接入示例。每个 ~150-250 行 Python, 带 --dry-run 跑 forkd 链路不需要 LLM key:

Recipe	驱动	forkd 特有动作
`mcp-agent/`	Claude Desktop / Cursor / Cline (MCP)	端到端验证 MCP 协议链路
`crewai-fanout/`	CrewAI	N 个 agent 跑在 N 个 microVM 上(同一父快照)——每个 agent 真正隔离,~24ms/child 启动
`autogen-branch/`	AutoGen	forkd-backed `CodeExecutor` + 对话进行中 BRANCH 出 N 条平行延续
`openai-swarm/`	OpenAI Swarm / Agents SDK	handoff = BRANCH:agent B 继承 agent A 的完整 VM 状态(文件系统、import、env)

预构建 rootfs recipe

不想自己设计 rootfs?直接从 recipes/ 选一个, 跑它的 build.sh:

Recipe	适合什么
`python-numpy/`	复现基准测试;最轻量的 Python + numpy
`e2b-codeinterpreter/`	AI 代码解释器 agent(E2B SDK 兼容)
`jupyter-kernel/`	预导入 notebook / SciPy 栈;每个 kernel ~1 ms
`coding-agent/`	SWE-bench / 编码 agent,带 `git` + 开发工具
`nodejs/`	JS / TS 负载,Playwright 扇出
`playwright-browser/`	驱动浏览器的 agent(computer-use / 网页研究 / UI 测试生成),fork 出已暖好的 Chromium ≈10 ms
`agent-workbench/`	全家桶——浏览器 + VSCode + Jupyter + MCP
`postgres-fixture/`	fork-per-test 隔离数据库,每个 child ~10 ms 拿到 ready-to-query postgres,跳过 ~2 s fresh initdb

守护进程模式部署

Controller 守护进程持有快照和活跃沙箱的注册表,对外暴露 REST API, 并写结构化审计日志。除了本地开发,推荐都用这种模式部署。

sudo install -m 0644 packaging/systemd/forkd-controller.service /etc/systemd/system/
sudo mkdir -p /etc/forkd
sudo bash -c 'head -c 32 /dev/urandom | base64 > /etc/forkd/token'
sudo chmod 600 /etc/forkd/token
sudo systemctl enable --now forkd-controller

然后用 HTTP 驱动它:

TOKEN=$(sudo cat /etc/forkd/token)
curl -H "Authorization: Bearer $TOKEN" -X POST http://127.0.0.1:8889/v1/sandboxes \
     -H 'Content-Type: application/json' \
     -d '{"snapshot_tag":"pyagent","n":5,"per_child_netns":true,"memory_limit_mib":256}'
# [{"id":"sb-67a1b3-0000","pid":...,...}, ...]

curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8889/metrics
# forkd_sandboxes_active 5

完整 API 参考:docs/API.md。运维手册:docs/RUNBOOK.md。安全姿态:docs/SECURITY.md。

仓库结构

crates/
  forkd-vmm/            Firecracker 封装:BootConfig、Vm、Snapshot、cgroup
  forkd-cli/            `forkd` 二进制(snapshot、fork、run、exec、eval)
  forkd-controller/     `forkd-controller` 守护进程:REST、注册表、审计
rootfs-init/
  forkd-init.sh         guest 内的 PID 1;挂载伪文件系统,启动 agent
  forkd-agent.py        guest 内 :8888 上的 TCP server(ping/exec/eval)
sdk/python/             E2B 兼容的 Python SDK
sdk/typescript/         `@deeplethe/forkd` —— TypeScript / Node.js SDK
sdk/mcp/                MCP server(`forkd-mcp`)—— 从 Claude
                        Desktop / Claude Code / 任何 MCP 客户端驱动 forkd
scripts/                宿主机侧的辅助脚本(KVM、Firecracker、netns、rootfs)
packaging/systemd/      Controller 的 systemd unit
packaging/k8s/          forkd-controller 的 Kubernetes starter manifest
recipes/                Framework 集成 recipe(mcp-agent、crewai-fanout、
                        autogen-branch、openai-swarm)+ 预构建 rootfs
                        recipe(python-numpy、e2b-codeinterpreter、
                        jupyter-kernel、coding-agent、nodejs、
                        playwright-browser、agent-workbench、
                        postgres-fixture)。详见 recipes/README.md。
bench/                  基准测试 harness、图表生成器、结果
docs/                   API.md、SECURITY.md、RUNBOOK.md

状态

Alpha。fork-on-write 原语、controller 守护进程、REST API、鉴权、审计日志、cgroup 内存限制、Prometheus metrics、 Python + TypeScript SDK 都已就绪,并由 CI 里的 25 个单元 + 集成测试覆盖。1.0 之前,磁盘格式和 API 形态可能还会有变化。

本版本暂未达到生产可用的项:

多节点调度(目前一个守护进程 = 一台主机)。
子 VM netns 的默认拒绝出站(目前是共享 MASQUERADE 规则; 想要 allow-list 策略的用户需要自己给每个 netns 加 iptables 规则)。
memory.max 之外的 cpu.max、io.max、pids.max 配额。
第三方安全审计。

Roadmap 和正在追踪的工作都在 GitHub issues。版本变更记录:CHANGELOG.md。安全策略与历史漏洞通告:docs/SECURITY.md。

v0.3 phase 1 已 ship (v0.3.0 → v0.3.4) —— diff-snapshot BRANCH 把源 VM 暂停时间从 29.3 秒砍到 205 毫秒（143x）(4 GiB SSD 源, 空闲); 典型 agent 工作负载(30-300 MiB 脏页)6-15x。v0.3.1 支持同一 sandbox 上多次 diff BRANCH —— 5 次连续 diff BRANCH 聚合下来 14x 总暂停时间减少。v0.3.2 把 Python SDK 的 spawn_sandboxes(prewarm=...) 和 branch_sandbox(diff=..., measure_diff=...) 补齐,跟 REST 和 TypeScript SDK 对齐。v0.3.4 通过 posix_fallocate 绕过 ext4 mballoc/wbt_wait,关掉了多 BRANCH 暂停异常 (#146)—— 第 6 次连续 BRANCH 从 2.7 秒砍到 153 毫秒,BRANCH 3-10 中位数加速 8.5x。完整表格和诚实 caveat 见 bench/pause-window/RESULTS-v0.3.md; 75 个 trial 的 sweep 原始数据在 bench/pause-window/*-sweep-*.csv。通过 POST /v1/sandboxes/:id/branch 请求体加 "diff": true 开启, 或用 forkd snapshot --from-sandbox --diff 的 CLI flag。

胜的是源 VM 的停机时间,不是 BRANCH API 的总延迟:source 的 memory.bin cp 在后台和 source 并行跑,然后 diff 窗口关闭、 source 恢复、diff 合到事先 cp 出来的输出上。源 VM 的 TCP 连接、 kvmclock、定时器只看到 ~200ms 的 gap 而不是 29 秒。BRANCH API 本身的总时间还是被 cp 带宽限制——这个 trade-off 对"长跑 agent 的 live BRANCH"是甜区。

v0.3.1 的多 BRANCH 用上一次 BRANCH 的输出当 chain head—— 没有 separate shadow file,零额外存储。用户 DELETE 中间快照时, chain 检测到文件缺失自动 fall back 到 source-tag (带 warning)。完整设计: docs/design/diff-snapshots.md。

v0.4 live BRANCH 已经把用户接口全部接通(REST mode: "live"、 CLI --live、Python / TypeScript / MCP SDK;PR #204–#207)。机制:spawn 时带 live_fork: true,guest RAM 用 memfd 后端(被 Firecracker 和 controller 共享),BRANCH 时用 UFFD_WP 异步抓脏页, 源 VM 在 vCPU 状态 dump 完立刻恢复(sub-50 ms),内存拷贝异步完成。原本想留在 vanilla FC,但 mem_backend.backend_type: "Shared" 配 shared: true(mmap MAP_SHARED)是绕不开的 upstream gap,因此 fork 了: deeplethe/firecracker:forkd-v0.4-mem-backend-shared-v1.12。我们已经向 upstream 提了 FIRECRACKER-UPSTREAM-PROPOSAL.md, 合并后 vendor 要求即可去掉。跟踪: issue #101。在干净父快照上的 bench 数字(bench/live-fork-pause-window.md) 正在跑——Phase 6 E2E 早期数据是 pause_ms = 41-48 ms,但那个 parent 带着 17 个已经 baked-in 的 guest Oopses,会污染测量。

0.1.4 包含 daemon 侧安全修复。POST /v1/sandboxes 的 snapshot_tag 校验缺失(任意路径 → 控制 grandchild VM volumes)和 K8s manifest 接受字面占位符 bearer token —— 两个 HIGH 影响 0.1.0–0.1.3,请升级。完整公告见 docs/SECURITY.md#past-advisories。 0.1.3 此前还修复了 CLI --tag path-traversal(影响 0.1.0–0.1.2)。

贡献

欢迎 Pull Request。开 PR 之前请:

先开 issue 描述你想改什么。API 还在动,我们更愿意提前对齐而不是让你重写补丁。
本地跑过 cargo fmt --all && cargo clippy --all-targets -- -D warnings && cargo test --all。
提交带 sign-off(git commit -s)。

Star 历史

License

Apache 2.0。详见 LICENSE 与 NOTICE。