Celesto 是一个为 AI Agent 提供安全、持久计算机（sandbox）的开源项目。当你在宿主机上调用vm.run("echo hello")或上传文件时，背后其实是宿主机与虚拟机之间的通信通道在工作。Celesto 同时支持两条控制通道：SSH 通道（传统、通用、全平台可用）和vsock 通道（原生虚拟机直通、更快、不依赖 IP 网络）。本文将带你快速理解这两种通道的设计原理、自动选择逻辑，以及如何在自己的场景下做出最佳选择。

一、为什么要设计两套通信通道？

AI Agent 的沙箱需要宿主机持续"遥控"虚拟机：执行命令、传输文件、探测开机是否就绪、打开交互式终端。Celesto 把这条"控制面"抽象成一个极小的接口CommChannel，定义在 src/celesto/comm/base.py 中，只暴露几个核心能力：

• run/run_stream：在客户机执行命令（支持流式输出）
• put_file/get_file：上传/下载文件
• wait_ready：阻塞等待客户机就绪
• close/connected：连接生命周期管理

接口刻意保持"最小公分母"，因此环境变量注入、预设凭据拷贝等上层功能只需要调用run和put_file，无论底层走 SSH 还是 vsock 都无需改一行代码。

二、SSH 通道：兼容性优先的"万金油"

SSH 实现位于 src/celesto/ssh.py，基于paramiko：

• 持久连接：首次使用时建立一条 TCP 连接，之后所有命令复用同一条连接，避免了每次调用 fork 新ssh进程带来的约 170ms 额外开销
• 全平台可用：无论宿主机是 Linux 还是 macOS，客户机是 Linux 还是 Windows，只要有 sshd 就能工作
• 自动等待 sshd：wait_for_ssh从 20ms 起步、按 1.5 倍退避轮询，尽早发现刚启动的 sshd，减少开机等待的"空转"

代价是它依赖虚拟机的 IP 网络：客户机需要先完成网络配置、sshd 启动，控制面流量还会被网络策略"顺带"影响。

三、vsock 通道：宿主机直插虚拟机的"快车道"

vsock（Virtual Socket）是虚拟化平台提供的专用套接字通道，不走 IP 网络，宿主机和客户机通过客户机 CID + 端口直接对话。Celesto 的 vsock 通道分两端实现：

3.1 宿主机端：Rust guest agent 的 HTTP 客户端

宿主机侧通道类RustHttpVsockChannel位于 src/celesto/comm/rust_http_vsock_channel.py，核心约定：

它本质上是"在 vsock 流上跑 HTTP/1.1"：/exec执行命令、/files/content传文件、/env管理受控环境变量、/capabilities协商协议版本与特性开关。

两种底层连接方式：

• QEMU（Linux）：使用原生AF_VSOCK，QEMU 启动时挂载vhost-vsock-pci设备并分配guest-cid（见 src/celesto/runtime/qemu_args.py），依赖宿主机/dev/vhost-vsock设备
• Firecracker（Linux）：没有原生 vhost 设备，Firecracker 提供宿主机侧 Unix Socket 桥；Celesto 连接该 socket 后先发送CONNECT <port>一行完成握手，再在其上流动 vsock 字节流

3.2 客户机端：常驻的 Rust guest agent

虚拟机内部运行一个用 Rust 编写的celesto-guest-agent，默认监听vsock://1024，源码见 guest-agent/src/server.rs 与路由定义 guest-agent/src/handler.rs。它与宿主机配合完成：

• 命令执行与 SSE 流式输出
• 文件/目录传输（目录以 tar 流式传递）
• 关机前sync落盘、端口就绪探测
• 终端会话（1025 端口）

3.3 vsock 的安全边界

由于 guest 被视为"不可信"，宿主机侧做了大量防御：下载目录时会剥离 setuid/setgid 权限位、拒绝绝对路径与符号链接穿越；响应体有大小上限（如单文件默认 256MB、tar 包 512MB），防止恶意 guest 借传输通道做权限提升或耗尽宿主机资源。

四、自动选择逻辑：谁来决定走哪条通道？

选择逻辑集中在 src/celesto/comm/select.py 的resolve_comm_channel，优先级为：

1. 调用方显式指定（comm_channel="vsock"或"ssh"）——最高优先级
2. VM 持久化配置中保存的通道
3. 自动模式：vsock 可用就优先 vsock，否则回退 SSH

自动模式判定"vsock 可用"的条件：

• 客户机不是 Windows（Windows guest 一律 SSH）
• 后端为 QEMU 时，宿主机是 Linux 且加载了vhost_vsock（存在/dev/vhost-vsock）；macOS/HVF 无对应设备，返回 False
• 后端为 Firecracker 时，宿主机必须是 Linux

一个关键设计原则：显式请求 vsock 但环境不满足时，抛出结构化的VsockNotSupportedError（带错误码与恢复建议），绝不静默降级为 SSH。自动模式下，facade 还会运行时探测 vsock 就绪（ping guest agent），探测失败即让 vsock 就绪判定失败，同样不做"悄悄换路"，保证行为可预期。相关约束见 src/celesto/facade.py。

五、怎么选？一张对照表帮你决策

vsock 与网络策略的关系在 docs/guides/networking.md 中有完整说明：Firecracker 关闭出站网络后，仍可通过comm_channel="vsock"直接执行命令、下载文件——这正是 vsock"脱离 IP 网络"价值的最佳体现。

六、核心模块导航

想深入源码？这些路径值得收藏：

• 通道抽象接口：src/celesto/comm/base.py
• 通道选择与降级策略：src/celesto/comm/select.py
• vsock HTTP 通道实现：src/celesto/comm/rust_http_vsock_channel.py
• SSH 通道实现：src/celesto/ssh.py
• 客户机 agent（Rust）：guest-agent/src/
• 通道行为测试：tests/communication/
• 架构总览：docs/contributing/architecture.md

七、总结：设计背后的三条理念

1. 接口最小化：CommChannel只有"执行、传文件、等就绪"几个动词，两条传输实现互相替换，上层零感知
2. 快速路径优先：在 vsock 可用的环境里自动走直连通道，省掉客户机网络栈和 sshd 启动等待，AI Agent 的高频命令调用受益最大
3. 失败要响亮：显式选择被环境拒绝时给出结构化错误与恢复命令，而不是静默换通道——对自动化场景而言，可预期的失败远好于隐蔽的降级

理解这套设计后，下次遇到"沙箱命令突然变快"或"断网模式无法 exec"的情况，你都能一眼定位到是通道选择策略在起作用。