通过 SDK 创建第一个云沙箱

开始之前

完成以下准备工作：

• 阿里云账号：已注册阿里云账号并完成实名认证

• 服务关联角色：首次登录函数计算控制台时，系统会自动创建服务关联角色 AliyunServiceRoleForFC，无需手动操作。如果已登录过控制台但从未创建过该角色，需在 RAM 控制台手动创建

• Python 环境：已安装 Python 3.10 及以上版本和 pip 工具

• 网络：可访问函数计算服务端地址

• 地域：可访问北京地域的云沙箱服务

步骤一：安装 SDK

阿里云函数计算云沙箱 API 兼容与 e2b SDK兼容。e2b 是国际知名的开源沙箱 SDK，阿里云函数计算云沙箱与其 API 高度兼容。因此可以直接复用 e2b SDK 和社区生态，无需额外学习新的 SDK。

pip install e2b>=2.20.0 python-dotenv>=1.0.0

安装完成后，可通过以下命令验证安装是否成功：

python -c "from e2b import Sandbox; print('SDK 安装成功')"

步骤二：配置环境变量

SDK 运行需要通过环境变量传递认证信息和服务地址。在项目根目录创建 .env 文件，配置所需的环境变量：

# .env 文件示例 
E2B_API_KEY=<您的API密钥>
E2B_DOMAIN=<服务域名>

E2B_DOMAIN 请配置为中国站服务域名。

E2B_DOMAIN 用于 SDK 与云沙箱控制面通信，包括创建沙箱和执行命令。SDK 会根据该值自动构造 API 地址（https://api.{E2B_DOMAIN}）。

请求流向为：SDK → E2B_DOMAIN（沙箱控制面） → 云沙箱网关 → 函数计算服务完成沙箱资源的创建和销毁。用户无需单独配置函数计算接入点，网关会自动路由。

步骤三：创建沙箱

导入 SDK 后，使用 Sandbox() 构造函数创建沙箱实例：

from e2b import Sandbox

# 创建沙箱（SDK 会自动从环境变量读取认证信息）
sbx = Sandbox()

# 获取沙箱唯一标识
print(f"沙箱 ID: {sbx.sandbox_id}")

创建完成后，通过 sbx.sandbox_id 获取沙箱的唯一标识符。如果返回的 sandbox_id 非空，说明沙箱已成功就绪。

Sandbox 构造函数参数

Sandbox() 构造函数支持以下参数：

步骤四：执行命令

沙箱基于 Linux 容器环境，预装了常用的 Shell 工具和 Python 3 运行时。创建完成后，通过 commands.run() 方法执行 Shell 命令：

# 执行 Shell 命令
result = sbx.commands.run("echo Hello World")

# 获取命令输出
print(f"stdout: {result.stdout}")
print(f"stderr: {result.stderr}")
print(f"退出码: {result.exit_code}")

commands.run() 返回 CommandResult 对象：

也可执行更复杂的命令：

# 查看系统信息
result = sbx.commands.run("uname -a && date")
print(result.stdout)

# 执行 Python 代码
result = sbx.commands.run("python3 -c 'print(\"Hello from Python\")'")
print(result.stdout)

步骤五：执行代码

除了通过 commands.run() 执行 Shell 命令外，还可以通过 run_code() 方法直接执行 Python 或 JavaScript 代码，无需手动将代码写入文件再执行。run_code() 方法需要使用 e2b_code_interpreter 包提供的 Sandbox 类。

from e2b_code_interpreter import Sandbox

# 创建代码解释器沙箱
sbx = Sandbox()

# 执行 Python 代码
execution = sbx.run_code("print(1 + 1)")

# 执行多行 Python 代码
code = """
import json
data = {"message": "Hello from Cloud Sandbox", "status": "success"}
print(json.dumps(data, indent=2))
"""
execution = sbx.run_code(code)

run_code() 方法支持以下参数：

run_code() 返回 Execution 对象，包含以下属性：

以下示例演示使用 JavaScript 语言执行代码：

# 执行 JavaScript 代码
execution = sbx.run_code("console.log('Hello from JavaScript')", language="javascript")

步骤六：销毁沙箱

使用完成后，主动销毁沙箱以释放资源：

# 主动销毁沙箱
sbx.kill()

完整示例

以上分步演示了完整流程的每个环节。以下示例代码可一次性运行，完成沙箱的创建、命令执行和资源释放：

import os
from dotenv import load_dotenv
from e2b import Sandbox

# 加载 .env 文件中的环境变量
load_dotenv()

try:
    # 创建沙箱
    print("正在创建沙箱...")
    sbx = Sandbox(template="base", timeout=300)
    print(f"沙箱创建成功，ID: {sbx.sandbox_id}")

    # 执行命令
    print("\n执行命令: echo Hello World")
    result = sbx.commands.run("echo Hello World")
    print(f"输出: {result.stdout.strip()}")

    print("\n执行命令: date")
    result = sbx.commands.run("date")
    print(f"输出: {result.stdout.strip()}")

    # 执行 Python 代码
    print("\n执行 Python 代码: sum(range(1, 101))")
    execution = sbx.run_code("print(sum(range(1, 101)))")

    # 销毁沙箱释放资源
    print("\n正在销毁沙箱...")
    sbx.kill()
    print("沙箱已销毁")

except Exception as e:
    print(f"操作失败: {e}")

预期输出：

正在创建沙箱...
沙箱创建成功，ID: <sandbox-id>

执行命令: echo Hello World
输出: Hello World

执行命令: date
输出: Mon May 26 10:00:00 UTC 2026

执行 Python 代码: sum(range(1, 101))

正在销毁沙箱...
沙箱已销毁

从 E2B 迁移

云沙箱完全兼容 E2B Python SDK（e2b 包），从 E2B 迁移到云沙箱仅需替换环境变量配置，代码逻辑无需修改。

常见问题

后续步骤

完成快速入门后，您可以继续了解以下内容：

• 沙箱深休眠 ：了解沙箱的暂停与恢复功能，实现沙箱状态持久化，降低长时间运行的资源开销。（内测）

• 自定义模板：使用自定义模板创建沙箱，预装您需要的依赖和工具，减少每次创建时的初始化时间。

• 存储挂载：通过 metadata 配置存储挂载（NAS、OSS），实现沙箱内数据的持久化存储。

• 文件操作：通过 sbx.files 模块进行沙箱文件系统的读写、目录管理等操作。

• 沙箱管理：使用 Sandbox.list() 查看运行中的沙箱，使用 Sandbox.connect() 连接已有沙箱。