基础概念

CubeSandbox 的定位是“面向 AI Agent 的安全沙箱服务”。它和传统在线代码执行器很像，但目标更宽：不仅执行一段代码，还能托管长期运行的 Agent、浏览器、数据库、开发环境和带状态的服务。

为什么 AI Agent 需要沙箱

AI Agent 会频繁执行模型生成的代码、打开网页、读写文件、调用第三方 API。这里天然有三类风险：

风险	典型问题	CubeSandbox 的处理方式
执行未知代码	代码可能读宿主机文件、逃逸容器、占满资源	每个沙箱运行在独立内核的 KVM MicroVM 中。
状态需要保留	Agent 对话跨轮执行，不能每次都丢掉文件和进程状态	支持暂停、恢复、快照、回滚和克隆。
出网不可失控	模型生成代码可能访问未授权域名或泄漏密钥	CubeVS + CubeEgress 执行 L3/L4 与 L7 出网策略。

一句话心智模型：CubeSandbox 用接近容器的启动速度，提供接近虚拟机的隔离边界，并把 Agent 需要的状态管理和网络安全变成平台能力。

沙箱是什么

在 CubeSandbox 中，Sandbox 是最小运行单元。一个沙箱通常包含：

• 一个独立 Linux Guest 内核。
• 一份从模板克隆出来的 rootfs。
• 一个或多个对外暴露端口。
• 生命周期状态，例如 running、paused、terminated。
• 可选的元数据、环境变量、网络策略和自动暂停策略。

它看起来像“容器实例”，但底层不是共享宿主机内核的 Linux namespace，而是 MicroVM。

MicroVM、KVM 与 PVM

概念	说明
MicroVM	极简虚拟机形态，只保留运行工作负载所需的设备和启动路径。
KVM	Linux 内核的虚拟化能力，CubeHypervisor 通过 KVM 管理虚拟 CPU、内存和设备。
RustVMM	Rust 虚拟化生态，CubeHypervisor 基于 RustVMM 组件构建。
PVM	Pagetable-based Virtual Machine，用于在普通云服务器上获得可运行 CubeSandbox 的 KVM 能力。

如果机器已经有 /dev/kvm，通常走裸金属或物理机部署。如果云服务器不开放嵌套虚拟化，则可以走 PVM 部署路线。

E2B 兼容是什么意思

CubeAPI 对外提供兼容 E2B 的 REST API。很多场景下，你可以保留 E2B SDK 调用方式，只替换 API URL、API Key 和模板 ID：

export E2B_API_URL="http://127.0.0.1:3000"
export E2B_API_KEY="e2b_000000"
export CUBE_TEMPLATE_ID="<template-id>"

然后在 Python 里继续使用 E2B Code Interpreter SDK：

import os
from e2b_code_interpreter import Sandbox

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    result = sandbox.run_code("print('hello from CubeSandbox')")
    print(result)

CubeSandbox 也提供 cubesandbox SDK，用于访问快照、克隆、回滚等 Cube 特有能力。

模板是什么

Template 是创建沙箱的基础镜像和预热状态。模板制作通常分三步：

1. 从 OCI 镜像构建 rootfs。
2. 冷启动一次 MicroVM，等待运行环境就绪。
3. 保存内存和磁盘状态，注册为可复用模板。

后续创建沙箱时，Cubelet 从模板快速克隆 rootfs 和内存快照，再由 CubeShim/CubeHypervisor 恢复运行，所以能做到毫秒级启动。

快照、克隆与回滚

能力	作用	常见用法
Snapshot	保存当前沙箱的完整状态	在关键步骤前打 checkpoint。
Clone	从当前状态派生多个独立沙箱	并行探索多条 Agent 分支。
Rollback	把当前沙箱恢复到某个快照	执行失败后回到上一步继续尝试。
Pause/Resume	暂停和恢复同一个沙箱	空闲释放资源，下次请求继续使用。

这些能力都依赖底层的 CubeCoW、内存快照和 MicroVM 恢复路径。

网络安全的两个层次

CubeSandbox 的出网控制分两层：

层次	组件	负责什么
L3/L4	CubeVS	IP/CIDR allow/deny、DNS 学习、NAT、连接追踪。
L7	CubeEgress	HTTP/HTTPS host、SNI、method、path、凭证注入、审计。

这意味着你既可以说“这个沙箱完全不能出公网”，也可以说“只允许访问 api.example.com 的 POST /v1/*，并由平台注入 Authorization 头”。

常用术语表

术语	快速解释
CubeAPI	对外 API 网关，兼容 E2B REST。
CubeMaster	集群调度器，决定沙箱在哪个节点运行。
Cubelet	节点代理，管理本机沙箱生命周期。
CubeShim	containerd Shim v2 实现，把容器运行时请求接到 MicroVM。
CubeHypervisor	基于 RustVMM/KVM 的轻量 VMM。
CubeCoW	Copy-on-Write 存储与快照引擎。
CubeVS	eBPF 网络虚拟化数据面。
CubeEgress	OpenResty 透明出网安全代理。
CubeProxy	访问沙箱内服务的反向代理。
WebUI	浏览器控制台，默认监听 12088。

下一步

继续阅读 系统架构，把这些术语放到一次真实请求链路里理解。