E2B 保姆级部署教程：给 AI 智能体一个安全的云沙箱跑代码

E2B（仓库 e2b-dev/e2b，最近提交 2026-10-28）是一个开源的云沙箱基础设施：你的 AI 智能体生成了代码，不敢直接在本机跑？E2B 给它在云端开一个一次性、隔离的 Linux 沙箱，把命令、文件、浏览器都关在里面跑，跑完即销毁。GPT-5、Claude、Devin 这类"会写代码的 AI"背后，几乎都离不开 E2B 这类沙箱。

本文严格对照官方 README 给出 Python / JavaScript SDK 的完整接入与自托管方式。

一、项目介绍与适用场景

E2B 官方定位："open-source infrastructure that allows you to run AI-generated code in secure isolated sandboxes in the cloud"——用 JavaScript SDK 或 Python SDK 启停沙箱、在里面跑命令、跑代码、甚至开桌面。

适用场景：

• AI 编程智能体：让 AI 生成的 Python/JS 代码在隔离沙箱里执行，避免污染本机；
• 数据科学助手：用户上传 CSV，AI 写 pandas 脚本，在沙箱里跑出图表；
• Web 浏览智能体：用 Desktop SDK 在沙箱里开 Chrome、截图、点鼠标；
• 自动批改 / 评测：批量跑学生提交的代码，互不干扰。

二、核心功能逐条拆解

1. 云沙箱 API：Sandbox.create() 一行开一个临时 Linux 环境。
2. 命令执行：sandbox.commands.run('...') 在沙箱里跑 shell 命令。
3. Code Interpreter：pip install e2b-code-interpreter 后用 run_code() 直接跑 Python 代码片段。
4. Desktop 桌面：pip install e2b-desktop 后可在沙箱里开 Chrome、截图、鼠标键盘。
5. 多语言 SDK：Python（PyPI）与 JavaScript（npm e2b）双 SDK。
6. Cookbook：官方仓库 e2b-cookbook 提供与各种 LLM / Agent 框架的集成示例。
7. 自托管运行时：通过 e2b-dev/runtime 仓库的 Embed 方案，可用 Terraform 部署到 AWS / GCP / Azure / 通用 Linux 机器。

三、全套官方链接

四、硬件与环境前置要求

官方 README 未列出硬性硬件门槛。SDK 本身极轻量，主要消耗在云端沙箱。

• Python 3.9+ 或 Node.js 18+；
• 一个 E2B 账号 + API Key（去 https://e2b.dev/dashboard?tab=keys 申请）；
• 网络：能访问 E2B 云 API；
• 自托管：若用 Terraform 自托管，需一台可跑 Docker 的 Linux 机器（Embed 模式）或 AWS/GCP/Azure 账号。

五、多平台部署步骤

5.1 安装 SDK（官方 Quickstart）

Python：

pip install e2b

官方 README 原文。JavaScript/TypeScript：

npm i e2b

5.2 配置 API Key

官方 README 步骤：

1. 注册 E2B 账号；
2. 在 https://e2b.dev/dashboard?tab=keys 拿 API Key；
3. 设环境变量：

export E2B_API_KEY=e2b_你的key

5.3 启动第一个沙箱并执行命令（官方示例）

Python 官方原文：

from e2b import Sandbox

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

逐段解释：

• Sandbox.create()：向 E2B 云端申请一个临时 Linux 沙箱；
• with 块结束自动销毁沙箱；
• sandbox.commands.run('echo ...') 在沙箱里执行 shell 命令；
• result.stdout 拿到标准输出。

JavaScript 官方原文：

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!

5.4 安装 Code Interpreter 跑 Python 代码

官方 README：

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

官方 JS 示例：

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)  // outputs 2

5.5 安装 Desktop SDK 开浏览器

官方 README：

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

官方 JS 示例：

import { Sandbox } from '@e2b/desktop'

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

5.6 自托管运行时（Embed，官方提供）

官方 README 指向 e2b-dev/runtime 仓库的 embed/README.md，用 Terraform 部署。支持：

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

官方未提供一键 Docker 镜像，自托管需按 runtime 仓库的 Terraform 方案执行，本文不展开其内部参数。

六、配置文件全部参数解释

其他 SDK 高级参数（env vars、metadata、template）以官方文档 https://e2b.dev/docs 为准，本文不臆造。

七、启动、后台常驻与开机自启

E2B 是 SDK 而非常驻服务，无 systemd 部署。若你要把它包成一个长期运行的微服务，可在你自己的后端里 pip install e2b，然后用 systemd 跑你的服务：

