CubeSandbox 使用教程
从入门到精通的完整指南
CubeSandbox 简介
CubeSandbox是腾讯开源的面向AI Agent的即时、并发、安全且轻量级沙箱服务。它基于MicroVM硬件隔离技术，每个沙箱运行独立的操作系统内核，提供强安全隔离。支持E2B SDK兼容，可作为E2B云服务的本地替代方案，仅需修改一个环境变量即可无缝切换。具备毫秒级启动、高密度部署（单机可运行数千实例）和快照状态管理能力，适用于AI Agent代码执行、浏览器自动化和强化学习训练等场景。
详细功能介绍
【工具简介】CubeSandbox是腾讯开源的AI Agent沙箱服务，基于MicroVM提供硬件级隔离的即时安全执行环境。
【核心功能】
①极速启动：通过资源池化和快照克隆技术跳过冷启动开销，沙箱创建速度达到毫秒级，满足Agent高频调用需求。
②硬件隔离安全：每个沙箱运行独立的MicroVM和专属操作系统内核，基于eBPF的CubeVS网络模型实现严格的沙箱间隔离和细粒度出网过滤。
③E2B SDK兼容：作为E2B云服务的本地替代方案，仅需修改一个环境变量即可无缝切换，客户端代码零改动。
④高密度部署：单个沙箱仅占用MB级资源开销，通过内核共享和写时复制技术，单台服务器可运行数千个沙箱实例。
⑤状态管理：支持对运行中的沙箱创建检查点、回滚到任意保存状态或分叉为并行探索环境，操作粒度达毫秒级。
【适用场景】
AI Agent平台需要为Agent提供安全隔离的代码执行环境时，CubeSandbox可替代云沙箱服务降低部署成本；强化学习训练场景中，需要大量并发的隔离环境进行并行实验；浏览器自动化和网页抓取任务，需要在隔离环境中运行不受信任的代码。
【快速入门】
①参考官方文档进行单机部署或PVM部署，配置基础运行环境。
②通过模板系统创建沙箱模板，选择预置镜像或从OCI镜像自定义构建。
③使用SDK或API创建沙箱实例，执行代码或运行Agent任务。
④通过WebUI控制台监控沙箱状态，使用快照和回滚功能管理沙箱生命周期。
【优缺点分析】
优点：硬件级隔离安全性远超容器方案，适合运行不受信任的代码；启动速度极快且资源占用低，适合大规模并发场景；E2B兼容设计降低了迁移成本，生态集成友好。
缺点：部署需要支持虚拟化的硬件环境，部分云服务器可能不满足要求；相比容器方案学习曲线更陡，需要理解MicroVM概念；项目仍在快速迭代中，部分功能可能不够稳定。
【适合人群】
AI Agent平台开发者，需要为Agent提供安全可靠的代码执行沙箱；云基础设施工程师，需要构建高密度、低延迟的沙箱服务集群；强化学习和自动化测试团队，需要大量并发隔离环境进行并行实验。
1CubeSandbox AI Agent沙箱服务入门教程
入门10分钟
CubeSandbox是腾讯开源的AI Agent沙箱服务，基于MicroVM硬件隔离技术，提供毫秒级启动、强安全隔离的代码执行环境，可作为E2B的本地替代方案。
一、快速开始
1. 确保系统已安装Docker和KVM支持，检查命令：ls /dev/kvm
2. 克隆项目：git clone https://github.com/tencent/CubeSandbox.git
3. 进入目录执行安装：cd CubeSandbox && make install
4. 启动服务：make start，服务默认监听在http://localhost:8080
5. 使用SDK连接：pip install cubesandbox（Python）或npm install cubesandbox（Node.js），即可通过代码创建和管理沙箱
二、核心功能演示
功能1：创建代码执行沙箱
通过SDK调用create_sandbox()接口创建一个新的沙箱实例。每个沙箱拥有独立的操作系统内核和文件系统，启动时间仅需毫秒级。创建后可获得沙箱ID和连接地址，通过该地址可在沙箱内执行任意代码。沙箱之间完全隔离，互不影响。
功能2：执行代码并获取结果
连接到沙箱后，使用execute()方法发送代码。支持Python、JavaScript、Shell等多种语言。代码在沙箱内安全执行，返回标准输出和错误信息。执行超时会自动终止，防止资源滥用。每次执行都在干净的环境中，不会受上一次执行的影响。
功能3：快照与状态恢复
对正在运行的沙箱创建快照，保存当前内存和磁盘状态。后续可以基于快照快速恢复沙箱到之前的状态，无需重新执行所有代码。这对于需要保存中间状态的长时间运行任务特别有用，比如机器学习训练的检查点保存。
三、实际使用案例
案例1：AI Agent代码执行后端
你在开发一个AI编程助手，Agent生成的代码需要安全执行。将CubeSandbox作为代码执行后端，每次Agent生成代码时自动创建沙箱执行，获取结果后反馈给用户。即使代码有恶意行为也不会影响主系统，强隔离保障安全性。高密度部署能力支持大量用户并发使用。
案例2：自动化浏览器测试
利用CubeSandbox的沙箱环境运行无头浏览器，执行Web自动化测试。每个测试用例在独立沙箱中运行，互不干扰。测试完成后沙箱自动销毁，无需手动清理环境。快照功能可以保存测试环境状态，快速复现问题。
四、常见问题FAQ
Q1：与E2B云服务相比有什么优势？
A：CubeSandbox完全本地部署，数据不离开你的基础设施，适合对数据安全有严格要求的场景。且兼容E2B SDK，只需修改一个环境变量即可从E2B切换到CubeSandbox，迁移成本极低。
Q2：单机最多能运行多少沙箱？
A：得益于MicroVM轻量化设计，单机可同时运行数千个沙箱实例。具体数量取决于主机内存和CPU资源，每个沙箱基础开销极小。
Q3：支持GPU加速吗？
A：当前版本主要支持CPU执行环境，GPU直通支持正在开发中。对于需要GPU的AI推理场景，建议在沙箱内通过API调用外部GPU服务。
五、小贴士
1. 合理设置超时：为沙箱执行设置合理的超时时间，既能防止恶意代码无限运行，又能给正常任务足够的时间完成。
2. 善用快照功能：对于需要初始化复杂环境的任务（如安装依赖），先初始化好再创建快照，后续从快照恢复可节省大量时间。
3. 监控资源使用：定期查看沙箱集群的资源使用情况，合理规划容量，避免因沙箱过多导致宿主机资源不足。