企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent 沙箱
• 后端

E2B 是一个开源的云基础设施，它让开发者能够把 AI 生成的代码放进云端安全、隔离的沙箱环境中运行，并通过 JavaScript/TypeScript SDK（e2b）或 Python SDK（e2b）启动与控制这些沙箱。阅读本文后，你将掌握从安装 SDK、获取 API Key、创建沙箱、执行命令，到使用 Code Interpreter 运行代码、借助 Desktop SDK 实现 Computer Use，以及自托管 E2B 基础设施的完整实战流程。

E2B 是什么

E2B 是一套开源基础设施，核心能力是"在云端安全隔离的沙箱中运行 AI 生成的代码"。它解决的核心问题是：当 LLM 生成代码片段、命令或需要真实操作系统环境时，如何安全、可控地执行它们，而不是让模型输出直接暴露在宿主机上。

从仓库的 SDK 实现看（packages/js-sdk/src/sandbox/index.ts），一个 E2B 云沙箱是"安全且隔离的云端环境"，具备以下能力：

• 访问完整的 Linux 操作系统；
• 创建、列出、删除文件和目录；
• 运行命令；
• 运行隔离的代码；
• 访问互联网。

SDK 为每个沙箱实例暴露了files（文件系统）、commands（命令执行）、pty（伪终端）等模块，并持有sandboxId与sandboxDomain标识，方便你在不同环境中重连同一沙箱。

运行你的第一个沙箱

1. 安装 SDK

根据项目语言选择对应的 SDK：

# JavaScript / TypeScript npm i e2b

# Python pip install e2b

仓库中的 SDK 包信息分别位于 packages/js-sdk/package.json 与 packages/python-sdk/pyproject.toml。JavaScript SDK 通过tsdown构建并输出dist/index.js、dist/index.mjs与类型声明dist/index.d.ts，同时针对 Cloudflare Workers、Deno、Bun 等运行时提供了专门的测试配置，说明该 SDK 被设计为可在多种现代 JS 运行时中工作。

2. 获取 E2B API Key

1. 在 E2B 官网注册账号；
2. 在 Dashboard 的 Keys 页面获取你的 API Key；
3. 将其设置为环境变量：

E2B_API_KEY=e2b_***

API Key 是沙箱创建与调用的凭证。从 CLI 源码（packages/cli/src/api.ts 中的ensureAPIKey）可以看到，E2B_API_KEY环境变量是 CLI 读取 API Key 的标准来源；SDK 侧同样默认从环境变量读取配置（见 packages/js-sdk/src/connectionConfig.ts）。

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!

在 Python 中，Sandbox以上下文管理器（with语句）的方式使用，退出代码块时会自动清理沙箱资源，这是推荐写法。

源码层面的执行细节：Sandbox.create()在 packages/js-sdk/src/sandbox/index.ts 中实现。它支持两种调用形式——无参数创建（使用默认模板base），或传入模板名/ID。创建过程最终调用受保护的createSandbox（packages/js-sdk/src/sandbox/sandboxApi.ts），向 API 的POST /v2/sandboxes发送请求，请求体包含templateID、metadata、envVars、timeout、allow_internet_access、network、iam、autoPause等字段。创建成功后还会校验沙箱内envdVersion是否满足 SDK 最低版本要求，若模板过旧会主动终止沙箱并抛出TemplateError，提示"需要更新模板以使用新版 SDK"。

关于模板（Template）：沙箱基于预定义的模板创建。仓库内置的默认模板位于 templates/base/e2b.Dockerfile，它基于python:3.11.6，并安装了build-essential、curl、git、gh（GitHub CLI）以及 Node.js 20.9.0 等常用开发工具。模板决定了沙箱内预置的运行时与依赖，你可以构建自定义模板来满足特定场景需求。

4. 使用 Code Interpreter 执行代码

如果你需要执行代码并获取结构化结果（即runCode()/run_code()能力），请安装 Code Interpreter SDK：

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

对应源码包为 packages/code-interpreter-js 与 packages/code-interpreter-python。

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

与普通commands.run不同，Code Interpreter 在沙箱内维护了一个持久的代码执行环境（Jupyter 内核，端口定义见 packages/code-interpreter-python/e2b_code_interpreter/constants.py）。从 packages/code-interpreter-python/e2b_code_interpreter/code_interpreter_sync.py 的源码可以看到，run_code支持：

• 多语言：python、javascript、typescript、r、java、bash等（见 packages/code-interpreter-js/src/sandbox.ts）；
• 状态保持：在同一个沙箱内，后续执行可以引用之前定义的变量、导入与函数；
• 回调处理：通过on_stdout、on_stderr、on_result、on_error实时处理流式输出与最终结果；
• 执行控制：timeout（执行超时，JS 侧默认 60 秒）、request_timeout（请求超时，默认 30 秒）、envs（自定义环境变量）等参数。

请求通过沙箱内的 Jupyter 端口/execute端点以流式方式提交，返回的Execution对象包含text、results（含图表等富媒体输出）、logs等字段。

5. 使用 Desktop 实现 Computer Use

如需鼠标、键盘、截屏、应用启动与桌面流式传输等 Computer Use API，安装 Desktop SDK：

npm i @e2b/desktop # JavaScript/TypeScript pip install e2b-desktop # Python

