企业官网建设流程全解析

Zeroboot API完整参考：从/v1/exec到批量并行执行的4个核心端点详解

【免费下载链接】zerobootSub-millisecond VM sandboxes for AI agents via copy-on-write forking项目地址: https://gitcode.com/gh_mirrors/ze/zeroboot

Zeroboot是一个用 Rust 编写的子毫秒级 VM 沙箱服务，专为 AI Agent 设计：每个请求都会通过 copy-on-write 分叉出一台真正的 KVM 虚拟机来执行代码，fork 延迟 p50 仅0.79ms。本文是它的 API 完整参考，带你逐一拆解/v1/exec、/v1/exec/batch、/v1/health、/v1/metrics这 4 个核心端点，从请求参数到响应字段，看完即可上手调用。

上图是官方 AI Agent 演示：Claude 通过run_python和run_parallel两个工具，把生成的代码交给 Zeroboot 沙箱执行，支持多方案并行对比。完整说明见 demo/README.md。

为什么需要子毫秒级代码沙箱？

AI Agent 生成代码后需要"安全地跑一下"。传统方案（容器、完整 VM）冷启动要几十到几百毫秒，而 Zeroboot 的思路是：

1. 一次性用 Firecracker 启动 VM、预加载运行时（Python + numpy、Node.js），并快照内存 + CPU 状态；
2. 每次请求通过mmap(MAP_PRIVATE)以写时复制方式把快照映射进新 KVM VM，恢复 CPU 状态——约0.8ms完成分叉；
3. 每个沙箱拥有独立的 KVM VM，隔离由 Intel VT-x/AMD-V 硬件强制，而非容器或 namespace。

官方基准（p50 延迟）：

架构全貌见 docs/ARCHITECTURE.md。

4 个核心端点一览

完整定义见 docs/API.md，实现位于 src/api/handlers.rs。

端点 1：POST /v1/exec —— 单次代码执行

这是最核心的端点：每调用一次，Zeroboot 就 fork 一台新 VM 沙箱执行你的代码。

请求体参数

响应字段解读（这是 API 最有价值的部分）

curl 示例

curl -X POST https://api.zeroboot.dev/v1/exec \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer zb_demo_hn2026' \ -d '{"code":"import numpy as np; print(np.random.rand(3))"}'

响应示例：

{ "id": "019cf684-1fd5-73c0-9299-52253f9aa79c", "stdout": "[0.5488 0.7152 0.6028]", "stderr": "", "exit_code": 0, "fork_time_ms": 0.75, "exec_time_ms": 7.2, "total_time_ms": 8.0 }

💡 注意：沙箱内无网络，代码通过串口 I/O 通信；fork 间共享快照的 CSPRNG 状态，涉及随机数的场景建议每次显式重播种。

端点 2：POST /v1/exec/batch —— 批量并行执行

当 AI Agent 需要"用 5 种不同方法解同一个问题再对比"时，就靠这个端点。一次请求里的每段代码都会跑在各自独立的 VM fork中，并行执行、互不干扰。

请求体

{ "executions": [ {"code": "print(1)", "language": "python"}, {"code": "console.log(2)", "language": "node"} ] }

响应体是一个results数组，每项字段与/v1/exec的响应完全一致，按输入顺序排列。

/v1/exec/batch的批量并行正是官方 AI Agent 演示里run_parallel工具背后的能力——Agent 一次并行跑多个方案，用一次往返拿到全部对比结果。

端点 3：GET /v1/health —— 健康检查与模板状态

无需鉴权即可调用，返回服务状态和每种语言模板是否就绪：

{ "status": "ok", "templates": { "python": {"ready": true, "memory_mb": 256}, "node": {"ready": true, "memory_mb": 256} } }

ready: true表示对应语言的快照模板已加载完毕，此时调用/v1/exec即可走子毫秒路径。

端点 4：GET /v1/metrics —— 监控指标

返回 Prometheus 文本格式，可直接被 Grafana / Prometheus 抓取。核心指标包括：

• zeroboot_fork_time_milliseconds—— fork 耗时直方图（桶边界 0.1ms~1000ms）
• zeroboot_exec_time_milliseconds—— 代码执行耗时直方图
• zeroboot_total_time_milliseconds—— 端到端耗时直方图
• zeroboot_concurrent_forks—— 当前并发 fork 数
• zeroboot_total_executions—— 成功 / 失败 / 超时执行总数

配套的监控面板模板在 deploy/grafana-dashboard.json，直方图的桶实现见 src/api/handlers.rs。

认证与速率限制

• API Key放在api_keys.json（或设置ZEROBOOT_API_KEYS_FILE环境变量），通过Authorization: Bearer <key>请求头携带；
• 未配置 key 文件时认证自动关闭（适合本地自托管）；
• 无效 / 缺失 key 返回HTTP 401；
• 正式 key 限流100 req/s（超出返回HTTP 429）；zb_demo_开头的演示 key 限10 次/分钟，且按客户端 IP 隔离——官方源码中该逻辑见 src/api/handlers.rs。

不手写 HTTP？两个零依赖 SDK

不想直接调 REST API，官方提供 Python 和 TypeScript 两套 SDK：

Python（sdk/python/，纯标准库实现）：

from zeroboot import Sandbox sb = Sandbox("zb_live_your_key") result = sb.run("print(1 + 1)") # 单次执行 → /v1/exec results = sb.run_batch(["print(1)", "print(2)"]) # 并行执行 → /v1/exec/batch

TypeScript（sdk/node/，基于 fetch）：

import { Sandbox } from "@zeroboot/sdk"; const result = await new Sandbox("zb_live_your_key").run("console.log(1+1)");

常见问题

Q：fork 这么快，隔离安全吗？每个沙箱是独立的 KVM VM，内存页写时复制，硬件级隔离，fork 间看不到彼此的数据。

Q：每个沙箱多少资源？每 fork 单 vCPU、快照默认 256MB，但实际 RSS 只有 ~265KB——未触碰的内存页仍共享快照文件。

Q：有哪些已知限制？fork 内暂无网络（仅串口 I/O）、单 vCPU、更新模板需重新全量快照（约 15s）。详见 README.md。

总结

Zeroboot 的 API 设计极简但信息密度很高：

核心关键词回顾：子毫秒 VM 沙箱、代码执行 API、批量并行执行、AI Agent 沙箱。想深入实现细节，推荐按顺序阅读 docs/ARCHITECTURE.md → src/vmm/kvm.rs（fork 引擎）→ src/api/handlers.rs（API 层）。

【免费下载链接】zerobootSub-millisecond VM sandboxes for AI agents via copy-on-write forking项目地址: https://gitcode.com/gh_mirrors/ze/zeroboot