trycua/cua

一句话定位： 给 AI agent 一台真正可操作的电脑，并把桌面驱动、跨 OS 沙箱、VM 管理、评测环境和 computer-use 决策模型收进一个 monorepo。核心口号是 “Computer-Use 2.0”：同一个任务里在 CLI、API 与 GUI 之间切换，而不是把桌面自动化当成孤立的截图点击循环。

在专题中的位置

本页属于 README 专题，代表 computer use 的整机级实现：它不只操作浏览器，还提供跨 macOS/Windows/Linux 的原生桌面驱动、跨 OS 沙箱与评测基础设施。与只在浏览器内工作的 browser-use 相比，Cua 的覆盖面更靠近「Agent 真正拥有一台电脑」这一端；概念框架见 computer-use。

为什么值得关注

1. 不是单个 GUI Agent，而是一套 Computer Use 基础设施

仓库同时提供五类能力：

Cua Driver：在 macOS、Windows、Linux 上检查并操作原生应用和浏览器。
Cua SDK / CLI / daemon：创建与调度本地 VM、容器、云沙箱，并统一 shell、文件、截图、输入、服务与流媒体接口。
cua-spacesd：运行在沙箱内的服务端，补齐流媒体、窗口、远程操作、Teleport 与多人 presence。
Lume / Lumier：在 Apple Silicon 上用 Virtualization.Framework 管理 macOS、Linux VM。
Cua Bench / CUA-S1：生成 computer-use 任务、评测 agent 轨迹，并研究专用的轻量决策模型。

这使 Cua 不只是 browser-use 一类的“让模型驱动浏览器”，而是同时覆盖机器生命周期、桌面控制、数据采集与评测。

2. Driver 与 Agent 解耦，MCP 是一等接口

Cua Driver 把“观察与执行”从模型决策中抽离。任何支持 MCP 的 agent 都可以通过 cua-driver mcp 连接；shell 型 agent 可走 cua-driver call；应用则可通过 Rust、Python、TypeScript 的进程内 SDK 调用同一套原生运行时。

Driver 支持后台投递：在平台允许时，agent 可以操作应用而不移动用户指针或抢占焦点。它也把 screenshot、窗口状态、无障碍树、浏览器 DOM/CDP 与像素动作放在同一个工具面中，便于 agent 根据任务在语义操作和视觉操作之间切换。

3. 同一 Sandbox API 跨越本地、云与自有机器

Cua SDK 将运行位置统一为 local、cloud、direct：

本地容器：Docker/Podman，可用 gVisor runsc 隔离。
本地 VM：Apple Silicon 上的 Lume，或按需下载的 QEMU。
云沙箱：Fleet 托管池，也可接到用户自己的 AWS、Google Cloud 或 Modal。
自有机器：cua host setup 通过 relay 暴露，不需要入站端口。

更关键的是，sandbox 生命周期和 readiness 不依赖 guest 内 agent。只有 shell、文件、流媒体等 Spaces 能力需要 guest 中的 cua-spacesd，因此普通沙箱与完整桌面沙箱可以复用同一创建路径。

4. 协议是代码生成的，不是事后文档

libs/cua/proto/ 下的 .proto 是服务契约唯一来源，代码构建时生成。当前分两组：

协议	服务
`cua.env.v1`	System、Process、Filesystem、Computer、Windows、Accessibility、Driver、Stream、Presence、Teleport、Tunnel、Volume
`cua.daemon.v1`	Sandbox、Space、Runtime、Daemon

规则包括 gRPC 与 gRPC-Web 同端口、变更只允许向后兼容、移除字段必须 reserve、双向流禁止、客户端流必须有 unary chunked fallback。视频与音频不塞进 gRPC，而是走独立媒体协议、HTTP 或 QUIC，这对于低延迟桌面流比“把所有东西都包成 RPC”更合理。

5. 评测、轨迹和模型研究已经接在基础设施上

Cua Bench 提供：

