SDK 兼容性矩阵

E2B × CubeSandbox

测试结果 全部通过实测版本 1.0.0 – 2.62.0最新验证 2.62.0推荐版本 ≥ 2.15.0

Python SDK 快速上手

已有 E2B 代码可以使用 E2B Python SDK，也可以使用 CubeSandbox 原生 Python SDK。安装并配置以下环境变量即可：

pip install "e2b==2.29.5"
pip install cubesandbox

export CUBE_API_URL="http://127.0.0.1:3000"
export CUBE_API_KEY="e2b_000000"
export CUBE_TEMPLATE_ID="tpl-xxx"
export E2B_API_URL="http://127.0.0.1:3000"
export E2B_API_KEY="e2b_000000"

兼容7

部分兼容14

有替代方案3

暂不支持6

Cube 扩展5

01 · 版本

E2B版本兼容性

从 1.0.0 到 2.62.0 的每个 E2B Python SDK 版本都跑了完整的兼容性测试套件。

通过 · 95基本通过 · 8不兼容 · 53

1.0.0 · 不兼容

1.0.1 · 不兼容

1.0.2 · 不兼容

1.0.3 · 不兼容

1.0.4 · 不兼容

1.0.5 · 不兼容

1.0.6 · 不兼容

1.1.0 · 不兼容

1.2.0 · 不兼容

1.2.1 · 不兼容

1.3.0 · 不兼容

1.3.1 · 不兼容

1.3.2 · 不兼容

1.3.3 · 不兼容

1.3.4 · 不兼容

1.3.5 · 不兼容

1.4.0 · 不兼容

1.5.0 · 不兼容

1.5.1 · 不兼容

1.5.2 · 不兼容

1.5.3 · 不兼容

1.5.4 · 不兼容

1.5.5 · 不兼容

1.5.6 · 不兼容

1.6.0 · 基本通过

1.7.0 · 基本通过

1.7.1 · 基本通过

1.8.0 · 基本通过

1.9.0 · 基本通过

1.10.0 · 基本通过

1.11.0 · 基本通过

1.11.1 · 基本通过

2.0.0 · 不兼容

2.0.1 · 不兼容

2.0.2 · 不兼容

2.1.0 · 不兼容

2.1.1 · 不兼容

2.1.2 · 不兼容

2.1.3 · 不兼容

2.1.4 · 不兼容

2.1.5 · 不兼容

2.2.0 · 不兼容

2.2.1 · 不兼容

2.2.2 · 不兼容

2.2.3 · 不兼容

2.2.4 · 不兼容

2.2.5 · 不兼容

2.2.6 · 不兼容

2.2.7 · 不兼容

2.3.0 · 不兼容

2.3.1 · 不兼容

2.3.2 · 不兼容

2.3.3 · 不兼容

2.3.4 · 不兼容

2.3.5 · 不兼容

2.3.6 · 不兼容

2.4.0 · 不兼容

2.4.1 · 不兼容

2.4.2 · 不兼容

2.4.3 · 不兼容

2.5.0 · 不兼容

2.6.0 · 通过

2.6.1 · 通过

2.6.2 · 通过

2.6.3 · 通过

2.6.4 · 通过

2.7.0 · 通过

2.8.0 · 通过

2.8.1 · 通过

2.9.0 · 通过

2.9.1 · 通过

2.10.0 · 通过

2.10.1 · 通过

2.10.2 · 通过

2.11.0 · 通过

2.12.0 · 通过

2.12.1 · 通过

2.12.2 · 通过

2.13.0 · 通过

2.13.1 · 通过

2.13.2 · 通过

2.13.3 · 通过

2.14.0 · 通过

2.14.1 · 通过

2.15.0 · 通过

2.15.1 · 通过

2.15.2 · 通过

2.15.3 · 通过

2.16.0 · 通过

2.17.0 · 通过

2.18.0 · 通过

2.19.0 · 通过

2.20.0 · 通过

2.20.1 · 通过

2.20.2 · 通过

2.20.3 · 通过

2.21.0 · 通过

2.21.1 · 通过

2.22.0 · 通过

2.23.0 · 通过

2.23.1 · 通过

2.24.0 · 通过

2.25.0 · 通过

2.25.1 · 通过

2.26.0 · 通过

