SDK 对象与运行接口
E2B SDK 主要提供 Template、Sandbox、commands、files 和 PTY。Template 定义可复用环境，Sandbox 表示有时限的隔离实例，其余对象负责命令、文件和终端操作。Agent 应通过受控 Tool 调用这些接口。
对 GoClaw 而言，E2B Adapter 不应把 SDK 对象泄漏到公开 API。公开契约应保留 Provider、Template/Environment、Sandbox、Operation、Artifact 和 Usage，并把 E2B 专属字段放进能力证据或 Provider 扩展。
- 控制面负责认证、授权、审批、预算、幂等和审计。
- Provider Adapter 负责协议、重试、错误映射和能力差异。
- Sandbox 数据面只接收已经批准、约束过的执行请求。
Template 的构建与快照
E2B 官方构建流程先根据定义创建容器文件系统，执行安装和配置，再启动 Sandbox；如果配置了 start command，会等待 ready command 成功，随后对运行中的文件系统和进程状态做快照。
快照可以保存已经启动的服务状态。Sandbox.create 传入的环境变量不会影响构建阶段已经运行并被快照的 start command；该进程所需变量必须写入 Template 定义。
生命周期与错误映射
创建、连接、执行、暂停/恢复、超时和终止必须映射到统一状态机。客户端 finally 负责快速释放，平台 TTL 回收器负责兜底，控制面则需要处理“Provider 已成功但响应丢失”这类 Unknown Outcome。
元数据应携带 Workspace、Invocation 和 Run 关联信息，但不能包含 Secret。错误映射至少要区分认证失败、限流、容量不足、超时、命令非零退出和 Provider 不可用。
import { Sandbox } from "e2b";
const sandbox = await Sandbox.create("coding-agent:stable", {
timeoutMs: 5 * 60 * 1000,
metadata: { workspace: "ws_42", invocation: "inv_1042" },
});
try {
const result = await sandbox.commands.run(
"git --version && python --version"
);
console.log(result.exitCode, result.stdout);
} finally {
await sandbox.kill();
}Firecracker 数据面包含什么
E2B 使用 Firecracker microVM 运行 Sandbox。microVM 提供 guest kernel 与宿主机之间的隔离；平台还要提供镜像和快照存储、模板构建、网络入口、调度、日志、指标、身份和生命周期管理。
单独接入 Firecracker 只完成了虚拟机运行部分。高并发调度、失败恢复、版本升级和多租户隔离仍需由上层系统处理。
- 隔离：guest kernel 与宿主机边界。
- 供应：Template build、snapshot、kernel 与 Firecracker 版本。
- 调度：容量、节点选择、并发和回收。
- 治理：网络、Secret、审计、预算和租户边界。
BYOC 与 self-host 的部署边界
E2B BYOC 当前面向 AWS 和 GCP：Sandbox Template、快照和运行日志保留在客户 VPC 内，敏感 Sandbox 流量直接进入客户 VPC；E2B Cloud 仍承担平台、可观测性和集群管理的一部分。
开源 self-host 方案需要部署 Terraform 定义的基础设施。官方 AWS 参考架构使用 Nomad/Consul 节点池、对象存储、容器仓库、数据库以及支持嵌套虚拟化的 Firecracker orchestrator 节点。
接入 GoClaw 时的映射关系
GoClaw 将 Template 映射为版本化环境，将 Sandbox 映射为短生命周期实例。Provider 能力记录版本和验证证据；运行结果保存日志、退出码、Artifact、Trace、Usage 和 Audit。
E2B、ACS、Local 和未来自研数据面实现相同的 GoClaw 运行契约，Provider 专属限制保留在能力声明和扩展字段中。
- 控制面统一，数据面可替换。
- 能力声明必须经过 Conformance 验证。
- Unknown Outcome、取消竞态和 TTL 清理进入 E2E 场景。
- 面向用户展示差异，而不是用最低共同分母掩盖差异。
官方来源与继续阅读
文中的技术信息来自以下官方文档和开源仓库。实施前请核对所用版本的最新说明。