Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
feat(cua-sandbox)!: require explicit pool names for Fleet images (#3215)
r33drichards605a7421e1db
diff --git a/docs/content/docs/how-to-guides/sandbox/create-pool-with-python.mdx b/docs/content/docs/how-to-guides/sandbox/create-pool-with-python.mdxindex 8043423aee..667cae1340 100644--- a/docs/content/docs/how-to-guides/sandbox/create-pool-with-python.mdx+++ b/docs/content/docs/how-to-guides/sandbox/create-pool-with-python.mdx@@ -155,6 +155,39 @@ uv run create_pool.pyUse stable names when later runs should reconcile the same pool and reuse thesame claim identity. Names must be lowercase DNS labels.+## Pool names are globally unique++A pool's name is also its namespace, and that namespace is shared across all+Cua accounts. `Pool.apply()` therefore requires an explicit `name=`, and+`Sandbox.create(image, ...)` refuses Fleet registry images without a pool —+apply a named pool first and pass it as `pool=`:++```python+pool = await Pool.apply(image, name="my-team-windows-pool")+sandbox = await Sandbox.create(pool=pool, name="my-claim")+```++If the name you pick already belongs to another account, the SDK raises+`PoolAccessDeniedError` explaining that the name is taken:++```text+PoolAccessDeniedError: Fleet denied create pool on pool namespace+'my-team-windows-pool' (HTTP 403: k8s request is not allowed). Pool names+are globally unique across accounts, so this name may already be taken —+try a new pool name. If that does not work, contact support on Discord:+https://discord.gg/mVnXXpdE85+```++Retrying does not help, and neither does claiming with fresh claim names: the+conflict is on the pool and its namespace, not the claim. Choose a different+pool name. Claim names never have this problem — they only need to be unique+inside your own pool's namespace, which is why the SDK generates random+`claim-<petname>` claims for you but never generates pool names.++`Sandbox.ephemeral(image)` remains a one-liner: it creates a disposable pool+under a random `cua-eph-<hex>` name and deletes it on exit. Passing+`keep_pool=True` requires `name=` so later runs can find the kept pool.+## Delete the poolThe example intentionally leaves the pool warm. If you no longer need it, calldiff --git a/docs/content/docs/how-to-guides/sandbox/minecraft.mdx b/docs/content/docs/how-to-guides/sandbox/minecraft.mdxindex 508db4038c..9f393c575d 100644--- a/docs/content/docs/how-to-guides/sandbox/minecraft.mdx+++ b/docs/content/docs/how-to-guides/sandbox/minecraft.mdx@@ -428,6 +428,8 @@ Booted locally, that image printed `Image(windows/registry:latest, kind=vm, ...)Expect the first Fleet boot on a given node to be slow: it has to pull the whole image before the sandbox can start, and Fleet enforces a **300-second bind deadline** that `time_to_start=` does not extend, so a cold pull can surface as `BindDeadlineExceeded: no adoptable Sandbox within 300s`.A second failure to expect is `403 k8s request is not allowed` on `update template`. A template can be **created but never updated**: both branches of the gateway's image policy are guarded by `input.method != "PATCH"`, so any request that takes the update path is refused, with the same opaque message you get for a disallowed image. Reusing the sandbox name guarantees it. A fresh name usually avoids it but **not reliably** — of four boots of the same image, one reused name and one fresh name both returned 403, while two other fresh names reached `READY` in 157 s and 187 s. Retry; it is intermittent, and nothing about your image changes the outcome.++ The SDK surfaces these 403s as `PoolAccessDeniedError`. The same error also appears when the pool name you chose is already owned by **another account** — pool names are globally unique across accounts — and in that case the fix is a different pool name, not a retry.</Callout>The reader's remaining work is the part that has to be theirs: open Prism, *Accounts → Add Microsoft*, approve the device code, and click Launch.@@ -440,9 +442,10 @@ The image and the agent loop are identical on Fleet. Two things change: there is```pythonimport httpx-from cua import Image, Sandbox+from cua import Image, Pool, Sandbox-sb = await Sandbox.create(Image.windows().expose(3000), name='mc-fleet', time_to_start=900)+pool = await Pool.apply(Image.windows().expose(3000), name='mc-fleet')+sb = await Sandbox.create(pool=pool, name='mc-fleet', time_to_start=900)tunnel = await sb.tunnel.forward(3000)# https://run.cua.ai/api/svc/<namespace>/<sandbox>-port-3000/@@ -462,7 +465,7 @@ That is the same `run()` as above, with only the URL and an auth header changed.Notice there is no `-cpu host` here. That flag exists on the local path because the bare-metal runtime defaults to the thin `qemu64` model; a Fleet sandbox is provisioned for you and already reports a full host CPU — `Intel Xeon Processor (SapphireRapids)`, with AVX, AVX2 and AVX-512 all present — so there is nothing to override, and no QEMU arguments to pass.-`Sandbox.create` also accepts `cpu` and `memory_mb`, but sizing a Fleet sandbox is account-dependent: passing them routes the request through a gated custom-resource path, which returned `403 create pool: k8s request is not allowed` at every size until a card-on-file requirement was lifted for the account. The default sandbox — 4 vCPU and 4 GB — is what this guide was written against, and it is enough.+`Pool.apply` also accepts `cpu` and `memory_mb`, but sizing a Fleet sandbox is account-dependent: passing them routes the request through a gated custom-resource path, which returned `403 create pool: k8s request is not allowed` at every size until a card-on-file requirement was lifted for the account. The default sandbox — 4 vCPU and 4 GB — is what this guide was written against, and it is enough.<Callout type="warn">**On Fleet the game needs one extra environment variable: `GALLIUM_DRIVER=softpipe`.** With Mesa's default llvmpipe renderer, Minecraft dies during resource loading every time — `Process crashed with exitcode -2147024809`, no Java exception, no `hs_err` file, nothing in the Windows event log, the log simply stopping after `Reloading ResourceManager`. Switching Mesa to its `softpipe` rasteriser fixes it, and the game runs.diff --git a/libs/python/cua-sandbox/README.md b/libs/python/cua-sandbox/README.mdindex 297e320920..6767c154c4 100644--- a/libs/python/cua-sandbox/README.md+++ b/libs/python/cua-sandbox/README.md@@ -119,7 +119,7 @@ await sb.keep_alive(minutes=30)await sb.close() # idempotently releases the claim```-If `pool=` is omitted, a registry image is required. `Sandbox.create(image)` applies a deterministic reusable pool and claims from it. `Sandbox.ephemeral(image)` instead creates an isolated temporary pool and deletes it after releasing the claim, preserving teardown-by-default semantics.+Fleet pool names are globally unique across accounts, so `Sandbox.create` requires an explicitly named pool for registry images: apply one with `Pool.apply(image, name=...)` and pass it as `pool=`. `Sandbox.ephemeral(image)` instead creates an isolated temporary pool under a random name and deletes it after releasing the claim, preserving teardown-by-default semantics. If a chosen pool name is already owned by another account, Fleet refuses it and the SDK raises `PoolAccessDeniedError` — pick a different name.```pythonfrom cua_sandbox import Image, Sandbox@@ -136,10 +136,10 @@ async with Sandbox.ephemeral(await sb.shell.run("uname -a")```-To deliberately retain deterministic warm capacity for later calls, opt in with `keep_pool=True`:+To deliberately retain warm capacity for later calls, opt in with `keep_pool=True`. It requires `name=` so later runs can find the kept pool:```python-async with Sandbox.ephemeral(image, keep_pool=True) as sb:+async with Sandbox.ephemeral(image, name="shared-pool", keep_pool=True) as sb:await sb.shell.run("uname -a")```@@ -150,6 +150,7 @@ from cua_sandbox import Image, Poolpool = await Pool.apply(Image.from_registry("registry.example/desktop-workspace@sha256:..."),+ name="desktop-workspace",replicas=1,cpu=4,memory_mb=4096,@@ -177,6 +178,7 @@ from cua_sandbox import Image, Pool, WarmPoolAutoscalingpool = await Pool.apply(Image.from_registry("registry.example/desktop-workspace@sha256:..."),+ name="desktop-workspace",cpu=4,memory_mb=4096,autoscaling=WarmPoolAutoscaling(diff --git a/libs/python/cua-sandbox/cua_sandbox/__init__.py b/libs/python/cua-sandbox/cua_sandbox/__init__.pyindex 9b01a3085e..e3cab04103 100644--- a/libs/python/cua-sandbox/cua_sandbox/__init__.py+++ b/libs/python/cua-sandbox/cua_sandbox/__init__.py@@ -30,6 +30,7 @@ from cua_sandbox.runtime.compat import ()from cua_sandbox.sandbox import Sandbox, SandboxInfo, sandboxfrom cua_sandbox.transport.cloud import CloudTransport+from cua_sandbox.transport.fleet_cloud import PoolAccessDeniedErrorfrom fleet_sdk import (ClaimSpec,CreatePoolRequest,@@ -62,6 +63,7 @@ __all__ = ["whoami","Image","Pool",+ "PoolAccessDeniedError","Template","TemplateResource","CreatePoolRequest",diff --git a/libs/python/cua-sandbox/cua_sandbox/pool.py b/libs/python/cua-sandbox/cua_sandbox/pool.pyindex b44fb37b83..482fb2aa01 100644--- a/libs/python/cua-sandbox/cua_sandbox/pool.py+++ b/libs/python/cua-sandbox/cua_sandbox/pool.py@@ -2,15 +2,17 @@from __future__ import annotations-import hashlib-import jsonimport loggingfrom typing import Any, Callable, Coroutine, Generic, TypeVar, cast-from cua_sandbox.image import Image, cloud_registry_image+from cua_sandbox.image import Imagefrom cua_sandbox.sandbox import Sandboxfrom cua_sandbox.transport.fleet import FleetTransport-from cua_sandbox.transport.fleet_cloud import FleetCloudTransport, _FleetClient+from cua_sandbox.transport.fleet_cloud import (+ FleetCloudTransport,+ _FleetClient,+ _pool_access_denied,+)from fleet_sdk import (Claim,ClaimSpec,@@ -72,7 +74,12 @@ class Template:raise TypeError("Template.reconcile requires a CreateTemplateRequest")client = _FleetClient()try:- return cls(await client.reconcile_template(request))+ try:+ return cls(await client.reconcile_template(request))+ except SdkError.Status as error:+ if error.status == 403:+ raise _pool_access_denied(request.namespace, error) from error+ raisefinally:await client.close()@@ -214,7 +221,12 @@ class Pool:raise TypeError("Pool.reconcile requires a CreatePoolRequest")client = _FleetClient()try:- return cls(await client.reconcile_pool(request))+ try:+ return cls(await client.reconcile_pool(request))+ except SdkError.Status as error:+ if error.status == 403:+ raise _pool_access_denied(request.namespace, error) from error+ raisefinally:await client.close()@@ -231,40 +243,23 @@ class Pool:cls,image: Image,*,- name: str | None = None,+ name: str,replicas: int = 1,cpu: int | None = None,memory_mb: int | None = None,services: dict[str, int] | None = None,autoscaling: WarmPoolAutoscaling | None = None,) -> "Pool":+ if not isinstance(name, str) or not name:+ raise ValueError(+ "Pool.apply requires an explicit non-empty pool name; pool "+ "names are globally unique across accounts"+ )FleetCloudTransport._validate_image(image)effective_services = services or {"server": 8000,**{f"port-{port}": port for port in image._ports if port != 8000},}- if name is None:- identity_fields: dict[str, Any] = {- "image": cloud_registry_image(image),- "replicas": replicas,- "cpu": cpu,- "memory_mb": memory_mb,- "services": sorted(effective_services.items()),- }- # Included only when set so pools created before autoscaling- # support keep their deterministic names.- if autoscaling is not None:- identity_fields["autoscaling"] = {- "min_pool_size": autoscaling.min_pool_size,- "initial_pool_size": autoscaling.initial_pool_size,- "max_pool_size": autoscaling.max_pool_size,- }- identity = json.dumps(- identity_fields,- separators=(",", ":"),- sort_keys=True,- )- name = f"cua-{hashlib.sha256(identity.encode()).hexdigest()[:12]}"transport = FleetCloudTransport(image=image,name=name,@@ -278,7 +273,12 @@ class Pool:try:template = await Template.reconcile(transport._template_request())except BaseException:- await pool.delete()+ try:+ await pool.delete()+ except Exception:+ logger.exception(+ "Failed to roll back Fleet pool %r after template reconcile failure", name+ )raisepool._owned_template = template.resourcereturn pooldiff --git a/libs/python/cua-sandbox/cua_sandbox/sandbox.py b/libs/python/cua-sandbox/cua_sandbox/sandbox.pyindex c8eba8ba26..e0f2650a0a 100644--- a/libs/python/cua-sandbox/cua_sandbox/sandbox.py+++ b/libs/python/cua-sandbox/cua_sandbox/sandbox.py@@ -5,10 +5,12 @@ as interface objects backed by a Transport.Usage::- from cua_sandbox import Sandbox, Image+ from cua_sandbox import Image, Pool, Sandbox- # Provision a new persistent sandbox- sb = await Sandbox.create(Image.desktop("ubuntu"))+ # Provision a persistent sandbox from an explicitly named pool+ # (pool names are globally unique across accounts)+ pool = await Pool.apply(Image.desktop("ubuntu"), name="my-pool")+ sb = await Sandbox.create(pool=pool, name="my-claim")await sb.shell.run("uname -a")await sb.disconnect()@@ -29,6 +31,7 @@ from __future__ import annotationsimport loggingimport random+import secretsimport timefrom collections.abc import Mappingfrom contextlib import asynccontextmanager@@ -613,8 +616,9 @@ class Sandbox:"""Provision or claim a persistent sandbox and return it connected.Supplying ``pool`` claims from an existing Fleet pool without changing- its configuration. Otherwise, registry images are applied as a- deterministic reusable pool before a claim is acquired.+ its configuration. Fleet registry images require an explicitly named+ pool — apply one with ``Pool.apply(image, name=...)`` and pass it as+ ``pool=`` — because pool names are globally unique across accounts."""from cua_sandbox.pool import Pool@@ -671,38 +675,14 @@ class Sandbox:and runtime is None)if fleet_image:- if disk_gb is not None or region != "us-east-1" or request_timeout is not None:- raise NotImplementedError("the requested option is not supported by Fleet")- services = {- "server": server_port,- **{f"port-{port}": port for port in image._ports if port != server_port},- }- resolved_pool = await Pool.apply(- image,- replicas=replicas,- cpu=cpu,- memory_mb=memory_mb,- services=services,- )- sandbox = await resolved_pool.claim(- name=name, spec=claim_spec, service=service, time_to_start=time_to_start- )- sandbox_claim_name = getattr(sandbox, "claim_name", None)- sandbox_pool_name = getattr(sandbox, "pool_name", None)- claim_name = (- sandbox_claim_name- if isinstance(sandbox_claim_name, str) and sandbox_claim_name- else name- )- pool_name = (- sandbox_pool_name- if isinstance(sandbox_pool_name, str) and sandbox_pool_name- else resolved_pool.name+ raise ValueError(+ "Sandbox.create requires an explicitly named pool for Fleet "+ "registry images because pool names are globally unique "+ "across accounts. Apply a pool first, then claim from it:\n"+ ' pool = await Pool.apply(image, name="my-pool")\n'+ ' sandbox = await Sandbox.create(pool=pool, name="my-claim")\n'+ "Or use Sandbox.ephemeral(image, ...) for a disposable sandbox.")- await _keep_alive_or_close(sandbox, keep_alive_minutes)- if claim_name is not None:- await _save_fleet_claim_or_close(sandbox, claim_name, pool_name)- return sandboxif image is None:raise ValueError("image is required when pool is omitted")@@ -822,6 +802,11 @@ class Sandbox:)if keep_pool and not fleet_image:raise ValueError("keep_pool is only supported for Fleet registry images")+ if keep_pool and name is None:+ raise ValueError(+ "keep_pool requires name= so later runs can find and reuse the "+ "kept pool; pool names are globally unique across accounts"+ )if pool is not None:sandbox = await cls.create(@@ -867,14 +852,16 @@ class Sandbox:"server": server_port,**{f"port-{port}": port for port in image._ports if port != server_port},}- pool_options = {"name": name} if name is not None else {}+ # A random pool name keeps this disposable pool out of foreign+ # namespaces: pool names are globally unique across accounts.+ pool_name = name if name is not None else f"cua-eph-{secrets.token_hex(6)}"owned_pool = await Pool.apply(image,+ name=pool_name,replicas=replicas,cpu=cpu,memory_mb=memory_mb,services=services,- **pool_options,)sandbox = Nonetry:diff --git a/libs/python/cua-sandbox/cua_sandbox/sync/__init__.py b/libs/python/cua-sandbox/cua_sandbox/sync/__init__.pyindex 222726c651..d797d028c5 100644--- a/libs/python/cua-sandbox/cua_sandbox/sync/__init__.py+++ b/libs/python/cua-sandbox/cua_sandbox/sync/__init__.py@@ -126,7 +126,7 @@ class Pool:cls,image: Image,*,- name: str | None = None,+ name: str,replicas: int = 1,cpu: int | None = None,memory_mb: int | None = None,diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/fleet_cloud.py b/libs/python/cua-sandbox/cua_sandbox/transport/fleet_cloud.pyindex c63367aefa..295073ab50 100644--- a/libs/python/cua-sandbox/cua_sandbox/transport/fleet_cloud.py+++ b/libs/python/cua-sandbox/cua_sandbox/transport/fleet_cloud.py@@ -41,6 +41,7 @@ from fleet_sdk import (PreservedJson,SandboxServiceBuilder,SandboxTemplateRefBuilder,+ SdkError,ServiceProtocol,VmTemplateBuilder,WarmPoolAutoscaling,@@ -59,6 +60,37 @@ _CLAIM_HASH_LENGTH = 16_READINESS_PROBE_TIMEOUT_SECS = 30+# Newer Fleet SDKs raise SdkError.PoolAccessDenied from the Rust core for 403s+# on pool-namespace writes, so every language binding shares one message. Use+# that type when the installed cua-fleet provides it; otherwise map the plain+# 403 Status errors older SDKs raise into an equivalent local error.+_UPSTREAM_POOL_ACCESS_DENIED = getattr(SdkError, "PoolAccessDenied", None)++if _UPSTREAM_POOL_ACCESS_DENIED is not None:+ PoolAccessDeniedError = _UPSTREAM_POOL_ACCESS_DENIED+else:++ class PoolAccessDeniedError(PermissionError): # type: ignore[no-redef]+ """Fleet refused a pool or template operation for this credential."""+++def _pool_access_denied(namespace: str, error: SdkError.Status) -> Exception:+ if _UPSTREAM_POOL_ACCESS_DENIED is not None:+ return _UPSTREAM_POOL_ACCESS_DENIED(+ operation=error.operation,+ namespace=namespace,+ status=error.status,+ body=error.body,+ )+ return PoolAccessDeniedError(+ f"Fleet denied {error.operation} on pool namespace '{namespace}' "+ f"(HTTP {error.status}: {error.body}). Pool names are globally unique "+ "across accounts, so this name may already be taken — try a new pool "+ "name. If that does not work, contact support on Discord: "+ "https://discord.gg/mVnXXpdE85"+ )++def _claim_name(pool_name: str) -> str:normalized_name = pool_name.lower()legacy_name = f"{normalized_name}-claim"@@ -455,10 +487,15 @@ class FleetCloudTransport(FleetTransport):self._pool = await self._sdk.wait_pool(self._pool)else:self._validate_image(self._image)- self._pool = await self._sdk.reconcile_pool(self._pool_request())- self._template = await self._sdk.reconcile_template(- self._template_request()- )+ try:+ self._pool = await self._sdk.reconcile_pool(self._pool_request())+ self._template = await self._sdk.reconcile_template(+ self._template_request()+ )+ except SdkError.Status as error:+ if error.status == 403:+ raise _pool_access_denied(self._pool_name, error) from error+ raiseself._pool = await self._sdk.wait_pool(self._pool)if self._claim is None:if self._image is None and not self._create_claim:diff --git a/libs/python/cua-sandbox/tests/test_cloud.py b/libs/python/cua-sandbox/tests/test_cloud.pyindex 26a825b60e..04d090c4ea 100644--- a/libs/python/cua-sandbox/tests/test_cloud.py+++ b/libs/python/cua-sandbox/tests/test_cloud.py@@ -42,19 +42,8 @@ async def test_cloud_routes_fleet_auth_without_explicit_legacy_key(monkeypatch,for variable, value in auth_environment.items():monkeypatch.setenv(variable, value)- class ClaimedSandbox:- async def disconnect(self):- return None-- class FleetPool:- name = "fleet-pool"-- async def claim(self, **kwargs):- routes.append(("fleet", kwargs))- return ClaimedSandbox()-- async def apply_pool(cls, image, **kwargs):- return FleetPool()+ async def reject_fleet_apply(cls, image, **kwargs):+ raise AssertionError("Fleet-routed images must demand an explicit pool, not apply one")class LegacyTransport:def __init__(self, **kwargs):@@ -67,25 +56,23 @@ async def test_cloud_routes_fleet_auth_without_explicit_legacy_key(monkeypatch,async def disconnect(self):return None- monkeypatch.setattr(Pool, "apply", classmethod(apply_pool))+ monkeypatch.setattr(Pool, "apply", classmethod(reject_fleet_apply))monkeypatch.setattr(sandbox_module, "_make_transport", lambda **kwargs: LegacyTransport(**kwargs))- fleet_sandbox = await Sandbox.create(Image.from_registry("example:latest"), name="fleet-demo")- default_linux_sandbox = await Sandbox.create(Image.linux(), name="linux-demo")+ with pytest.raises(ValueError, match="Pool.apply"):+ await Sandbox.create(Image.from_registry("example:latest"), name="fleet-demo")+ with pytest.raises(ValueError, match="Pool.apply"):+ await Sandbox.create(Image.linux(), name="linux-demo")legacy_sandbox = await Sandbox.create(Image.from_registry("example:latest"), name="legacy-demo", api_key="sk-explicit")- await fleet_sandbox.disconnect()- await default_linux_sandbox.disconnect()await legacy_sandbox.disconnect()assert Sandbox._uses_fleet(None)assert not Sandbox._uses_fleet("sk-explicit")assert [(route, values["name"]) for route, values in routes] == [- ("fleet", "fleet-demo"),- ("fleet", "linux-demo"),("legacy", "legacy-demo"),]diff --git a/libs/python/cua-sandbox/tests/test_pool.py b/libs/python/cua-sandbox/tests/test_pool.pyindex 286d8aea73..c7c29b77eb 100644--- a/libs/python/cua-sandbox/tests/test_pool.py+++ b/libs/python/cua-sandbox/tests/test_pool.py@@ -14,6 +14,7 @@ from cua_sandbox import (OsGymSandboxTemplateSpecBuilder,OsGymSandboxWarmPoolSpecBuilder,Pool,+ PoolAccessDeniedError,RuntimeKind,SandboxServiceBuilder,SandboxTemplateRefBuilder,@@ -840,6 +841,7 @@ async def test_pool_apply_delegates_to_template_and_pool_reconcile(monkeypatch):pool = await Pool.apply(Image.from_registry("registry.example/workspace:latest"),+ name="workspace",cpu=4,memory_mb=4096,)@@ -917,23 +919,15 @@ async def test_pool_apply_without_autoscaling_leaves_the_pool_spec_static(monkey@pytest.mark.asyncio-async def test_pool_apply_autoscaling_extends_the_deterministic_name(monkeypatch):- clients = [FakeFleetClient() for _ in range(6)]- iterator = iter(clients)- monkeypatch.setattr("cua_sandbox.pool._FleetClient", lambda: next(iterator))+async def test_pool_apply_requires_an_explicit_name():image = Image.from_registry("registry.example/workspace:latest")- autoscaling = WarmPoolAutoscaling(min_pool_size=0, initial_pool_size=2, max_pool_size=10)-- static = await Pool.apply(image)- scaled = await Pool.apply(image, autoscaling=autoscaling)- scaled_again = await Pool.apply(- image,- autoscaling=WarmPoolAutoscaling(min_pool_size=0, initial_pool_size=2, max_pool_size=10),- )- assert scaled.name != static.name- assert scaled.name == scaled_again.name- assert scaled.name.startswith("cua-")+ with pytest.raises(TypeError):+ await Pool.apply(image)+ with pytest.raises(ValueError, match="globally unique"):+ await Pool.apply(image, name="")+ with pytest.raises(ValueError, match="globally unique"):+ await Pool.apply(image, name=None)def test_sync_pool_apply_forwards_autoscaling(monkeypatch):@@ -952,25 +946,64 @@ def test_sync_pool_apply_forwards_autoscaling(monkeypatch):assert clients[0].reconciled[0].spec.autoscaling == autoscaling+def _forbidden(operation: str) -> SdkError.Status:+ return SdkError.Status(operation=operation, status=403, body="k8s request is not allowed")++@pytest.mark.asyncio-async def test_pool_apply_uses_stable_configuration_name(monkeypatch):- from cua_sandbox import Image+async def test_pool_apply_maps_forbidden_pool_reconcile_to_access_denied(monkeypatch):+ clients = [FakeFleetClient(reconcile_error=_forbidden("create pool"))]+ iterator = iter(clients)+ monkeypatch.setattr("cua_sandbox.pool._FleetClient", lambda: next(iterator))++ with pytest.raises(PoolAccessDeniedError, match="globally unique") as error:+ await Pool.apply(+ Image.from_registry("registry.example/workspace:latest"),+ name="workspace",+ )++ assert "'workspace'" in str(error.value)+ assert isinstance(error.value.__cause__, SdkError.Status)+- clients = [FakeFleetClient() for _ in range(6)]+async def test_pool_apply_maps_forbidden_template_reconcile_and_still_rolls_back(monkeypatch):+ clients = [+ FakeFleetClient(),+ FakeFleetClient(reconcile_error=_forbidden("update template")),+ FakeFleetClient(),+ ]iterator = iter(clients)monkeypatch.setattr("cua_sandbox.pool._FleetClient", lambda: next(iterator))- image = Image.from_registry("registry.example/workspace:latest")- first = await Pool.apply(image, replicas=1, cpu=4, memory_mb=4096)- second = await Pool.apply(image, replicas=1, cpu=4, memory_mb=4096)- explicit_default = await Pool.apply(- image, replicas=1, cpu=4, memory_mb=4096, services={"server": 8000}- )+ with pytest.raises(PoolAccessDeniedError, match="globally unique"):+ await Pool.apply(+ Image.from_registry("registry.example/workspace:latest"),+ name="workspace",+ )++ assert clients[2].deleted_pools == ["workspace"]+++async def test_pool_apply_rollback_failure_does_not_mask_template_error(monkeypatch):+ class DeleteDeniedClient(FakeFleetClient):+ async def delete_pool(self, pool: object) -> None:+ raise _forbidden("delete pool")- assert first.name == second.name == explicit_default.name- assert first.name.startswith("cua-")- assert clients[0].reconciled[0].namespace == first.name- assert clients[1].reconciled_templates[0].name == first.name+ clients = [+ FakeFleetClient(),+ FakeFleetClient(reconcile_error=_forbidden("update template")),+ DeleteDeniedClient(),+ ]+ iterator = iter(clients)+ monkeypatch.setattr("cua_sandbox.pool._FleetClient", lambda: next(iterator))++ with pytest.raises(PoolAccessDeniedError, match="update template"):+ await Pool.apply(+ Image.from_registry("registry.example/workspace:latest"),+ name="workspace",+ )@pytest.mark.asynciodiff --git a/libs/python/cua-sandbox/tests/test_sandbox_fleet_lifecycle.py b/libs/python/cua-sandbox/tests/test_sandbox_fleet_lifecycle.pyindex 781df3d58e..8453111c25 100644--- a/libs/python/cua-sandbox/tests/test_sandbox_fleet_lifecycle.py+++ b/libs/python/cua-sandbox/tests/test_sandbox_fleet_lifecycle.py@@ -47,49 +47,29 @@ async def test_create_with_pool_name_uses_read_only_pool_lookup(monkeypatch):@pytest.mark.asyncio-async def test_create_without_pool_applies_image_then_claims(monkeypatch):- pool = FakePool("derived-pool")- applied: list[dict] = []-- async def apply_pool(cls, image, **kwargs):- applied.append({"image": image, **kwargs})- return pool-- monkeypatch.setattr(Pool, "apply", classmethod(apply_pool), raising=False)- image = Image.from_registry("registry.example/workspace:latest")+async def test_create_with_fleet_image_requires_explicit_pool(monkeypatch):+ apply_pool = AsyncMock()+ monkeypatch.setattr(Pool, "apply", apply_pool)- sandbox = await Sandbox.create(- image,- name="job-123",- replicas=1,- cpu=4,- memory_mb=4096,- service="mcp",- )+ with pytest.raises(ValueError, match="Pool.apply"):+ await Sandbox.create(+ Image.from_registry("registry.example/workspace:latest"),+ name="job-123",+ )- assert applied == [- {- "image": image,- "replicas": 1,- "cpu": 4,- "memory_mb": 4096,- "services": {"server": 8000},- }- ]- assert pool.claims[0]["name"] == "job-123"- assert sandbox.pool_name == "derived-pool"+ apply_pool.assert_not_awaited()@pytest.mark.asyncio-async def test_image_create_persists_generated_claim_pool_mapping(monkeypatch, tmp_path):+async def test_pool_create_persists_generated_claim_pool_mapping(monkeypatch, tmp_path):from cua_sandbox import sandbox_stateclass ClaimedSandbox:name = "bound-sandbox-1"claim_name = "generated-claim-1"- pool_name = "derived-pool"+ pool_name = "workspace"- pool = FakePool("derived-pool")+ pool = FakePool("workspace")async def claim(**kwargs):pool.claims.append(kwargs)@@ -97,16 +77,16 @@ async def test_image_create_persists_generated_claim_pool_mapping(monkeypatch, tpool.claim = claimmonkeypatch.setattr(sandbox_state, "SANDBOX_STATE_DIR", tmp_path)- monkeypatch.setattr(Pool, "apply", AsyncMock(return_value=pool))+ monkeypatch.setattr(Pool, "get", AsyncMock(return_value=pool))- sandbox = await Sandbox.create(Image.from_registry("registry.example/workspace:latest"))+ sandbox = await Sandbox.create(pool="workspace")assert sandbox.name == "bound-sandbox-1"assert sandbox.claim_name == "generated-claim-1"- assert sandbox_state.load("generated-claim-1")["pool_name"] == "derived-pool"+ assert sandbox_state.load("generated-claim-1")["pool_name"] == "workspace"[email protected]("source", ["existing-pool", "image"])[email protected]("source", ["existing-pool", "pool-object"])@pytest.mark.asyncioasync def test_keep_alive_failure_releases_claim_without_persisting_state(monkeypatch, tmp_path, source@@ -128,12 +108,7 @@ async def test_keep_alive_failure_releases_claim_without_persisting_state(monkeypatch.setattr(Pool, "get", AsyncMock(return_value=pool))create = Sandbox.create(pool="workspace", name="job-123", keep_alive_minutes=30)else:- monkeypatch.setattr(Pool, "apply", AsyncMock(return_value=pool))- create = Sandbox.create(- Image.from_registry("registry.example/workspace:latest"),- name="job-123",- keep_alive_minutes=30,- )+ create = Sandbox.create(pool=pool, name="job-123", keep_alive_minutes=30)with pytest.raises(RuntimeError, match="renew failed"):await create@@ -179,14 +154,9 @@ async def test_keep_alive_failure_preserves_error_when_claim_close_fails(monkeyp)pool = FakePool("workspace")pool.claim = AsyncMock(return_value=claimed)- monkeypatch.setattr(Pool, "apply", AsyncMock(return_value=pool))with pytest.raises(RuntimeError, match="renew failed") as error:- await Sandbox.create(- Image.from_registry("registry.example/workspace:latest"),- name="job-123",- keep_alive_minutes=30,- )+ await Sandbox.create(pool=pool, name="job-123", keep_alive_minutes=30)assert isinstance(error.value.__cause__, RuntimeError)assert str(error.value.__cause__) == "close failed"@@ -356,7 +326,7 @@ async def test_ephemeral_image_uses_name_for_owned_pool_and_claim(monkeypatch):@pytest.mark.asyncio-async def test_ephemeral_image_keep_pool_reuses_deterministic_pool(monkeypatch):+async def test_ephemeral_image_keep_pool_reuses_named_pool(monkeypatch):claimed = SimpleNamespace(close=AsyncMock())pool = FakePool("shared-pool")pool.claim = AsyncMock(return_value=claimed)@@ -364,14 +334,48 @@ async def test_ephemeral_image_keep_pool_reuses_deterministic_pool(monkeypatch):monkeypatch.setattr(Pool, "apply", apply_pool)image = Image.from_registry("registry.example/workspace:latest")- async with Sandbox.ephemeral(image, keep_pool=True):+ async with Sandbox.ephemeral(image, name="shared-pool", keep_pool=True):pass- assert "name" not in apply_pool.await_args.kwargs+ assert apply_pool.await_args.kwargs["name"] == "shared-pool"claimed.close.assert_awaited_once()assert pool.deletes == 0+async def test_ephemeral_image_keep_pool_requires_name(monkeypatch):+ apply_pool = AsyncMock()+ monkeypatch.setattr(Pool, "apply", apply_pool)++ with pytest.raises(ValueError, match="keep_pool requires name="):+ async with Sandbox.ephemeral(+ Image.from_registry("registry.example/workspace:latest"),+ keep_pool=True,+ ):+ pass++ apply_pool.assert_not_awaited()+++async def test_ephemeral_image_without_name_applies_random_disposable_pool(monkeypatch):+ claimed = SimpleNamespace(close=AsyncMock())+ pool = FakePool("owned-pool")+ pool.claim = AsyncMock(return_value=claimed)+ apply_pool = AsyncMock(return_value=pool)+ monkeypatch.setattr(Pool, "apply", apply_pool)++ async with Sandbox.ephemeral(Image.from_registry("registry.example/workspace:latest")):+ pass++ pool_name = apply_pool.await_args.kwargs["name"]+ assert pool_name.startswith("cua-eph-")+ assert len(pool_name) == len("cua-eph-") + 12+ pool.claim.assert_awaited_once_with(name=None, spec=None, service="server", time_to_start=None)+ claimed.close.assert_awaited_once()+ assert pool.deletes == 1++@pytest.mark.asyncioasync def test_ephemeral_rejects_keep_pool_for_existing_pool():with pytest.raises(ValueError, match="keep_pool"):diff --git a/libs/python/cua-sandbox/tests/test_vm_cleanup.py b/libs/python/cua-sandbox/tests/test_vm_cleanup.pyindex d42cd468ea..4a2e951383 100644--- a/libs/python/cua-sandbox/tests/test_vm_cleanup.py+++ b/libs/python/cua-sandbox/tests/test_vm_cleanup.py@@ -253,37 +253,18 @@ class TestFleetServerPortForwarding:def _select_fleet(self, monkeypatch):monkeypatch.setattr(Sandbox, "_uses_fleet", staticmethod(lambda api_key: api_key is None))- @pytest.mark.parametrize("server_port", [1, 65535])- async def test_create_forwards_server_port(self, server_port):- claimed = object()- pool = MagicMock()- pool.claim = AsyncMock(return_value=claimed)- apply = AsyncMock(return_value=pool)-- with patch("cua_sandbox.pool.Pool.apply", new=apply):- result = await Sandbox.create(- Image.from_registry("registry.example/workspace:latest"),- server_port=server_port,- telemetry_enabled=False,- )-- assert result is claimed- assert apply.await_args.kwargs["services"] == {"server": server_port}-- async def test_create_forwards_default_server_port(self):- claimed = object()- pool = MagicMock()- pool.claim = AsyncMock(return_value=claimed)- apply = AsyncMock(return_value=pool)+ async def test_create_with_fleet_image_requires_explicit_pool(self):+ apply = AsyncMock()with patch("cua_sandbox.pool.Pool.apply", new=apply):- result = await Sandbox.create(- Image.from_registry("registry.example/workspace:latest"),- telemetry_enabled=False,- )+ with pytest.raises(ValueError, match="Pool.apply"):+ await Sandbox.create(+ Image.from_registry("registry.example/workspace:latest"),+ server_port=5000,+ telemetry_enabled=False,+ )- assert result is claimed- assert apply.await_args.kwargs["services"] == {"server": 8000}+ apply.assert_not_awaited()async def test_ephemeral_forwards_server_port(self):claimed = MagicMock()diff --git a/libs/python/cua/cua/__init__.py b/libs/python/cua/cua/__init__.pyindex eeb35c7289..509529ccb9 100644--- a/libs/python/cua/cua/__init__.py+++ b/libs/python/cua/cua/__init__.py@@ -30,6 +30,8 @@ from cua_sandbox import (CloudTransport,Image,Localhost,+ Pool,+ PoolAccessDeniedError,Sandbox,SandboxInfo,configure,@@ -117,6 +119,8 @@ __all__ = ["login","whoami","Image",+ "Pool",+ "PoolAccessDeniedError","Sandbox","SandboxInfo","sandbox",diff --git a/tests/android_rps_benchmark.py b/tests/android_rps_benchmark.pyindex bac049d6e3..567d7949b9 100644--- a/tests/android_rps_benchmark.py+++ b/tests/android_rps_benchmark.py@@ -20,7 +20,7 @@ import statisticsimport timefrom dataclasses import dataclass, field-from cua_sandbox import Image, Sandbox+from cua_sandbox import Image, Pool, Sandboxfrom cua_sandbox.transport.cloud import CloudTransportprint = functools.partial(builtins.print, flush=True)@@ -84,9 +84,9 @@ def _percentile(data: list[float], p: float) -> float:# ── Sandbox lifecycle ─────────────────────────────────────────────────────────-async def _provision(image: Image, idx: int) -> tuple[Sandbox, SandboxStats]:+async def _provision(pool: Pool, idx: int) -> tuple[Sandbox, SandboxStats]:t0 = time.monotonic()- sb = await Sandbox.create(image)+ sb = await Sandbox.create(pool=pool)elapsed = time.monotonic() - t0name = getattr(sb, "name", None) or f"sb-{idx}"print(f" [{idx + 1:>3}] {name} provisioned in {elapsed:.1f}s")@@ -94,13 +94,16 @@ async def _provision(image: Image, idx: int) -> tuple[Sandbox, SandboxStats]:async def _provision_fleet(- image: Image, n: int, parallel: int = 2+ image: Image, n: int, parallel: int = 2, pool_name: str = "android-rps-bench") -> tuple[list[Sandbox], list[SandboxStats], list[float]]:+ # Pool names are globally unique across accounts, so the benchmark pool+ # carries an explicit name and is reconciled once per run.+ pool = await Pool.apply(image, name=pool_name)sandboxes, stats, provision_times = [], [], []for batch_start in range(0, n, parallel):batch = range(batch_start, min(batch_start + parallel, n))- tasks = [_provision(image, i) for i in batch]+ tasks = [_provision(pool, i) for i in batch]raw = await asyncio.gather(*tasks, return_exceptions=True)for i, res in zip(batch, raw):if isinstance(res, Exception):