E2B：AI Agent 代码执行沙盒云基础设施，一行 SDK 起隔离云端沙箱｜部署与使用全指南

仓库：https://github.com/e2b-dev/E2B 语言：TypeScript / Python SDK；运行时基础设施由 e2b-dev/runtime 提供 形态：托管云服务（默认）+ 开源自托管（Terraform 部署到 AWS / GCP / Azure / 通用 Linux） 默认端口：沙箱内进程由 SDK 动态分配，外部通过 SDK API 访问

1. 项目简介

E2B 是一套开源基础设施，用于在云端安全隔离的沙箱中运行 AI 生成的代码。它对外提供 JavaScript / Python SDK，开发者只需几行代码即可启动一个临时沙箱、执行 shell 命令、跑代码解释器，甚至启动浏览器做 Computer Use。沙箱底层由独立的 runtime 仓库 e2b-dev/runtime 提供，支持 AWS、GCP、Azure，以及通过 Embed 方式部署到任意通用 Linux 机器。

1.1 核心信息一览

1.2 适用场景

• 给 LLM Agent 提供一个可以安全执行任意 Python / JS / Shell 代码的临时环境。
• 在 AI 应用中跑数据处理脚本、调用系统命令、装包、起临时 HTTP 服务。
• 做 Code Interpreter 类产品（ChatGPT Code Interpreter 类体验）。
• 做 Desktop / Computer Use 类 Agent：在沙箱里启动 Chrome、截屏、模拟鼠标键盘。

1.3 能力边界（官方口径）

• 默认用法是连 E2B 托管云，需要在 e2b.dev 注册并拿 API Key。
• 自托管 runtime 由 Terraform 部署到 AWS / GCP / Azure / 通用 Linux（Embed），属于较重的基础设施工作，不是 docker run 级别。
• 本仓库本身是 SDK 与文档；完整 runtime 代码在 e2b-dev/runtime。
• 沙箱是临时隔离环境，不用于长期运行有状态服务。

2. 功能特性

• 📦 一行 Sandbox.create() 起一个隔离云端沙箱，支持 JS / Python。
• 🖥️ commands.run() 在沙箱里执行任意 shell 命令并取回 stdout / stderr。
• 🐍 Code Interpreter SDK：runCode() / run_code() 直接跑 Python 代码并取回文本结果。
• 🖥️ Desktop SDK：在沙箱里启动 Chrome 等应用，支持鼠标、键盘、截屏、桌面流。
• 🔌 沙箱内可起任意 HTTP 服务，由 SDK 暴露给外部调用。
• 🧩 自托管支持 AWS、GCP、Azure，以及通过 Embed 部署到通用 Linux 机器。
• 📚 官方 Cookbook 提供与主流 LLM 与 Agent 框架集成的示例。

3. 官方界面预览

README 未提供运行截图，仅提供 Logo 与示意架构；沙箱是无界面的 SDK 服务，使用方式完全在代码中。

4. 官方跳转链接汇总

• 仓库：https://github.com/e2b-dev/E2B
• Runtime 仓库（自托管）：https://github.com/e2b-dev/runtime
• 官网 / 控制台：https://e2b.dev
• 文档：https://e2b.dev/docs
• API Key 控制台：https://e2b.dev/dashboard?tab=keys
• Cookbook：https://github.com/e2b-dev/e2b-cookbook
• PyPI：https://pypi.org/project/e2b/
• npm：https://www.npmjs.com/package/e2b
• 自托管 Embed 指南：runtime/blob/main/embed/README.md

5. 前置要求与服务器配置

5.1 软件前提（默认托管云用法）

• Node.js 18+ 或 Python 3.8+。
• 一个 E2B 账号与 API Key（e2b.dev/dashboard?tab=keys）。
• 你的应用所在机器能访问 api.e2b.dev。

5.2 软件前提（自托管 runtime）

• 一台有 AWS / GCP / Azure 账号，或一台通用 Linux 机器。
• 安装 Terraform。
• 足够配额用于跑沙箱虚拟机。

5.3 端口分配

5.4 磁盘与资源

• 托管云：按沙箱时长与规格计费，无需关心底层资源。
• 自托管：按所选用云厂商的 VM 规格计费。

6. 方式一：托管云（默认推荐，3 行代码）

6.1 安装 SDK

JavaScript / TypeScript：

npm i e2b

Python：

pip install e2b

6.2 申请并设置 API Key

1. 注册：https://e2b.dev。
2. 在控制台拿 Key：https://e2b.dev/dashboard?tab=keys。
3. 设置环境变量：

