企业官网建设流程全解析

解码 CubeSandbox 的 guest-init 与 agent：3分钟读懂沙箱 Guest 内的守护进程

【免费下载链接】CubeSandboxInstant, Concurrent, Secure & Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox

CubeSandbox 是一个即时、并发、安全且轻量的 AI Agent 沙箱平台，而它"秒级启动"的秘密，就藏在每个 MicroVM 内部的一对守护进程里：轻量的guest-init（cube-init）与全能型的cube-agent。本文带你完整解析这两个 Guest 内部组件的分工、启动流程与核心能力，无需深厚内核基础也能轻松上手。

为什么要专门写一对 Guest 守护进程？

普通容器的"守护"由宿主的 systemd 等工具承担，而 CubeSandbox 为每个沙箱启动独立的 MicroVM。Guest 内没有操作系统发行版的完整 init 系统，只需要做两件事：把文件系统准备好，然后把控制权交给真正的沙箱代理。

于是出现了清晰的职责分层（来自 guest-init/README.md）：

这种"极简 init + 专职 agent"的设计，正是沙箱内存占用低、启动快的关键之一。

cube-init：一个只做 5 件事的 PID 1

cube-init被打包进 Guest 镜像并作为/sbin/init存在，全部源码只有两个文件：guest-init/src/main.rs 与 guest-init/src/init_env.rs。它的启动流程可以概括为：

1. 校验自己是 PID 1（不是就 panic，见 main.rs）
2. 挂载基础文件系统：/proc、/sys、/dev/shm、/dev/pts、/run，并设置wrapper_mode=on环境变量，告诉 agent"基础挂载已完成，别再重复做"
3. 按内核命令行选择 cgroup 版本：若agent.unified_cgroup_hierarchy=true（CubeShim 默认）则挂载 cgroup2；否则回退到 cgroup v1 的各子系统挂载（逻辑在 init_env.rs）
4. 挂载独立 agent 平面：把/dev/pmem1（由 CubeShim 注入的cube-agent.ext4镜像文件）以ext4,ro,dax方式挂到/run/support
5. execvp执行/run/support/cube-agent，init 使命结束

💡 值得注意的设计取舍：开源版cube-init故意不做SysCtrl 快照握手（snapshot-mode下的SYS_START/SYS_RESTORE），因为产品模板走的是对运行中沙箱的 APP 快照路径，冷启动并不需要这一步——详见 guest-init/README.md。

cube-agent：Guest 内的"总指挥"

cube-agent派生自 Kata Containers 社区 agent（Apache-2.0），Cube 项目在此基础上替换了运行时协议、增加了 Cube 专属扩展（见 agent/README.md）。它在 Guest 内承担六大角色：

• 跳过重复挂载：检测到wrapper_mode=on后直接跳过general_mount（main.rs）
• 通过 SysCtrl 通知宿主：写入VsockServerReady标记（x86 PIO0x680/ aarch64 MMIO0x0903_0000），告知 CubeShim"我准备好了"
• 提供 ttrpc over vsock 服务：宿主侧containerd-shim-cube-rs通过 vsock 通道下发指令
• 管理容器生命周期：处理CreateContainer、StartContainer、ExecProcess、SignalProcess、RemoveContainer等请求，实现见 agent/src/rpc.rs
• 转发容器 I/O：把容器 stdio 流通过 vsock 代理回宿主
• 导出 Prometheus 指标：Guest CPU、内存、容器健康度，导出器见 agent/vsock-exporter/src/lib.rs

核心 API：一份 protobuf 定义的完整契约

Agent 暴露的全部能力由 agent/libs/protocols/protos/agent.proto 定义，涵盖执行、stdio、网络、可观测性四大类：

service AgentService { // execution rpc CreateContainer(...); rpc StartContainer(...); rpc RemoveContainer(...); rpc ExecProcess(...); rpc SignalProcess(...); rpc WaitProcess(...); rpc UpdateContainer(...); rpc StatsContainer(...); rpc PauseContainer(...); rpc ResumeContainer(...); // stdio / networking / observability ... }

同一份 proto 同时生成 Rust（agent 侧）与 Go（CubeShim 侧）绑定，保证两端协议严格一致。

rustjail：OCI 合规的容器运行时基座

真正"把容器跑起来"的重活交给 agent/rustjail/ 子 crate，它提供命名空间、cgroup（fs 与 systemd 双后端，见 rustjail/src/cgroups/）、seccomp、capabilities 等 OCI 运行时原语。而 agent/cube/ 子 crate 则承载 Cube 特有扩展，例如 exec 前的 rootfs 挂载处理（do_exec_mount，入口在 main.rs）。

从构建到注入：两个组件如何进入沙箱

构建与注入链路非常简洁，均在仓库内完成：

• make cube-init（别名make guest-init）构建 init 二进制，随后由deploy/one-click/build-guest-image.sh注入 Guest 镜像
• make agent-ext4将 musl 静态编译的cube-agent打包为独立平面文件cube-agent.ext4，由 CubeShim 作为virtio-pmem1设备注入
• make pmem-assets可一次性产出两者

把 agent 从 Guest OS 镜像中剥离、以只读 DAX 方式挂载，意味着 agent 升级不必重做 OS 镜像，也为安全隔离提供了更清晰的边界。

源码路径速查

小结

CubeSandbox 的 Guest 内部是一对"轻 init + 重 agent"的经典组合：cube-init用最少的挂载动作把系统环境备齐，随后立刻把舞台交给cube-agent；后者通过 vsock + ttrpc 接受宿主指挥，配合 rustjail 完成 OCI 容器的创建、执行与销毁。理解这条"PID 1 → exec agent → vsock 服务"的启动链，就理解了 CubeSandbox 沙箱即开即用的底层骨架。

【免费下载链接】CubeSandboxInstant, Concurrent, Secure & Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox