CubeSandbox

一个极速启动、高并发、安全且轻量化的 AI Agent 沙箱服务

--- Cube Sandbox 是一款基于 RustVMM 与 KVM 构建的高性能、开箱即用的安全沙箱服务。它既支持单机部署，也能够很方便的扩展到多台机器的集群服务。同时对外兼容E2B SDK，在60ms内就可以创建一个具备服务能力的硬件隔离沙箱环境，并保持着小于5M的内存开销。

## 视频演示 (Demos)


安装及功能演示	性能测试	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 已在腾讯云生产环境中经历大规模的服务验证，稳定可靠。 ## 性能与方案对比 (Benchmarks) 在 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 物理机，或在云厂商购买一台裸金属服务器。准备好环境后，四步启动你的第一个沙箱： 1. **准备运行环境** 在你的 WSL / Linux 机器上执行： ```bash 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 退出） ``` 新开一个终端，进入上一步准备好的环境： ```bash cd CubeSandbox/dev-env && ./login.sh ``` > 该命令会把你送进一台一次性的 Linux 环境中，后续所有安装都在这里进行，不会污染你的宿主机。 2. **启动 Cube 沙箱服务** 在上一步 `login.sh` 进入的环境里（或你自己的裸金属服务器上），根据你的网络环境执行**其中一条**命令： - **国内用户**（走 CDN 镜像，推荐）： ```bash curl -sL https://cnb.cool/CubeSandbox/CubeSandbox/-/git/raw/master/deploy/one-click/online-install.sh | MIRROR=cn bash ``` - **海外用户**（从 GitHub 下载）： ```bash curl -sL https://github.com/tencentcloud/CubeSandbox/raw/master/deploy/one-click/online-install.sh | bash ``` 3. **制作代码解释器沙箱模板** 安装完成后，使用预构建镜像创建代码解释器模板： ```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 ``` 然后，执行下面的这行命令，监控构建进度： ```bash cubemastercli tpl watch --job-id ``` ⚠️ **注意：**由于镜像比较大，下载、解压、模板制作过程可能比较久，请耐心等待。等待上述命令结束，模板状态变为 `READY`。记录输出中的**模板 ID** (`template_id`)，下一步会用到。 4. **运行你的第一段 Agent 代码** 安装 Python SDK： ```bash yum install -y python3 python3-pip pip config set global.index-url https://mirrors.ustc.edu.cn/pypi/simple pip install e2b-code-interpreter ``` 设置环境变量： ```bash 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" ``` 在隔离沙箱中运行代码： ```python 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) ``` > 更多变量说明和示例见[快速开始 — 第四步](./docs/zh/guide/quickstart.md#第四步运行第一段-agent-代码)。想要探索更多玩法？查看 📂 [`examples/`](./examples/) 目录，涵盖：代码执行、Shell 命令、文件操作、浏览器自动化、网络策略、暂停/恢复、OpenClaw 集成、RL 训练等场景。 ## 深入探索 - [文档首页](./docs/zh/index.md) — 完整指南导航 - [模板概览](./docs/zh/guide/templates.md) — 镜像到模板的概念与工作流 - [示例项目](./docs/zh/guide/tutorials/examples.md) — 展示各种使用场景的示例（涵盖代码执行、浏览器自动化、OpenClaw 集成与 RL 训练等） - [开发环境（QEMU 虚机）](./docs/zh/guide/dev-environment.md) — 没有 bare-metal？在一次性的 OpenCloudOS 9 虚机里跑 Cube Sandbox ## 架构概览

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 接口，将沙箱集成到容器运行时。 | 详见[架构概览](./docs/zh/architecture/overview.md)和 [CubeVS 网络模型](./docs/zh/architecture/network.md)。 ## 社区与贡献我们欢迎各种形式的贡献——Bug 报告、功能建议、文档改进、代码提交。 - **发现 Bug** —— 在这里报告问题或提出建议 - **有新想法** — 提问交流与想法分享 - **想写代码？** — 查看我们的 CONTRIBUTING.md 贡献指南，了解如何提交Pull Requst。 - **想聊聊天？** 扫描二维码，加入我们的微信交流群。 ---

💬 扫描上方二维码加入微信交流群，与核心开发者和社区伙伴零距离沟通！

## 许可证 Cube Sandbox 使用 [Apache License 2.0](./LICENSE) 开源许可证。 Cube Sandbox 的诞生离不开开源社区的基石，特别鸣谢 [Cloud Hypervisor](https://github.com/cloud-hypervisor/cloud-hypervisor)、[Kata Containers](https://github.com/kata-containers/kata-containers)、virtiofsd、containerd-shim-rs、ttrpc-rust 等。部分组件为适配 Cube Sandbox 运行模型进行了定制修改，原始上游归属声明均已保留。