2.27.0 · 通过

2.27.1 · 通过

2.28.0 · 通过

2.28.1 · 通过

2.28.2 · 通过

2.29.0 · 通过

2.29.1 · 通过

2.29.2 · 通过

2.29.3 · 通过

2.29.4 · 通过

2.29.5 · 通过

2.29.6 · 通过

2.30.0 · 通过

2.31.0 · 通过

2.32.0 · 通过

2.32.1 · 通过

2.33.0 · 通过

2.34.0 · 通过

2.35.0 · 通过

2.36.0 · 通过

2.37.0 · 通过

2.37.1 · 通过

2.38.0 · 通过

2.39.0 · 通过

2.39.1 · 通过

2.40.0 · 通过

2.41.0 · 通过

2.42.0 · 通过

2.43.0 · 通过

2.44.0 · 通过

2.45.0 · 通过

2.45.1 · 通过

2.46.0 · 通过

2.46.4 · 通过

2.48.0 · 通过

2.49.0 · 通过

2.49.1 · 通过

2.50.0 · 通过

2.51.0 · 通过

2.52.0 · 通过

2.52.1 · 通过

2.53.1 · 通过

2.55.0 · 通过

2.55.1 · 通过

2.56.0 · 通过

2.57.0 · 通过

2.58.0 · 通过

2.59.0 · 通过

2.60.0 · 通过

2.61.0 · 通过

2.62.0 · 通过

1.0.02.62.0

版本区间判定套件通过版本数说明

2.15.0 – 2.62.0通过全部通过72

整套用例全部通过。

2.6.0 – 2.14.1通过部分通过23

逐项核对后判为通过——剩余失败都是这些 SDK 版本自身缺少的能力，不是平台问题。

1.6.0 – 1.11.1基本通过部分通过8

创建、命令、文件、查询均可正常使用；这些版本自身没有暂停、网络等新参数。

2.0.0 – 2.5.0不兼容未通过29

该区间未通过测试，建议使用 2.6.0 及以上版本。

1.0.0 – 1.5.6不兼容未通过24

该区间未通过测试。仅需基础能力时，1.6.0 及以上可用。

02 · API 对比

SDK API

按公开方法判断兼容性。同名方法不代表默认值、返回类型和副作用完全一致。

⌕

沙箱生命周期

Sandbox.create()

从模板创建一个新的隔离沙箱。

部分兼容

Cube 不支持：autoPauseMemory=false——Cube 始终保留内存快照，该参数会被拒绝。Cube 的默认模板环境变量为 CUBE_TEMPLATE_ID，E2B 需要显式传入模板。

查看示例 ↓收起示例 ↑

import os
from e2b import Sandbox

# 上下文管理器会在代码块结束时自动销毁沙箱。
with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"], timeout=60) as sandbox:
    print(sandbox.sandbox_id)

Sandbox.connect()

让 SDK 客户端连接到已有沙箱。

部分兼容

连接与恢复运行完全可用。唯一差异是 timeout 的含义：E2B 是固定到期时间（到点即销毁，无论是否活跃），Cube 是空闲窗口（闲置满 N 秒才回收，活跃使用会自动续活）。connect() 两边都只能延长、不能缩短，覆盖请用 set_timeout()；-1 会被 E2B v2 接口拒绝，尽管 Cube 支持永不超时。

查看示例 ↓收起示例 ↑

import os
from e2b import Sandbox

sandbox = Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"], timeout=120)
try:
    connected = Sandbox.connect(sandbox.sandbox_id, timeout=60)
    print(connected.commands.run("echo connected").stdout)
finally:
    sandbox.kill()

Sandbox.list()

分页查询当前项目中的沙箱。

部分兼容

列表查询和 state/metadata 筛选都可直接使用。唯一差异是返回形式：Cube 一次性返回普通列表，排序和开始时间/模板过滤暂不可用。

查看示例 ↓收起示例 ↑

from e2b import Sandbox

paginator = Sandbox.list(limit=10)
while paginator.has_next:
    for info in paginator.next_items():
        print(info.sandbox_id, info.state)

sandbox.get_info()

读取沙箱身份、状态、资源和时间信息。

兼容

核心字段一致（含 E2B 读取的模板名称）。Cube 额外提供磁盘大小、更细的状态信息。

