forkd Python SDK完全指南：2行代码替代E2B Sandbox，让AI代码跑在KVM隔离的microVM里
【免费下载链接】forkdFork() for AI agent microVMs. Spawn 100 children in ~100ms from a warm parent; BRANCH a live VM in ~150ms. KVM-isolated, snapshot CoW.项目地址: https://gitcode.com/gh_mirrors/fo/forkd
forkd是一个面向 AI Agent 的开源 microVM 沙箱运行时，基于 Firecracker + KVM 硬件隔离，核心原语是「fork 热快照」——父 VM 启动预热一次后，子 VM 通过内核 Copy-on-Write 继承其内存，100 个子沙箱约101 ms拉起、150 ms 内完成一个运行中 VM 的 BRANCH。它自带的Python SDK（pip install forkd）与 E2B 线协议兼容：把from e2b import Sandbox换成from forkd import Sandbox，你的 AI 代码就能跑在自托管、无按秒计费的 KVM 隔离 microVM 里。
本文将带你完成 forkd Python SDK 的安装、两套核心 API（Sandbox与Controller）的用法、性能数据解读与常见问题解答，全程只需几行代码。
为什么是 forkd：E2B 的自托管平替
如果你在用 E2B，大概熟悉这套体验：云端 SaaS、按秒计费、厂商锁定、冷启动受平台调度影响。forkd 把同样的能力搬到你自己的 Linux 机器上：
| 维度 | E2B（云托管） | forkd（自托管） |
|---|---|---|
| 部署形态 | 云端 SaaS | 单二进制守护进程，pip install forkd即接入 |
| 隔离级别 | microVM | KVM microVM，每子沙箱独立 Firecracker 进程 |
| 每沙箱网络/内存配额 | 平台管理 | 独立 netns + cgroup v2memory.max |
| 100 沙箱冷启动 | 云端调度 | 101 ms（fork 热父快照） |
| 许可证/成本 | API 计费 | Apache 2.0，免费 |
关键差异在「fork 热快照」：父 VM 预热后（import numpy、JIT 编译、模型权重全部驻留内存），每个子 VM 不再冷启动自己的内核，而是mmap(MAP_PRIVATE)共享父 VM 的内存映像，直到页面被修改才分叉。这带来两个同时成立的好处——每个子沙箱都是独立 KVM VM，同时启动成本接近fork(2)而非冷启动 VM。
📌 架构全貌见 DESIGN.md，分支模型见 docs/design/branching.md。
快速安装：3 步跑通环境
forkd Python SDK 是纯 Python 客户端，本身没有依赖；真正干活的是宿主上的forkdCLI +forkd-controller守护进程。环境要求：x86_64 Linux、内核 ≥ 5.7（live 分支需要 KVM）。
第 1 步：安装 CLI 并准备宿主
# 预编译二进制，无需 Rust 工具链 curl -sSL <releases>/forkd-v0.5.3-x86_64-linux.tar.gz | sudo tar -xz -C /usr/local/bin/ sudo bash scripts/setup-host.sh # KVM + tap 设备，一次性 sudo bash scripts/netns-setup.sh 100 # 每子沙箱网络命名空间宿主脚本位于 scripts/setup-host.sh 和 scripts/netns-setup.sh。
第 2 步：准备一个父快照
forkd pull deeplethe/langgraph-react # 从 Hub 拉现成快照，~15 s # 或从 Docker 镜像自建： sudo -E forkd from-image python:3.12-slim --tag py-numpy --extra python3-numpy第 3 步：安装 Python SDK
pip install forkd一键自检：forkd doctor
装完务必先跑forkd doctor，它会做 17 项检查（KVM、cgroup v2、tap、netns、Firecracker 版本、快照目录、daemon 可达性……），每项不通过都给出具体修复提示：
forkd doctor # pass=14 warn=0 fail=0 skip=02 行代码上手：E2B 兼容的 Sandbox
SDK 里最重要的类是Sandbox（sdk/python/forkd/sandbox.py），API 表面与 E2B 对齐——创建沙箱、跑命令、退出：
from forkd import Sandbox # drop-in replacement for `from e2b import Sandbox` with Sandbox() as sb: print(sb.commands.run("uname -a").stdout) print(sb.eval("numpy.zeros(5).tolist()"))就这么多。Sandbox()构造时会自动 fork 一个子 microVM 并等待内部 agent 就绪（典型 ~150 ms）；with块退出时自动回收。commands.run()返回CommandResult（stdout/stderr/exit_code），与 E2B 用法一致。
常用环境变量（见 sdk/python/forkd/sandbox.py）：
| 环境变量 | 默认值 | 作用 |
|---|---|---|
FORKD_TAG | pyagent | 指定 fork 的父快照 tag |
FORKD_TARGET | 10.42.0.2:8888 | 子沙箱内 guest agent 地址 |
完整可运行示例见 sdk/python/example.py。
隐藏大招：eval 直接复用预热态，快 100 倍
forkd 相比 E2B 的「杀手锏」是sb.eval()：它把表达式送进子 VM 里已经预热好的 PID 1 Python 解释器执行，而不是新起python3子进程重新import。实测同一台机器、同一条 numpy 表达式：
| 调用方式 | 耗时 | 说明 |
|---|---|---|
sandbox.eval("numpy.zeros(5).tolist()") | 1 ms | 复用预热态 PID 1，零 import |
sandbox.commands.run("python3 -c '...'") | 96 ms | 冷子进程，重新 import numpy |
对 AI 代码解释器场景意义重大：用户每问一句话都要import numpy / pandas / torch？在 forkd 里这些成本被父快照直接「继承」，接近为零。
Controller 进阶：spawn、BRANCH、kill 一套 REST API
Sandbox负责「钻进单个 VM 里执行代码」；Controller（sdk/python/forkd/controller.py）负责宿主侧的生命周期编排——建沙箱、分支、回收，全部走守护进程的 REST API：
from forkd import Controller c = Controller() # 读 FORKD_URL / FORKD_TOKEN，默认 http://127.0.0.1:8889 parent = c.spawn_sandboxes("pyagent", n=1, per_child_netns=True, live_fork=True)[0] # Agent 跑到一半，随时打分支（UFFD_WP 实时脏页捕获） branch = c.branch_sandbox(parent["id"], tag="checkpoint-1", mode="live", wait=False) # 从分支扇出 5 个孙沙箱做投机执行 kids = c.spawn_sandbox(branch["tag"], n=5)branch_sandbox提供三种模式，对应不同的「源沙箱暂停窗口」：
| mode | 暂停窗口 | 适用 |
|---|---|---|
"full"（默认） | 0.5–8 s | 通用，任何父快照 |
"diff" | ~200 ms | 增量快照，v0.3+ |
"live" | < 50 ms | 长驻 Agent 中途中断，v0.4+，需live_fork=True启动 |
wait=False时调用方约 10 ms 即返回（源 VM 已恢复运行），后台内存拷贝异步完成——Agent 代码「想到一半分叉」几乎无感。完整 REST 端点参考 docs/API.md。
上图是官方 recipes/langgraph-react/ 实测：LangGraph ReAct Agent 跑到一半被 BRANCH，三个孙沙箱各自收到不同引导提示、独立产出不同行程，却继承完全相同的推理历史。
性能实测：100 个 microVM 只要 101 ms
在同一台 Ubuntu 24.04 / 20 vCPU / KVM 宿主机上，「拉起 100 个沙箱并跑通import numpy」的墙钟时间对比（完整方法学见 bench/）：
内存同样划算：100 个子沙箱合计只多出0.12 MiB/个的宿主内存（CoW 共享父页），而 Firecracker 冷启动每 VM 要 84 MiB：
| 后端 | N=100 墙钟 | 每沙箱内存增量 |
|---|---|---|
| forkd | 101 ms | 0.12 MiB |
| CubeSandbox | 1.06 s | 5 MiB |
| Firecracker 冷启动 | 759 ms | 84 MiB |
| Docker (runc) | 335.3 s | 4 MiB |
| gVisor (runsc) | 288.6 s | — |
真实场景：官方 Recipes 直接抄
每个 recipe 都是完整可跑的父快照配方 + 演示脚本，按需取用：
| Recipe | 场景 |
|---|---|
| recipes/e2b-codeinterpreter/ | AI 代码解释器，Jupyter + SciPy 全家桶预热，E2B 模板平替 |
| recipes/langgraph-react/ | LangGraph Agent 中途 BRANCH + 扇出 |
| recipes/crewai-fanout/ | CrewAI：N 个 Agent 跑 N 个 microVM，~24 ms/子 |
| recipes/postgres-fixture/ | Fork-per-test：~10 ms 拿到可查询的 postgres，替代 ~2 s 的 initdb |
| recipes/playwright-browser/ | 预热 Chromium，~10 ms fork 一个浏览器沙箱 |
更多清单见 recipes/README.md。
常见问题（FAQ）
Q：必须连本机吗？能连远程守护进程吗？能。Controller读FORKD_URL和FORKD_TOKEN环境变量，指向任何一台装了 forkd-controller 的机器即可；生产部署方式（systemd + token）见 docs/RUNBOOK.md 与 packaging/systemd/forkd-controller.service。
Q：我的 E2B 代码要改多少？通常只改 import。Sandbox/commands.run/ 结果对象都与 E2B 对齐；尚未覆盖files.read/write与流式输出（见 sdk/python/README.md 的能力清单）。
Q：快照不跨版本/跨 CPU 迁移怎么办？快照不跨 Firecracker 版本和宿主 CPU 微架构迁移；forkd doctor会同时报告 FC 版本与 guest 内核，方便集群内一致性断言。
Q：项目成熟度？当前为 Alpha：核心原语、REST、鉴权、审计日志、cgroup 限额、Prometheus 指标与双 SDK 均已就绪并有 25 个单元/集成测试；磁盘格式与 API 在 1.0 前可能变动，版本轨迹见 CHANGELOG.md。
小结
forkd Python SDK 给了 AI 开发者一个干净的取舍：保留 E2B 的写码习惯，换回 KVM 硬件隔离 + 101 ms 百沙箱扇出 + 自托管零费用。三步走：
forkd doctor全绿后pip install forkd；- 用
Sandbox两行代码跑通第一个 microVM； - 用
Controller.spawn_sandboxes / branch_sandbox编排扇出与分支。
延伸资料：REST 全量 API 见 docs/API.md，运行手册 docs/RUNBOOK.md，安全模型 docs/SECURITY.md，live 分支设计 DESIGN-v0.4.md。
【免费下载链接】forkdFork() for AI agent microVMs. Spawn 100 children in ~100ms from a warm parent; BRANCH a live VM in ~150ms. KVM-isolated, snapshot CoW.项目地址: https://gitcode.com/gh_mirrors/fo/forkd
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
