容器隔离

为什么需要容器隔离？

当 AI Agent 在你的机器上执行 shell 命令时，它拥有与你用户账户相同的文件访问权限——它可以读取 ~/.ssh、删除 ~/Documents 中的文件、或修改系统配置。这对于生产工具来说是不可接受的。 Zeus 通过容器隔离解决这个问题：当你在 Desktop 中选择一个工作目录后，所有命令都在隔离的 Linux 容器内执行。容器只能看到那一个目录（挂载在 /workspace）。你机器上的其他所有内容都是不可见且不可达的。

架构总览

Zeus 根据使用方式有两种不同的执行环境：

Web 用户（浏览器）                    Desktop 用户（Electron 应用）
     │                                         │
     ▼                                         ▼
sandbox_mode: "cloud"                 sandbox_mode: "local"
     │                                         │
     ▼                                         ▼
云沙盒                                 本地容器
(E2B / OpenSandbox / Daytona)         (Docker / Apple Containerization)
     │                                         │
     ▼                                         ▼
远程 VM，完全隔离                       本地容器，bind mount
文件存储在远端                          文件保留在你的磁盘上

API 请求中的 sandbox_mode 字段控制走哪条路径：

模式	执行环境	何时使用
`cloud`	远程云沙盒（E2B / OpenSandbox / Daytona）	Web 用户；所有请求的默认值
`local`	你机器上的本地容器	Desktop 用户，选择了工作目录时
`none`	完全不执行代码	纯对话模式；不注入任何沙盒工具

当 sandbox_mode 为 "local" 时，云沙盒被完全绕过——不会创建远程 VM，不会注入沙盒工具（write/read/edit/bash）。取而代之的是，Agent 使用通过本地容器路由的 desktop_exec。

`local` 模式端到端流程

以下是 Desktop 用户发送消息（带工作目录）时的完整数据流：

用户选择 ~/Projects/my-app 作为工作目录
Desktop 渲染进程设置 sandbox_mode = "local" + working_directory = "~/Projects/my-app"
请求到达 AI Backend（Python）
AgentService.invoke() 识别到 sandbox_mode = "local"
   → 跳过云沙盒工具注入
   → 注入系统提示词："你在 /workspace 中操作，使用 desktop_exec"
LLM 决定执行：desktop_exec(command="npm install")
Backend 通过 WebSocket 将工具调用发送到 Desktop 应用
Desktop actions.ts 收到调用，payload 中包含 working_directory
actions.ts 检测容器运行时（Apple Containerization > Docker）
容器启动（或复用已有的），带 bind mount：
   docker run -v ~/Projects/my-app:/workspace ...
命令在容器内执行：docker exec <id> bash -c "npm install"
输出通过 WebSocket → Backend → SSE → UI 返回

系统提示词注入

当 sandbox_mode == "local" 时，后端会向 Agent 的系统提示词中注入：

## Working Directory (Desktop Local Workspace)
You are operating in the user's local workspace: ~/Projects/my-app
- All commands execute inside an isolated container with this directory mounted at /workspace
- You can ONLY access files within /workspace
- Use desktop_exec for all file operations and shell commands
- Do NOT attempt to access paths outside /workspace

这是一个软约束（LLM 遵循指令）。硬约束是容器运行时本身——即使 LLM 试图访问 /etc/passwd，容器的文件系统中根本不存在这个文件。

容器运行时

Zeus Desktop 启动时按优先级顺序检测运行时，结果会被缓存。

1. Apple Containerization（优先）

适用于 macOS 26+（Tahoe），需要 Apple Silicon。 工作原理： 与 Docker 通过命名空间共享宿主 Linux 内核不同，Apple Containerization 将每个容器运行在独立的 micro-VM 中——一个轻量级虚拟机，拥有专属的 Linux 内核，由 Apple 的 Virtualization.framework 管理。