查看示例 ↓收起示例 ↑

import os
from e2b import Sandbox

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    info = sandbox.get_info()
    print(info.sandbox_id, info.state, info.started_at)

sandbox.is_running()

检查沙箱当前是否仍在运行。

兼容

与 E2B 行为一致，检查沙箱当前是否仍在运行。

查看示例 ↓收起示例 ↑

import os
from e2b import Sandbox

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    print("running:", sandbox.is_running())

sandbox.kill()

永久停止并删除一个沙箱。

部分兼容

可以销毁沙箱。不支持：ID 不存在时返回 False——Cube 会改抛 not-found 错误。

查看示例 ↓收起示例 ↑

import os
from e2b import Sandbox

sandbox = Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"])
sandbox_id = sandbox.sandbox_id
removed = sandbox.kill()
print(sandbox_id, removed)

sandbox.pause()

暂停并持久化沙箱，以便之后恢复。

部分兼容

可以暂停并保留内存。不支持：keep_memory=False（仅暂停文件系统）——Cube 总是保存内存。

查看示例 ↓收起示例 ↑

import os
from e2b import Sandbox

sandbox = Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"])
sandbox_id = sandbox.sandbox_id
sandbox.pause()  # 保存当前状态，之后可以继续恢复运行。

resumed = Sandbox.connect(sandbox_id)
print(resumed.commands.run("echo resumed").stdout)
resumed.kill()

sandbox.set_timeout()

重新设置沙箱的生命周期超时时间。

部分兼容

可以重新设置超时。不支持：E2B 接口传负数——Cube 把 -1 解释为永不过期，E2B 接口则直接拒绝。

查看示例 ↓收起示例 ↑

import os
from e2b import Sandbox

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"], timeout=60) as sandbox:
    # 把当前生命周期超时时间重新设置为 5 分钟。
    sandbox.set_timeout(300)
    print(sandbox.get_info().end_at)

sandbox.update_network()

原子替换沙箱的出站网络规则。

部分兼容

可以整包替换策略。不支持：egress_proxy、https_ports 和 IAM transform；Cube 另提供有序 L7 规则。

查看示例 ↓收起示例 ↑

import os
from e2b import Sandbox

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    # 此操作会整体替换策略，因此未填写的字段会被清空。
    sandbox.update_network({"deny_out": ["10.0.0.0/8"]})
    print("network policy updated")

sandbox.get_metrics()

读取近期 CPU、内存和磁盘指标。

暂不支持

未实现该接口；Cube 通过 Cubelet 导出自己的指标。

查看示例 ↓收起示例 ↑

import os
from e2b import Sandbox

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    sandbox.commands.run("python -c 'sum(range(1000000))'")
    for sample in sandbox.get_metrics():
        print(sample)

命令、文件与 PTY

sandbox.commands.run()

在沙箱内部执行一条 Shell 命令。

兼容

命令、cwd、环境变量、用户、stdout/stderr、退出码和执行超时通过兼容的 envd process 协议工作。

查看示例 ↓收起示例 ↑

import os
from e2b import Sandbox

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    result = sandbox.commands.run(
        "python -c 'print(6 * 7)'",
        timeout=30,
    )
    print(result.stdout, result.exit_code)

commands.connect()

重新连接正在运行的后台命令。

部分兼容

执行命令正常。不支持：重连后台命令——Cube Commands 只有 run，重连请改用 PTY。

查看示例 ↓收起示例 ↑

import os
from e2b import Sandbox

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    process = sandbox.commands.run("sleep 2; echo done", background=True)
    pid = process.pid
    process.disconnect()  # 断开句柄后，进程仍会继续在沙箱中运行。
    result = sandbox.commands.connect(pid).wait()
    print(result.stdout)

commands.listkillsend_stdin

查看并控制沙箱中的运行进程。

暂不支持

未暴露这些方法；可用 PTY 控制交互进程，或用 commands.run 执行系统工具。

查看示例 ↓收起示例 ↑

import os
from e2b import Sandbox

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    process = sandbox.commands.run("cat", background=True, stdin=True)
    sandbox.commands.send_stdin(process.pid, "hello\n")
    print([item.pid for item in sandbox.commands.list()])
    sandbox.commands.kill(process.pid)

files.readwritewrite_files

