一个极速启动、高并发、安全且轻量化的 AI Agent 沙箱服务
Cube Sandbox 是一款基于 RustVMM 与 KVM 构建的高性能、开箱即用的安全沙箱服务。它既支持单机部署，也能够很方便的扩展到多台机器的集群服务。同时对外兼容E2B SDK， 在60ms内就可以创建一个具备服务能力的硬件隔离沙箱环境，并保持着小于5M的内存开销。
| 安装及功能演示 | 性能测试 | RL场景演示 (SWE-Bench) |
- 极致冷启动： 基于资源池化预置和快照克隆技术，直接跳过耗时初始化流程。整个沙箱服务端到端冷启动一个可服务的沙箱时间平均 < 60ms
- 单机千例的高密部署： 基于 CoW 技术实现极致内存复用，用 Rust 重构底层极致裁剪，使得单实例内存开销低至 <5MB，轻松在一台机器上跑起数千个 Agent。
- 真正的内核级隔离： 告别不安全的 Docker 共享内核（Namespace）。每个 Agent 拥有独立的 Guest OS 内核，杜绝容器逃逸，放心运行任何大模型生成的未知代码。
- 零成本迁移（E2B 完美平替）： 原生兼容 E2B SDK 接口规范。只需替换一个 URL 环境变量，无需业务代码改动就可切换到免费的 Cube Sandbox，并获得更好的性能体验。
- 网络安全： 基于 eBPF 的 CubeVS 在内核态实现严格的沙箱间网络隔离，支持细粒度出站流量过滤策略。
- 开箱即用： 可一键快速部署，同时支持单机部署和集群部署。
- 事件级快照回滚（coming soon）： 百毫秒级的高频快照回滚能力，基于快照快速创建分叉探索环境
- 可用于生产环境： Cube Sandbox 已在腾讯云生产环境中经历大规模的服务验证，稳定可靠。
在 AI Agent 代码执行场景下，Cube Sandbox 实现了安全与性能的兼得：
| 维度 | Docker 容器 | 传统虚拟机 (VM) | CubeSandbox |
|---|---|---|---|
| 隔离级别 | 低 (共享内核 Namespaces) | 高 (独立内核) | 极高 (独立内核 + eBPF网络隔离) |
| 启动速度 *完整启动OS时长 | 200ms | 秒级 | 毫秒级 (< 60ms) |
| 内存开销 | 低（共享内核） | 高 (完整 OS ) | 低 (极限裁剪，< 5MB) |
| 部署密度 | 高 | 低 | 极高 (单机数千实例) |
| E2B SDK 兼容 | / | / | ✅ 完全兼容 (Drop-in) |
Cube Sandbox 测试数据说明：其中，启动速度项基于裸金属环境测试，单并发下为 60ms，50 并发场景下平均 67ms（P95 90ms，P99 137ms），整体保持在百毫秒级。内存开销项基于 ≤ 32GB 规格沙箱实测，更大规格下开销会略有上升，但幅度极小。
详细的创建时延和资源消耗情况可参考：
|
|
|
| 单 / 高并发场景下百毫秒级的沙箱交付 |
不同规格沙箱 Cube Sandbox 自身内存消耗 *其中蓝色部分为沙箱规格，橙色部分为对应规格下消耗内存，随着规格扩大，内存消耗呈现少量增长 | |
⚡ 毫秒级启动 —— 观看快速启动流程，然后进入快速开始指南。
Cube Sandbox 需要一台开启了 KVM 的 x86_64 Linux 环境，WSL 2 / Linux 物理机 / 云上裸金属均可。
还没有这样的环境？
- Windows 用户：在管理员 PowerShell 里执行
wsl --install安装 WSL 2（需 Windows 11 22H2+，并在 BIOS / WSL 里开启嵌套虚拟化）。- 其他用户：准备一台 x86_64 Linux 物理机，或在云厂商购买一台裸金属服务器。
准备好环境后，四步启动你的第一个沙箱：
- 准备运行环境
在你的 WSL / Linux 机器上执行：
git clone https://github.com/tencentcloud/CubeSandbox.git
# 国内用户建议改用镜像仓库：
# git clone https://cnb.cool/CubeSandbox/CubeSandbox
cd CubeSandbox/dev-env
./prepare_image.sh # 仅首次：下载并初始化运行环境
./run_vm.sh # 启动环境，保持此终端不关（Ctrl+a x 退出）
新开一个终端，进入上一步准备好的环境：
cd CubeSandbox/dev-env && ./login.sh
该命令会把你送进一台一次性的 Linux 环境中，后续所有安装都在这里进行，不会污染你的宿主机。
- 启动 Cube 沙箱服务
在上一步 login.sh 进入的环境里（或你自己的裸金属服务器上），根据你的网络环境执行其中一条命令：
-
国内用户（走 CDN 镜像，推荐）：
curl -sL https://cnb.cool/CubeSandbox/CubeSandbox/-/git/raw/master/deploy/one-click/online-install.sh | MIRROR=cn bash -
海外用户（从 GitHub 下载）：
curl -sL https://github.com/tencentcloud/CubeSandbox/raw/master/deploy/one-click/online-install.sh | bash
- 制作代码解释器沙箱模板
安装完成后，使用预构建镜像创建代码解释器模板：
cubemastercli tpl create-from-image \ --image ccr.ccs.tencentyun.com/ags-image/sandbox-code:latest \ --writable-layer-size 1G \ --expose-port 49999 \ --expose-port 49983 \ --probe 49999
然后，执行下面的这行命令，监控构建进度：
cubemastercli tpl watch --job-id <job_id>
⚠️ **注意：**由于镜像比较大，下载、解压、模板制作过程可能比较久，请耐心等待。
等待上述命令结束，模板状态变为 READY。记录输出中的模板 ID (template_id)，下一步会用到。
- 运行你的第一段 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="dummy"
export CUBE_TEMPLATE_ID="<你的模板ID>" # 第三步获取的模板 ID
export SSL_CERT_FILE="$(mkcert -CAROOT)/rootCA.pem"
在隔离沙箱中运行代码：
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)
更多变量说明和示例见快速开始 — 第四步。
想要探索更多玩法？查看 📂 examples/ 目录，涵盖：代码执行、Shell 命令、文件操作、浏览器自动化、网络策略、暂停/恢复、OpenClaw 集成、RL 训练等场景。
- 文档首页 — 完整指南导航
- 模板概览 — 镜像到模板的概念与工作流
- 示例项目 — 展示各种使用场景的示例（涵盖代码执行、浏览器自动化、OpenClaw 集成与 RL 训练等）
- 开发环境（QEMU 虚机） — 没有 bare-metal？在一次性的 OpenCloudOS 9 虚机里跑 Cube Sandbox
| 组件 | 职责 |
|---|---|
| CubeAPI | 兼容 E2B 的 REST API 网关（Rust），替换 URL 即可从 E2B 无缝切换。 |
| CubeMaster | 编排调度器，接收 API 请求并分发到对应 Cubelet，负责资源调度与集群状态维护。 |
| CubeProxy | 反向代理，兼容 E2B 协议，将请求路由到对应沙箱。 |
| Cubelet | 计算节点本地调度组件，管理单节点所有沙箱实例的完整生命周期。 |
| CubeVS | 基于 eBPF 内核态转发的虚拟交换机，提供网络隔离与安全策略支持。 |
| CubeHypervisor & CubeShim | 虚拟化层 —— CubeHypervisor 负责管理 KVM MicroVM，CubeShim 实现 containerd Shim v2 接口，将沙箱集成到容器运行时。 |
详见架构概览和 CubeVS 网络模型。
我们欢迎各种形式的贡献——Bug 报告、功能建议、文档改进、代码提交。
- 发现 Bug —— 在这里报告问题或提出建议
- 有新想法 — 提问交流与想法分享
- 想写代码？ — 查看我们的 CONTRIBUTING.md 贡献指南，了解如何提交Pull Requst。
- 想聊聊天？ 扫描二维码，加入我们的微信交流群。
💬 扫描上方二维码加入微信交流群，与核心开发者和社区伙伴零距离沟通！
Cube Sandbox 使用 Apache License 2.0 开源许可证。
Cube Sandbox 的诞生离不开开源社区的基石，特别鸣谢 Cloud Hypervisor、Kata Containers、virtiofsd、containerd-shim-rs、ttrpc-rust 等。部分组件为适配 Cube Sandbox 运行模型进行了定制修改，原始上游归属声明均已保留。
