E2B SDK 兼容 API 清单

阅读本文时需要注意三点：

• 方法名和参数形态以当前使用的 E2B SDK 版本为准。Python 和 TypeScript 的命名风格可能不同。

• 标记为“兼容”的能力，仍需要结合账号配额、地域、模板状态和 SDK 版本验证。

• 标记为“受限”或“暂不兼容”的能力，不应作为生产接入主路径。

Sandbox

Sandbox 是云沙箱的核心对象。当前主路径是通过 E2B SDK 创建、连接、查询、暂停、恢复、设置超时和终止 Sandbox。

兼容能力：

• 创建 Sandbox：Sandbox.create()。

• 连接已有 Sandbox：Sandbox.connect(sandboxId)。

• 查询 Sandbox 列表：Sandbox.list()。

• 查询 Sandbox 信息：Sandbox.getInfo(sandboxId)、sandbox.getInfo()。

• 判断运行状态：sandbox.isRunning()。

• 设置超时时间：Sandbox.setTimeout(sandboxId, ms)、sandbox.setTimeout(ms)。

• 暂停 Sandbox：sandbox.pause()。

• 终止 Sandbox：Sandbox.kill(sandboxId)、sandbox.kill()。

• 获取文件上传 / 下载地址：sandbox.uploadUrl(path)、sandbox.downloadUrl(path)。

• 获取端口访问地址：sandbox.getHost(port)。

使用建议：

• 业务代码应在 try/finally 中释放 Sandbox，避免任务异常时资源持续占用。

• Sandbox.connect(sandboxId) 适合恢复或接管已有 Sandbox。目标 Sandbox 已终止、超时回收或不属于当前账号 / 地域时，连接会失败。

• 端口访问能力适合预览临时 Web 服务，不应直接替代正式 API 网关、鉴权和流量治理。

Commands

Commands 用于在 Sandbox 内执行命令、管理后台进程和处理输入输出。

兼容能力：

• 执行命令：sandbox.commands.run()。

• 查询命令 / 进程列表：sandbox.commands.list()。

• 连接后台命令：sandbox.commands.connect()。

• 向命令发送标准输入：sandbox.commands.sendStdin()。

• 终止命令：sandbox.commands.kill()。

• 交互式终端：使用独立的 sandbox.pty API。

使用建议：

• 普通批处理命令优先使用 commands.run()；只有交互式 CLI、彩色输出、进度条或依赖 TTY 判断的命令才使用 sandbox.pty。

• 长任务建议设置命令级超时，并处理 stdout / stderr，避免业务侧只等待最终结果。

• 不要把未经校验的用户输入直接拼接进 shell 命令。

Filesystem

Filesystem 用于在 Sandbox 生命周期内读写文件和管理目录。

兼容能力：

• 列出目录：sandbox.files.list()。

• 判断路径是否存在：sandbox.files.exists()。

• 获取文件或目录元信息：sandbox.files.getInfo() / sandbox.files.get_info()。

• 读取文件：sandbox.files.read()。

• 写入文件：sandbox.files.write()。

• 创建目录：sandbox.files.makeDir()。

• 删除文件或目录：sandbox.files.remove()。

• 重命名：sandbox.files.rename()。

• 目录监听：sandbox.files.watchDir() / sandbox.files.watch_dir()。

使用建议：

• 云沙箱当前不支持文件自定义元数据。即使 SDK 的 files.write() 方法签名接受 metadata，调用仍可能因 Sandbox 的 envd 版本低于 0.6.2 而在请求发送前失败。普通文件读写不受影响。

• 目录监听可用于等待文件生成或同步任务产物。只等待单个文件时，也可以使用 exists() 做有限次数轮询。

• Sandbox 本地文件系统适合任务临时文件，不应作为长期持久化存储。

• 跨 Sandbox 保留、共享或长期保存的数据，应写入 NAS、OSS 等外部存储。

• 处理用户上传路径时，应限制可写目录和文件大小，避免路径穿越和资源耗尽。