对应源码包为 packages/desktop-js 与 packages/desktop-python。

import { Sandbox } from '@e2b/desktop' const desktop = await Sandbox.create() await desktop.launch('google-chrome') const screenshot = await desktop.screenshot()

Desktop 沙箱基于默认模板desktop（见 packages/desktop-js/src/sandbox.ts），在普通沙箱之上叠加了虚拟桌面能力。从源码看，它支持：

• 屏幕分辨率与 DPI 配置（resolution、dpi、display选项，见 packages/desktop-js/src/sandbox.ts）；
• 丰富的键盘按键映射（ctrl、enter、tab等）与鼠标按钮（左、中、右）；
• 桌面流式传输（desktop.stream.start()，可指定窗口 ID 并启用鉴权）；
• 创建时会自动注入DISPLAY环境变量并启动桌面环境（packages/desktop-js/src/sandbox.ts）。

这为构建"能看屏幕、能操作界面"的 Agent 提供了基础设施。

6. 查阅文档

完整的 API 参考与使用文档见 E2B 官方文档站点（https://e2b.dev/docs）。仓库内同样沉淀了 API 规范文件，例如 spec/openapi.yml、spec/envd/process/process.proto 与 spec/envd/filesystem/filesystem.proto，它们定义了沙箱控制面与 envd（沙箱内运行时）的通信协议。

7. 参考 E2B Cookbook

官方 Cookbook（示例代码集）提供了结合不同 LLM 与 AI 框架的完整示例，是快速获得灵感的好去处。仓库内的 packages/cli/testground/demo-basic 也提供了一个带Dockerfile、main.mjs与package.json的可运行演示项目，展示了沙箱配合 CLI 的典型用法。

沙箱生命周期与进阶操作

除了create，SDK 还提供一整套沙箱管理 API（在 packages/js-sdk/src/sandbox/index.ts 与 packages/js-sdk/src/sandbox/sandboxApi.ts 中实现）：

关于超时与生命周期：创建沙箱时可配置timeoutMs（超时时间）。从 packages/js-sdk/src/sandbox/sandboxApi.ts 的校验逻辑可以看到，lifecycle.onTimeout只允许'pause'或'kill'两种取值：

• kill：超时后直接销毁沙箱（默认行为）；
• pause：超时后暂停沙箱并保留内存快照，可配合autoResume: true在收到流量时自动恢复（此时要求快照模式保留内存，纯文件系统快照无法被流量自动恢复）。

这些能力让开发者能够精细控制沙箱成本与资源回收策略。Python SDK 侧对应的默认超时为 300 秒（见 packages/python-sdk/e2b/sandbox/main.py）。

使用 CLI 管理沙箱

仓库同时提供了完整的命令行工具（packages/cli），方便在终端中直接操作沙箱。核心命令包括：

e2b sandbox create [template] # 创建沙箱并连接终端；-d/--detach 仅创建不连终端 e2b sandbox connect <sandboxID> # 连接到一个已运行的沙箱 e2b sandbox exec <sandboxID> <command...> # 在运行中的沙箱内执行命令 e2b sandbox list # 列出沙箱 e2b sandbox kill <sandboxID> # 终止沙箱

从源码看（packages/cli/src/commands/sandbox/create.ts），e2b sandbox create支持丰富的选项：

• --timeout <seconds>：沙箱超时时间（源码中最小为 30 秒）；
• --lifecycle.ontimeout <action>：超时后动作（pause或kill）；
• --lifecycle.autoresume：启用自动恢复（需配合pause）；
• -u, --user <user>：终端会话以指定用户启动；
• -c, --cwd <dir>：指定工作目录；
• -e, --env <KEY=VALUE>：设置环境变量（可重复）。

e2b sandbox exec还支持-b, --background后台运行（见 packages/cli/src/commands/sandbox/exec.ts）。CLI 本身也是基于e2bSDK 实现的——例如connect命令底层调用e2b.Sandbox.connect(sandboxID, { apiKey })（见 packages/cli/src/commands/sandbox/connect.ts），这印证了 SDK 是控制沙箱的统一入口。

自托管 E2B（Self-hosting）

如果你希望把沙箱运行在自己的基础设施上，E2B 提供了自托管方案：通过Embed 部署指南在自有环境中搭建 E2B runtime，整个基础设施使用Terraform部署。

支持的云平台：

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

自托管模式下，沙箱依然通过 SDK/CLI 以相同的方式创建与控制，区别仅在于 API 端点与域名指向你自建的部署。仓库中的 spec 目录完整开放了 envd 的协议定义（process、filesystem 的 protobuf 与 OpenAPI 规范），为自托管及二次开发提供了接口级参考。

小结

E2B 通过"安全隔离的云沙箱 + 多语言 SDK + CLI + 模板系统"的组合，为 AI 应用提供了一套开箱即用的代码执行基础设施。从Sandbox.create()创建环境、commands.run执行命令、Code Interpreter 运行持久化代码，到 Desktop SDK 模拟真实电脑操作，再到基于 Terraform 的自托管部署，本文覆盖了从入门到进阶的完整路径。你可以从安装 SDK 并运行第一个echo "Hello from E2B!"开始，逐步在真实项目中落地 AI 代码执行能力。

• 人工智能
• AI Agent
• Agent 沙箱
• 后端