构建 E2B Template：Coding Agent 环境的版本与验证

把固定依赖放进 Template

Coding Agent 如果每次创建 Sandbox 后再安装 Git、Python、Node.js 和测试工具，会放大启动时间、网络不确定性和供应链风险。Template 把稳定依赖前移到构建阶段，并产出可复用的版本化环境。

示例 Template 包含 Git、Python、curl、工作目录和一个健康检查服务。仓库和短期凭据在每次 Run 时注入。

• 进入 Template：系统包、固定版本工具、非敏感配置和基础服务。
• 进入 Run：仓库、任务输入、短期 Token、网络 Policy 和用户数据。

定义环境与就绪条件

E2B 当前 Template SDK 支持从 Debian 系基础镜像开始，安装依赖、复制文件、设置用户和工作目录，并配置 start/ready command。

ready check 不应只等待固定秒数。端口、URL、文件或自定义健康命令能更准确地证明快照时进程已经可用。

import { Template, waitForPort } from "e2b";

export const codingAgent = Template()
  .fromUbuntuImage("24.04")
  .aptInstall(["git", "python3", "python3-pip", "curl", "ca-certificates"])
  .setWorkdir("/workspace")
  .setEnvs({
    PYTHONDONTWRITEBYTECODE: "1",
    PYTHONUNBUFFERED: "1",
  })
  .setStartCmd(
    "python3 -m http.server 8000 --directory /workspace",
    waitForPort(8000),
  );

保存 Build ID 与构建信息

名称和 tag 便于人类理解，Build ID 才适合精确复现。CI 构建后应保存 Template 名称、tag、Build ID、SDK 版本、源代码提交和验证时间。

官方文档建议按环境使用不同 tag，也支持从一个经过验证的构建分配 stable、staging 等标签，而不必重新构建。

import "dotenv/config";
import { Template, defaultBuildLogger } from "e2b";
import { codingAgent } from "./template";

const build = await Template.build(codingAgent, "goclaw-coding:v0.1.0", {
  cpuCount: 2,
  memoryMB: 2048,
  onBuildLogs: defaultBuildLogger(),
});

console.log({
  buildId: build.buildId,
  templateId: build.templateId,
});

发布前运行 Sandbox Smoke Test

每个发布 tag 都应启动真实 Sandbox 做 Smoke Test：检查工具版本、默认用户、工作目录、健康端口、文件权限和网络策略。验证通过后再把 Build ID 提升为 stable。

测试必须显式回收 Sandbox，并对失败输出做脱敏。CI 还应保存构建日志与 Smoke Test 结果，形成 Capability Evidence。

import "dotenv/config";
import { Sandbox } from "e2b";

const sandbox = await Sandbox.create("goclaw-coding:v0.1.0");

try {
  const versions = await sandbox.commands.run(
    "git --version && python3 --version && curl -fsS http://localhost:8000"
  );
  if (versions.exitCode !== 0) throw new Error(versions.stderr);
  console.log(versions.stdout);
} finally {
  await sandbox.kill();
}

版本、缓存与回滚策略

Template 构建具有层缓存，但缓存不是版本语义。修改依赖后创建新语义版本，不要让同一个稳定标签悄悄漂移；先验证不可变 Build ID，再移动 stable 标签。

内核版本与 Template 构建时间绑定。官方说明旧 Template 的内核不能原地升级，需要重建 Template。内核、基础镜像和 SDK 升级都应生成新的 Conformance 记录。

• dev：允许快速迭代，不承诺长期复现。
• staging：运行完整 Smoke 与 Agent Workload。
• stable：只指向已验证 Build ID。
• deprecated：保留迁移窗口和替代版本。

生产环境检查清单

Template 只解决环境供应问题。运行 Agent 工作负载前，还要验证网络出口、凭据注入、资源限制、并发、日志/Artifact 大小和超时回收。

• 默认拒绝网络，再按域名或 IP 策略开放。
• 使用短期凭据，不把 Secret 固化进 Template。
• 对 CPU、内存、磁盘、并发和总费用设置预算。
• 命令输出、PTY、Markdown 和 Artifact 一律视为不可信。
• Provider 超时与客户端超时分别记录。
• 用同一 Workload 做 E2B 与其他 Provider 的 Conformance 对比。

官方来源与继续阅读

文中的技术信息来自以下官方文档和开源仓库。实施前请核对所用版本的最新说明。