第一个沙箱

这一页的目标是跑通最小闭环：有一个 READY 模板，用 SDK 创建沙箱，在隔离环境里执行代码，然后释放资源。

前提

你需要已经完成：

• CubeAPI 可访问，默认 http://127.0.0.1:3000。
• WebUI 可访问，默认 http://<host>:12088。
• 至少一个模板处于 READY 状态。

如果还没有模板，先按 快速开始的模板创建步骤 创建一个代码解释器模板。

创建模板

示例命令如下：

cubemastercli tpl create-from-image \
  --image cube-sandbox-cn.tencentcloudcr.com/cube-sandbox/sandbox-code:latest \
  --writable-layer-size 1G \
  --expose-port 49999 \
  --expose-port 49983 \
  --probe 49999

命令会返回 job_id。继续观察构建进度：

cubemastercli tpl watch --job-id <job_id>

模板进入 READY 后，记下输出里的 template_id。

TIP

--probe 是模板制作中的健康探针。它告诉平台等沙箱内指定端口准备好之后再打快照，避免模板虽然创建成功但运行时服务还没起来。

配置 SDK 环境变量

E2B 兼容路径使用这些变量：

export E2B_API_URL="http://127.0.0.1:3000"
export E2B_API_KEY="e2b_000000"
export CUBE_TEMPLATE_ID="<你的 template_id>"
export SSL_CERT_FILE="/root/.local/share/mkcert/rootCA.pem"

变量	说明
E2B_API_URL	指向本地 CubeAPI，而不是 E2B 云服务。
E2B_API_KEY	本地未开启鉴权时可填任意非空字符串；开启鉴权时填真实 Key。
CUBE_TEMPLATE_ID	创建沙箱时使用的模板。
SSL_CERT_FILE	信任本地 mkcert CA，用于访问沙箱服务时的 TLS。

安装 Python SDK：

pip install e2b-code-interpreter

执行第一段代码

import os
from e2b_code_interpreter import Sandbox

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    result = sandbox.run_code("print('Hello from CubeSandbox')")
    print(result)

这段代码完成了四件事：

1. SDK 向 CubeAPI 发起创建沙箱请求。
2. CubeMaster 调度到某个 Cubelet。
3. 节点从模板恢复 MicroVM。
4. SDK 在沙箱内执行 Python 代码，并把结果返回。

用 WebUI 观察

打开 http://<控制节点 IP>:12088，重点看三个页面：

页面	看什么
Overview	节点是否健康，资源是否有余量。
Templates	模板是否 READY，有没有构建失败。
Sandboxes	新建沙箱的状态、日志、暂停/销毁动作。

当你运行上面的 Python 代码时，可以在 Sandboxes 页面看到沙箱出现、运行，然后在 with 退出后被销毁。

试两个小练习

练习 1：保留文件状态

import os
from e2b_code_interpreter import Sandbox

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sb:
    sb.run_code("open('/tmp/cube.txt', 'w').write('stateful')")
    out = sb.run_code("print(open('/tmp/cube.txt').read())")
    print(out.logs.stdout)

同一个沙箱内，文件系统状态会跨多次调用保留。

练习 2：关闭公网

import os
from e2b_code_interpreter import Sandbox

with Sandbox.create(
    template=os.environ["CUBE_TEMPLATE_ID"],
    allow_internet_access=False,
) as sb:
    out = sb.commands.run("curl -m 2 https://example.com || true")
    print(out.stderr or out.stdout)

这能帮你直观理解网络策略不是事后审计，而是在数据面直接阻断。

常见失败点

现象	常见原因
SDK 连接不上	E2B_API_URL 端口不对，或 CubeAPI 未启动。
模板一直不是 READY	镜像拉取慢、探针端口不对、XFS/磁盘空间问题。
HTTPS 访问沙箱报证书错误	SSL_CERT_FILE 没指向 mkcert root CA，或模板未烘入 CubeEgress CA。
创建沙箱超时	KVM/PVM 未就绪、节点资源不足、模板文件缺失。

下一步

继续阅读 模板体系，理解为什么模板是 CubeSandbox 毫秒级启动的核心。