> ## Documentation Index > Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt > Use this file to discover all available pages before exploring further. # 容器隔离 > Zeus Desktop 如何使用容器隔离命令执行 ## 为什么需要容器隔离？ 当 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 用户发送消息（带工作目录）时的完整数据流： ``` 1. 用户选择 ~/Projects/my-app 作为工作目录 2. Desktop 渲染进程设置 sandbox_mode = "local" + working_directory = "~/Projects/my-app" 3. 请求到达 AI Backend（Python） 4. AgentService.invoke() 识别到 sandbox_mode = "local" → 跳过云沙盒工具注入 → 注入系统提示词："你在 /workspace 中操作，使用 desktop_exec" 5. LLM 决定执行：desktop_exec(command="npm install") 6. Backend 通过 WebSocket 将工具调用发送到 Desktop 应用 7. Desktop actions.ts 收到调用，payload 中包含 working_directory 8. actions.ts 检测容器运行时（Apple Containerization > Docker） 9. 容器启动（或复用已有的），带 bind mount： docker run -v ~/Projects/my-app:/workspace ... 10. 命令在容器内执行：docker exec bash -c "npm install" 11. 输出通过 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 为每个会话管理一个容器： 1. **启动**：当第一个带 `working_directory` 的 `desktop_exec` 命令到达时，Zeus 检测运行时、创建容器（`docker run -d` 或 `container run -d`），并 bind-mount 目录。 2. **执行**：后续命令通过 `docker exec` / `container exec` 发送到运行中的容器。 3. **复用**：如果该会话的容器已存在且运行中，直接复用。 4. **停止**：会话结束（或 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` 构建方式： ```bash theme={null} # 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 1. 从 [docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop/) 下载 2. 安装并启动 Docker Desktop 3. 验证：在终端运行 `docker info`——应显示服务器版本和存储驱动 4. 构建镜像：`docker build -t zeus-desktop-sandbox:latest apps/desktop/docker/` ### Apple Containerization（macOS 26+） 1. 升级到 macOS 26（Tahoe）或更新版本 2. `container` CLI 随系统附带（Containerization 框架的一部分） 3. 验证：在终端运行 `container --version` 4. 构建镜像：`container build -t zeus-desktop-sandbox:latest apps/desktop/docker/`