Cua SDK 是什么:一段话说清

Cua SDK 是开源 computer-use 基础设施项目 Cua(GitHub star 约 2.8 万,2026-10 查询为 28,243)的程序化入口:一套 SDK 加一条 cua 命令,统一管理本地 VM、容器和任何跑着 cua-spacesd 的机器。SDK 提供 Python、TypeScript、Swift、Kotlin 四种语言包,沙箱基于 gVisor 容器,一条命令就能给 AI Agent 配出一台隔离、可编程、可自托管的电脑。

SDK 设计:一个 SDK、一条命令、四种语言

结论:Cua SDK 的核心设计是统一——四种语言共用一套概念模型,本地与远端机器共用一条 cua 命令。四个语言包如下(包名出自官方 README):

语言包
Pythoncua(pip install cua)
TypeScript@trycua/cua
SwiftCua
Kotlin生成绑定

接入形态有两种:作为库嵌进你的进程,或者经共享的 cua daemon 统一管理。对多端团队的意义(工程解释):服务端用 Python 写任务编排,桌面端用 Swift 或 Kotlin 做原生应用,Web 控制台用 TypeScript——三条技术栈对着同一套 API 概念写,不用各学一套方言;daemon 模式还允许多个进程共用同一批机器,避免各开各的沙箱造成浪费。Cua 整体的六大组件构成,见 Cua 是什么。

安装:一条脚本装齐 CLI、Spaces 与 MCP

SDK 与 CLI 的安装脚本和 Cua Spaces 是同一条:

curl -fsSL https://cua.ai/install.sh | sh

按官方 README,脚本清单包含四样:cua CLI、Spaces 应用(macOS 默认安装)、cua-driver 的 MCP 与 skill(可装进 Claude Code、Codex、Cursor 等,MCP 配置方法可参照本站的 Claude Code MCP 指南)、本机托管组件。装完执行 cua auth login 登录,按需可选安装 skills 与 MCP server。

沙箱快速上手:四条 cua sb 命令

结论:cua sb 是沙箱的命令族,创建、执行、截图、销毁各一条命令,Ubuntu 镜像开箱即用。

cua sb create ubuntu --name dev
cua sb exec dev uname -a
cua sb screenshot dev
cua sb rm dev

逐条解释:第一条创建名为 dev 的 Ubuntu 沙箱,底层是 gVisor 容器,首次使用时会初始化运行时,需要等一下;第二条在 dev 里执行 uname -a 验证系统信息;第三条对沙箱截屏,用于确认界面状态;第四条销毁沙箱。四条命令构成一个完整生命周期,适合放进 CI 或批处理里当一次性环境用。

gVisor 的隔离为什么算「强」(工程解释):普通容器里的进程直接向宿主内核发起系统调用,内核攻击面完整暴露;gVisor 在中间架了一个用户态内核,系统调用先经它实现和过滤,宿主内核不直接接触沙箱内进程。这也是下文对比表里把 gVisor 容器的隔离强度列为「强」的依据。

Python 等价写法:Sandbox.ephemeral 的上下文管理器风格

命令行能做的事,Python 里对应这样写(示例出自官方 README):

from cua_sandbox import Image, Sandbox

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

逐行看:Image.linux() 声明镜像,Linux 通用镜像;local=True 指定在本机跑,同一套 API 换个参数就能指到远端机器;Sandbox.ephemeral 用异步上下文管理器把沙箱生命周期框住,离开 with 块环境即回收——这正是上面四条 cua sb 命令的库版本;shell.run 在沙箱里执行命令。对写过 asyncio 的工程师,整个模式没有新概念,gVisor 的隔离由运行时保证。

沙箱内部不需要装 Agent:就绪判定换了个思路

结论:Cua 沙箱的设计是内部无需 Agent——就绪判定来自运行时与可选的端口探测,这是它与传统「VM 里预装受控代理」方案的分界线。