读写文本或二进制文件内容。

兼容

常用文本/二进制传输和批量写入通过兼容的文件系统协议提供。

查看示例 ↓收起示例 ↑

import os
from e2b import Sandbox
from e2b.sandbox.filesystem.filesystem import WriteEntry

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    sandbox.files.write("/tmp/one.txt", "one")
    sandbox.files.write_files([
        WriteEntry(path="/tmp/two.txt", data="two"),
        WriteEntry(path="/tmp/three.bin", data=b"three"),
    ])
    print(sandbox.files.read("/tmp/one.txt"))

files.listexistsremoverenamemake_dir

管理文件以及目录结构。

兼容

常用目录和文件管理工作流已经对齐，并由双后端测试覆盖。

查看示例 ↓收起示例 ↑

import os
from e2b import Sandbox

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    sandbox.files.make_dir("/tmp/demo")
    sandbox.files.write("/tmp/demo/a.txt", "hello")
    print(sandbox.files.exists("/tmp/demo/a.txt"))
    print([entry.name for entry in sandbox.files.list("/tmp/demo")])
    sandbox.files.rename("/tmp/demo/a.txt", "/tmp/demo/b.txt")
    sandbox.files.remove("/tmp/demo")

files.get_info()

读取文件或目录的元数据。

有替代方案

Cube Python 以不同的方法名提供该能力，返回 dict，而不是 E2B 的类型化对象。

查看示例 ↓收起示例 ↑

import os
from e2b import Sandbox

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    sandbox.files.write("/tmp/info.txt", "hello")
    info = sandbox.files.get_info("/tmp/info.txt")
    print(info.name, info.type, info.path)

files.watch_dir()

监听目录中的文件系统变化。

部分兼容

可以监听目录变化。不支持：与 E2B 完全一致的句柄生命周期、事件类型和回调 API——两个 SDK 在此不同。

查看示例 ↓收起示例 ↑

import os
from e2b import Sandbox

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    sandbox.files.make_dir("/tmp/watched")
    watcher = sandbox.files.watch_dir("/tmp/watched")
    try:
        sandbox.files.write("/tmp/watched/new.txt", "hello")
        print(watcher.get_new_events())
    finally:
        watcher.stop()

sandbox.pty.*

创建并控制交互式终端。

兼容

支持 create、connect、resize、输入、kill、disconnect 和 wait；回调与异常类型仍由各 SDK 自行定义。

查看示例 ↓收起示例 ↑

import os
from e2b import PtySize, Sandbox

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    terminal = sandbox.pty.create(PtySize(rows=24, cols=80))
    sandbox.pty.send_stdin(terminal.pid, b"echo hello from PTY\n")
    sandbox.pty.resize(terminal.pid, PtySize(rows=30, cols=100))
    sandbox.pty.kill(terminal.pid)

sandbox.git.*

在沙箱中执行常见 Git 操作。

有替代方案

Cube Python 没有高层 Git facade；如果模板中安装了 Git，可以通过命令 API 调用。

查看示例 ↓收起示例 ↑

import os
from e2b import Sandbox

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    # 基础 sandbox-code 模板默认不包含 Git。
    sandbox.commands.run(
        "apt-get update -qq && apt-get install -y -qq git",
        timeout=120,
    )
    sandbox.git.clone(
        "https://github.com/octocat/Hello-World.git",
        path="/tmp/hello-world",
        depth=1,
    )
    print(sandbox.git.status("/tmp/hello-world"))

sandbox.run_code()

执行有状态代码并获得富媒体结果。

部分兼容

支持有状态执行和富媒体结果。不支持：版本错配——e2b 核心与 e2b-code-interpreter 必须配对。

查看示例 ↓收起示例 ↑

import os
from e2b_code_interpreter import Sandbox

# 需要安装 e2b-code-interpreter，并与 e2b SDK 版本保持匹配。
with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    execution = sandbox.run_code("x = 6 * 7; x")
    print(execution.results[0].text)

快照、Volume 与模板

createlistdelete_snapshot

创建、查询和删除持久化快照。

部分兼容

创建、查询、删除（含按名称）都可用。不支持：分页器式查询——Cube 返回列表加 next_token 二元组。

查看示例 ↓收起示例 ↑

