首页 / 开源热榜 / CubeSandbox / 使用教程

CubeSandbox 中文教程：先过宿主机门槛，再接 E2B SDK

官方资料核对：2026-09-23 · 文档核对，未部署 MicroVM

CubeSandbox 用 RustVMM 与 KVM 为 AI Agent 提供 MicroVM 沙箱，并提供 E2B 兼容 API。当前最新正式版是 v0.7.1；v0.7.2-rc1 是预发布版。

这不是普通应用安装：官方快速路径要求 root，会安装宿主内核、修改 GRUB 并重启。先用能回滚的测试服务器，生产机器不要照抄。

1. 先选原生 KVM 还是 PVM

环境	路径	关键限制
x86_64 裸金属或已暴露 KVM	官方 Bare-metal Deployment	直接使用原生 KVM
x86_64 普通云主机，没有 /dev/kvm	PVM Quick Start	安装项目提供的宿主内核并重启
ARM64	原生 KVM 裸金属或 Self-build	PVM 宿主内核不支持 ARM64

官方快速开始的功能体验配置是至少 4 核、8GB 内存、50GB 磁盘，推荐 32 核、64GB 和 200GB 以上。二进制基于 Ubuntu 20.04 构建，要求 glibc 2.31 或更高。

2. XFS 是硬条件，不是性能建议

uname -m
ldd --version | head -n 1
findmnt -no FSTYPE /data/cubelet
df -h /data/cubelet

CubeSandbox 的写时复制快照依赖 XFS reflink，因此 /data/cubelet 必须在 XFS 上。Ubuntu、Debian 和 WSL 常见默认盘是 ext4，需要另备数据盘或文件系统。官方要求至少 50GB；多模板或自定义镜像建议 200GB 以上。

3. PVM 路径会改宿主机

官方流程要求从专用 kernel-release-* 下载适合 RPM 或 DEB 的主内核包，设为默认启动项，再运行 GRUB 配置脚本并重启。重启后应先验证：

uname -r
modprobe kvm_pvm
lsmod | grep kvm

输出应包含项目 PVM 内核标识与 kvm_pvm。如果没有，不要继续安装控制面。内核回滚、远程控制台和磁盘快照应在修改前准备好。

4. 安装控制面并了解它装了什么

# 仅在已核对脚本、可回滚的测试机，以 root 执行
curl -sL https://github.com/tencentcloud/CubeSandbox/raw/master/deploy/one-click/online-install.sh \
  | CUBE_PVM_ENABLE=1 bash

官方说明安装器会部署监听 3000 端口的 E2B 兼容 API、CubeMaster、Cubelet、CubeShim、CubeProxy、CoreDNS，并通过 Docker Compose 管理 MySQL 和 Redis。跳过预检只影响提前下载检查，正式安装仍会强制系统约束。

5. 创建第一个模板

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

cubemastercli tpl watch --job-id <job_id>

等状态变成 READY 后记录模板 ID。官方当前只明确 sandbox-code:latest 是多架构镜像，其他官方镜像可能尚未覆盖 ARM64。

6. 用 E2B SDK 做最小验证

python3 -m venv .venv
source .venv/bin/activate
pip install e2b-code-interpreter

export E2B_API_URL="http://127.0.0.1:3000"
export E2B_API_KEY="e2b_000000"
export CUBE_TEMPLATE_ID="<your-template-id>"
export SSL_CERT_FILE="/root/.local/share/mkcert/rootCA.pem"

先执行无网络、无秘密的简单命令，记录创建时间、退出码和日志。换 URL 能降低客户端迁移成本，但官方路线图仍列有 E2B 兼容补齐工作；模板、文件、命令、超时、快照和错误语义都要跑合约测试。

7. 性能数字应怎样读

README 的冷启动数据来自项目方裸金属测试：单并发约 60ms，50 并发平均 67ms、P95 90ms、P99 137ms。单实例小于 5MB 也有沙箱规格不超过 32GB等前提。宿主内核、磁盘、镜像、网络和并发都会改变结果，容量规划必须用自己的负载复测。