传统方案的流程是:做镜像时把受控 agent 预装进去,控制端启动后轮询 agent 心跳来判断可用。这个方案能用,但镜像被 agent 绑架:换 agent 版本要重做镜像,给非主流系统做镜像的成本更高。Cua 把就绪判定放在控制端一侧(运行时状态加端口探测),镜像保持干净(以上为工程分析)。分界线是一条端口:带 cua-spacesd(端口 3211)的镜像在基础沙箱能力之上,追加进程、文件、截图、经 cua-driver 的输入,以及低延迟视频与音频流——Driver 的接入细节见 Cua Driver 教程。按需决定你的沙箱是「能跑命令」还是「全能力电脑」。

自托管与远程:relay、自有云与闲置 Mac

结论:Cua 的机器可以全在你自己手里,cua host setup 让本机经 cua.ai relay 可达,不需要端口转发。

机器侧的选项有三档:你自己的 Mac(本地方案直接构建 VM)、其他你拥有的机器、你自己的云账号(AWS、Google Cloud、Modal)。闲置的旧 Mac 也能变成 Space 主机,官方文档给了 relay、Tailscale、SSH 三种接入方式。对不想把工作负载放进第三方托管沙箱的团队,「自有机器加 relay 通道」就是自托管路线的完整拼图。如果你的场景是「编码会话跑进云端一次性沙箱」,另一条路线是 Omnigent 的云沙箱,见 Omnigent 治理与沙箱。

沙箱形态对比:gVisor 容器、Lume VM、Spaces 完整桌面

Cua 里有三种「给 Agent 的电脑」,隔离强度与适用任务不同。下表「启动速度」与「适用任务」两列是工程量级判断,供选型参考,未做实测。

形态隔离强度启动速度适用任务
gVisor 容器(cua sb)强,gVisor 以系统调用拦截层实现用户态内核(gVisor 官方定位)快,容器级跑命令、处理文件等无 GUI 任务
Lume VMVM 边界隔离中,需引导操作系统需要完整 macOS/Linux 系统环境
Spaces 完整桌面VM 加完整桌面栈相对最慢,完整桌面启动人机同机协作、GUI 应用操作

选择逻辑(工程建议):任务无 GUI 就用 cua sb,成本最低、启动最快;需要 macOS 或完整 Linux 系统环境用 Lume,细节见 Cua Lume 虚拟机指南;要人盯着、要操作 GUI 应用、要 Teleport 登录态,用 Spaces。三者在 Cua 体系里不互斥,同一套 SDK 与 cua 命令都能管。

常见问题

Q:AI Agent 沙箱为什么必要?和直接用真机有什么区别?

直接答:沙箱给 Agent 一台用完即弃、边界清晰的一次性电脑,真机是长期存在的环境——前者适合不可信代码与批量任务,后者适合需要登录态与持久状态的工作。展开说:Cua 的 gVisor 沙箱在用户态拦截系统调用,隔离强度高于普通容器;配合 ephemeral 生命周期,每个任务拿到干净环境,互不污染。需要 GUI 能力时,选带 cua-spacesd(端口 3211)的镜像即可追加输入与音视频流;要登录态和完整桌面,再升级到 VM 或 Spaces。

Q:cua sdk 和 Agent 框架是什么关系?写 python computer use 用哪个?

直接答:Agent 框架管「Agent 怎么思考和决策」,Cua SDK 管「Agent 的电脑长什么样」,两者是叠加关系。展开说:写 python computer use 时,框架负责规划与工具调用循环,Cua SDK 负责那台电脑——pip install cua 之后,Sandbox、镜像、命令执行、截图、输入都是现成的;官方理念是你自带代理和模型,Cua 提供电脑与自动化工具。

Q:cua sdk 支持哪些语言?免费吗?

直接答:四种语言——Python(pip install cua)、TypeScript(@trycua/cua)、Swift(Cua)、Kotlin(生成绑定),均属 MIT 开源部分,免费使用。展开说:SDK 与 cua 命令在 README 的 Licensing 一节明确列在 MIT 清单里,商用没有额外条件;要注意的是两个可选扩展包(cua-som 与 cua-perception)带 AGPL 义务,默认不装就不受影响。