Cua 沙箱：一套 API 让 AI 代理在任意操作系统桌面上自主干活
【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua
Cua 是一个开源的计算机使用（computer-use）平台。它把隔离沙箱、后台驱动和基准测试打包成一套 SDK，让你用几行 Python 就能让 AI 代理在 Linux、macOS、Windows、Android 环境里看屏幕、点鼠标、跑命令。
定位与核心能力
Cua 解决的是一个具体问题：AI 代理想完成 GUI 任务，需要一台"真"电脑，而这台电脑必须隔离、可复现、用完即毁。Cua 把虚拟机/容器、桌面环境、输入注入和屏幕观测封装成同一个Sandbox对象，你只写代理逻辑，不用管底层跑在 Docker、QEMU 还是云上。
| 能力 | 说明 | 适用场景 |
|---|---|---|
| 跨 OS 沙箱 | 同一套 API 启动 Linux 容器/VM、macOS、Windows、Android，云端或本地均可 | 多平台代理开发、GUI 自动化测试 |
| 代码 + GUI 双通道 | 同一沙箱内既能跑 shell/Python，也能截图、点击、输入 | 先用代码建状态再操作 UI，或 UI 产出后用代码校验 |
| 图片即状态 | Image是不可变的初始环境描述，支持快照与 fork | 环境复现、并行跑大批沙箱 |
| 后台驱动 | Cua Driver 在你自己的机器上后台操控原生应用，不抢鼠标焦点 | 给现有编码代理补桌面能力 |
| 基准与 RL 环境 | Cua-Bench 提供可验证任务并导出轨迹 | 评测与训练计算机使用模型 |
环境与前置条件
- Python ≥ 3.11（Sandbox SDK 支持 3.11–3.13）
- uv（Python 包管理器），用于运行自带依赖声明的脚本
- 本地模式：Linux 容器走 Docker，macOS VM 走 Lume（需 Apple Silicon + macOS 14 及以上），Windows/Android 走 QEMU
- 云端模式：一个有沙箱池管理权限的 Fleet 访问令牌
从零到跑通：安装、配置与最小调用 ⚡
- 克隆仓库，拿到示例与文档：
git clone https://gitcode.com/GitHub_Trending/cua/cua预期结果：本地出现 cua 目录，samples/python/下有两个可直接运行的示例脚本。
- 安装沙箱 SDK：
pip install cua预期结果：import cua_sandbox不报错。
- 配置凭据（二选一）：
# 云端沙箱：导出 Fleet 令牌 export FLEETS_TOKEN="<your-access-token>" # 本地沙箱：确认 Docker Desktop 或 Lume 已就绪，无需令牌预期结果：uv run能连上对应后端。
- 运行下一节的最小调用，看到截图文件生成就算跑通。
最小可用示例：启动一台跨系统 Cua 沙箱
核心代码（摘自 README.md）：
from cua import Sandbox, Image async with Sandbox.ephemeral(Image.linux()) as sb: # 从官方 Linux 镜像起一台一次性沙箱，退出即销毁 result = await sb.shell.run("echo hello") # 代码通道：在沙箱里跑 shell 命令 screenshot = await sb.screenshot() # GUI 通道：抓当前屏幕 await sb.mouse.click(100, 200) # 在坐标 (100, 200) 点击 await sb.keyboard.type("Hello from Cua!") # 模拟键盘输入两个要点：Sandbox.ephemeral是"用完即焚"模式，结束上下文自动销毁机器；Image.linux()换成.macos()、.windows()、.android()就能换操作系统，API 一个字母都不用改。
真实场景演示：并发压测与一次性 Android 沙箱 🖥️
场景一：99 台云沙箱并发压测，脚本在 samples/python/1_fleet_throughput.py
- 目标：量化云端 Fleet 的高并发吞吐上限
- 操作：顺序连接 99 台 Android 云沙箱，再对每台并发下发 20 路"点击 + 截图"，每轮 3 组
- 结果：终端输出连接耗时的 p50/p95，以及每小时可执行的步骤总数（steps/hour），一眼看出你的 Fleet 能扛多少代理
场景二：一次性 Android 沙箱装 F-Droid，脚本在 samples/python/2_ephemeral_fdroid.py
- 目标：在干净安卓环境里预装 F-Droid 并验证它能启动
- 操作：用
Image.android().apk_install(...)声明镜像，起一台本地 ephemeral Android VM，先截主页，再用am start拉起 F-Droid 截第二张图 - 结果：
out/目录生成fdroid_home.png与fdroid_launched.png，VM 随上下文退出自动销毁，宿主机不留任何残留
生态与周边组件
- cua-sandbox：核心 SDK，创建和控制沙箱的入口，本文的主角
- cua-computer-server：沙箱内的 UI 交互与代码执行驱动，SDK 在沙箱里实际调用的那一层
- cua-agent：计算机使用代理框架，把 LLM 决策循环接在沙箱上
- cua-driver：后台计算机使用驱动，CLI 与 MCP 两种接入方式，支持 macOS/Windows/Linux
- cua-bench：基准测试与 RL 环境，跑 OSWorld、ScreenSpot 等任务并导出训练轨迹
- lume：Apple Silicon 上的 macOS/Linux 虚拟机管理工具，本地跑 macOS 沙箱的底座
- lumier：Lume 虚拟机的 Docker 兼容接口，把 VM 当容器用
资源导航
- 总入口：README.md
- 云沙箱教程：docs/content/docs/tutorials/your-first-cloud-fleet.mdx
- 示例脚本：samples/python/
【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
