# https://github.com/agent-sh/agent-workspace-linux 项目说明书 生成时间：2026-06-14 20:53:38 UTC ## 目录 - [Project Overview & System Architecture](#page-1) - [Permission Model & Security Boundary](#page-2) - [MCP Tools, Workspace Lifecycle & Browser Automation](#page-3) - [Installation, GPUI Viewer & Deployment](#page-4) ## Project Overview & System Architecture ### 相关页面 相关主题：[Permission Model & Security Boundary](#page-2), [MCP Tools, Workspace Lifecycle & Browser Automation](#page-3), [Installation, GPUI Viewer & Deployment](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) - [npm/README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/npm/README.md) - [npm/package.json](https://github.com/agent-sh/agent-workspace-linux/blob/main/npm/package.json) - [scripts/lib/chrome_cdp.js](https://github.com/agent-sh/agent-workspace-linux/blob/main/scripts/lib/chrome_cdp.js) - [install.sh](https://github.com/agent-sh/agent-workspace-linux/blob/main/install.sh) - [SECURITY.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/SECURITY.md) - [docs/permission-model.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/docs/permission-model.md)
# Project Overview & System Architecture ## 项目定位与目标 `agent-workspace-linux` 提供一个**独立的、隐藏的 Linux 桌面**，让 AI 智能体（agent）能够通过 [MCP](https://modelcontextprotocol.io) 完全控制该桌面，而**不会触碰用户真实的鼠标、键盘、焦点或浏览器**。该项目的核心命题是：当 agent 需要进行 GUI 自动化、网站 QA 或浏览器操作时，应当在一个与其宿主环境**隔离**的 X11 会话中执行。资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) 仓库明确定义了适用场景： - 在 agent 不能劫持用户真实桌面或 Chrome 会话的前提下进行 GUI / Web QA； - 在可观察、可停止的"一次性" profile 中执行浏览器自动化； - 提供一个可启动、截图、检视后销毁的洁净 Linux 桌面； - 为长时间运行或无头的 agent 提供一个无需人工值守的桌面环境。资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) 项目的**反向互补项目**为 [`computer-use-linux`](https://github.com/agent-sh/computer-use-linux)：后者自动化的是**用户当前的真实桌面**，而本项目自动化的是**agent 独占的隔离桌面**。资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) ## 系统架构总览 系统采用"**MCP 前端 + 工作区守护进程 + 隐藏 X11 会话 + 可选 GPUI 浮窗**"的分层结构。MCP 服务器通过 stdio 与 Claude Code、Codex 等 MCP host 通信，对外暴露约 86 个工具；后端通过一个 Unix 控制套接字（模式 `0600`）管理隐藏的 Xvfb 显示与窗口管理器实例。资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) ```mermaid flowchart TB Host["MCP Host
(Claude Code / Codex)"] MCP["agent-workspace-linux MCP Server
stdio / JSON-RPC"] Doc["docs/permission-model.md
权限边界"] Daemon["工作区守护进程
Unix 控制套接字 (0600)"] Xvfb["Xvfb 隐藏显示
+ openbox 窗口管理器"] Apps["工作区内应用
(xterm / Chromium / 自定义)"] CDP["Chromium DevTools
(loopback CDP)"] Bwrap["bubblewrap
挂载 / 网络隔离"] Viewer["GPUI 浮窗
pause / read-only / stop"] Skill["skills/agent-workspace-linux/SKILL.md
渐进式工具加载"] Host <-->|stdio| MCP MCP --> Doc MCP <-->|控制套接字| Daemon Daemon --> Xvfb Xvfb --> Apps Apps <--> CDP Daemon -.可选.-> Bwrap Daemon -.可选.-> Viewer Host -.按需读取.-> Skill Skill -.路由.-> MCP ``` 核心组件职责划分： - **隐藏工作区**（Hidden workspace）— 私有的 `Xvfb` 显示 + 窗口管理器 + 控制套接字。创建时强制要求 `--ack-hidden-workspace` 显式确认，避免静默启动。资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) - **权限上限**（Permission ceiling）— 可通过 `--permissions file.json` 或环境变量 `AGENT_WORKSPACE_PERMISSIONS` 声明网络模式、挂载路径、应用白名单；bubblewrap 可用时即生效，否则仅声明不执行并由运行时提示。资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) - **Profiles** — 可复用的工作区定义（挂载、网络模式、setup 命令、启动应用）。资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) - **Viewer** — 基于 GPUI 的小型浮窗，展示工作区状态与实时屏幕视图，提供 `pause` / `read-only` / `stop`，默认不强制置顶。资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) - **工作区浏览器** — 通过 loopback CDP 端点控制的、归属于工作区的 Chromium，**绝不**接入用户宿主 Chrome。资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) - **Skill** — 仓库内置 `skills/agent-workspace-linux/SKILL.md`，仅加载短描述，agent 按需读取并按"orient → start → observe → act → stop"阶段路由到具体工具，避免一次性向上下文注入全部 ~86 个工具的 schema。资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) ## 安装与分发 `install.sh` 是仓库提供的一键脚本：构建 release 二进制、安装到 `~/.local/bin/`，并将 skill 默认安装到 `~/.codex/skills/`，可安全重复运行。Codex MCP 注册为可选流程，建议仅在通用 MCP host 工作流下使用 `--codex-configure`。资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) 也可从源码安装： ```bash cargo install --git https://github.com/agent-sh/agent-workspace-linux ``` 资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) npm 包 `@agent-sh/agent-workspace-linux` 是一个分发包装器（version `0.1.4`），其 `postinstall` 脚本从匹配的 GitHub Release 下载预编译的 Linux 二进制，并校验同名的 `.sha256` 附属文件。仅支持 Linux，`x64` 与 `arm64`。资料来源：[npm/package.json](https://github.com/agent-sh/agent-workspace-linux/blob/main/npm/package.json)、[npm/README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/npm/README.md) ## 权限边界与信任模型 仓库在 README 中以表格显式划分了**四种边界控制者**，这一点对理解架构至关重要： | 场景 | 谁设定边界 | 强制内容 | 是否可运行时变更 | |---|---|---|---| | 默认（无 `--permissions`） | MCP host（Claude Code / Codex） | MCP 不施加自有上限，仅一次显式确认隐藏工作区 | 是 — 由 host/用户负责审批 | | 开发者上限（`--permissions` / 环境变量） | 启动 MCP 的开发者/运维者 | 网络模式、挂载、应用白名单；在 MCP 前端 **和** 守护进程 IPC 两处强制 | **否** — 仅能通过重启 MCP 改变 | | Viewer 实时控制（pause / read-only） | 实时观看的人类 | 当共享控制状态可读时尊重运行时 pause；不可读时**fail-open** | 仅为便捷层，非安全边界 | | 工作区 vs. 宿主 | 运行时 | 输入、截图、窗口、剪贴板、浏览器控制**仅**作用于隐藏工作区 | 泄露到宿主视为可上报缺陷 | 资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) 整体模型可概括为：**默认由 agent host 拥有权限；开发者可通过 flag/env 锁定由守护进程强制执行的硬上限；Viewer 为人类提供尽力而为的实时停止能力**——三者分层而非冲突。资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) 控制套接字为同 uid 的 Unix socket，模式 `0600`；**默认不提供跨用户保护**，需要多用户隔离时应以专用用户运行。资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) ## 浏览器与 CDP 子系统 `scripts/lib/chrome_cdp.js` 实现了一个面向 loopback 的 Chrome DevTools 客户端：使用原生 Node.js `http` 与 `net` 模块，避免引入 puppeteer 等重型依赖。其关键约束包括： - HTTP 端点必须为 `http:` 且主机名必须为 `127.0.0.1` / `localhost` / `::1`，否则抛出异常。资料来源：[scripts/lib/chrome_cdp.js](https://github.com/agent-sh/agent-workspace-linux/blob/main/scripts/lib/chrome_cdp.js) - WebSocket 必须为 `ws:` 且同样限定为 loopback，否则拒绝连接。资料来源：[scripts/lib/chrome_cdp.js](https://github.com/agent-sh/agent-workspace-linux/blob/main/scripts/lib/chrome_cdp.js) - 帧解析阶段对超大长度（`> Number.MAX_SAFE_INTEGER`）进行显式拒绝，防止 OOM。资料来源：[scripts/lib/chrome_cdp.js](https://github.com/agent-sh/agent-workspace-linux/blob/main/scripts/lib/chrome_cdp.js) - `createTarget` 在收到 `HTTP 405` / `HTTP 501` 时回退到 `GET`，兼容某些 Chromium 版本。资料来源：[scripts/lib/chrome_cdp.js](https://github.com/agent-sh/agent-workspace-linux/blob/main/scripts/lib/chrome_cdp.js) 该实现支撑了"用工作区浏览器工具替代宿主 Chrome bridge"的真实 profile 验证脚本（`scripts/mcp_real_profile_browser_session_dogfood.js`）。资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) ## 已知社区关注点 社区 issue 中已经识别出两个与架构直接相关的边界风险： - **#21** — 工作区守护进程的 live-control 闸门在 `mcp-control.json` 不可读时**对变更型 IPC 请求 fail-open**；由于守护进程是 viewer-forwarded input（不经 MCP 前端）的权威执行点，该行为放大了未经授权的写入面。资料来源：[issue #21](https://github.com/agent-sh/agent-workspace-linux/issues/21) - **#22** — 宿主剪贴板粘贴到工作区**没有大小上限、也没有显式同意提示**，构成 host → workspace 的机密性泄露面（宿主 secret、token、提示可能进入 agent 控制的环境）。资料来源：[issue #22](https://github.com/agent-sh/agent-workspace-linux/issues/22) 这两点均与 README 中"viewer 是尽力而为、安全边界在权限上限"的承诺形成张力，提示用户在依赖 Viewer 控制的同时，应优先启用开发者上限并核对 bubblewrap 是否实际生效。资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) ## See Also - [Permission Model](./permission-model.md) - [GPUI Viewer Direction](./gpui-viewer-direction.md) - [SECURITY Policy](../SECURITY.md) - [Sibling project: computer-use-linux](https://github.com/agent-sh/computer-use-linux) --- ## Permission Model & Security Boundary ### 相关页面 相关主题：[Project Overview & System Architecture](#page-1), [MCP Tools, Workspace Lifecycle & Browser Automation](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [src/permissions.rs](https://github.com/agent-sh/agent-workspace-linux/blob/main/src/permissions.rs) - [src/policy.rs](https://github.com/agent-sh/agent-workspace-linux/blob/main/src/policy.rs) - [src/guardrails.rs](https://github.com/agent-sh/agent-workspace-linux/blob/main/src/guardrails.rs) - [src/control.rs](https://github.com/agent-sh/agent-workspace-linux/blob/main/src/control.rs) - [src/approval.rs](https://github.com/agent-sh/agent-workspace-linux/blob/main/src/approval.rs) - [docs/permission-model.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/docs/permission-model.md) - [README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) - [SECURITY.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/SECURITY.md)
# Permission Model & Security Boundary ## 概述与设计目标 `agent-workspace-linux` 的核心目标是为 AI agent 提供一个完全隔离的 Linux 桌面（Xvfb 显示 + 窗口管理器 + 控制 socket），同时保证 agent 的所有输入、截图、剪贴板与浏览器控制都不会触达用户的真实桌面。围绕这一目标，项目建立了一套**分层而非冲突**的权限边界体系，明确区分"由谁设界"、"如何生效"以及"是否可被运行时覆盖"。 资料来源：[README.md:12-22]() ## 三层边界模型 项目的权限模型由三个相互独立、互不冲突的层次组成，下表展示了它们各自的作用域与失效语义。 | 层级 | 设置者 | 强制点 | 运行时是否可覆盖 | |------|--------|--------|------------------| | 默认模式（无 `--permissions`） | agent host（如 Claude Code、Codex） | MCP 自身不设置上限，交给宿主审批流；通过 `--ack-hidden-workspace` 显式确认将 workspace 本地操作限定在该环境内 | 是——宿主/用户掌控审批 | | 开发者上限（`--permissions file.json` 或 `AGENT_WORKSPACE_PERMISSIONS` 环境变量） | 启动 MCP 的开发者/运维者 | 网络模式、挂载路径、应用白名单在 MCP 前端与 workspace daemon 的 IPC socket **双重强制**——即使 workspace 启动的 app 或其他同 uid 进程也被限制 | 否——只能通过重启 MCP 并使用新配置覆盖；**这是权威边界** | | 实时 viewer 控制（暂停/只读/停止） | 实时观看的人工用户 | 仅尽力而为：可读控制状态时遵循暂停状态；不可读时**失败开放**（fail open） | 仅作为便捷层，**非安全边界** | 资料来源：[README.md:62-78]() ### 关键概念 - **Hidden workspace**：私有 Xvfb 显示 + 窗口管理器 + 控制 socket；创建时必须使用 `--ack-hidden-workspace`，确保用户明确知晓。资料来源：[README.md:82-86]() - **Permission ceiling**：可选的 JSON 配置（含 `network`、`mounts`、`apps`），在 MCP 进程生命周期内强制生效。资料来源：[README.md:82-86]() - **bubblewrap 隔离**：挂载与网络隔离在 [bubblewrap](https://github.com/containers/bubblewrap) 可用时通过其执行；不可用时策略仅被声明但不会被强制执行，运行时会有相应提示。资料来源：[README.md:82-86]() - **Workspace 浏览器**：通过 loopback CDP 控制 workspace 自有 Chrome/Chromium，浏览器自动化**绝不连接宿主机 Chrome**。资料来源：[README.md:14-22]() ## 控制状态门控与已知失效模式 viewer 与 workspace daemon 通过共享控制状态文件 `mcp-control.json`（状态值如 `active` / `read_only` / `paused`）协调暂停/只读行为。该门控是 viewer 转发的输入（不走 MCP 前端）的权威强制点，控制逻辑主要由 `src/control.rs` 与 `src/guardrails.rs` 负责。 ```mermaid flowchart LR A[viewer 用户点击暂停] --> B[写入 mcp-control.json] B --> C{daemon 能否读取?} C -- 可读 --> D[拒绝变更类 IPC] C -- 不可读 --> E[失败开放: 允许变更类 IPC] E --> F[Issue #21 报告面] ``` 社区已记录一项目前已知缺陷：当 daemon **无法读取** `mcp-control.json` 时，活体控制门**对变更类 IPC 请求失败开放**——这意味着在配置不可达的状态下，变更类请求仍会被执行。由于 daemon 是 viewer 输入转发的唯一权威强制点，该缺陷具有较高影响，应作为 fail-closed 设计目标来处理。资料来源：[Issue #21: Daemon live-control gate fails open on unreadable mcp-control.json](https://github.com/agent-sh/agent-workspace-linux/issues/21) ## 已知信息流风险与社区反馈 ### 剪贴板的宿主→workspace 泄露面 社区同样记录了剪贴板方向上的风险：宿主剪贴板内容被粘贴进隔离 workspace 时**没有大小上限**，也**没有显式提示**用户"这会把宿主剪贴板内容送入 agent 控制的工作区"。这构成 host → workspace 的机密性泄露面——宿主侧的秘密、token、提示词可能被 agent 观测到。资料来源：[Issue #22: No size cap or explicit consent on host->workspace clipboard paste](https://github.com/agent-sh/agent-workspace-linux/issues/22) ### 文档参考与可报告缺陷边界 - `docs/permission-model.md` 详细阐述了权威模型。资料来源：[README.md:30-36]() - `SECURITY.md` 描述信任模型与漏洞报告路径。资料来源：[README.md:30-36]() - 项目明确声明：host↔workspace 之间的截图、窗口、剪贴板、浏览器控制**只对隐藏 workspace 生效**——任何向宿主侧的泄露均视为可报告缺陷。资料来源：[README.md:62-78]() ## 单用户信任前提 控制 socket 是同 uid 的 Unix socket（mode 0600），设计上**不提供跨用户保护**。多用户隔离需要将 MCP 以专用用户身份运行。资料来源：[README.md:18-22]() ## 总结 `agent-workspace-linux` 的权限模型是一个**分层而非冲突**的体系：默认下放权给 agent host，可叠加硬性 daemon 级上限，叠加人工实时 viewer 控制。任何对边界的偏离——无论是 daemon 失败开放、剪贴板泄露，还是向宿主 Chrome 桥接——都应作为可报告缺陷处理，而非依赖运行时审批流兜底。开发者最稳妥的实践是显式提供 `--permissions` JSON，使网络、挂载、应用白名单在 MCP 前端与 IPC socket 双重强制生效。 ## 另见 - [README.md](README.md) - [docs/permission-model.md](docs/permission-model.md) - [SECURITY.md](SECURITY.md) - [Issue #21 — Daemon live-control gate fails open](https://github.com/agent-sh/agent-workspace-linux/issues/21) - [Issue #22 — Host→workspace clipboard paste risk](https://github.com/agent-sh/agent-workspace-linux/issues/22) --- ## MCP Tools, Workspace Lifecycle & Browser Automation ### 相关页面 相关主题：[Project Overview & System Architecture](#page-1), [Permission Model & Security Boundary](#page-2), [Installation, GPUI Viewer & Deployment](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) - [npm/package.json](https://github.com/agent-sh/agent-workspace-linux/blob/main/npm/package.json) - [npm/README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/npm/README.md) - [scripts/lib/chrome_cdp.js](https://github.com/agent-sh/agent-workspace-linux/blob/main/scripts/lib/chrome_cdp.js) - [skills/agent-workspace-linux/SKILL.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/skills/agent-workspace-linux/SKILL.md) - [install.sh](https://github.com/agent-sh/agent-workspace-linux/blob/main/install.sh) - [scripts/mcp_real_profile_browser_session_dogfood.js](https://github.com/agent-sh/agent-workspace-linux/blob/main/scripts/mcp_real_profile_browser_session_dogfood.js) - [docs/permission-model.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/docs/permission-model.md) - [SECURITY.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/SECURITY.md)
# MCP Tools、Workspace Lifecycle 与浏览器自动化 ## 1. 概述 `agent-workspace-linux` 通过 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 在 stdio 上对外提供约 **86 个工具**，覆盖隐藏 X11 工作区的创建、观测、应用启动、剪贴板交互以及基于 Chrome DevTools Protocol（CDP）的浏览器自动化 资料来源：[README.md](README.md)。其核心理念是让 AI 代理拥有**独立的桌面**——一个由 `Xvfb` 启动的私有 X11 显示器，加上 `openbox` 窗口管理器和仅对该显示器可见的 CDP 浏览器——而不侵占用户真实桌面、焦点或已登录的 Chrome 会话 资料来源：[README.md](README.md)。 ```mermaid flowchart LR Agent[MCP 代理 / Claude Code] -- "JSON-RPC / stdio" --> MCP[agent-workspace-linux mcp] MCP -- "权限闸门 (MCP 前端)" --> Daemon[工作区守护进程
Unix socket 0600] Daemon -- "X11 协议" --> Xvfb[Xvfb 隐藏显示器] Daemon -- "CDP over loopback" --> Chromium[Workspace Chromium] Daemon -- "viewer IPC" --> Viewer[GPUI 浮动查看器] Daemon -. "bubblewrap" .-> Sandbox[网络/挂载隔离] ``` ## 2. MCP 工具与渐进式 Skill 加载 MCP 进程（`agent-workspace-linux mcp`）一次性向宿主（Claude Code、Codex 等）注册全部工具，但默认不在初始上下文中加载它们的全部 schema，而是发布一个**短描述 Skill** 资料来源：[README.md](README.md)。Skill 文件位于 [`skills/agent-workspace-linux/SKILL.md`](skills/agent-workspace-linux/SKILL.md)，其安装路径默认为 `~/.codex/skills/`，可通过 `./install.sh --skills-dir` 或 `--no-skill` 覆盖；Claude 用户可改用 `--skills-dir ~/.claude/skills` 资料来源：[README.md](README.md)。 工具按生命周期阶段路由：**orient → start → observe → act → stop**。`install.sh` 在安装时把 Skill 复制到宿主 Skills 目录，但 MCP 服务端的注册（`mcpServers.agent-workspace-linux` 的 `command` 与 `args`）由各宿主自行完成——Codex for Linux 推荐使用专门的 **Agent Workspaces** 功能页进行配置，而非泛用的 MCP 设置页 资料来源：[npm/README.md](npm/README.md)。npm 包装器（`@agent-sh/agent-workspace-linux`）在 `postinstall` 阶段会从 GitHub Release 下载匹配架构的预编译二进制，并使用同名的 `.sha256` 副文件进行校验 资料来源：[npm/package.json](npm/package.json)。 ## 3. 工作区生命周期 工作区生命周期由 CLI 与 MCP 工具共同驱动，且创建隐藏工作区必须显式加上 `--ack-hidden-workspace` 标志，以避免静默接管 资料来源：[README.md](README.md)。典型快速启动流程如下 资料来源：[README.md](README.md)： ```bash agent-workspace-linux doctor # 诊断依赖、显示、沙箱后端 agent-workspace-linux workspace start --dry-run # 预览，不创建 agent-workspace-linux workspace start --ack-hidden-workspace --purpose "QA run" agent-workspace-linux viewer # 浮动查看器 agent-workspace-linux workspace launch --name editor -- xterm agent-workspace-linux workspace observe --screenshot --output /tmp/ws.png agent-workspace-linux workspace stop ``` **核心概念**包括：隐藏工作区（私有 `Xvfb` + 控制 socket）、权限上限（JSON 中的 `network`/`mounts`/`apps`，由守护进程强制执行）、可复用的 **Profiles**（挂载、网络模式、启动命令与启动应用），以及 workspace-owned 浏览器（通过 loopback CDP 控制，不接触宿主机 Chrome） 资料来源：[README.md](README.md)。bubblewrap 可用时，网络隔离（`disabled` / `local_only` / `inherit_host`）与挂载隔离由其实施；不可用时这些策略**仅声明不强制**，运行时会在诊断中明确指出 资料来源：[README.md](README.md)。 ## 4. 基于 Chrome DevTools Protocol 的浏览器自动化 浏览器由工作区所有：Chrome/Chromium 通过 loopback HTTP/WS 暴露 DevTools 端点，所有 CDP 调用被限定为 `127.0.0.1`、`localhost`、`::1` 或 `[::1]`，并要求 `ws:` / `http:` 协议 资料来源：[scripts/lib/chrome_cdp.js:24-43](scripts/lib/chrome_cdp.js) 与 [scripts/lib/chrome_cdp.js:90-104](scripts/lib/chrome_cdp.js)。`chrome_cdp.js` 提供如下原语： | 导出函数 | 作用 | |---------|------| | `normalizeEndpoint(endpoint)` | 强制 loopback 主机与 http 协议 | | `listTargets(endpoint)` | 通过 `/json/list` 列出可用目标 | | `createTarget(endpoint, targetUrl)` | 通过 `/json/new`（PUT/GET）打开新标签页 | | `waitForDevToolsEndpoint(file)` | 轮询 `DevToolsActivePort` 文件直到就绪 | | `CdpConnection.connect(url)` | 完成 RFC 6455 握手，校验 `Sec-WebSocket-Accept` | | `evaluateExpression(target, expr)` | `Runtime.enable` + `Runtime.evaluate` 取 `returnByValue` | 握手实现手写完成：生成 16 字节随机 `Sec-WebSocket-Key`、计算 SHA-1 + base64 的期望 `Sec-WebSocket-Accept`，并解析 `HTTP/1.1 101` 响应以处理拆包 资料来源：[scripts/lib/chrome_cdp.js:106-145](scripts/lib/chrome_cdp.js)。 对于真实账户（Slack/GitHub）验证，推荐使用 `scripts/mcp_real_profile_browser_session_dogfood.js` 显式 dogfood 流程：先由人工批准一份 Chrome 用户数据目录，再由脚本复制到一次性目录、复用 `browser-session` 模板启动，并通过 workspace 浏览器工具而不是宿主机 Chrome 桥来证明登录页可见 资料来源：[README.md](README.md) 与 [scripts/mcp_real_profile_browser_session_dogfood.js](scripts/mcp_real_profile_browser_session_dogfood.js)。 ## 5. 权限与社区关注的边界 项目在文档中显式划分了**谁**拥有边界 资料来源：[README.md](README.md)、[docs/permission-model.md](docs/permission-model.md)： | 场景 | 边界所有者 | 是否运行时可覆盖 | |------|----------|----------------| | 默认（无 `--permissions`） | Agent 宿主 | 是（宿主审批流） | | 开发者上限（`--permissions` 或 `AGENT_WORKSPACE_PERMISSIONS`） | 启动 MCP 的开发者/运维 | **否**，权威边界 | | 实时查看器控制（pause / read-only） | 观看的人类 | 尽力而为，非安全边界 | **已知社区问题：** - **#21** 守护进程的实时控制闸门（`active`/`read_only`/`paused`）在 `mcp-control.json` 不可读时**对可变 IPC 请求 fail-open**——这是 viewer 转发的输入（不经过 MCP 前端）的权威执行点，因此该状态在不可读时本应拒绝但当前放行 资料来源：[Issue #21](https://github.com/agent-sh/agent-workspace-linux/issues/21)。 - **#22** 主机→工作区的剪贴板粘贴**无大小上限也无显式同意**——宿主剪贴板中的密钥/令牌可能被无声地发送进 Agent 控制的工作区 资料来源：[Issue #22](https://github.com/agent-sh/agent-workspace-linux/issues/22)。 - **v0.1.3** 引入了**可选的查看器输入转发**（PR #17），进一步把"查看器是旁观者"的前提改成了"可选介入者" 资料来源：[Release v0.1.3](https://github.com/agent-sh/agent-workspace-linux/releases/tag/v0.1.3)。 ## 6. 失败模式与最佳实践 - **bubblewrap 缺失**：网络/挂载策略**仅声明、不强制**。生产部署应优先在具备 bubblewrap 的环境运行。 - **单用户信任模型**：控制 socket 是同 UID 的 Unix socket（权限 0600），按设计**不提供跨用户保护**。多用户隔离需以专用用户运行 资料来源：[README.md](README.md)。 - **Wayland 支持**：查看器在 X11/Xwayland 验证，原生 Wayland 仍在演进 资料来源：[README.md](README.md)。 - **Live 控件是便利层**，而非安全边界——所有约束都应通过 `--permissions` JSON 在 MCP 启动时钉死。 ## 另请参阅 - [Permission boundary](https://github.com/agent-sh/agent-workspace-linux/blob/main/docs/permission-model.md) - [GPUI viewer direction](https://github.com/agent-sh/agent-workspace-linux/blob/main/docs/gpui-viewer-direction.md) - [SECURITY.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/SECURITY.md) - [CONTRIBUTING.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/CONTRIBUTING.md) - 兄弟项目 [computer-use-linux](https://github.com/agent-sh/computer-use-linux)（驱动**用户真实**桌面） --- ## Installation, GPUI Viewer & Deployment ### 相关页面 相关主题：[Project Overview & System Architecture](#page-1), [MCP Tools, Workspace Lifecycle & Browser Automation](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) - [install.sh](https://github.com/agent-sh/agent-workspace-linux/blob/main/install.sh) - [npm/README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/npm/README.md) - [npm/package.json](https://github.com/agent-sh/agent-workspace-linux/blob/main/npm/package.json) - [scripts/lib/chrome_cdp.js](https://github.com/agent-sh/agent-workspace-linux/blob/main/scripts/lib/chrome_cdp.js) - [docs/gpui-viewer-direction.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/docs/gpui-viewer-direction.md)
# Installation, GPUI Viewer & Deployment 本页聚焦 `agent-workspace-linux` 的安装路径、GPUI 浮窗查看器的部署形态，以及面向 MCP 主机的整体部署流程。当前发布版为 **v0.1.4**（仅 Linux），主要面向 X11（`Xvfb`）工作区，Wayland 仍属"逐步成熟"状态。 ## 安装总览 `agent-workspace-linux` 提供三种安装通道：仓库根目录的 `install.sh` 一键脚本、从 git 直接 `cargo install`、以及 npm 包装器。每条通道的产物一致：把 `agent-workspace-linux` 可执行文件落到 `PATH` 上，并按需安装技能包（默认 `~/.codex/skills/`）。`install.sh` 是可重复执行的，并提供多项可选开关，适合升级与清理。 资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) ## 安装通道 ### 系统依赖 `install.sh` 与 `cargo install` 通道都假定以下运行时依赖已经存在。Debian/Ubuntu 发行版一行即可： ```bash sudo apt install xvfb openbox xdotool xauth x11-utils imagemagick xclip \ bubblewrap pkg-config libxkbcommon-x11-dev ``` `bubblewrap` 是 mount / network 隔离的执行后端；缺失时这些策略只会被声明，不会被强制执行（运行时会在诊断中告知）。 资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) ### `install.sh` 一键安装 仓库根目录下的 [`install.sh`](https://github.com/agent-sh/agent-workspace-linux/blob/main/install.sh) 完成"构建 + 安装二进制 + 安装技能"的端到端流程。可用参数如下： | 参数 | 用途 | |------|------| | `--permissions` | 以 JSON 文件声明开发者强制的权限天花板 | | `--clean-codex-config` | 清理 Codex 通用 MCP/配置页中残留的旧条目 | | `--skills-dir` | 覆盖默认的技能包目录（如 `~/.claude/skills`） | | `--no-skill` | 跳过技能包安装 | | `--dry-run` | 只演练，不落盘 | | `--codex-configure` | 在通用 MCP/配置页上注册（仅推荐通用 MCP 主机场景） | 资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md)；[install.sh](https://github.com/agent-sh/agent-workspace-linux/blob/main/install.sh) ### 从源码 `cargo install` 无需 crates.io，直接从 git 拉取并以锁定版本构建： ```bash cargo install --git https://github.com/agent-sh/agent-workspace-linux # 或锁定标签 cargo install --git https://github.com/agent-sh/agent-workspace-linux --tag v0.1.4 ``` 该路径只安装二进制；技能包与 MCP 客户端注册需手动完成。 资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) ### npm 包装器 [`@agent-sh/agent-workspace-linux`](https://github.com/agent-sh/agent-workspace-linux/blob/main/npm/README.md) 是 npm 侧的分发包，仅作二进制分发使用。其 `postinstall` 脚本会从匹配的 GitHub Release 下载对应架构的预构建产物，并使用 `.sha256` 侧车文件校验完整性。`package.json` 中明确： - `os: ["linux"]`，`cpu: ["x64", "arm64"]` - `engines.node >= 18` - `bin.agent-workspace-linux` 指向 `bin/agent-workspace-linux.js` 安装命令： ```bash npm install -g @agent-sh/agent-workspace-linux ``` 若包管理器跳过 lifecycle script（如 `pnpm` 配合 `ignore-scripts=true`），可手动补救： ```bash node $(npm root -g)/@agent-sh/agent-workspace-linux/scripts/postinstall.js ``` 资料来源：[npm/README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/npm/README.md)；[npm/package.json](https://github.com/agent-sh/agent-workspace-linux/blob/main/npm/package.json) ### 预构建二进制 每个 [GitHub Release](https://github.com/agent-sh/agent-workspace-linux/releases/latest) 同时附带 `x86_64` 与 `aarch64` 的 Linux 二进制及 `.sha256` 侧车文件；按常规方式下载、`sha256sum -c` 校验、`chmod +x` 后即可放到 `PATH` 上。 资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) ## MCP 主机部署 服务以 stdio 上的 JSON-RPC 对外暴露 MCP。最小化的 `.mcp.json` 片段： ```json { "mcpServers": { "agent-workspace-linux": { "command": "/home/YOU/.local/bin/agent-workspace-linux", "args": ["mcp"] } } } ``` 在 Codex for Linux 上，官方推荐使用专属的 **Agent Workspaces** 功能页配置后端、权限天花板与重连控制，避免把该后端写入通用 MCP/配置页。如果历史安装遗留了旧条目，可运行 `./install.sh --clean-codex-config` 清理。 资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md)；[install.sh](https://github.com/agent-sh/agent-workspace-linux/blob/main/install.sh) ### 技能包与渐进式工具加载 MCP 一共暴露约 86 个工具，为避免全部灌入上下文，仓库随附技能 [`skills/agent-workspace-linux/SKILL.md`](https://github.com/agent-sh/agent-workspace-linux/blob/main/skills/agent-workspace-linux/SKILL.md)。宿主只在元信息层面看到技能的简介；当任务真正需要隔离桌面或浏览器时，再按"orient → start → observe → act → stop"阶段按需载入工具 schema。`./install.sh` 默认把它装到 `~/.codex/skills/`，Claude 用户可通过 `--skills-dir ~/.claude/skills` 覆盖。 资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) ### 真实账号浏览器会话 对于需要在隔离工作区中复用 GitHub / Slack 已登录 Chrome profile 的场景，仓库提供 [`scripts/mcp_real_profile_browser_session_dogfood.js`](https://github.com/agent-sh/agent-workspace-linux/blob/main/scripts/mcp_real_profile_browser_session_dogfood.js) 作为可选辅助脚本。脚本会拒绝显而易见的危险 profile、把批准的 profile 复制到一次性目录、通过仓库 MCP 路径启动 `browser-session` 模板，并最终用工作区浏览器工具（而非主机 Chrome）验证登录页面。 底层通过 [`scripts/lib/chrome_cdp.js`](https://github.com/agent-sh/agent-workspace-linux/blob/main/scripts/lib/chrome_cdp.js) 中的 `CdpConnection`、`createTarget`、`evaluateExpression`、`normalizeEndpoint` 等函数与 Chrome DevTools 协议交互。模块强制要求端点协议为 `http:`、WebSocket 协议为 `ws:`，且主机名必须为 loopback（`127.0.0.1` / `localhost` / `::1`），以保证隔离边界不被绕过。 资料来源：[scripts/lib/chrome_cdp.js](https://github.com/agent-sh/agent-workspace-linux/blob/main/scripts/lib/chrome_cdp.js) ## GPUI 浮窗查看器 ### 方向与设计 GPUI 浮窗查看器是项目面向人类的"可视控制面"，由独立的方向文档 [`docs/gpui-viewer-direction.md`](https://github.com/agent-sh/agent-workspace-linux/blob/main/docs/gpui-viewer-direction.md) 定义。它以小型浮动窗口呈现工作区状态和实时屏幕画面，并提供 `pause / read-only / stop` 等控制项。默认**不强制置顶**，定位为"人类实时监督"的便利层。 资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md)；[docs/gpui-viewer-direction.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/docs/gpui-viewer-direction.md) ### 部署形态 启动方式： ```bash agent-workspace-linux viewer ``` 完整工作流演示： ```bash agent-workspace-linux doctor # 探测依赖/显示/沙箱后端 agent-workspace-linux workspace start --dry-run # 演练，不创建任何东西 agent-workspace-linux workspace start --ack-hidden-workspace --purpose "QA run" agent-workspace-linux viewer # 打开浮窗查看器 agent-workspace-linux workspace launch --name editor -- xterm agent-workspace-linux workspace observe --screenshot --output /tmp/ws.png agent-workspace-linux workspace stop ``` 通过 MCP 主机调用时无需手敲上述命令——agent 通过匹配的 MCP 工具完成等价流程，并由技能按需加载工具 schema。 资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md) ### 部署时需要关注的运行时风险 v0.1.3 通过 [#17](https://github.com/agent-sh/agent-workspace-linux/pull/17) 引入了"查看器输入转发（opt-in）"。随后社区报告揭示了两条与查看器/控制面相关的运行时风险，部署时必须留意： - **#21**：当 `mcp-control.json` 不可读时，daemon 的 live-control（`active / read_only / paused`）闸门对变更类 IPC **失败开放（fail-open）**。由于查看器转发的输入不经过 MCP 前端，daemon 是事实上的权威执行点——配置不可读时，变更类请求仍被放行，违反最小权限假设。 - **#22**：从主机剪贴板向工作区的粘贴**没有大小上限**，也没有"你正在把主机剪贴板内容送入 agent 控制的工作区"的显式同意提示——这是 host → workspace 方向的机密性表面，主机端的 secrets / tokens / 提示可能被工作区侧读取。 这两点不改变安装流程，但提醒管理员：在生产部署中应同时启用开发者权限天花板（`--permissions` 或 `AGENT_WORKSPACE_PERMISSIONS`），把 daemon 当作真正的安全边界，并将查看器仅视为辅助工具。 资料来源：[README.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/README.md)；社区 issue [#21](https://github.com/agent-sh/agent-workspace-linux/issues/21)、[#22](https://github.com/agent-sh/agent-workspace-linux/issues/22) ## See Also - [Permission boundary](https://github.com/agent-sh/agent-workspace-linux/blob/main/docs/permission-model.md) — 权威权限模型 - [GPUI viewer direction](https://github.com/agent-sh/agent-workspace-linux/blob/main/docs/gpui-viewer-direction.md) — 可视控制面的设计 - [SECURITY.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/SECURITY.md) — 信任模型与漏洞报告 - [CONTRIBUTING.md](https://github.com/agent-sh/agent-workspace-linux/blob/main/CONTRIBUTING.md) — 贡献指南与发版门槛 - 兄弟项目：[computer-use-linux](https://github.com/agent-sh/computer-use-linux) — 操作**用户真实**桌面，与本项目互为补充 --- --- ## Doramagic 踩坑日志 项目：agent-sh/agent-workspace-linux 摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。 ## 1. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | github_repo:1247893483 | https://github.com/agent-sh/agent-workspace-linux | host_targets=mcp_host, claude_code, claude ## 2. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | github_repo:1247893483 | https://github.com/agent-sh/agent-workspace-linux | README/documentation is current enough for a first validation pass. ## 3. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | github_repo:1247893483 | https://github.com/agent-sh/agent-workspace-linux | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | github_repo:1247893483 | https://github.com/agent-sh/agent-workspace-linux | no_demo; severity=medium ## 5. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | github_repo:1247893483 | https://github.com/agent-sh/agent-workspace-linux | no_demo; severity=medium ## 6. 安全/权限坑 · 来源证据：Daemon live-control gate fails open on unreadable mcp-control.json (mutating IPC allowed) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Daemon live-control gate fails open on unreadable mcp-control.json (mutating IPC allowed) - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/agent-sh/agent-workspace-linux/issues/21 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。 ## 7. 安全/权限坑 · 来源证据：No size cap or explicit consent on host->workspace clipboard paste - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：No size cap or explicit consent on host->workspace clipboard paste - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/agent-sh/agent-workspace-linux/issues/22 | 来源类型 github_issue 暴露的待验证使用条件。 ## 8. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | github_repo:1247893483 | https://github.com/agent-sh/agent-workspace-linux | issue_or_pr_quality=unknown ## 9. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | github_repo:1247893483 | https://github.com/agent-sh/agent-workspace-linux | release_recency=unknown