Code Interpreter

Code Interpreter 用于执行代码片段，并在多次执行之间保持上下文。

兼容能力：

• 执行代码：sandbox.runCode() / sandbox.run_code()。

• 创建执行上下文：sandbox.createCodeContext() / sandbox.create_code_context()。

• 查询执行上下文：sandbox.listCodeContexts() / sandbox.list_code_contexts()。

• 重启执行上下文：sandbox.restartCodeContext() / sandbox.restart_code_context()。

• 删除执行上下文：sandbox.removeCodeContext() / sandbox.remove_code_context()。

• 获取执行输出，包括 stdout、stderr、execution count、表达式结果和 execution.results 富结果。

• stdout、stderr 和结果回调。

• 通过 language 参数执行 Python、JavaScript、TypeScript 和 Bash。不支持 Java 和 R。

• 在同一 Context 内保持变量和执行状态。

使用建议：

• 数据分析、代码解释器和 Notebook 风格任务适合使用 Code Interpreter。

• 如果任务更接近固定脚本执行，直接使用 Commands 更容易做审计、超时控制和输出校验。

• 不要默认允许代码访问任意路径、任意网络或无限资源。

Templates

Templates 用于沉淀可复用运行环境。当前主路径是复用内置模板或构建自定义模板，再通过 SDK / CLI 创建 Sandbox。

兼容能力：

• 查询模板。

• 创建 / 更新 / 删除模板。

• 构建模板。

• 使用标签、版本或别名管理模板。

• 基于模板创建 Sandbox。

使用建议：

• 生产环境应固定模板名称、版本或别名，避免“latest”类引用造成不可控变更。

• 语言运行时、系统依赖、基础 CLI 和稳定业务 SDK 应前置到模板中，减少每次 Sandbox 启动后的临时安装。

• 模板构建依赖镜像仓库、网络和账号权限；构建失败时应先排查这些基础条件，再排查 SDK 参数。

CLI

云沙箱兼容 E2B CLI 的常用调试和管理命令。CLI 适合本地验证、排障和轻量管理，不建议作为生产系统的主控制面。

兼容命令：

• 查看模板：e2b template list。

• 创建 Sandbox：e2b sandbox create。

• 查看 Sandbox：e2b sandbox list。

• 终止 Sandbox：e2b sandbox kill <sandbox-id>。

• 连接 Sandbox：e2b sandbox connect <sandbox-id>。

• 执行命令：e2b sandbox exec <sandbox-id> <command>。

• 查看指标：e2b sandbox metrics <sandbox-id>。

配置要求：

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"

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

CLI 命令参数可能随 E2B CLI 版本变化。命令行为与文档不一致时，先执行 e2b --version 和对应命令的 --help，确认本机 CLI 版本和参数形态。

受限能力

以下 E2B SDK 能力当前用于保持调用兼容或返回占位结果，不适合作为生产依赖：

• Sandbox Logs：可能返回空结果，不应用于正式日志采集。

• Network Config Update：可能返回成功但不执行实际网络变更，不应用于动态网络治理。

Sandbox Metrics 当前支持查看 CPU、内存指标；磁盘/页缓存字段会返回占位值，不建议用于容量判断。指标按 1 分钟粒度返回。计费、告警和容量治理应以函数计算控制台、云监控或日志服务中的正式数据为准。

如果业务需要日志、网络变更、VPC 接入或云上存储访问，应按云沙箱当前开放能力和阿里云基础设施方案单独设计，不要直接照搬 E2B 对应 API。

暂不兼容能力

以下能力当前不属于云沙箱 E2B 兼容主路径：

• Snapshots。

• Volume API。

• Team 管理。

• API Key / Access Token 管理。

• E2B 托管 MCP Gateway。

• E2B 自定义域名、代理隧道、Bring Your Own Cloud 等平台侧能力。

迁移已有 E2B 应用时，应先识别是否依赖上述能力。如果依赖，需要先调整架构或确认云沙箱是否已有替代方案，再进入开发接入。