cb run 在本地或云端运行单个任务、任务集和变体。
Registry 任务集按版本和 git commit 固定，首次拉取后缓存。
result.json 兼容 Harbor trial 字段，trajectory.json 使用 ATIF-v1.8，可直接导出训练数据。
支持把 Claude Code、Codex、Gemini CLI、OpenCode、Goose 等 coding-agent harness 放进被测沙箱。

CUA-S1 则是与通用 agent 分开的研究线：包含 855K 参数 option-attention 分类器和基于 Qwen3.5-4B 的 LoRA adapter，重点研究“只从调用方给出的候选项中选择动作”，而不是让模型直接生成任意工具参数。

组件地图

组件	路径	作用
Cua SDK / CLI / daemon	`libs/cua`	Rust 核心、UniFFI 绑定、sandbox/Space/云/本地 runtime/媒体/Teleport
Cua Driver	`libs/cua-driver`	跨平台桌面驱动、MCP/CLI/SDK、工具注册、权限与策略
cua-spacesd	`libs/cua-spacesd`	沙箱内服务端：进程、文件、桌面、窗口、流、presence、relay
Cua Spaces	`apps/cua-spaces*`	桌面应用、菜单栏/刘海入口、多人桌面、Teleport
Lume / Lumier	`libs/lume`, `libs/lumier`	Apple Silicon 本地 VM 管理，以及 Docker 兼容接口
Cua Bench	`libs/cua-bench`	任务、数据集、评测 runner、轨迹与 RL 环境
CUA-S1	`libs/cua-s1`	小型专用 computer-use 决策模型研究代码与评测
镜像与沙箱资产	`libs/images`, `libs/kasm`, `libs/qemu-docker`, `libs/xfce*`	桌面镜像、容器与 VM 运行环境

组件版本独立发布。分析时 cua-driver 为 0.36.0、cua-spacesd 为 0.5.3、cua-bench 为 0.3.0；仓库使用 Release Please 按组件 bump，不能用 GitHub 仓库级 “Latest” 推断某个组件版本。

架构主线

Python / Node / Swift / Kotlin / wasm
               |
             UniFFI
               |
          cua-sdk / cua CLI / cua daemon
     +---------+----------+----------+
     |         |          |          |
 cua-vmm   cua-image   cua-fleet   cua-spaces
 Lume/QEMU  build/pull  pool/claim  registry/MCP
     |         |          |          |
     +---------+----------+----------+
               |
       local / cloud / direct sandbox
               |
       cua-spacesd :3211 / media QUIC :3212
               |
     cua-driver -> native input / windows / browser

Cua Driver

Rust workspace 按平台拆成 platform-macos、platform-windows、platform-linux，公共协议、工具模型、会话、策略和 capture 逻辑在 cua-driver-core。平台层分别接 macOS Accessibility/ScreenCaptureKit、Windows UIA/Windows.Graphics.Capture、Linux AT-SPI/X11/Wayland。

Driver 的权限边界不只靠弹窗：

standard：普通自动化，默认不逐次提示。
bounded：只允许 reviewed manifest 中的工具和资源。
unrestricted：必须显式使用 --dangerously-bypass-approvals。
可加载 YAML 或 Rego 策略，对工具参数做范围、长度、正则和 allowlist 约束。
附加到已登录 Chromium profile、操作现有应用等高风险能力需要显式授权。

MCP 侧实现了 2026-07-28 stdio profile，同时兼容 legacy initialize 流程；内置 skill pack 可作为 MCP resources 被客户端发现和校验。HTTP endpoint 仍只支持 legacy MCP，现代 HTTP 需要等 session/application-handle 契约稳定。

cua-spacesd

cua-spacesd 是 guest 内单二进制服务，默认监听 3211：

gRPC 与 gRPC-Web 同端口，另有 reflection、/health、签名文件上传下载。
/mcp 把桌面工具注册表暴露成 Streamable HTTP MCP。
/tunnel、/hotspot 提供端口转发与反向 SOCKS。
/media 和 QUIC 3212 承载 H.264/Opus 低延迟流。
无 token 时只允许 loopback；非 loopback 强制 Bearer token，文件与 socket 使用短时 ticket 或签名 URL。