import os
from e2b import Sandbox

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    sandbox.files.write("/tmp/state.txt", "snapshot me")
    snapshot = sandbox.create_snapshot(name="docs-example")

paginator = Sandbox.list_snapshots(name="docs-example")
while paginator.has_next:
    print([item.snapshot_id for item in paginator.next_items()])

Sandbox.delete_snapshot(snapshot.snapshot_id)

sandbox.fork()

把一个运行中的沙箱分叉成多个副本。

兼容

已原生支持，语义与 E2B 一致。

查看示例 ↓收起示例 ↑

import os
from e2b import Sandbox

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as parent:
    parent.files.write("/tmp/shared.txt", "before fork")
    children = parent.fork(count=2, timeout=60)
    for child in children:
        if isinstance(child, Exception):
            print("fork failed:", child)
            continue
        print(child.files.read("/tmp/shared.txt"))
        child.kill()

Volume.createconnectlistdestroy

独立于沙箱管理持久化 Volume。

部分兼容

增删改查与挂载可用。不支持：E2B 风格的驱动名称——Cube 使用运维方安装的驱动，另支持可选名称和单次挂载只读。

查看示例 ↓收起示例 ↑

from uuid import uuid4
from e2b import Volume

volume = Volume.create(f"docs-{uuid4().hex[:8]}")
connected = Volume.connect(volume.volume_id)
print(connected.volume_id)
print([(item.volume_id, item.name) for item in Volume.list()])
Volume.destroy(volume.volume_id)

volume.read_filewrite_filelist

通过 Volume 服务直接访问其中的文件。

暂不支持

Cube 没有独立的 Volume 内容服务；请先挂载，再通过 sandbox.files 访问。

查看示例 ↓收起示例 ↑

from uuid import uuid4
from e2b import Volume

volume = Volume.create(f"docs-{uuid4().hex[:8]}")
try:
    volume.write_file("/hello.txt", "hello", force=True)
    print(volume.read_file("/hello.txt"))
    print([entry.name for entry in volume.list("/")])
finally:
    Volume.destroy(volume.volume_id)

Template.build() fluent API

定义并构建可复用的沙箱模板。

有替代方案

模板系统不互通；Cube 基于 OCI 镜像构建，有自己的模板工具。

查看示例 ↓收起示例 ↑

from uuid import uuid4
from e2b import Template

template = (
    Template()
    .from_python_image("3.12")
    .run_cmd("python --version")
)
# 构建可能需要几分钟，并会在当前项目中创建模板。
Template.build(template, f"docs-python-{uuid4().hex[:8]}")

Sandbox.create(template=snapshot_id)

从可复用快照创建或恢复沙箱。

部分兼容

双方都支持用快照 ID 创建新沙箱。E2B 的快照在托管集群内天然可跨节点恢复；Cube 的跨节点恢复要求快照使用 S3 后端、远端状态就绪且宿主机兼容，同节点恢复使用本地存储即可。

查看示例 ↓收起示例 ↑

import os
from e2b import Sandbox

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as source:
    source.files.write("/tmp/state.txt", "portable state")
    snapshot = source.create_snapshot()

try:
    # E2B 的快照本身就是模板，任何节点都可以恢复。
    with Sandbox.create(template=snapshot.snapshot_id) as restored:
        print(restored.files.read("/tmp/state.txt"))
finally:
    Sandbox.delete_snapshot(snapshot.snapshot_id)

平台服务

sandbox.get_mcp_token()

获取已启用 MCP Gateway 的访问令牌。

部分兼容

Cube SDK 可用：在沙箱内启动网关并返回地址和令牌。不支持：E2B SDK 自身的令牌接口——使用 MCP 请改用 Cube SDK。

查看示例 ↓收起示例 ↑

import os
from e2b import Sandbox

mcp = {
    "github/modelcontextprotocol/servers": {
        "run_cmd": "npx -y @modelcontextprotocol/server-everything"
    }
}
with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"], mcp=mcp) as sandbox:
    print(sandbox.get_mcp_token())

Sandbox.create(iam=...)

为沙箱配置短期工作负载身份。

暂不支持

未实现 E2B workload identity；Cube 将凭据保留在 Guest 之外。

查看示例 ↓收起示例 ↑

import os
from e2b import Sandbox, Secret