[Unit]
Description=My E2B Backend
After=network.target

[Service]
Type=simple
User=ubuntu
Environment="E2B_API_KEY=e2b_..."
WorkingDirectory=/home/ubuntu/myapp
ExecStart=/home/ubuntu/.venv/bin/python app.py
Restart=on-failure

[Install]
WantedBy=multi-user.target

开机自启：sudo systemctl enable --now myapp。

八、功能实操教程

第 1 步：pip install e2b，export E2B_API_KEY=...。 第 2 步：写一个 test.py，粘贴 5.3 的 Python 示例，python test.py。 第 3 步：终端打印 Hello from E2B!，说明沙箱已成功在云端创建并执行命令。 第 4 步：把命令换成 pip list，看看沙箱预装了哪些包；换成 python --version 看沙箱 Python 版本。 第 5 步：装 e2b-code-interpreter，写一个"用户上传 CSV → AI 写 pandas → 沙箱跑出均值"的脚本，验证代码隔离执行。 第 6 步：装 e2b-desktop，按 5.5 开 Chrome 截图，验证桌面级自动化。

九、全套报错故障排查

1. 报错：Sandbox.create() 401 / Unauthorized。 原因：E2B_API_KEY 没设或写错。 解决：echo $E2B_API_KEY 确认；去 dashboard 重新生成 key。

2. 报错：pip install e2b 超时。 原因：PyPI 慢。 解决：换清华镜像 -i https://pypi.tuna.tsinghua.edu.cn/simple。

3. 报错：commands.run 超时。 原因：沙箱里跑的命令耗时超过默认等待时间。 解决：在 SDK 调用里加大超时参数（以官方 SDK 文档为准），或把长任务改后台跑。

4. 报错：沙箱里没有某条命令。 原因：基础镜像不含该工具。 解决：先 sandbox.commands.run('apt install -y ...') 装，或自建 template（见官方文档）。

5. 报错：自托管 Embed 起不来。 原因：Terraform 依赖云账号权限。 解决：严格按 e2b-dev/runtime 的 embed/README.md 执行；本地机器需 Docker 可用。

十、升级、回滚与卸载

• 升级：pip install -U e2b e2b-code-interpreter e2b-desktop。
• 回滚：pip install e2b==<旧版本>。
• 卸载：pip uninstall e2b e2b-code-interpreter e2b-desktop；沙箱是云端临时资源，无需清理。

十二、进阶：沙箱镜像、文件传输与多沙箱并发

自定义沙箱模板：默认沙箱是精简 Linux 镜像，缺的工具每次都 apt install 很慢。官方支持基于基础镜像打自定义 template（预装 pandas、ffmpeg、特定 Python 包），后续 Sandbox.create(template=...) 秒级启动，具体命令以 https://e2b.dev/docs 文档为准。

文件上传下载：SDK 提供 sandbox.files.write() 与 sandbox.files.read()，可以把用户上传的 CSV 推到沙箱里，跑完再把生成的图表下载回来。常见模式：前端传文件 → 你的后端存临时目录 → 调 E2B 沙箱执行 → 拉回结果给前端。

多沙箱并发：每个 Sandbox.create() 是独立隔离环境，天然支持并发。批量跑 100 个用户请求时，用 Python asyncio.gather 同时开 10–20 个沙箱，每个跑自己的任务；注意 E2B 云端有并发上限，大批量任务建议排队。

网络与出网控制：默认沙箱允许出网，AI 生成的代码可以 pip install、访问外网。生产环境如果你不信任 AI 生成的代码，配合 E2B 自托管 Embed 方案 + 云厂商安全组做网络白名单，避免沙箱被当成跳板。

十一、商用许可与合规风险提示

E2B 开源 SDK 采用 Apache-2.0，商用友好。

注意：

1. 云沙箱按秒计费：自托管 Embed 方案免费，但托管在 AWS/GCP/Azure 会产生云资源费用；E2B Cloud 按沙箱时长计费。
2. 代码安全：沙箱是隔离边界，但不要把生产密钥写进沙箱里跑；AI 生成的代码仍可能有恶意行为，建议配合网络策略。
3. 数据合规：用户代码出了本机进入云端，涉及敏感数据时建议自托管 Embed 方案。

参考链接

• 官方 README：https://github.com/e2b-dev/e2b
• 官方文档：https://e2b.dev/docs
• 自托管 Embed：https://github.com/e2b-dev/runtime/blob/main/embed/README.md
• Cookbook：https://github.com/e2b-dev/e2b-cookbook