它采用 provider 边界隔离 target、capture、action、interactive input 和 accessibility；session policy 分为 view-only、background-only、allow-activation，并在调用平台动作前执行。目标身份、几何、帧、无障碍快照与 codec 各自维护 freshness，避免用错误窗口的旧坐标执行点击。

快速使用

安装并创建本地沙箱：

curl -fsSL https://cua.ai/install.sh | sh
 
cua sb create ubuntu --name dev
cua sb exec dev uname -a
cua sb screenshot dev
cua sb rm dev

Python SDK：

from cua_sandbox import Image, Sandbox
 
async with Sandbox.ephemeral(Image.linux(), local=True) as sb:
    print((await sb.shell.run("uname -a")).stdout)

把 Driver 接到 Claude Code：

claude mcp add --transport stdio cua-driver -- cua-driver mcp

运行 Cua Bench：

cb dataset list
cb run cua-bench-basic --task-filter click-button
cb run cua-bench-basic --agent cua-agent \
  --model anthropic/claude-sonnet-4-20250514 -j 4

与相邻项目的关系

项目	层级	与 Cua 的区别
agentenv	面向 agentic RL 的分布式沙箱平台	AgentENV 更偏大规模环境调度与存储；Cua 同时覆盖本地桌面体验、Driver、流与评测
cloudflare-computer	Serverless 虚拟电脑 SDK	Cloudflare Computer 偏 Durable Object 与容器/Worker；Cua 的桌面 VM、原生 GUI 与跨 OS 范围更广
harbor	Agent 评测执行框架	Harbor 擅长 task × agent × verifier 编排；Cua Bench 可产生同类评测与 ATIF 轨迹，并把 sandbox 和 computer-use 环境一起提供
browser-use	浏览器自动化 agent	browser-use 聚焦浏览器；Cua 从驱动层向上覆盖原生桌面、OS 沙箱和模型研究
playwright-mcp	浏览器 MCP	Playwright MCP 走 DOM/浏览器协议；Cua Driver 可走无障碍树、CDP 或像素级桌面操作
agent-harness-anatomy	Harness 结构概念	Cua 是 harness 与 computer-use substrate 的一个完整工程样本

局限与注意

License 不是全仓 MIT：SDK、Driver、Lume 等主体是 MIT；Cua Spaces、cua-spacesd、Cua Driver Bench 是 FSL-1.1-MIT，两年后转 MIT。可选 cua-perception 与 OmniParser 相关部分是 AGPL，商业分发或网络托管前必须单独审查。
仓库体量大且变化快：约 9,000 个 tracked files、多语言 workspace、多个独立发布流。跟踪一个能力时要先确认它属于 SDK、Driver、spacesd 还是 app，不能把整个仓库当成一个版本。
能力随平台不同：后台输入、无障碍、窗口管理、capture、音频与 cursor shape 都有平台矩阵。正确做法是查询 System.GetCapabilities，而不是按 OS 名称假设。
macOS 权限合约较重：Accessibility 与 Screen Recording grant 绑定签名 app identity；不受支持的裸二进制启动方式可能无法稳定持有权限。
CUA-S1 不是通用模型：它主要在闭合候选项中决策，卡片的 in-distribution 高分不能外推到开放 GUI。Forms 版本在目录外标签上会高置信 skip，实测 held-out accuracy 只有 29.3%。
旧包有安全历史：cuabot 已停止维护且 README 明确提示已知安全问题，不应继续运行；迁移目标是 Cua Driver 或 cua CLI。
云服务与账号耦合：本地 runtime 可独立使用，但 Fleet 托管池、relay、Cua Spaces 的部分能力依赖 cua.ai 账号与云侧服务。

zhaoweiguo 的知识库

目录