8. 和 E2B 怎么比较

相比 E2B 官方 infra，CubeSandbox 强调兼容 E2B SDK 并让用户自建控制面、网络和节点；E2B SDK 默认连接 E2B Cloud，也公开了自托管基础设施代码。需要控制数据面并愿意承担内核、XFS、数据库和集群运维时，可评估 CubeSandbox；想少运维时，应直接比较 E2B Cloud 的当前服务和费用。

9. v0.7.1 与验证边界

v0.7.1 于 2026-09-11 发布，新增独立模板中心、CubeMaster 多副本、CLM 主备，并让 Host Mount 和 Volume Plugin 支持快照、恢复、回滚与克隆。版本还包含 virtiofsd 加固、外部 PostgreSQL、S3 快照开关及部署修复。

验证状态：本轮核对官方 README、Quick Start、v0.7.1 changelog 与 Release。没有 root/KVM 测试机，未安装内核、未运行脚本、未创建 MicroVM。

验证边界：未验证安装器、内核兼容、E2B 合约、启动时间、内存、网络隔离、快照一致性、控制面高可用或云上部署。生产暴露服务前必须按官方 Network Hardening 文档配置。

这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。

先判断这个项目是否适合你

近期变化与关注原因

Agent 执行未知代码需要比共享宿主内核的普通容器更强的隔离，同时又要控制启动时间和密度。CubeSandbox 把 MicroVM、快照、eBPF 网络策略、E2B 兼容接口和集群部署放在一个开源项目中；v0.7.1 又补上控制面高可用和外部挂载快照。

适合谁用

适合自建 Code Interpreter、需要多租户未知代码隔离的 Agent 平台、已有 E2B 客户端但需要自管基础设施的团队，以及需要快照分叉的评测任务。不适合没有 root/KVM/XFS 条件、不能承担宿主内核与控制面运维，或只需要简单容器任务隔离的小型应用。

采用建议

CubeSandbox 适合有 Linux 虚拟化和平台运维能力、确实需要自建强隔离执行面的团队。评估顺序应是先在可回滚服务器验证内核、XFS 与最小 E2B 流程，再测安全策略和容量；只想快速调用托管沙箱时，自建这套控制面可能过重。

原教程未展开的系统信息

核心功能

MicroVM 硬件隔离
每个沙箱运行独立 Guest OS 内核，虚拟化层由 KVM、CubeHypervisor 与 containerd Shim v2 组成。
E2B SDK 兼容接口
CubeAPI 和 CubeProxy 提供 E2B 兼容路径，客户端可通过修改 API URL 接入自建服务；兼容差距仍在官方路线图中。
网络和凭据边界
eBPF 负责沙箱间隔离和出站过滤，L7 代理可按域名、路径和方法控制请求，并在沙箱外注入凭据。

版本与同类选择

常见问题

普通云服务器没有 /dev/kvm，能安装 CubeSandbox 吗？

x86_64 普通云主机可按官方 Quick Start 安装 PVM 宿主内核，重启后加载 kvm_pvm；这会改动宿主内核，应只在可回滚测试机验证。ARM64 不支持这条 PVM 路径。

CubeSandbox 为什么要求 /data/cubelet 使用 XFS？

官方说明快照和写时复制依赖 XFS reflink。Ubuntu、Debian 和 WSL 常见的 ext4 默认盘不满足要求，需要另行准备并挂载 XFS，至少留出 50GB。

把 E2B_API_URL 改掉就能完全替代 E2B 吗？

客户端迁移入口确实是修改 API URL，但官方路线图仍写有继续补齐 E2B API 兼容差距。上线前要对模板、文件、命令、超时、快照和错误语义跑自己的合约测试。

README 的 60ms 启动和 5MB 开销能直接当容量规划依据吗？

不能。60ms 来自官方裸金属测试，50 并发时平均 67ms、P95 90ms、P99 137ms；内存数字也有规格前提。应在自己的内核、磁盘、镜像和并发下重测。