cua-sandbox 技术指南用统一 Python API 管理临时 VM、云沙箱与 Fleet 暖池【免费下载链接】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/cuacua-sandbox 是 cua 仓库中提供带沙箱的虚拟计算环境 统一 Python API的库当前版本0.7.0见 libs/python/cua-sandbox/cua_sandbox/init.py它把 QEMU、Lume、Docker 等本地运行时与 Fleet 云端后端抽象为同一组Sandbox/Pool接口。读完本篇你可以掌握从临时沙箱、持久沙箱、连接已有沙箱到 Fleet 暖池自动扩缩容的完整生命周期管理方式并理解每个 API 背后的 Transport/接口对象设计。安装与依赖基础安装pip install cua-sandboxFleet 支持由已发布的cua-fleetwheel 提供其中捆绑了平台相关的fleet_sdk原生绑定。使用 pip 解析依赖时需指定 Cua wheel 索引pip install --extra-index-url https://wheels.cua.ai/simple cua-sandbox若要通过sb.driver.connect()对 Fleet 沙箱做类型化桌面控制需安装可选 Driver SDKpip install --extra-index-url https://wheels.cua.ai/simple cua-sandbox[driver]driverextra 固定cua-driver0.27.0该版本提供类型化窗口 API 和兼容的远程通道桥接且要求该版本已发布到你所在的平台同时沙箱镜像内必须运行兼容的 Driver 服务。可选 MCP envelope carrierSDK 还可以通过命名 MCP 服务承载同一套类型化 Driver 接口。这要求 guest 显式启用类型化 envelope 扩展而不仅是普通的 MCP tools 端点from cua_driver import GetScreenSizeInput async def observe_guest(pool): async with pool.claim() as sb: async with sb.driver.connect(servicemcp, transportmcp) as driver: # This is the generated cua_driver.CuaDriver, not an MCP facade. result await driver.get_screen_size(GetScreenSizeInput(sessionNone)) return resultsb.driver.connect()与sb.driver.connect(servicedriver)保持原有的 envelope HTTP 路径CuaDriver.connect(socket_path)不变。Shell、files、terminal、既有的 Sandbox desktop 调用以及 claim/pool 生命周期仍使用各自原有接口——该选项只影响sb.driver。MCP 选型会执行初始化并校验capabilities.experimental[ai.cua.driver.envelopes].version 1通过后才打开 receiver只有 tools 的旧镜像会在任何桌面动作之前就失败。连接保留 receiver 的 generation、宿主端选定的权限与取消信号但不会重连、重放动作或回退到本地 desktop。退出时 SDK 会尝试有界的 receiver 与 MCP session 清理清理未确认只会告警不构成回滚或 guest 删除的证明。线路与 launcher 契约详见 mcp-envelope-carrier.md。对外宣称支持之前应针对精确镜像与匹配的版本/原生库做测试使用固定版本的可选 extra 和兼容的 guest 运行时。Sandbox 对象一个 Transport 背后的整套接口理解各示例之前先看Sandbox的结构。从源码 cua_sandbox/sandbox.py 可以看到每个Sandbox实例在构造时把同一份Transport注入到一组接口对象上screen/mouse/keyboard/clipboard—— 屏幕与输入shell/files/terminal—— 命令行与文件window/mobile/apps—— 窗口与移动端tunnel/services—— 端口转发与服务 URLdriver—— 类型化 Driver 连接。接口实现集中在 libs/python/cua-sandbox/cua_sandbox/interfaces/ 目录shell.py、mouse.py、screen.py、driver.py、services.py、tunnel.py等传输层则位于 libs/python/cua-sandbox/cua_sandbox/transport/包括本地local.py、ssh.py、vnc.py、HTTP/WebSockethttp.py、websocket.py与 Fleet 云fleet.py、fleet_cloud.py。这种接口对象 Transport的拆分使得同一份用户代码可以无改动地跑在本地 VM 或云上。类文档字符串明确了一个设计原则Sandbox 永远是隔离的从不直接控制宿主机需要无沙箱宿主控制时要用专门的Localhost。临时沙箱Ephemeral进入时创建、退出时销毁from cua_sandbox import Sandbox, Image async with Sandbox.ephemeral( Image.from_registry(registry.example/desktop-workspacesha256:...) ) as sb: await sb.shell.run(uname -a) await sb.screenshot()从ephemeral()的实现看sandbox.py 第 772-929 行退出时的清理策略是teardown by default普通路径下退出调用sandbox.destroy()若该沙箱有快照_has_snapshots则改为Sandbox.suspend()把状态挂起而非删除对 Fleet registry 镜像ephemeral()实际上是在随机池名cua-eph- 随机 hex下创建一个一次性 poolclaim 出沙箱退出时依次close()claim、delete()pool清理逻辑见_cleanup_ephemeral_fleet即使中途抛异常也会执行清理suppress_errorsTrue路径。这意味着临时沙箱在云端的完整语义是claim 释放 隔离池删除恢复默认拆除语义。持久沙箱Persistent创建一个在脚本退出后仍然存活的沙箱from cua_sandbox import Sandbox, Image sb await Sandbox.create( Image.from_registry(registry.example/desktop-workspacesha256:...) ) await sb.shell.run(uname -a) print(sb.claim_name) # Fleet lifecycle identifier; save this to reconnect later await sb.disconnect()注意claim_name与sb.name是两个概念前者是 Fleet 生命周期标识claim 名后者是绑定的沙箱资源名。源码中claim_name属性直接返回 claim handle 的 namesandbox.py 第 422-430 行并特意在注释中强调与绑定的 sandbox name 不同。Sandbox.create()的完整签名还支持pool、replicas、service、claim_spec、keep_alive_minutes、cpu、memory_mb、disk_gb、region默认us-east-1、server_port默认8000、local、runtime等参数sandbox.py 第 598-711 行。其中有几条硬约束值得注意image与pool互斥指定pool时不允许再传replicas/cpu/memory_mb/disk_gbSupplyingpoolnever changes its configurationserver_port必须是 1-65535 的整数否则抛ValueError。连接已有沙箱按名字附着到正在运行的沙箱支持普通await和上下文管理器两种用法from cua_sandbox import Sandbox # plain await sb await Sandbox.connect(my-sandbox) await sb.shell.run(whoami) await sb.disconnect() # context manager — disconnects on exit, sandbox keeps running async with Sandbox.connect(my-sandbox) as sb: await sb.shell.run(whoami)实现上connect()返回一个_ConnectResult对象sandbox.py 第 166-194 行它同时实现__await__和__aenter__/__aexit__直接await得到沙箱作为上下文管理器时退出调用disconnect()——只断开传输连接沙箱本身继续运行。connect()还支持ws_url/http_url/container_name等参数可直接附着到远端 computer-server。销毁沙箱await sb.destroy() # disconnect permanently deletedestroy()是断开 永久删除的复合操作与disconnect()只断开、沙箱保留形成对照sandbox.py 第 389-518 行。本地 VMSandbox.ephemeral(..., localTrue)会启动本地 VMQEMU 或 Lume退出时销毁from cua_sandbox import Sandbox, Image from cua_sandbox.runtime import QEMURuntime async with Sandbox.ephemeral(Image.linux(), localTrue, runtimeQEMURuntime()) as sb: await sb.shell.run(uname -a)运行时抽象位于 libs/python/cua-sandbox/cua_sandbox/runtime/包括qemu.pyQEMU、lume.pymacOS 的 Lume、docker.pyDocker 容器、hyperv.pyWindows Hyper-V、tart.py、android_emulator.py等。当不显式传runtime时_auto_runtime()会按镜像的kind与os_type自动选择sandbox.py 第 220-292 行kind container→DockerRuntime(ephemeralTrue)macOS VM →LumeRuntimeAndroid →AndroidEmulatorRuntimeWindows VM 在 Windows 宿主且检测到 Hyper-V 时用HyperVRuntime带本地磁盘路径的镜像 → 裸金属 QEMULinux VM → 裸金属 QEMU与 Fleet 云端启动的是同一张 pinned containerDisk源码注释特别说明 Docker 包装的 QEMU 走不到该路径否则要 VM 却悄悄拿到容器未安装 QEMU 时抛带apt/dnf/brew安装提示的RuntimeErrorWindows VM 在 Linux 宿主上优先 Docker 包装的 QEMU无 Docker 时回退裸金属。运行时选择依赖镜像的kind字段registry 镜像若未解析 kind必须显式传runtime。本地支持的探测工具check_local_support/skip_if_unsupported也从runtime.compat导出方便测试按宿主能力跳过。Localhost无沙箱直接控制宿主机——没有沙箱谨慎使用from cua_sandbox import Localhost async with Localhost.connect() as host: await host.shell.run(echo hello) await host.screenshot()Localhost与Sandbox暴露同构的接口shell、screenshot等实现见 cua_sandbox/localhost.py。它是Sandbox永远隔离原则的显式例外入口。云沙箱Fleet 后端与受限能力Fleet 是 OAuth 云端后端。一次性配置 OAuth 凭据即可Fleet 默认使用https://run.cua.ai可用configure(fleet_base_url...)或环境变量CUA_FLEET_BASE_URL覆盖。旧的 API-key VM API 继续使用https://api.cua.ai。云镜像必须使用 registry 引用expose()用于声明额外的 Fleet 服务。Fleet 的能力边界README 明示不支持快照snapshots与自定义磁盘custom disks目前仅支持us-east-1区域await sb.tunnel.forward(3000)返回暴露端口的带认证的 Fleet 服务 URL而不是打开本地 SSH 隧道本地镜像构建、layers、注入文件/环境变量、快照、自定义磁盘、不支持的区域、跨 provider 的序列化都会抛NotImplementedError。Fleet 沙箱还可以为暴露的服务创建限时、可撤销的公共 URL——每个 URL 应视为 bearer credential接收方不再需要访问时立即撤销signed_url await sb.services.create_signed_url( mcp, labelCustomer demo, expires_in_seconds3600, ) print(signed_url.url) active_urls await sb.services.list_signed_urls() await sb.services.revoke_signed_url(signed_url)services接口的实现与SignedServiceURL模型见 interfaces/services.pySignedServiceURL也直接从包顶层导出init.py。Fleet 池Pools与持久 claim生产负载建议从既有池 claim。name命名的是 claimsb.name是独立绑定的沙箱资源from cua_sandbox import Sandbox sb await Sandbox.create( poolworkspace, nameworkflow-123, servicemcp, keep_alive_minutes30, ) reference sb.to_dict() await sb.disconnect() # claim remains held # A later process or Temporal activity re-resolves the live claim. sb await Sandbox.from_dict(reference) await sb.keep_alive(minutes30) await sb.close() # idempotently releases the claim这组持久化 API 的源码对应关系to_dict()序列化持久 Fleet 沙箱引用非 Fleet claim 会抛NotImplementedErrorsandbox.py 第 432-450 行from_dict()返回_ConnectResult内部经由_ClaimHandle.from_dict重新解析出活跃 claim并校验namespace pool_name防止跨池误用keep_alive(minutes...)把 claim 的控制器强制关机时间向后推基于 UTC 时间戳续约见 sandbox.py 第 452-459 行close()幂等地释放 claim重复调用安全_claim_released标志位。claim 的可序列化身份由_ClaimHandle承载claim 获取则封装在_ClaimResult中——它既是 awaitable又是异步上下文管理器退出时自动close()这解释了下面pool.claim()的双用法。池名的全局唯一性Fleet 池名跨账户全局唯一因此Sandbox.create对 registry 镜像要求显式命名的池先用Pool.apply(image, name...)建池再作为pool传入create()会对未命名池的 registry 镜像直接抛ValueError并给出两步示例Sandbox.ephemeral(image)则在随机名下创建隔离的临时池释放 claim 后删除它若所选池名已被其他账户占用Fleet 拒绝该操作SDK 抛出PoolAccessDeniedError该异常由 transport/fleet_cloud.py 归一化后抛出并在包顶层导出——换一个名字即可。带完整参数的临时沙箱示例from cua_sandbox import Image, Sandbox image Image.from_registry(registry.example/desktop-workspacesha256:...) async with Sandbox.ephemeral( image, namejob-123, cpu4, memory_mb4096, server_port5000, ) as sb: await sb.shell.run(uname -a)保留暖容量keep_pool若希望沙箱释放后池继续保留暖容量供后续调用显式keep_poolTrue选择加入。它要求传name这样后续运行才能找到被保留的池async with Sandbox.ephemeral(image, nameshared-pool, keep_poolTrue) as sb: await sb.shell.run(uname -a)源码中对应两条前置校验keep_pool仅支持 Fleet registry 镜像keep_poolTrue且未给name时抛ValueErrorsandbox.py 第 807-813 行。低层可复用池 API等价的低层 API 直接使用Poolfrom cua_sandbox import Image, Pool pool await Pool.apply( Image.from_registry(registry.example/desktop-workspacesha256:...), namedesktop-workspace, replicas1, cpu4, memory_mb4096, services{server: 8000, mcp: 3000}, ) sb await pool.claim(namejob-123, servicemcp) await sb.close()Pool.claim()既可 await也支持异步上下文管理器既有 scoped 用法继续有效async with pool.claim(namejob-123) as sb: await sb.shell.run(echo hello)按需自动扩缩WarmPoolAutoscaling用autoscaling替代静态replicas池在 claim 等待时向max_pool_size增长claim 释放时缩回min_pool_sizeinitial_pool_size在创建时提供一次性的预热起点from cua_sandbox import Image, Pool, WarmPoolAutoscaling pool await Pool.apply( Image.from_registry(registry.example/desktop-workspacesha256:...), namedesktop-workspace, cpu4, memory_mb4096, autoscalingWarmPoolAutoscaling( min_pool_size0, initial_pool_size2, max_pool_size10, ), )WarmPoolAutoscaling由fleet_sdk提供并经包顶层再导出init.py 第 55-60 行其生成 schema 的 builder如WarmPoolAutoscalingBuilder、CreatePoolRequestBuilder同样在顶层可用。Pool.reconcile(CreatePoolRequest(...))与Template.reconcile(CreateTemplateRequest(...))仍保留给需要高级生成 schema 的场景pool.py 第 60-89 行官方建议优先使用公开的生成 builder而不是直接构造启用 builder 的 Fleet 记录。镜像要求与端口约定镜像必须在配置的server_port上运行 CUA computer-server 的/cmdAPIWindows computer-server 镜像继续使用默认端口8000。这解释了server_port参数为何贯穿create()/ephemeral()全链路以及ephemeral()如何把Image.expose()的端口自动映射成port-N服务名sandbox.py 第 855-858 行。测试与验证路径本 README 所述行为在仓库中有对应的回归与集成测试可作为行为契约的参照生命周期与序列化tests/test_sandbox_fleet_lifecycle.py、tests/test_pool.py、tests/test_fleet_transport.pyDriver 与 MCP carriertests/test_typed_driver.py、tests/test_driver_mcp.pyFleet 真实端到端按需运行tests/live/test_fleet_ephemeral.py、tests/live/test_fleet_pool_persistent.py文档回归防止 README 示例与实际 API 漂移tests/test_docs_regressions.py。此外仓库文档侧还有面向 Fleet 池指南的设计计划docs/superpowers/specs/2026-08-12-sandbox-pool-guides.md 相关计划目录与 cua-sandbox server 端口的设计说明docs/superpowers/specs/2026-08-08-cua-sandbox-server-port-design.md可进一步理解server_port语义的演进背景。小结cua-sandbox 的价值在于用一套接口覆盖了沙箱的完整生命周期ephemeral进创建、出销毁云端自动拆临时池、persistentcreatedisconnectclaim_name重连、connect附着、上下文管理器断开但保留、destroy断开 永久删除、local VMQEMU/Lume 等运行时自动或显式选择、Localhost唯一的无沙箱入口、Fleet 云池命名池、全局唯一池名、keep_pool暖容量、WarmPoolAutoscaling按需扩缩、签名 URL 与tunnel.forward。所有能力的实现都收敛在接口对象 Transport的架构上这让你可以在本地开发用本地 QEMU 验证的同一份脚本生产环境切换到 Fleet 时只改入参而非重写控制逻辑。【免费下载链接】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），仅供参考