identity = Secret.iam_token(
    audience="sts.amazonaws.com",
    token_type="JWT-SVID",
)
with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"], iam={"tokens": {"aws": identity}}) as sandbox:
    print(sandbox.sandbox_id)

Secret.*

创建、轮换、查询和删除项目密钥。

暂不支持

Cube 没有 E2B Secrets API；密钥由部署系统或 CubeEgress 管理。

查看示例 ↓收起示例 ↑

from uuid import uuid4
from e2b import Secret

name = f"docs-{uuid4().hex[:8]}"
created = Secret.create(name, "initial-value")
Secret.update(name, "rotated-value")
print(Secret.get_info(name))  # 密钥值只可写入，不会由查询接口返回。
print(Secret.list(limit=10).next_items())
Secret.destroy(created.secret_id)

AsyncSandboxasync resources

在异步 Python 程序中使用沙箱资源。

暂不支持

Cube Python 是同步 API；异步场景请使用原生 Node.js 或 Go SDK。

查看示例 ↓收起示例 ↑

import os
import asyncio
from e2b import AsyncSandbox

async def main():
    sandbox = await AsyncSandbox.create(template=os.environ["CUBE_TEMPLATE_ID"])
    try:
        result = await sandbox.commands.run("echo async")
        print(result.stdout)
    finally:
        await sandbox.kill()

asyncio.run(main())

Cube 扩展能力

sandbox.rollback()

把运行中的沙箱恢复到之前的快照状态。

Cube 扩展

Cube 可在保持沙箱 ID 不变的情况下原地恢复文件系统和内存；E2B 有快照和 fork，但没有等价的原地回滚方法。

查看示例 ↓收起示例 ↑

from cubesandbox import Sandbox

with Sandbox.create() as sandbox:
    sandbox.files.write("/tmp/value.txt", "v1")
    snapshot = sandbox.create_snapshot()
    try:
        sandbox.files.write("/tmp/value.txt", "v2")
        sandbox.rollback(snapshot.snapshot_id)
        print(sandbox.files.read("/tmp/value.txt"))
    finally:
        Sandbox.delete_snapshot(snapshot.snapshot_id)

Volume.create(driver=...)VolumeMount(read_only=True)

选择 Volume 后端并控制单次挂载模式。

Cube 扩展

Volume 的增删改查与挂载是双方共有的 E2B 兼容工作流；只有这两个参数是 Cube 独有的：指定运维方安装的 Volume 驱动、把某一次挂载设为只读。

查看示例 ↓收起示例 ↑

from cubesandbox import Sandbox, Volume, VolumeMount

# CUBE_VOLUME_DRIVER 必须指向已经配置的 Cube Volume 插件。
volume = Volume.create("docs-data", driver=os.environ["CUBE_VOLUME_DRIVER"])
try:
    with Sandbox.create(
        volume_mounts={"/data": VolumeMount(volume, read_only=True)}
    ) as sandbox:
        print(sandbox.files.list("/data"))
finally:
    Volume.destroy(volume.volume_id)

sandbox.update_network(rules=...)

应用高级有序 L7 出站动作。

Cube 扩展

Cube 增加有序 L7 规则：可按主机、端口、路径放行或拒绝，并支持审计和请求头注入。

查看示例 ↓收起示例 ↑

from cubesandbox import Action, Match, Rule, Sandbox

rule = Rule(
    name="allow-example-api",
    match=Match(host="api.example.com", path="/v1/"),
    action=Action(allow=True, audit="metadata"),
)
with Sandbox.create() as sandbox:
    sandbox.update_network({"rules": [rule]})

Sandbox.create(distribution_scope=...)

限制沙箱可以被调度到哪些节点。

Cube 扩展

Cube 可以限制沙箱可调度的计算节点，或将其固定到单个节点；E2B 公共 SDK 没有等价的放置控制。

查看示例 ↓收起示例 ↑

from cubesandbox import Sandbox

# 使用 CubeOps 返回的计算节点 ID 或宿主机 IP。
with Sandbox.create(
    distribution_scope=[os.environ["CUBE_COMPUTE_NODE"]]
) as sandbox:
    print(sandbox.sandbox_id)

GET /v1/metrics/resource

向 Prometheus 暴露原生沙箱资源指标。

