E2B SDK 接入参数说明

本文不替代 E2B SDK 官方类型定义。不同语言 SDK 的参数命名、默认值和单位可能不同，业务代码应以所使用 SDK 版本的类型定义为准；本文只说明接入云沙箱时必须关注的参数和兼容边界。

基础配置

使用 E2B SDK 或 E2B CLI 接入云沙箱时，至少需要配置 API Key、API URL 和域名。

export E2B_API_KEY="<your-api-key>"
export E2B_API_URL="https://api.<region>.e2b.fc.aliyuncs.com"
export E2B_DOMAIN="<region>.e2b.fc.aliyuncs.com"

其中 <region> 需要与云沙箱所在地域一致。当前支持的 <region> 包括 cn-beijing、cn-shanghai、cn-hangzhou 和 cn-shenzhen。如果 API URL、域名、模板和 Sandbox 不在同一地域，常见结果是创建失败、连接失败或模板不可见。

API Key 应在函数计算控制台创建和管理，具体步骤参见创建 API Key。不要通过 E2B SDK 管理云沙箱 API Key，也不要把 API Key 写入代码仓库、日志、截图或前端页面。

E2B CLI 配置

新版本 E2B CLI 使用 E2B_API_KEY 认证。E2B_ACCESS_TOKEN 是 E2B 已废弃的旧认证变量，不建议在新接入流程中使用。

如果 SDK 可以访问云沙箱，但 CLI 认证失败，优先检查 CLI 版本、E2B_API_KEY、E2B_API_URL 和 E2B_DOMAIN。

Python SDK 常用参数

Python SDK 通常使用 snake_case 参数名：

• api_key：云沙箱 API Key，对应 E2B_API_KEY。

• api_url：云沙箱 API URL，对应 E2B_API_URL。

• domain：Sandbox 域名后缀，对应 E2B_DOMAIN。

• template：创建 Sandbox 使用的模板名称或模板 ID。

• timeout：Sandbox 超时时间。不同 Python SDK 对单位和默认值的定义可能不同，使用前应确认当前版本类型定义。

• envs：创建 Sandbox 时注入的环境变量。

• metadata：写入控制面的自定义元数据，适合保存任务 ID、业务来源、Agent 类型等可索引信息。

示例：

import os
from e2b_code_interpreter import Sandbox

sandbox = Sandbox.create(
    template="code-interpreter-v1",
    api_key=os.environ["E2B_API_KEY"],
    api_url=os.environ["E2B_API_URL"],
    domain=os.environ["E2B_DOMAIN"],
    metadata={"task_id": "task-001"},
    envs={"TASK_ID": "task-001"},
)

try:
    result = sandbox.commands.run("python3 -c \"print('hello from sandbox')\"")
    print(result.stdout.strip())
finally:
    sandbox.kill()

TypeScript SDK 常用参数

TypeScript SDK 通常使用 camelCase 参数名：

• apiKey：云沙箱 API Key，对应 E2B_API_KEY。

• apiUrl：云沙箱 API URL，对应 E2B_API_URL。

• domain：Sandbox 域名后缀，对应 E2B_DOMAIN。

• template：创建 Sandbox 使用的模板名称或模板 ID。部分调用方式会把模板作为 Sandbox.create() 的第一个参数传入。

• timeoutMs：Sandbox 超时时间，通常以毫秒为单位。

• envs：创建 Sandbox 时注入的环境变量。

• metadata：写入控制面的自定义元数据。

示例：

import { Sandbox } from "e2b";

const sandbox = await Sandbox.create("code-interpreter-v1", {
  apiKey: process.env.E2B_API_KEY,
  apiUrl: process.env.E2B_API_URL,
  domain: process.env.E2B_DOMAIN,
  timeoutMs: 10 * 60 * 1000,
  metadata: { task_id: "task-001" },
  envs: { TASK_ID: "task-001" },
});

try {
  const result = await sandbox.commands.run("python3 -c \"print('hello from sandbox')\"");
  console.log(result.stdout.trim());
} finally {
  await sandbox.kill();
}

参数使用建议

• 优先通过环境变量传入 apiKey / api_key、apiUrl / api_url 和 domain，避免在代码中写死地域和凭证。

• metadata 用于控制面查询、审计和业务关联，不会自动进入 Sandbox 运行环境。

• envs 用于 Sandbox 内进程读取，不应保存需要长期持久化的业务状态。

• 超时时间要按任务实际运行时长设置。过短会导致任务中断，过长会增加资源占用和费用风险。

• 任务完成后应主动调用 sandbox.kill()。需要保留现场时再使用暂停与恢复，不要把暂停当成默认释放资源方式。

• 迁移已有 E2B 应用时，先只替换 API Key、API URL 和域名；确认最小创建、命令执行、文件读写和资源释放链路通过后，再接入模板、Code Interpreter、元数据和环境变量等能力。

不作为接入参数的能力

以下能力当前不应写入云沙箱的默认 SDK 接入路径：

• 云沙箱 API Key / Access Token 管理：通过函数计算控制台完成，不通过 E2B SDK 管理。API Key 创建和管理参见创建 API Key。

• Snapshots、Volume、Team 管理：当前不属于云沙箱 E2B 兼容主路径。

• Metrics、Logs、Network Config Update：当前属于受限能力，不适合作为生产监控、日志采集或网络变更的控制面依赖。

完整能力边界参见E2B SDK 兼容 API 清单和开始使用 / E2B 兼容说明。