裸金属 / 物理机部署

适用场景： 已有支持 KVM 的 x86_64 或 aarch64（ARM64）Linux 机器（/dev/kvm 可用），例如物理机、裸金属服务器、或已开启嵌套虚拟化的云服务器。

如果你用的是普通云服务器（/dev/kvm 不可用），无需裸金属 —— 通过 PVM 即可在普通云服务器上启用 KVM，请参阅快速开始。

生产环境注意

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

前置条件

• x86_64 或 aarch64（ARM64）架构的 Linux 机器
• /dev/kvm 存在且可读写（ls -la /dev/kvm）
• 有 root 权限
• Docker 已安装并正常运行
• 可访问互联网（用于下载发布包、拉取 Docker 镜像）
• 内存 ≥ 8 GB，磁盘空余 ≥ 50 GB

以 root 身份执行所有操作

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

sudo su root

第一步：安装

x86_64（AMD64）

以 root 身份执行：

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

ARM64（aarch64）主机

online-install.sh 即将支持 ARM64

online-install.sh 一键安装脚本当前仅自动发现 x86_64 包。ARM64 的自动检测与一键安装支持将于近期版本补齐。目前 ARM64 用户请按照以下手动步骤操作。

第一步： 前往对应平台的发布页面，找到包含 ARM64 资产的最新 Release，下载 cube-sandbox-one-click-*-arm64.tar.gz 包：

平台	发布页面
GitHub	TencentCloud/CubeSandbox/releases
CNB（国内）	CubeSandbox/CubeSandbox/-/releases

第二步： 解压并运行安装脚本：

# 将 <version> 替换为你实际下载的版本（如 v0.5.0-rc3）
tar -xzf cube-sandbox-one-click-<version>-arm64.tar.gz
cd cube-sandbox-one-click-<version>-arm64
./install.sh

安装了哪些组件

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

无 guest PMU 的 ARM64 主机

在部分 aarch64 主机上——较旧的内核、嵌套虚拟化环境、或某些 ARM 核心——KVM 不会向 guest 暴露 PMUv3。这些主机上 MicroVM 仍可正常启动：hypervisor 会在不启用 PMU 的情况下初始化 vCPU，guest 只是看不到硬件性能计数器，无需任何额外操作。

第二步：制作模板

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

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 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 镜像制作模板 — 自定义沙箱运行环境
• 多机集群部署 — 扩展到多台机器
• HTTPS 证书与域名解析 — TLS 配置选项
• 鉴权 — 启用 API 鉴权