快速开始

四步完成 Cube Sandbox 的完整部署，无需本地构建。

下面的流程会引导你在腾讯云购买一台普通云服务器，通过 PVM 启用 KVM，然后在这台服务器上安装并体验 Cube Sandbox。

⚠️请严格按照文档操作，这样能让你在几分钟内快速体验到CubeSandbox！

生产环境注意

如果您计划在生产环境中使用 Cube Sandbox，请参阅网络加固指南，在将服务暴露到不可信网络之前完成安全加固。

已经有支持 KVM 的服务器？

如果你已经有一台开启了 KVM 的 x86_64 Linux 服务器（物理机或裸金属服务器），可以直接参阅裸金属 / 物理机部署，跳过 PVM 安装步骤。

前置条件

• x86_64 架构的云服务器（普通云服务器即可，无需 /dev/kvm）
• 有 root 权限
• 可访问互联网（用于下载发布包、拉取 Docker 镜像）

🖥 受支持的系统

CubeSandbox 二进制文件基于 Ubuntu 20.04（glibc 2.31） 构建，系统 glibc 必须 ≥ 2.31，否则二进制无法运行。

系统	状态	说明
🏆 OpenCloudOS 9	✅ 推荐	最佳兼容性，默认 XFS 文件系统，生产就绪
🏆 TencentOS 4	✅ 推荐	最佳兼容性，默认 XFS 文件系统，生产就绪
Ubuntu（20.04 / 22.04 / 24.04）	✅ 已测试	glibc 2.31+ — 可用。需手动配置 XFS →
其他 RPM 系（CentOS、RHEL 等）	⚠️ 检查 glibc	glibc 必须 ≥ 2.31，且 /data/cubelet 需为 XFS
Debian / WSL	⚠️ 检查 glibc	同上要求；详见 XFS FAQ →

ℹ️ 为什么需要 XFS？ CubeSandbox 依赖 XFS reflink 实现 Copy-on-Write 快照。Ubuntu / Debian / WSL 默认使用 ext4，你需要将 XFS 文件系统挂载到 /data/cubelet。逐步操作指南见 FAQ #311。

💾 磁盘空间

/data/cubelet 至少需要 50 GB 可用磁盘空间，用于存放沙箱镜像和可写层。如需制作多个模板或自定义镜像，建议 200 GB 及以上。

第一步：购买云服务器并安装 PVM 内核

购买云服务器

在腾讯云购买一台 x86_64 架构的云服务器，无特殊要求。

操作系统推荐选择 OpenCloudOS 9（RPM 系）。Cube Sandbox 的 PVM 宿主机内核基于 OpenCloudOS 内核构建，选用 OpenCloudOS 9 可获得最佳兼容性，且无需处理发行版差异。Ubuntu / Debian / CentOS 等其他主流发行版同样支持。

配置	CPU	内存	磁盘
功能体验	≥ 4 核	≥ 8 GB	≥ 50 GB
推荐	32 核	64 GB	≥ 200 GB

以 root 身份执行所有操作

本文档中的所有命令均需在 root 用户下执行。请先切换到 root：

sudo su root

安装 PVM 宿主机内核

前往 CubeSandbox Releases 页面，打开最新包含 PVM 内核附件的 Release，在对应附件上右键 → 复制链接地址，然后用 wget 下载。

根据你的 Linux 发行版选择对应格式：

RPM 系（OpenCloudOS、RHEL、CentOS、TencentOS、Fedora）

在 Release 附件列表 中找到 kernel-*opencloudos9.cubesandbox.pvm.host*.x86_64.rpm，右键复制下载链接：

# 将下面的 URL 替换为你从 Releases 页面右键复制的实际下载链接
wget "<kernel rpm 下载链接>"

# 若宿主机已有更高版本内核，--oldpackage 跳过版本号比较
rpm -ivh --oldpackage kernel-*.rpm

设置 PVM 内核为默认启动项：

# 查看已安装内核列表，找到 PVM 内核对应的序号
grubby --info=ALL | grep -E "^kernel|^index"

# 将 <index> 替换为上面输出中 PVM 内核对应的数字
grubby --set-default-index=<index>

# 确认设置生效
grubby --default-kernel

配置内核启动参数：

curl -sL https://cnb.cool/CubeSandbox/CubeSandbox/-/git/raw/master/deploy/pvm/grub/host_grub_config.sh | bash

DEB 系（Ubuntu、Debian）

在 Release 附件列表 中找到 linux-image-*opencloudos9.cubesandbox.pvm.host*_amd64.deb，右键复制下载链接：

# 将下面的 URL 替换为你从 Releases 页面右键复制的实际下载链接
wget "<linux-image deb 下载链接>"

dpkg -i linux-image-*opencloudos9.cubesandbox.pvm.host*.deb

设置 PVM 内核为默认启动项：

# 查看已安装的内核列表，确认 PVM 内核版本字符串
ls /boot/vmlinuz-*

# 将 GRUB 默认启动项指向 PVM 内核（将下面的内核版本替换为上一步看到的实际版本字符串）
KVER="$(ls /boot/vmlinuz-*opencloudos9.cubesandbox.pvm.host* | sed 's|/boot/vmlinuz-||' | tail -1)"
sed -i "s|^GRUB_DEFAULT=.*|GRUB_DEFAULT=\"Advanced options for Ubuntu>Ubuntu, with Linux ${KVER}\"|" \
  /etc/default/grub

配置内核启动参数（脚本内部会调用 update-grub 使上述设置生效）：

