基础沙箱与命令执行-函数计算(FC)-阿里云帮助中心

AI Agent 运行时需要安全隔离的环境来执行动态生成的代码或命令。基础沙箱（base template）提供通用的隔离执行环境，适合执行 Shell 命令、运行脚本和轻量调试任务。通过 E2B SDK，可以使用沙箱执行任意命令并获取输出结果，也可以将沙箱内的服务端口映射为公网可访问的地址。

创建沙箱并执行命令

开始前，确保已完成以下准备：

已获取云沙箱 API Key，获取方式参见管理 API Key。
已安装 E2B SDK（Python：pip install e2b==2.26.0，TypeScript：npm i e2b@2.28.0）。

以下示例演示如何创建基础沙箱，执行 Shell 命令并获取端口映射地址。

运行前，先在终端配置环境变量（将 e2b_xxxxx 替换为您的实际 API Key）：

export E2B_API_URL="https://api.cn-beijing.e2b.fc.aliyuncs.com"
export E2B_DOMAIN="cn-beijing.e2b.fc.aliyuncs.com"
export E2B_API_KEY="e2b_xxxxx"

Python

from e2b import Sandbox
import os

# 连接参数（北京地域）
conn_opts = {}
if os.environ.get("E2B_API_URL"):
    conn_opts["api_url"] = os.environ["E2B_API_URL"]
if os.environ.get("E2B_DOMAIN"):
    conn_opts["domain"] = os.environ["E2B_DOMAIN"]

sandbox = None
try:
    sandbox = Sandbox.create(
        template="base",
        api_key=os.environ["E2B_API_KEY"],
        timeout=300,
        **conn_opts,
    )
    print(f"sandbox_id: {sandbox.sandbox_id}")

    # 执行命令
    result = sandbox.commands.run("echo 'Hello, World!' && date")
    print(result.stdout)

    # 获取端口映射地址
    address_with_host = sandbox.get_host(3000)
    print(f"port 3000 host: https://{address_with_host}")
finally:
    if sandbox is not None:
        sandbox.kill()

TypeScript

import 'dotenv/config';
import { Sandbox } from 'e2b';

async function main() {
  const sbx = await Sandbox.create({
    apiKey: process.env.E2B_API_KEY,
    timeoutMs: 300_000,
  });

  try {
    console.log(`sandboxId: ${sbx.sandboxId}`);

    // 执行命令
    const result = await sbx.commands.run("echo 'Hello, World!' && date");
    console.log(result.stdout);

    // 获取端口映射地址
    const host = sbx.getHost(3000);
    console.log(`port 3000 host: https://${host}`);
  } finally {
    await sbx.kill();
  }
}

main();

命令执行结果

commands.run 返回 CommandResult 对象，包含以下字段：

字段	类型	说明
`stdout`	`string`	命令的标准输出
`stderr`	`string`	命令的标准错误输出
`exit_code`	`int`	进程退出码，0 表示执行成功
`error`	`string`/`None`	执行错误信息（内部错误时有值）

当命令以非零退出码结束时，SDK 抛出 CommandExitException。

访问沙箱端口

get_host(port) 返回沙箱内指定端口对应的公网主机名，格式为 {port}-{sandbox_id}.{domain}。该方法为纯客户端字符串拼接，不产生 API 请求。使用时需自行拼接协议前缀：

address_with_host = sandbox.get_host(3000) 
url = f"https://{address_with_host}"

管理沙箱生命周期

方法	说明
`sandbox.kill()`	立即终止沙箱，释放所有资源。建议配合 `finally` 块调用。
`sandbox.set_timeout(seconds)`	动态修改沙箱剩余存活时间。
`Sandbox.connect(sandbox_id)`	重连运行中的沙箱，返回新的 `Sandbox` 实例。
`sandbox.is_running()`	检查沙箱是否仍在运行。

Python SDK 也支持上下文管理器，退出 with 块后自动终止沙箱：

with Sandbox.create(template="base", api_key=api_key, **conn_opts) as sbx:
    result = sbx.commands.run("echo hello")
    print(result.stdout)
# 退出 with 块后沙箱自动终止

常用参数

Sandbox.create 参数

参数	Python	TypeScript	说明
模板	`template="base"`	`template: 'base'`	沙箱模板名或模板 ID，未指定时使用默认模板（base）。
存活时间	`timeout=300`（秒）	`timeoutMs: 300_000`（毫秒）	沙箱最大存活时间，默认 300 秒，到期后沙箱自动终止。
API Key	`api_key=...`	`apiKey: ...`	云沙箱 API Key，也可通过 `E2B_API_KEY` 环境变量设置。
连接域名	`domain=...`	SDK 自动读取 `E2B_DOMAIN` 环境变量	北京地域服务入口域名。
API 地址	`api_url=...`	-	控制面 API 入口 URL，对应 `E2B_API_URL` 环境变量。
环境变量	`envs={"KEY": "value"}`	`envs: {KEY: 'value'}`	沙箱全局环境变量，所有 `commands.run` 调用均继承。
元数据	`metadata={...}`	`metadata: {...}`	自定义键值对，随沙箱存储，可通过 `get_info()` 读取。

commands.run 参数

参数	类型	说明
`cmd`	`string`	要执行的 Shell 命令，支持管道和重定向。
`background`	`bool`	是否后台执行，默认 False。设为 True 时立即返回 `CommandHandle`。
`envs`	`dict`	本次命令专属环境变量，与沙箱全局环境变量合并后生效。
`user`	`string`	以指定用户身份执行，例如 `root`。
`cwd`	`string`	命令执行时的工作目录。
`timeout`	`number`	命令执行超时时间（秒），超时后命令被终止。

配置连接参数

使用阿里云 FC Sandbox 时，需要配置北京地域的连接参数。

Python：通过 api_url 和 domain 参数传入，或设置 E2B_API_URL 和 E2B_DOMAIN 环境变量。

conn_opts = {}
if os.environ.get("E2B_API_URL"):
    conn_opts["api_url"] = os.environ["E2B_API_URL"]
if os.environ.get("E2B_DOMAIN"):
    conn_opts["domain"] = os.environ["E2B_DOMAIN"]

TypeScript：SDK 自动读取 E2B_DOMAIN 环境变量。

环境变量	说明
`E2B_API_KEY`	云沙箱 API Key（必需）
`E2B_DOMAIN`	地域域名，例如 `cn-beijing.fc-e2b.aliyuncs.com`
`E2B_API_URL`	控制面 API 入口（Python SDK 使用）