┌─────────────────────────────────────────┐
│ macOS 宿主机                             │
│                                         │
│  ┌────────────────────────────────────┐ │
│  │ micro-VM (Virtualization.framework)│ │
│  │                                    │ │
│  │  ┌──────────────────────────────┐  │ │
│  │  │ Linux 内核（专属）            │  │ │
│  │  │                              │  │ │
│  │  │ 容器进程                      │  │ │
│  │  │  /workspace ← virtiofs 挂载  │  │ │
│  │  └──────────────────────────────┘  │ │
│  └────────────────────────────────────┘ │
│                                         │
│  ~/Projects/my-app ──virtiofs──┘        │
└─────────────────────────────────────────┘

关键特性：

隔离级别：VM 级别。即使容器内发生内核漏洞利用，也无法触达宿主机。
通过 virtiofs 共享目录：Apple 实现的 virtio-fs 协议。宿主机通过 virtio 传输将目录暴露给客户 VM。在 VM 内部，它表现为 /workspace 的普通挂载。读写操作实时透传，但客户进程无法导航到共享目录之外。
性能：接近原生。virtiofs 使用共享内存区域（DAX），避免了早期 Docker for Mac 文件共享中 9p 协议的性能开销。
启动：亚秒级。micro-VM 启动一个为快速启动优化的最小 Linux 内核。
OCI 兼容：使用标准 OCI 容器镜像——同一个 Dockerfile 同时适用于 Docker 和 Apple Containerization。

检测方式：Zeus 执行 container --version，超时 3 秒。

2. Docker（回退方案）

适用于 macOS、Windows 和 Linux。需要安装 Docker Desktop（Linux 上为 Docker Engine）。 工作原理： Docker 使用 Linux 命名空间和 cgroups 隔离进程。在 macOS 上，Docker Desktop 运行一个隐藏的 Linux VM（底层使用 Apple Virtualization.framework），容器在这个共享 VM 内运行。

┌────────────────────────────────────────────┐
│ macOS 宿主机                                │
│                                            │
│  ┌──────────────────────────────────────┐  │
│  │ Docker Desktop VM（共享 Linux）       │  │
│  │                                      │  │
│  │  容器 A          容器 B              │  │
│  │  /workspace      /workspace          │  │
│  │      ↑               ↑              │  │
│  └──────│───────────────│──────────────┘  │
│         │               │                  │
│  bind mount        bind mount              │
│         │               │                  │
│  ~/Projects/a    ~/Projects/b              │
└────────────────────────────────────────────┘

关键特性：

隔离级别：容器级（命名空间隔离）。所有容器共享 Docker VM 内同一个 Linux 内核。内核漏洞利用可能影响其他容器。
通过 bind mount 共享目录：-v 宿主路径:容器路径 标志将宿主目录映射到容器文件系统中。Docker Desktop 使用 virtiofs（macOS 12.5+）或 gRPC-FUSE 在 macOS 宿主和 Linux VM 之间桥接。
性能：良好。使用 virtiofs 后端的 bind mount（Docker Desktop 4.15+）接近原生速度。旧版 gRPC-FUSE 后端在 node_modules 密集型工作负载中明显较慢。
启动：容器约 1-2 秒（VM 已经在运行）。
OCI 兼容：标准 Docker 镜像。

检测方式：Zeus 执行 docker info，超时 5 秒。

3. 无可用运行时

如果两种运行时都未检测到，当设置了 working_directory 时，Zeus 拒绝执行任何命令。返回给 Agent 的错误信息为：

“未检测到容器运行时，请安装 Docker Desktop 或升级到 macOS 26 以使用 Apple Containerization。”

这是一个刻意的设计选择——没有软隔离回退方案。我们不会尝试通过 cwd 或 shell 技巧来限制路径，因为这些可以被轻易绕过（cd /、符号链接、$HOME 展开等）。

对比：Apple Containerization vs Docker

