forkd TypeScript SDK与MCP服务器教程让Node.js Agent和Claude/Cursor直接驱动microVM【免费下载链接】forkd高性能Agent沙箱预热虚拟机可以在约 100 毫秒内派生出 100 个独立实例运行过程中约 150 毫秒“分叉”出一个新的运行环境。底层使用 KVM 隔离并利用快照写时复制降低资源开销。项目地址: https://gitcode.com/deeplethe/forkdforkd是一款面向 AI Agent 的高性能 microVM 沙箱运行时预热虚拟机可在约 100 毫秒内派生出 100 个独立实例运行中约 150 毫秒分叉出一个继承完整状态的新沙箱。本文带你快速上手它的TypeScript SDKdeeplethe/forkd和MCP 服务器forkd-mcp让你的 Node.js Agent 或 Claude/Cursor 直接指挥一批隔离的 microVM 执行代码、分叉、并行探索。一、准备工作先让 forkd 守护进程跑起来 ️SDK 和 MCP 服务器都是薄客户端真正的 VM 分叉由forkd-controller守护进程完成默认监听http://127.0.0.1:8889。确认环境是否就绪sudo bash scripts/setup-host.sh # 一次性主机配置 forkd doctor # 自检全部通过即可开工forkd doctor会检查 KVM、userfaultfd、内核版本等 14 项前置条件 如果你还没有父快照snapshot可以用现成配方构建例如 Node.js 父镜像recipes/nodejs/README.mdrootfs 仅约 250 MB适合 JS/TS 负载。二、安装 TypeScript SDK一条 npm 命令搞定 要求 Node 18使用全局fetchnpm install deeplethe/forkd # 或 pnpm add deeplethe/forkdSDK 核心就两个类见 sdk/typescript/src/index.ts类定位Controller对 forkd-controller REST API 的完整封装快照、派生、分叉、执行命令Sandbox单个沙箱的高级封装接口风格对齐 E2B/Daytona方便迁移现有 Agent 代码配置文件见 sdk/typescript/src/controller.ts它会自动读取环境变量FORKD_URL和FORKD_TOKEN大多数场景零配置即可连接本守护进程。三、3 行代码派生 microVM、执行命令、自动清理 ⚡最短路径是Sandbox.with()——派生、执行、无论成败都自动清理import { Sandbox } from deeplethe/forkd; const result await Sandbox.with( { snapshotTag: python-3-12-slim }, async (sb) sb.exec([python3, -c, print(22)]), ); console.log(result.stdout); // 4\n几个常用方法源码sdk/typescript/src/sandbox.tssb.exec(args)— 在沙箱里跑子进程返回{ stdout, stderr, exitCode }sb.eval(code)— 在已预热的 PID-1 Python 进程里求值表达式返回单位数毫秒新子进程冷启要约 100 mssb.branch({ diff: true })— 把运行中的沙箱分叉成新快照标签sb.kill()— 幂等终止批量派生则用Controller.spawnSandboxes({ snapshotTag, n: 20 })一次分叉出 N 个隔离的 microVM 子实例。四、杀手锏 BRANCH运行中分叉再扇出多个子 Agent forkd 最有价值的能力是BRANCH——暂停运行中的沙箱、快照其内存与 vCPU 状态、立即恢复子代以**写时复制copy-on-write**继承源状态。这对投机并行的 Agent 至关重要主 Agent 跑到一半把当前状态分叉成 4 个子 Agent 各走一条路。import { Controller } from deeplethe/forkd; const ctrl new Controller({ token: process.env.FORKD_TOKEN }); const [source] await ctrl.spawnSandboxes({ snapshotTag: langgraph-react }); await ctrl.execCommand(source.id, [python3, /opt/agent.py]); // 预热 // BRANCH暂停源沙箱→快照→恢复得到可复用的新标签 const checkpoint await ctrl.branchSandbox(source.id, { tag: after-warmup, diff: true }); // 从检查点扇出 4 个子沙箱全部继承预热后的精确状态 const children await ctrl.spawnSandboxes({ snapshotTag: checkpoint.tag, n: 4 });性能实测详见 sdk/typescript/README.md 与 bench/chart-spawn-100.pngdiff: true模式4 GiB SSD 源沙箱的暂停窗口从 29 秒降到205 ms143× 提速v0.4mode: live暂停窗口进一步压到56 ms p50配合wait: false约 10 ms 即可返回错误处理也很直接捕获ControllerError用status区分 404沙箱不存在、409标签冲突等import { ControllerError } from deeplethe/forkd; try { await ctrl.getSandbox(sb-missing); } catch (e) { if (e instanceof ControllerError e.status 404) { /* 沙箱不存在 */ } }五、MCP 服务器让 Claude 和 Cursor 直接指挥沙箱 forkd-mcp把 forkd 的能力封装成 MCP 工具任何支持 MCP 的客户端Claude Desktop、Claude Code、Cursor、Cline注册后Agent 就能自己决定何时建沙箱、何时分叉、执行什么命令。安装需守护进程已在运行pip install forkd-mcp11 个工具一览MCP 工具能力list_snapshots/create_snapshot查看/构建父模板spawn_sandboxes从模板分叉 N 个 microVM 子沙箱branch_sandbox⭐ 运行中分叉出新快照支持diff/live模式exec_command/eval_code在沙箱内执行命令 / 求值 Pythonwait_for_text轮询沙箱内文件直到出现标记串触发分叉时机的利器list_sandboxes/get_sandbox/ping_sandbox/kill_sandbox沙箱生命周期管理实现源码在 sdk/mcp/forkd_mcp/server.py每个工具 1:1 映射到 controller REST 端点见 docs/API.md。注册到 Claude Desktop / Cursor在claude_desktop_config.json或~/.cursor/mcp.json中加入{ mcpServers: { forkd: { command: forkd-mcp, env: { FORKD_URL: http://127.0.0.1:8889, FORKD_TOKEN: contents-of-/etc/forkd/token } } } }Claude Code 用户也可以一行注册claude mcp add forkd --env FORKD_URLhttp://127.0.0.1:8889 \ --env FORKD_TOKEN$(sudo cat /etc/forkd/token) -- forkd-mcp重启客户端后工具即出现在 MCP 列表中。Cline 用户可把只读工具list_snapshots、ping_sandbox等加入autoApprove免去逐次确认完整配置见 sdk/mcp/README.md。典型玩法Agent 自己管理沙箱生命周期注册后你只需对 Claude 说一句起一个 Python 沙箱跑完这个脚本把状态 branch 成检查点然后扇出 3 个子沙箱分别尝试三种修复方案告诉我哪个通过测试。Agent 会自行编排spawn_sandboxes→exec_command→wait_for_text→branch_sandbox→ 再次spawn_sandboxes全程无需你写胶水代码。六、常见问题速答 ❓问题解答连不上守护进程确认sudo systemctl start forkd-controller并核对FORKD_URL/FORKD_TOKENdiff: true返回 400需要forkd-controller 0.3.0旧版本请升级要网络隔离吗派生时传perChildNetns: true先跑scripts/netns-setup.sh NTypeScript 之外有其他语言Python SDKsdk/python/pip install forkdAPI 与 TS 完全对等更多端到端示例浏览 recipes/ 目录含 Node.js、Playwright、CI 并行测试等配方总结用deeplethe/forkdTypeScript SDK你可以在 Node.js 里几行代码派生、分叉、执行 microVM 沙箱用forkd-mcpClaude/Cursor 这样的 AI 编程助手则可以直接把 forkd 当成代码执行后端自主调度。两者都构建在同一套 REST API 之上docs/API.md从原型到生产无缝切换。关键资料导航TypeScript SDK 文档sdk/typescript/README.mdMCP 服务器文档sdk/mcp/README.mdREST API 参考docs/API.mdNode.js 父镜像配方recipes/nodejs/README.md运行手册守护进程模式docs/RUNBOOK.md安全模型说明docs/SECURITY.md【免费下载链接】forkd高性能Agent沙箱预热虚拟机可以在约 100 毫秒内派生出 100 个独立实例运行过程中约 150 毫秒“分叉”出一个新的运行环境。底层使用 KVM 隔离并利用快照写时复制降低资源开销。项目地址: https://gitcode.com/deeplethe/forkd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
forkd TypeScript SDK与MCP服务器教程：让Node.js Agent和Claude/Cursor直接驱动microVM
forkd TypeScript SDK与MCP服务器教程让Node.js Agent和Claude/Cursor直接驱动microVM【免费下载链接】forkd高性能Agent沙箱预热虚拟机可以在约 100 毫秒内派生出 100 个独立实例运行过程中约 150 毫秒“分叉”出一个新的运行环境。底层使用 KVM 隔离并利用快照写时复制降低资源开销。项目地址: https://gitcode.com/deeplethe/forkdforkd是一款面向 AI Agent 的高性能 microVM 沙箱运行时预热虚拟机可在约 100 毫秒内派生出 100 个独立实例运行中约 150 毫秒分叉出一个继承完整状态的新沙箱。本文带你快速上手它的TypeScript SDKdeeplethe/forkd和MCP 服务器forkd-mcp让你的 Node.js Agent 或 Claude/Cursor 直接指挥一批隔离的 microVM 执行代码、分叉、并行探索。一、准备工作先让 forkd 守护进程跑起来 ️SDK 和 MCP 服务器都是薄客户端真正的 VM 分叉由forkd-controller守护进程完成默认监听http://127.0.0.1:8889。确认环境是否就绪sudo bash scripts/setup-host.sh # 一次性主机配置 forkd doctor # 自检全部通过即可开工forkd doctor会检查 KVM、userfaultfd、内核版本等 14 项前置条件 如果你还没有父快照snapshot可以用现成配方构建例如 Node.js 父镜像recipes/nodejs/README.mdrootfs 仅约 250 MB适合 JS/TS 负载。二、安装 TypeScript SDK一条 npm 命令搞定 要求 Node 18使用全局fetchnpm install deeplethe/forkd # 或 pnpm add deeplethe/forkdSDK 核心就两个类见 sdk/typescript/src/index.ts类定位Controller对 forkd-controller REST API 的完整封装快照、派生、分叉、执行命令Sandbox单个沙箱的高级封装接口风格对齐 E2B/Daytona方便迁移现有 Agent 代码配置文件见 sdk/typescript/src/controller.ts它会自动读取环境变量FORKD_URL和FORKD_TOKEN大多数场景零配置即可连接本守护进程。三、3 行代码派生 microVM、执行命令、自动清理 ⚡最短路径是Sandbox.with()——派生、执行、无论成败都自动清理import { Sandbox } from deeplethe/forkd; const result await Sandbox.with( { snapshotTag: python-3-12-slim }, async (sb) sb.exec([python3, -c, print(22)]), ); console.log(result.stdout); // 4\n几个常用方法源码sdk/typescript/src/sandbox.tssb.exec(args)— 在沙箱里跑子进程返回{ stdout, stderr, exitCode }sb.eval(code)— 在已预热的 PID-1 Python 进程里求值表达式返回单位数毫秒新子进程冷启要约 100 mssb.branch({ diff: true })— 把运行中的沙箱分叉成新快照标签sb.kill()— 幂等终止批量派生则用Controller.spawnSandboxes({ snapshotTag, n: 20 })一次分叉出 N 个隔离的 microVM 子实例。四、杀手锏 BRANCH运行中分叉再扇出多个子 Agent forkd 最有价值的能力是BRANCH——暂停运行中的沙箱、快照其内存与 vCPU 状态、立即恢复子代以**写时复制copy-on-write**继承源状态。这对投机并行的 Agent 至关重要主 Agent 跑到一半把当前状态分叉成 4 个子 Agent 各走一条路。import { Controller } from deeplethe/forkd; const ctrl new Controller({ token: process.env.FORKD_TOKEN }); const [source] await ctrl.spawnSandboxes({ snapshotTag: langgraph-react }); await ctrl.execCommand(source.id, [python3, /opt/agent.py]); // 预热 // BRANCH暂停源沙箱→快照→恢复得到可复用的新标签 const checkpoint await ctrl.branchSandbox(source.id, { tag: after-warmup, diff: true }); // 从检查点扇出 4 个子沙箱全部继承预热后的精确状态 const children await ctrl.spawnSandboxes({ snapshotTag: checkpoint.tag, n: 4 });性能实测详见 sdk/typescript/README.md 与 bench/chart-spawn-100.pngdiff: true模式4 GiB SSD 源沙箱的暂停窗口从 29 秒降到205 ms143× 提速v0.4mode: live暂停窗口进一步压到56 ms p50配合wait: false约 10 ms 即可返回错误处理也很直接捕获ControllerError用status区分 404沙箱不存在、409标签冲突等import { ControllerError } from deeplethe/forkd; try { await ctrl.getSandbox(sb-missing); } catch (e) { if (e instanceof ControllerError e.status 404) { /* 沙箱不存在 */ } }五、MCP 服务器让 Claude 和 Cursor 直接指挥沙箱 forkd-mcp把 forkd 的能力封装成 MCP 工具任何支持 MCP 的客户端Claude Desktop、Claude Code、Cursor、Cline注册后Agent 就能自己决定何时建沙箱、何时分叉、执行什么命令。安装需守护进程已在运行pip install forkd-mcp11 个工具一览MCP 工具能力list_snapshots/create_snapshot查看/构建父模板spawn_sandboxes从模板分叉 N 个 microVM 子沙箱branch_sandbox⭐ 运行中分叉出新快照支持diff/live模式exec_command/eval_code在沙箱内执行命令 / 求值 Pythonwait_for_text轮询沙箱内文件直到出现标记串触发分叉时机的利器list_sandboxes/get_sandbox/ping_sandbox/kill_sandbox沙箱生命周期管理实现源码在 sdk/mcp/forkd_mcp/server.py每个工具 1:1 映射到 controller REST 端点见 docs/API.md。注册到 Claude Desktop / Cursor在claude_desktop_config.json或~/.cursor/mcp.json中加入{ mcpServers: { forkd: { command: forkd-mcp, env: { FORKD_URL: http://127.0.0.1:8889, FORKD_TOKEN: contents-of-/etc/forkd/token } } } }Claude Code 用户也可以一行注册claude mcp add forkd --env FORKD_URLhttp://127.0.0.1:8889 \ --env FORKD_TOKEN$(sudo cat /etc/forkd/token) -- forkd-mcp重启客户端后工具即出现在 MCP 列表中。Cline 用户可把只读工具list_snapshots、ping_sandbox等加入autoApprove免去逐次确认完整配置见 sdk/mcp/README.md。典型玩法Agent 自己管理沙箱生命周期注册后你只需对 Claude 说一句起一个 Python 沙箱跑完这个脚本把状态 branch 成检查点然后扇出 3 个子沙箱分别尝试三种修复方案告诉我哪个通过测试。Agent 会自行编排spawn_sandboxes→exec_command→wait_for_text→branch_sandbox→ 再次spawn_sandboxes全程无需你写胶水代码。六、常见问题速答 ❓问题解答连不上守护进程确认sudo systemctl start forkd-controller并核对FORKD_URL/FORKD_TOKENdiff: true返回 400需要forkd-controller 0.3.0旧版本请升级要网络隔离吗派生时传perChildNetns: true先跑scripts/netns-setup.sh NTypeScript 之外有其他语言Python SDKsdk/python/pip install forkdAPI 与 TS 完全对等更多端到端示例浏览 recipes/ 目录含 Node.js、Playwright、CI 并行测试等配方总结用deeplethe/forkdTypeScript SDK你可以在 Node.js 里几行代码派生、分叉、执行 microVM 沙箱用forkd-mcpClaude/Cursor 这样的 AI 编程助手则可以直接把 forkd 当成代码执行后端自主调度。两者都构建在同一套 REST API 之上docs/API.md从原型到生产无缝切换。关键资料导航TypeScript SDK 文档sdk/typescript/README.mdMCP 服务器文档sdk/mcp/README.mdREST API 参考docs/API.mdNode.js 父镜像配方recipes/nodejs/README.md运行手册守护进程模式docs/RUNBOOK.md安全模型说明docs/SECURITY.md【免费下载链接】forkd高性能Agent沙箱预热虚拟机可以在约 100 毫秒内派生出 100 个独立实例运行过程中约 150 毫秒“分叉”出一个新的运行环境。底层使用 KVM 隔离并利用快照写时复制降低资源开销。项目地址: https://gitcode.com/deeplethe/forkd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