Cube 扩展

Cubelet 分别导出宿主机与 Guest 的资源指标，供 Prometheus 使用。

查看示例 ↓收起示例 ↑

import os
from urllib.request import urlopen

cubelet_url = os.environ.get("CUBELET_URL", "http://127.0.0.1:9998")
url = f'{cubelet_url.rstrip("/")}/v1/metrics/resource'
with urlopen(url, timeout=5) as response:
    print(response.read().decode())

03 · Cube API

REST API 兼容性

SDK 之下的协议层：逐端点对比 e2b 客户端与 CubeAPI 的路径、入参、响应与错误码。

沙箱

POST/v2/sandboxes有差异

缺 secure/iam 入参，其余一致（响应含 alias）。

GET/v2/sandboxes有差异

支持 state/metadata 筛选；缺排序、开始时间和模板筛选。

GET/sandboxes/{id}一致

必填字段齐全（endAt、alias、磁盘大小）。

DELETE/sandboxes/{id}有差异

路由一致；404 时 e2b 返回 False、Cube 抛异常。

POST/v2/sandboxes/{id}/connect有差异

缺 on_resume 参数；恢复固定回到保存时的状态。

POST/sandboxes/{id}/pause不兼容

keep_memory=false 被拒绝；暂停总是保留内存。

POST/sandboxes/{id}/timeout一致

完全一致；-1 表示永不超时。

POST/sandboxes/{id}/fork一致

一致；一次快照派生多份，逐个返回结果。

POST/sandboxes/{id}/snapshots不兼容

mode="filesystem" 被拒绝；快照总是保留内存。

PUT/sandboxes/{id}/network有差异

缺 egress_proxy、https_ports 参数。

GET/sandboxes/{id}/metrics缺失

无此路由；请使用 Cubelet 指标。

POST/sandboxes/{id}/resumeCube 独有

Cube 独有：显式恢复。

POST/sandboxes/{id}/rollbackCube 独有

Cube 独有：原地回滚。

POST/sandboxes/{id}/cloneCube 独有

Cube 独有：克隆沙箱。

快照

GET/snapshots一致

支持按名称过滤，分页一致。

DELETE/templates/{id or name}一致

按 ID 或名称删除快照，返回 bool；名称歧义时返回 409。

DELETE/templates/{id}一致

模板删除一致。

模板

GET/templates有差异

返回扁平列表；缺 public/builds 字段。

GET/templates/aliases/{alias}不兼容

缺 aliases 字段，e2b 模型解析失败。

GET/templates/{id}一致

字段齐全。

POST/templates不兼容

构建模型不同：e2b 收 Dockerfile DSL，Cube 收镜像引用。

GET/v2/templates缺失

无 v2 模板路由（tags 相关）。

POST/templates/tags缺失

无 tags 模型。

GET/templates/{id}/builds/{bid}/status有差异

缺 log_entries；多 progress/message。

GET/templates/{id}/builds/{bid}/logsCube 独有

Cube 独有：构建日志。

POST/templates/{id}/rebuildCube 独有

Cube 独有：重新构建。

PUT/templates/{id}/aliasCube 独有

Cube 独有：写入别名。

Volume

POST/volumes一致

一致（name 可省略；响应缺 domain 字段）。

GET/volumes一致

一致。

GET/volumes/{id}一致

一致（缺 domain 字段）。

DELETE/volumes/{id}一致

一致；404 返回 False。

*/volumecontent/**缺失

卷内容 API 整组缺失（7 个端点）；请先挂载，再通过 sandbox.files 访问。

ENVD 数据面

RPCprocess / filesystem / files / execute一致

命令、文件、PTY、代码执行全部一致。

数据面不经 CubeAPI：CubeProxy 直接转发到沙箱内的 envd（编译自上游 e2b-dev/infra），请求体、流式分片与错误帧完全一致；固定地址流量通过 E2b-Sandbox-* 头路由。

Kubernetes 部署

框架与工具集成

案例实践

E2B × CubeSandbox

Python SDK 快速上手

E2B版本兼容性

SDK API

沙箱生命周期

命令、文件与 PTY

快照、Volume 与模板

平台服务

Cube 扩展能力

REST API 兼容性

沙箱

快照

模板

Volume

ENVD 数据面