Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

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.mdx
index 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.py
Use stable names when later runs should reconcile the same pool and reuse the
same 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 pool
The example intentionally leaves the pool warm. If you no longer need it, call
diff --git a/docs/content/docs/how-to-guides/sandbox/minecraft.mdx b/docs/content/docs/how-to-guides/sandbox/minecraft.mdx
index 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
```python
import 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.md
index 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.
```python
from 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, Pool
pool = 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, WarmPoolAutoscaling
pool = 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__.py
index 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, sandbox
from cua_sandbox.transport.cloud import CloudTransport
+from cua_sandbox.transport.fleet_cloud import PoolAccessDeniedError
from 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.py
index 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 json
import logging
from typing import Any, Callable, Coroutine, Generic, TypeVar, cast
-from cua_sandbox.image import Image, cloud_registry_image
+from cua_sandbox.image import Image
from cua_sandbox.sandbox import Sandbox
from 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
+ raise
finally:
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
+ raise
finally:
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
+ )
raise
pool._owned_template = template.resource
return pool
diff --git a/libs/python/cua-sandbox/cua_sandbox/sandbox.py b/libs/python/cua-sandbox/cua_sandbox/sandbox.py
index 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 annotations
import logging
import random
+import secrets
import time
from collections.abc import Mapping
from 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 sandbox
if 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 = None
try:
diff --git a/libs/python/cua-sandbox/cua_sandbox/sync/__init__.py b/libs/python/cua-sandbox/cua_sandbox/sync/__init__.py
index 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.py
index 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
+ raise
self._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.py
index 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.py
index 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.asyncio
diff --git a/libs/python/cua-sandbox/tests/test_sandbox_fleet_lifecycle.py b/libs/python/cua-sandbox/tests/test_sandbox_fleet_lifecycle.py
index 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_state
class 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, t
pool.claim = claim
monkeypatch.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.asyncio
async 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.asyncio
async 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.py
index 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__.py
index 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.py
index bac049d6e3..567d7949b9 100644
--- a/tests/android_rps_benchmark.py
+++ b/tests/android_rps_benchmark.py
@@ -20,7 +20,7 @@ import statistics
import time
from dataclasses import dataclass, field
-from cua_sandbox import Image, Sandbox
+from cua_sandbox import Image, Pool, Sandbox
from cua_sandbox.transport.cloud import CloudTransport
print = 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() - t0
name = 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):