export E2B_API_KEY=e2b_你的Key

6.3 起一个沙箱并执行命令

JavaScript / TypeScript：

import Sandbox from 'e2b'

const sandbox = await Sandbox.create()
const result = await sandbox.commands.run('echo "Hello from E2B!"')
console.log(result.stdout) // Hello from E2B!

Python：

from e2b import Sandbox

with Sandbox.create() as sandbox:
    result = sandbox.commands.run('echo "Hello from E2B!"')
    print(result.stdout)  # Hello from E2B!

6.4 用 Code Interpreter SDK 跑 Python

# JS
npm i @e2b/code-interpreter
# Python
pip install e2b-code-interpreter

import { Sandbox } from '@e2b/code-interpreter'

const sandbox = await Sandbox.create()
const execution = await sandbox.runCode('x = 1; x += 1; x')
console.log(execution.text)  // 2

6.5 用 Desktop SDK 做 Computer Use

# JS
npm i @e2b/desktop
# Python
pip install e2b-desktop

import { Sandbox } from '@e2b/desktop'

const desktop = await Sandbox.create()
await desktop.launch('google-chrome')
const screenshot = await desktop.screenshot()

7. 方式二：自托管 runtime（Terraform）

官方 README 明确：自托管需要阅读 embed deployment guide，用 Terraform 把 E2B runtime 部署到自己的基础设施。

支持的云厂商：

• 🟢 AWS
• 🟢 Google Cloud（GCP）
• 🟢 Azure
• 🟢 通用 Linux 机器（通过 Embed）

简要步骤：

# 1. 拉取 runtime 仓库
git clone https://github.com/e2b-dev/runtime.git
cd runtime

# 2. 按所选云厂商 / Embed 模式准备 Terraform 变量
#    具体变量、网络、IAM 要求见 runtime/embed/README.md

# 3. 初始化并应用 Terraform
terraform init
terraform apply

自托管属于基础设施级工作，需要云厂商 IAM、网络、配额等知识；首次部署请严格按官方 embed README 操作。

8. 配置项说明

Code Interpreter 与 Desktop SDK 的子命令参数较多，详见官方文档：

• Code Interpreter：https://e2b.dev/docs/code-interpreting
• Desktop：https://e2b.dev/docs

9. 常用运维命令

# JS / Python 应用侧：沙箱由 SDK 创建，无需手动 start / stop
# 沙箱默认在闲置一段时间后自动销毁；也可在代码中显式 close

# JS
await sandbox.kill()

# Python
sandbox.kill()

# 自托管 runtime：用 Terraform 管理
terraform plan
terraform apply
terraform destroy

# 查看沙箱使用与计费：登录 https://e2b.dev/dashboard

10. 常见故障排查

• E2B_API_KEY 未设置：SDK 初始化会直接报错；先 export E2B_API_KEY=...。
• 网络不通 api.e2b.dev：在服务器上 curl https://api.e2b.dev 验证；公司代理环境需配置 HTTPS_PROXY。
• 沙箱内命令找不到：沙箱是精简镜像，需要先 pip install / npm i / apt install 对应包，再执行。
• Code Interpreter 跑大库报错：沙箱默认资源有限，先确认数据量与依赖大小在沙箱规格内。
• Desktop SDK 截屏为空：确认 desktop.launch('google-chrome') 成功返回后再截屏；首次启动浏览器可能需要等待。
• 自托管 Terraform apply 失败：先核对云厂商 IAM、配额、VPC / 子网；错误信息通常在 terraform plan 阶段就会暴露。
• 误用 Docker 部署：本项目不是 docker run 类服务，SDK 即客户端，runtime 才是服务端，二者不要混淆。

11. 风险与合规说明

• 许可证：E2B SDK 与 runtime 仓库开源，具体许可证以仓库根目录 LICENSE 为准；商用前请核对。
• 数据隐私：托管云模式下，AI 生成的代码与命令会在 E2B 云沙箱中执行；涉密任务请走自托管 runtime，或确认沙箱不写入敏感数据。
• 成本：托管云按沙箱时长与规格计费，高频 Agent 调用前先在控制台设置用量告警；自托管按云厂商 VM 计费。
• 安全：沙箱虽隔离，但仍可能被用来跑挖矿、爬虫等滥用行为；对外提供沙箱服务时应做鉴权与配额限制。
• 第三方依赖：沙箱内安装的第三方 pip / npm 包由对应仓库维护，供应链风险请自行评估。
• 版本演进：SDK 与 runtime 解耦，升级时请同步 npm / PyPI 版本与 runtime 版本。