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): add Fleet pool API (#2742)

r33drichards5812670617ba
diff --git a/libs/python/cua-sandbox/README.md b/libs/python/cua-sandbox/README.md
index 0a54a313bb..16b214dfcd 100644
--- a/libs/python/cua-sandbox/README.md
+++ b/libs/python/cua-sandbox/README.md
@@ -93,6 +93,33 @@ Fleet is the OAuth cloud backend. Configure OAuth credentials once; Fleet uses `
Fleet does not support snapshots or custom disks, and currently supports only `us-east-1`. `await sb.tunnel.forward(3000)` returns the authenticated Fleet service URL for an exposed port; it does not open a local SSH tunnel.
+## Fleet pools
+
+Use a pool to keep reusable registry-image sandboxes warm. Reconciliation is idempotent: it creates a missing pool or updates the existing pool with the same name. Each claim is released when the context exits, including when the block raises.
+
+```python
+from cua_sandbox import Image, Pool
+
+pool = await Pool.reconcile({
+ "name": "foo",
+ "image": Image.from_registry("registry.example/workspace:latest"),
+})
+
+async with pool.claim() as sb:
+ result = await sb.shell.run("echo hello")
+```
+
+For scripts that use the synchronous facade:
+
+```python
+from cua_sandbox import Image
+from cua_sandbox.sync import Pool
+
+pool = Pool.reconcile({"name": "foo", "image": Image.from_registry("example:latest")})
+with pool.claim() as sb:
+ result = sb.shell.run("echo hello")
+```
+
```python
import os
diff --git a/libs/python/cua-sandbox/cua_sandbox/__init__.py b/libs/python/cua-sandbox/cua_sandbox/__init__.py
index d6196448e8..eb92197982 100644
--- a/libs/python/cua-sandbox/cua_sandbox/__init__.py
+++ b/libs/python/cua-sandbox/cua_sandbox/__init__.py
@@ -22,6 +22,7 @@ from cua_sandbox._auth import login, whoami
from cua_sandbox._config import configure
from cua_sandbox.image import Image
from cua_sandbox.localhost import Localhost, localhost
+from cua_sandbox.pool import Pool
from cua_sandbox.runtime.compat import (
RuntimeSupport,
check_local_support,
@@ -35,6 +36,7 @@ __all__ = [
"login",
"whoami",
"Image",
+ "Pool",
"Sandbox",
"SandboxInfo",
"sandbox",
diff --git a/libs/python/cua-sandbox/cua_sandbox/pool.py b/libs/python/cua-sandbox/cua_sandbox/pool.py
new file mode 100644
index 0000000000..9b4584d955
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/pool.py
@@ -0,0 +1,137 @@
+"""Fleet pool API for reusable cloud sandboxes."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator, Mapping
+from contextlib import asynccontextmanager
+from typing import Any, cast
+
+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 cyclops_sdk import CreateClaimRequest
+
+logger = logging.getLogger(__name__)
+
+
+class Pool:
+ """A reconciled Fleet pool that can lease cloud sandboxes.
+
+ ``reconcile`` creates a pool when it is absent and updates its desired
+ configuration when it already exists. The supplied ``image`` must be an
+ :meth:`Image.from_registry` image; Fleet does not support locally-built
+ images, layers, snapshots, or custom disks.
+
+ Pool instances retain only Fleet resource metadata. Each call to
+ :meth:`claim` creates and closes its own Fleet client, so a Pool may be
+ reused for sequential claims without the caller managing client lifetime.
+ """
+
+ def __init__(self, resource: Any) -> None:
+ self._resource = resource
+
+ @property
+ def name(self) -> str:
+ """The pool name."""
+ return cast(str, self._resource.metadata.name)
+
+ @property
+ def resource(self) -> Any:
+ """The underlying Fleet SDK pool resource."""
+ return self._resource
+
+ @classmethod
+ async def reconcile(cls, config: Mapping[str, Any]) -> "Pool":
+ """Create or update a Fleet pool from its desired configuration.
+
+ Repeated calls with the same configuration are idempotent: an existing
+ pool is updated in place rather than creating another pool. ``config``
+ requires a non-empty ``name`` and an ``image`` created with
+ :meth:`Image.from_registry`.
+
+ The Fleet client used to reconcile is closed before this method returns.
+ """
+ name, image = cls._validate_config(config)
+ desired = FleetCloudTransport(image=image, name=name)._pool_request()
+ client = _FleetClient()
+ try:
+ try:
+ resource = await client.get_pool(name)
+ except LookupError:
+ resource = await client.create_pool(desired)
+ else:
+ resource.spec = desired.spec
+ resource = await client.update_pool(resource)
+ return cls(resource)
+ finally:
+ await client.close()
+
+ @asynccontextmanager
+ async def claim(self) -> AsyncIterator[Sandbox]:
+ """Lease a sandbox and release its Fleet claim when the block exits.
+
+ A claim is released after both normal and exceptional block exits. If
+ release fails while the block is already raising, the original block
+ exception is preserved and the release failure is logged. Otherwise,
+ the release failure is raised to the caller.
+ """
+ client = _FleetClient()
+ claim: Any = None
+ sandbox: Sandbox | None = None
+ primary_error: BaseException | None = None
+ cleanup_error: Exception | None = None
+
+ try:
+ claim = await client.create_claim(CreateClaimRequest(pool=self._resource, spec=None))
+ bound = await client.wait_claim(claim)
+ sandbox = Sandbox(
+ FleetTransport(sdk=client, bound=bound, service_name="server"), name=bound.name
+ )
+ await sandbox._connect()
+ yield sandbox
+ except BaseException as error:
+ primary_error = error
+ raise
+ finally:
+ if sandbox is not None:
+ try:
+ await sandbox.disconnect()
+ except Exception:
+ logger.exception("Failed to disconnect claimed sandbox %r", sandbox.name)
+
+ if claim is not None:
+ try:
+ await client.delete_claim(claim)
+ except Exception as error:
+ if primary_error is not None:
+ logger.exception("Failed to release Fleet claim after an earlier error")
+ else:
+ cleanup_error = error
+
+ try:
+ await client.close()
+ except Exception:
+ if primary_error is not None or cleanup_error is not None:
+ logger.exception("Failed to close Fleet client")
+ else:
+ raise
+
+ if cleanup_error is not None:
+ raise cleanup_error
+
+ @staticmethod
+ def _validate_config(config: Mapping[str, Any]) -> tuple[str, Image]:
+ if not isinstance(config, Mapping):
+ raise TypeError("Pool configuration must be a mapping")
+
+ name = config.get("name")
+ if not isinstance(name, str) or not name:
+ raise ValueError("Pool configuration requires a non-empty string 'name'")
+
+ image = config.get("image")
+ if not isinstance(image, Image):
+ raise TypeError("Pool configuration 'image' must be an Image.from_registry(...) value")
+ FleetCloudTransport._validate_image(image)
+ return name, image
diff --git a/libs/python/cua-sandbox/cua_sandbox/sync/__init__.py b/libs/python/cua-sandbox/cua_sandbox/sync/__init__.py
index 8d38d77b68..9a473f8ad8 100644
--- a/libs/python/cua-sandbox/cua_sandbox/sync/__init__.py
+++ b/libs/python/cua-sandbox/cua_sandbox/sync/__init__.py
@@ -18,10 +18,11 @@ from __future__ import annotations
import asyncio
from contextlib import contextmanager
-from typing import Any, Iterator, Optional
+from typing import Any, Iterator, Mapping, Optional
from cua_sandbox.image import Image
from cua_sandbox.localhost import Localhost as _AsyncLocalhost
+from cua_sandbox.pool import Pool as _AsyncPool
from cua_sandbox.sandbox import Sandbox as _AsyncSandbox
@@ -72,6 +73,40 @@ class _SyncProxy:
return f"Sync({self._async_obj!r})"
+class Pool:
+ """Blocking facade for :class:`cua_sandbox.Pool`.
+
+ ``Pool.reconcile`` and ``pool.claim`` use the same Fleet lifecycle as the
+ async API, but yield synchronous sandbox interface methods for scripts and
+ notebooks.
+ """
+
+ def __init__(self, async_pool: _AsyncPool) -> None:
+ self._async_pool = async_pool
+
+ @property
+ def name(self) -> str:
+ return self._async_pool.name
+
+ @classmethod
+ def reconcile(cls, config: Mapping[str, Any]) -> "Pool":
+ """Synchronously create or update a Fleet pool."""
+ return cls(_run(_AsyncPool.reconcile(config)))
+
+ @contextmanager
+ def claim(self) -> Iterator[_SyncProxy]:
+ """Synchronously lease a sandbox and release the claim on exit."""
+ context = self._async_pool.claim()
+ sandbox = _run(context.__aenter__())
+ try:
+ yield _SyncProxy(sandbox)
+ except BaseException as error:
+ _run(context.__aexit__(type(error), error, error.__traceback__))
+ raise
+ else:
+ _run(context.__aexit__(None, None, None))
+
+
@contextmanager
def sandbox(
*,
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 f3c92001df..663bb526c7 100644
--- a/libs/python/cua-sandbox/cua_sandbox/transport/fleet_cloud.py
+++ b/libs/python/cua-sandbox/cua_sandbox/transport/fleet_cloud.py
@@ -95,6 +95,9 @@ class _FleetClient:
async def delete_pool(self, pool: Any) -> None:
await self._client.delete_pool(pool)
+ async def update_pool(self, pool: Any) -> Any:
+ return await self._client.update_pool(pool)
+
async def service_request(
self, sandbox: Any, service: str, path: str, request: HttpRequest
) -> Any:
diff --git a/libs/python/cua-sandbox/tests/test_pool.py b/libs/python/cua-sandbox/tests/test_pool.py
new file mode 100644
index 0000000000..326fa6f9ad
--- /dev/null
+++ b/libs/python/cua-sandbox/tests/test_pool.py
@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+from cua_sandbox import Image, Pool
+from cua_sandbox.sync import Pool as SyncPool
+from cyclops_sdk import Sandbox as FleetSandbox
+
+
+def fleet_pool(name: str = "foo") -> SimpleNamespace:
+ return SimpleNamespace(
+ metadata=SimpleNamespace(name=name, namespace=name),
+ spec=SimpleNamespace(services=[]),
+ )
+
+
+class FakeFleetClient:
+ def __init__(
+ self,
+ *,
+ existing: object | None = None,
+ create_error: Exception | None = None,
+ release_error: Exception | None = None,
+ ):
+ self.existing = existing
+ self.create_error = create_error
+ self.release_error = release_error
+ self.created: list[object] = []
+ self.updated: list[object] = []
+ self.claims: list[object] = []
+ self.released: list[object] = []
+ self.closed = False
+
+ async def get_pool(self, name: str) -> object:
+ if self.existing is None:
+ raise LookupError(name)
+ return self.existing
+
+ async def create_pool(self, request: object) -> object:
+ self.created.append(request)
+ if self.create_error:
+ raise self.create_error
+ return fleet_pool(request.namespace)
+
+ async def update_pool(self, pool: object) -> object:
+ self.updated.append(pool)
+ return pool
+
+ async def create_claim(self, request: object) -> object:
+ self.claims.append(request)
+ return "claim-1"
+
+ async def wait_claim(self, claim: object) -> FleetSandbox:
+ assert claim == "claim-1"
+ return FleetSandbox(namespace="foo", claim="claim-1", name="sandbox-1", services=["server"])
+
+ async def delete_claim(self, claim: object) -> None:
+ self.released.append(claim)
+ if self.release_error:
+ raise self.release_error
+
+ async def close(self) -> None:
+ self.closed = True
+
+
+async def test_reconcile_creates_pool_from_registry_image(monkeypatch):
+ client = FakeFleetClient()
+ monkeypatch.setattr("cua_sandbox.pool._FleetClient", lambda: client)
+
+ pool = await Pool.reconcile(
+ {
+ "name": "foo",
+ "image": Image.from_registry("registry.example/workspace:latest").expose(3000),
+ }
+ )
+
+ assert pool.name == "foo"
+ assert pool.resource.metadata.name == "foo"
+ assert client.closed is True
+ assert len(client.created) == 1
+ request = client.created[0]
+ assert request.namespace == "foo"
+ assert request.spec.template.container_disk_image == "registry.example/workspace:latest"
+ assert [(service.name, service.target_port) for service in request.spec.services] == [
+ ("server", 8000),
+ ("port-3000", 3000),
+ ]
+
+
+async def test_reconcile_closes_temporary_client_when_creation_fails(monkeypatch):
+ client = FakeFleetClient(create_error=RuntimeError("create failed"))
+ monkeypatch.setattr("cua_sandbox.pool._FleetClient", lambda: client)
+
+ with pytest.raises(RuntimeError, match="create failed"):
+ await Pool.reconcile({"name": "foo", "image": Image.from_registry("example:latest")})
+
+ assert client.closed is True
+
+
+async def test_reconcile_updates_existing_pool_idempotently(monkeypatch):
+ existing = fleet_pool()
+ client = FakeFleetClient(existing=existing)
+ monkeypatch.setattr("cua_sandbox.pool._FleetClient", lambda: client)
+
+ pool = await Pool.reconcile({"name": "foo", "image": Image.from_registry("example:latest")})
+
+ assert pool.resource is existing
+ assert client.created == []
+ assert client.updated == [existing]
+ assert existing.spec.template.container_disk_image == "example:latest"
+ assert client.closed is True
+
+
+async def test_claim_releases_claim_and_client_after_block_exception(monkeypatch):
+ reconcile_client = FakeFleetClient()
+ claim_client = FakeFleetClient()
+ clients = iter([reconcile_client, claim_client])
+ monkeypatch.setattr("cua_sandbox.pool._FleetClient", lambda: next(clients))
+ pool = await Pool.reconcile({"name": "foo", "image": Image.from_registry("example:latest")})
+
+ with pytest.raises(RuntimeError, match="body failed"):
+ async with pool.claim() as sandbox:
+ assert sandbox.name == "sandbox-1"
+ raise RuntimeError("body failed")
+
+ assert claim_client.claims[0].pool is pool.resource
+ assert claim_client.claims[0].spec is None
+ assert claim_client.released == ["claim-1"]
+ assert claim_client.closed is True
+
+
+async def test_claim_preserves_block_exception_when_release_fails(monkeypatch):
+ reconcile_client = FakeFleetClient()
+ claim_client = FakeFleetClient(release_error=RuntimeError("release failed"))
+ clients = iter([reconcile_client, claim_client])
+ monkeypatch.setattr("cua_sandbox.pool._FleetClient", lambda: next(clients))
+ pool = await Pool.reconcile({"name": "foo", "image": Image.from_registry("example:latest")})
+
+ with pytest.raises(ValueError, match="body failed"):
+ async with pool.claim():
+ raise ValueError("body failed")
+
+ assert claim_client.released == ["claim-1"]
+ assert claim_client.closed is True
+
+
+async def test_claim_raises_release_failure_without_block_exception(monkeypatch):
+ reconcile_client = FakeFleetClient()
+ claim_client = FakeFleetClient(release_error=RuntimeError("release failed"))
+ clients = iter([reconcile_client, claim_client])
+ monkeypatch.setattr("cua_sandbox.pool._FleetClient", lambda: next(clients))
+ pool = await Pool.reconcile({"name": "foo", "image": Image.from_registry("example:latest")})
+
+ with pytest.raises(RuntimeError, match="release failed"):
+ async with pool.claim():
+ pass
+
+ assert claim_client.closed is True
+
+
+ "config, message",
+ [
+ ({"image": Image.from_registry("example:latest")}, "name"),
+ ({"name": "foo"}, "image"),
+ ({"name": "foo", "image": "example:latest"}, "Image.from_registry"),
+ ({"name": "foo", "image": Image.linux()}, "Image.from_registry"),
+ ],
+)
+async def test_reconcile_rejects_invalid_config(config, message):
+ with pytest.raises((TypeError, ValueError), match=message):
+ await Pool.reconcile(config)
+
+
+def test_sync_pool_matches_blocking_context_manager(monkeypatch):
+ reconcile_client = FakeFleetClient()
+ claim_client = FakeFleetClient()
+ clients = iter([reconcile_client, claim_client])
+ monkeypatch.setattr("cua_sandbox.pool._FleetClient", lambda: next(clients))
+
+ pool = SyncPool.reconcile({"name": "foo", "image": Image.from_registry("example:latest")})
+ with pool.claim() as sandbox:
+ assert sandbox.name == "sandbox-1"
+
+ assert claim_client.released == ["claim-1"]
+ assert claim_client.closed is True