方面	Apple Containerization	Docker
隔离边界	VM（专属内核）	命名空间（共享内核）
内核漏洞风险	限制在 micro-VM 内	可能影响所有容器
目录共享协议	virtiofs（原生）	virtiofs（通过 Docker Desktop）
macOS 版本要求	26+（Tahoe）	12+
跨平台	仅 Apple Silicon	macOS、Windows、Linux
启动时间	不到 1 秒	约 1-2 秒
镜像格式	OCI	OCI
运行时检测	`container --version`	`docker info`

容器生命周期

Zeus 为每个会话管理一个容器：

启动：当第一个带 working_directory 的 desktop_exec 命令到达时，Zeus 检测运行时、创建容器（docker run -d 或 container run -d），并 bind-mount 目录。
执行：后续命令通过 docker exec / container exec 发送到运行中的容器。
复用：如果该会话的容器已存在且运行中，直接复用。
停止：会话结束（或 Desktop 应用关闭）时，容器被移除（docker rm -f / container rm -f）。

容器以 sleep infinity 作为入口点——保持存活直到被显式停止。

沙盒镜像

两种运行时使用同一个 OCI 镜像：zeus-desktop-sandbox:latest。内容（定义在 apps/desktop/docker/Dockerfile）：

基础：Ubuntu 22.04
语言：Python 3 + pip + venv, Node.js 22 LTS + npm + pnpm
工具：git, curl, wget, jq, build-essential (gcc, make 等)
工作目录：/workspace

构建方式：

# Docker
cd apps/desktop/docker
docker build -t zeus-desktop-sandbox:latest .

# Apple Containerization
cd apps/desktop/docker
container build -t zeus-desktop-sandbox:latest .

镜像刻意保持精简（约 300MB）。用户可以构建自己的镜像并修改沙盒实现中的 IMAGE_NAME 常量来扩展。

安全模型总结

Zeus 采用纵深防御，共三层：

层级	机制	由谁执行
1. LLM 指令	系统提示词声明”仅访问 /workspace”	AI 模型遵循
2. 容器文件系统	仅挂载 `/workspace`；宿主路径不存在	容器运行时（内核）
3. 无回退	无容器运行时则完全拒绝执行	应用逻辑

仅靠第 1 层是不够的（LLM 可能产生幻觉或被越狱）。第 2 层提供硬边界。第 3 层确保我们永远不会降级到不安全状态。

安装指引

Docker Desktop

从 docker.com/products/docker-desktop 下载
安装并启动 Docker Desktop
验证：在终端运行 docker info——应显示服务器版本和存储驱动
构建镜像：docker build -t zeus-desktop-sandbox:latest apps/desktop/docker/

Apple Containerization（macOS 26+）

升级到 macOS 26（Tahoe）或更新版本
container CLI 随系统附带（Containerization 框架的一部分）
验证：在终端运行 container --version
构建镜像：container build -t zeus-desktop-sandbox:latest apps/desktop/docker/

开始使用

基础概念

核心能力

基础设施

渠道

为什么需要容器隔离？

架构总览

`local` 模式端到端流程

系统提示词注入

容器运行时

1. Apple Containerization（优先）

2. Docker（回退方案）

3. 无可用运行时

对比：Apple Containerization vs Docker

容器生命周期

沙盒镜像

安全模型总结

安装指引

Docker Desktop

Apple Containerization（macOS 26+）

开始使用

基础概念

核心能力

基础设施

渠道

​为什么需要容器隔离？

​架构总览

​local 模式端到端流程

​系统提示词注入

​容器运行时

​1. Apple Containerization（优先）

​2. Docker（回退方案）

​3. 无可用运行时

​对比：Apple Containerization vs Docker

​容器生命周期

​沙盒镜像

​安全模型总结

​安装指引

​Docker Desktop

​Apple Containerization（macOS 26+）

为什么需要容器隔离？

架构总览

`local` 模式端到端流程

系统提示词注入

容器运行时

1. Apple Containerization（优先）

2. Docker（回退方案）

3. 无可用运行时

对比：Apple Containerization vs Docker

容器生命周期

沙盒镜像

安全模型总结

安装指引

Docker Desktop

Apple Containerization（macOS 26+）