curl -sL https://cnb.cool/CubeSandbox/CubeSandbox/-/git/raw/master/deploy/pvm/grub/host_grub_config.sh | bash

重启并验证

reboot

重启后，确认已进入 PVM 内核并加载 KVM 模块：

# 确认内核版本
uname -r
# 期望输出包含：opencloudos9.cubesandbox.pvm.host

# 加载 PVM KVM 模块
modprobe kvm_pvm

# 确认模块已加载
lsmod | grep kvm
# 期望输出中包含 kvm_pvm

设置开机自动加载 kvm_pvm 模块：

echo 'kvm_pvm' > /etc/modules-load.d/kvm-pvm.conf

什么是 PVM？（技术原理）

PVM（Pagetable-based Virtual Machine）是一种基于页表的嵌套虚拟化框架，构建于 KVM 之上。与传统嵌套虚拟化不同，PVM 不依赖宿主 hypervisor 向 guest 暴露 Intel VT-x / AMD-V 等硬件虚拟化扩展，而是在 guest 内核层通过共享内存区域和影子页表（shadow page table）来完成特权级切换与内存虚拟化，对宿主 hypervisor 完全透明。

腾讯云已在生产环境大规模部署 PVM 实例，可靠性经过充分验证，并将改进成果开源至 OpenCloudOS 内核。

完整的 PVM 部署说明请参阅 PVM 部署。

第二步：安装

以 root 身份执行：

curl -sL https://cnb.cool/CubeSandbox/CubeSandbox/-/git/raw/master/deploy/one-click/online-install.sh | CUBE_PVM_ENABLE=1 MIRROR=cn bash

跳过下载前环境检测（Precheck）

在线安装脚本默认会在下载庞大的发布包前对系统环境（操作系统、内存、KVM 支持、/data/cubelet 文件系统为 XFS 等）进行轻量前置检测，以防下载大包后因环境不满足而安装失败。 如需在特定测试环境跳过该下载前检测，可通过设置环境变量 ONE_CLICK_SKIP_PRECHECK=1 或传递参数 --skip-precheck 绕过：

# 方式 A：通过环境变量绕过
curl -sL https://cnb.cool/CubeSandbox/CubeSandbox/-/git/raw/master/deploy/one-click/online-install.sh | ONE_CLICK_SKIP_PRECHECK=1 CUBE_PVM_ENABLE=1 MIRROR=cn bash

# 方式 B：通过脚本传参绕过
curl -sL https://cnb.cool/CubeSandbox/CubeSandbox/-/git/raw/master/deploy/one-click/online-install.sh | CUBE_PVM_ENABLE=1 MIRROR=cn bash -s -- --skip-precheck

⚠️ 注意：跳过前置检测仅影响 online-install.sh 的包下载拦截。解压后实际执行部署的 install.sh 仍会强制执行最权威的系统条件检测，以确保系统稳定运行。

安装了哪些组件

• E2B 兼容 REST API 监听在 3000 端口
• CubeMaster、Cubelet、network-agent、CubeShim 作为宿主机进程运行
• MySQL 和 Redis 通过 Docker Compose 管理
• CubeProxy 提供 TLS（mkcert）和 CoreDNS 域名路由（cube.app）

第三步：制作模板

安装完成后，使用预构建镜像创建代码解释器模板：

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

镜像仓库说明： 国内优先使用 cube-sandbox-cn.tencentcloudcr.com/cube-sandbox/sandbox-code:latest；境外访问推荐使用 cube-sandbox-int.tencentcloudcr.com/cube-sandbox/sandbox-code:latest。

然后，执行下面的这行命令，监控构建进度：

cubemastercli tpl watch --job-id <job_id>

⚠️ 注意：由于镜像比较大，下载、解压、模板制作过程可能比较久，请耐心等待。

等待上述命令结束，模板状态变为 READY。

记录输出中的模板 ID (template_id)，下一步会用到。

完整的模板创建流程和更多参数说明，请参阅从 OCI 镜像制作模板。

第四步：运行第一段 Agent 代码

安装 Python SDK：

yum (RPM)

yum install -y python3 python3-pip

apt (DEB)

apt update && apt install -y python3 python3-pip

pip config set global.index-url https://mirrors.ustc.edu.cn/pypi/simple

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="<你的模板ID>"
export SSL_CERT_FILE="/root/.local/share/mkcert/rootCA.pem"

变量	说明
E2B_API_URL	将 E2B SDK 请求指向本地 Cube Sandbox，而非 E2B 官方云服务
E2B_API_KEY	SDK 强制非空校验，本地部署填任意字符串即可
CUBE_TEMPLATE_ID	第三步获取的模板 ID
SSL_CERT_FILE	mkcert 签发的 CA 根证书路径，沙箱 HTTPS 连接需要

在隔离沙箱中运行代码：

import os
from e2b_code_interpreter import Sandbox  # 直接使用 E2B SDK！

# CubeSandbox 在底层无缝接管了所有的请求
with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    result = sandbox.run_code("print('Hello from Cube Sandbox, safely isolated!')")
    print(result)

更多端到端示例，请参阅示例项目。

下一步

• 从 OCI 镜像制作模板 — 自定义沙箱运行环境
• 裸金属 / 物理机部署 — 已有支持 KVM 的机器直接部署
• 多机集群部署 — 扩展到多台机器
• HTTPS 证书与域名解析 — TLS 配置选项
• 鉴权 — 启用 API 鉴权

附录：从源码构建

以上步骤使用的是预构建发布包。如果需要自定义组件、使用特定 commit 或参与开发贡献，可以自行构建发布包。完整说明请参阅本地构建部署。