cua-sandboxes 是 trycua/cua 项目中的一项技能，核心概念是“沙箱”：一台一次性的计算机，即本机上的容器或虚拟机。cua CLI 与 cua SDK（Python、TypeScript、Swift、Kotlin、Rust）共享同一个运行时和同一份沙箱列表。
用途
该技能用于在本机创建、使用和清理 cua 沙箱（一次性的 Linux 或 macOS 计算机），并在沙箱内浏览网页。本地沙箱无需账号，用完即可删除。
开始之前
可用以下命令检查环境：
cua --version # the Rust cua CLI cua config get default.on # where sandboxes run without --on (local unless changed) cua runtime doctor # local runtimes (containers, gVisor, QEMU, Lume); read-only
创建沙箱
cua sb create linux --name dev # local (default): a gVisor container cua sb create linux --kind vm --name dev # local Linux VM (QEMU) cua sb create macos --name mac # local macOS VM (Apple silicon, Lume) cua sb create ghcr.io/org/image:tag --name x # any OCI image cua sb create --on direct:127.0.0.1:3211 --token TOKEN --name mine # an existing machine running cua-spacesd
其中 --on 指定位置（local、direct:<addr>），--kind 指定类型（auto、container、vm），--runtime 指定引擎（auto、gvisor、runc、qemu、lume）。不可能的组会以 invalid placement 失败并列出有效值。本地运行时在首次使用时设置（cua runtime setup 可显式执行）。省略 --name 会生成名称。cua sb ls 打印每个沙箱的 ref（local:dev、direct:host:port）；每个 NAME 参数接受 ref 或跨位置唯一的裸名称（--local 可缩小范围）。任何命令加 --json 可获得机器可读输出。exec、shell、cp、截图和 GUI 控制都经过 cua-spacesd，因此需使用自带它的镜像（linux 别名即如此）。普通镜像仍可获得生命周期、日志和端口转发。
使用沙箱
cua sb ls # every location (--local filters) cua sb exec dev -- uname -a # run a command cua sb shell dev # interactive shell cua sb screenshot dev # save a screenshot cua sb vnc dev # open the desktop in a browser
对于 GUI 工作，先选择一次沙箱，然后使用 cua do（参见 gui-automation 技能）：
cua do switch dev cua do screenshot cua do click 400 300
清理
cua sb rm dev --force # delete
cua sb suspend dev # or pause it and cua sb resume dev later
从代码使用（Python）
import asyncio, cua
async def main(): c = cua.embedded() sb = await c.sandboxes().create(cua.SandboxCreateOptions( on="local", image="ghcr.io/trycua/linux:24.04", name="dev")) env = await sb.spacesd(None) out = await env.run(cua.SpacesdCommand(program="uname", args=["-a"])) print(out.stdout.decode()) await sb.delete()
asyncio.run(main())
TypeScript、Swift 和 Kotlin 绑定暴露相同的对象（Cua、sandboxes()、Sandbox.spacesd()）。
从 cua MCP 服务器使用
当 cua MCP 服务器连接后，优先使用其工具：images_list（存在哪些镜像）、sandbox_list、sandbox_create、sandbox_get、sandbox_delete，然后针对沙箱使用 computer_* 工具（screenshot、click、type、shell、file）。
在沙箱内浏览网页
浏览应在沙箱内进行，绝不在用户自己的浏览器中。以下均为 cua MCP 工具调用，无需其他浏览器工具或设置。
选择镜像：images_list {"browser": true}（规范的 ghcr.io/trycua/linux:24.04 自带 Chromium）。
创建带浏览器的沙箱：sandbox_create {"browser": true, "url": "https://example.com"}。它返回 id、session 以及 browser.target_id / browser.tab_id。
通过 call_tool {"space": <id>, "tool": <tool>, "arguments": {"session", "target_id", "tab_id", ...}} 驱动浏览器：
读取：get_browser_state {"snapshot_format": "semantic_v2"} 返回大纲和 refs（p1:0）；加 "include_screenshot": true 可获得图像；
browser_navigate {"url"}、browser_click {"ref", "delivery_mode": "foreground"}、browser_type {"ref", "text", "replace": true}（文本 "\n" 配合 "mode": "keystrokes" 会按下 Enter）、browser_pointer（hover、scroll、drag）；
每次页面变化后重新读取：refs 是按快照的。要测试本地应用，在沙箱中运行它（space_write、space_bash）并打开 http://127.0.0.1:<port>。
已登录站点：仅在用户要求时。teleport_browser_session 先针对确切站点返回将移动的内容和同意要求；展示给用户并仅在其批准后继续。未经批准绝不移动会话。
清理：sandbox_delete {"name": <id>}。
从终端：cua images ls --browser、cua sb create --browser --open https://example.com、cua sb view <id> 可观看。
规则
当沙箱可以完成时，绝不在用户自己的机器上运行破坏性命令。
任务结束后立即删除自己创建的沙箱。
报告所使用的沙箱名称，以便用户检查或删除。
任何指向所运行内容（预览、仪表盘、文件）的链接：使用 cua share，绝不用 localhost；发送前先打开一次确认可用。