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(sandbox): support warm pool autoscaling through Pool.apply (#3168)
r33drichards792a791d23fa
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 35ac6da7a6..8043423aee 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@@ -114,6 +114,33 @@ the next claim.The script writes `sandbox.png` in the current directory and raises an error if`uname -a` does not complete successfully.+## Scale the pool with claim demand++Instead of a static `replicas` count, pass `autoscaling=` to let the pool grow+and shrink with claim demand. The pool scales toward `max_pool_size` while+claims are pending and back down to `min_pool_size` as claims are released;+`initial_pool_size` seeds a one-time warm head start when the pool is created:++```python+from cua_sandbox import Image, Pool, WarmPoolAutoscaling++pool = await Pool.apply(+ Image.from_registry(IMAGE),+ name=POOL_NAME,+ cpu=4,+ memory_mb=4096,+ autoscaling=WarmPoolAutoscaling(+ min_pool_size=0,+ initial_pool_size=2,+ max_pool_size=10,+ ),+)+```++Each field is optional (pass `None` to accept the server default). With+`min_pool_size=0` the pool scales to zero when no claims are held, so the+first claim after an idle period cold-starts a sandbox.+## Choose pool and claim namesThe defaults use the same value for the pool and claim. Override either namediff --git a/libs/python/cua-sandbox/README.md b/libs/python/cua-sandbox/README.mdindex 455a6a74d8..297e320920 100644--- a/libs/python/cua-sandbox/README.md+++ b/libs/python/cua-sandbox/README.md@@ -167,9 +167,29 @@ async with pool.claim(name="job-123") as sb:await sb.shell.run("echo hello")```+Instead of a static `replicas` count, a pool can scale with claim demand by+passing `autoscaling=`. The pool then grows toward `max_pool_size` while claims+are pending and shrinks back to `min_pool_size` as they are released;+`initial_pool_size` seeds a one-time warm head start at creation:++```python+from cua_sandbox import Image, Pool, WarmPoolAutoscaling++pool = await Pool.apply(+ Image.from_registry("registry.example/desktop-workspace@sha256:..."),+ cpu=4,+ memory_mb=4096,+ autoscaling=WarmPoolAutoscaling(+ min_pool_size=0,+ initial_pool_size=2,+ max_pool_size=10,+ ),+)+```+`Pool.reconcile(CreatePoolRequest(...))` and `Template.reconcile(CreateTemplateRequest(...))` remain available for advanced generated-schema configuration. The public generated builders should be used instead of constructing builder-enabled Fleet records directly.The image must run the CUA computer-server `/cmd` API on the configured `server_port`.Windows computer-server images continue to use the default port `8000`.-Fleet currently supports registry images, CPU, memory, replica count, and named TCP services. Local image builds, layers, injected files or environment, snapshots, custom disks, unsupported regions, and provider-crossing serialization raise `NotImplementedError`.+Fleet currently supports registry images, CPU, memory, replica count, claim-demand autoscaling, and named TCP services. Local image builds, layers, injected files or environment, snapshots, custom disks, unsupported regions, and provider-crossing serialization raise `NotImplementedError`.diff --git a/libs/python/cua-sandbox/cua_sandbox/__init__.py b/libs/python/cua-sandbox/cua_sandbox/__init__.pyindex 1be463b840..9b01a3085e 100644--- a/libs/python/cua-sandbox/cua_sandbox/__init__.py+++ b/libs/python/cua-sandbox/cua_sandbox/__init__.py@@ -52,6 +52,8 @@ from fleet_sdk import Template as TemplateResourcefrom fleet_sdk import (VmTemplate,VmTemplateBuilder,+ WarmPoolAutoscaling,+ WarmPoolAutoscalingBuilder,)__all__ = [@@ -71,6 +73,8 @@ __all__ = ["SandboxTemplateRefBuilder","OsGymSandboxWarmPoolSpec","OsGymSandboxWarmPoolSpecBuilder",+ "WarmPoolAutoscaling",+ "WarmPoolAutoscalingBuilder","OsGymSandboxTemplateSpec","OsGymSandboxTemplateSpecBuilder","RuntimeKind",diff --git a/libs/python/cua-sandbox/cua_sandbox/pool.py b/libs/python/cua-sandbox/cua_sandbox/pool.pyindex f80835762a..b44fb37b83 100644--- a/libs/python/cua-sandbox/cua_sandbox/pool.py+++ b/libs/python/cua-sandbox/cua_sandbox/pool.py@@ -20,6 +20,7 @@ from fleet_sdk import (ResourceMetadata,SandboxTemplateRefBuilder,SdkError,+ WarmPoolAutoscaling,)_T = TypeVar("_T")@@ -235,6 +236,7 @@ class Pool:cpu: int | None = None,memory_mb: int | None = None,services: dict[str, int] | None = None,+ autoscaling: WarmPoolAutoscaling | None = None,) -> "Pool":FleetCloudTransport._validate_image(image)effective_services = services or {@@ -242,14 +244,23 @@ class Pool:**{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(- {- "image": cloud_registry_image(image),- "replicas": replicas,- "cpu": cpu,- "memory_mb": memory_mb,- "services": sorted(effective_services.items()),- },+ identity_fields,separators=(",", ":"),sort_keys=True,)@@ -261,6 +272,7 @@ class Pool:cpu=cpu,memory_mb=memory_mb,services=effective_services,+ autoscaling=autoscaling,)pool = await cls.reconcile(transport._pool_request())try:diff --git a/libs/python/cua-sandbox/cua_sandbox/sync/__init__.py b/libs/python/cua-sandbox/cua_sandbox/sync/__init__.pyindex 31b1899e63..222726c651 100644--- a/libs/python/cua-sandbox/cua_sandbox/sync/__init__.py+++ b/libs/python/cua-sandbox/cua_sandbox/sync/__init__.py@@ -25,7 +25,12 @@ from cua_sandbox.localhost import Localhost as _AsyncLocalhostfrom cua_sandbox.pool import Pool as _AsyncPoolfrom cua_sandbox.pool import Template as _AsyncTemplatefrom cua_sandbox.sandbox import Sandbox as _AsyncSandbox-from fleet_sdk import ClaimSpec, CreatePoolRequest, CreateTemplateRequest+from fleet_sdk import (+ ClaimSpec,+ CreatePoolRequest,+ CreateTemplateRequest,+ WarmPoolAutoscaling,+)def _get_or_create_loop() -> asyncio.AbstractEventLoop:@@ -126,6 +131,7 @@ class Pool:cpu: int | None = None,memory_mb: int | None = None,services: dict[str, int] | None = None,+ autoscaling: WarmPoolAutoscaling | None = None,) -> "Pool":"""Synchronously apply an image-backed Fleet pool."""return cls(@@ -137,6 +143,7 @@ class Pool:cpu=cpu,memory_mb=memory_mb,services=services,+ autoscaling=autoscaling,)))diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/fleet_cloud.py b/libs/python/cua-sandbox/cua_sandbox/transport/fleet_cloud.pyindex e61cdc707a..23b5c330d2 100644--- a/libs/python/cua-sandbox/cua_sandbox/transport/fleet_cloud.py+++ b/libs/python/cua-sandbox/cua_sandbox/transport/fleet_cloud.py@@ -43,6 +43,7 @@ from fleet_sdk import (SandboxTemplateRefBuilder,ServiceProtocol,VmTemplateBuilder,+ WarmPoolAutoscaling,)if TYPE_CHECKING:@@ -361,6 +362,7 @@ class FleetCloudTransport(FleetTransport):create_claim: bool = False,replicas: int = 1,services: Mapping[str, int] | None = None,+ autoscaling: Optional[WarmPoolAutoscaling] = None,) -> None:if (isinstance(server_port, bool)@@ -388,6 +390,27 @@ class FleetCloudTransport(FleetTransport):)):raise ValueError("services must map non-empty names to TCP ports")+ if autoscaling is not None:+ if not isinstance(autoscaling, WarmPoolAutoscaling):+ raise TypeError("autoscaling must be a fleet_sdk.WarmPoolAutoscaling")+ for field, minimum in (+ ("min_pool_size", 0),+ ("initial_pool_size", 0),+ ("max_pool_size", 1),+ ):+ value = getattr(autoscaling, field)+ if value is not None and (+ isinstance(value, bool) or not isinstance(value, int) or value < minimum+ ):+ raise ValueError(f"autoscaling.{field} must be an integer >= {minimum}")+ if (+ autoscaling.min_pool_size is not None+ and autoscaling.max_pool_size is not None+ and autoscaling.min_pool_size > autoscaling.max_pool_size+ ):+ raise ValueError(+ "autoscaling.min_pool_size must not exceed autoscaling.max_pool_size"+ )self._image = imageself._name = nameself._explicit_pool = pool_name is not None@@ -401,6 +424,7 @@ class FleetCloudTransport(FleetTransport):self._server_port = server_portself._replicas = replicasself._services = dict(services) if services is not None else None+ self._autoscaling = autoscalingself._provisioned = Falseself._owns_resources = image is not None or create_claimself._template: Any = None@@ -623,13 +647,19 @@ class FleetCloudTransport(FleetTransport):def _pool_request(self) -> CreatePoolRequest:template_ref = SandboxTemplateRefBuilder().name(self._pool_name).build()- pool_spec = (+ pool_spec_builder = (OsGymSandboxWarmPoolSpecBuilder().replicas(self._replicas).sandbox_template_ref(template_ref)+ )+ if self._autoscaling is not None:+ pool_spec_builder = pool_spec_builder.autoscaling(self._autoscaling)+ return (+ CreatePoolRequestBuilder()+ .namespace(self._pool_name)+ .spec(pool_spec_builder.build()).build())- return CreatePoolRequestBuilder().namespace(self._pool_name).spec(pool_spec).build()@staticmethoddef _service_names(template: Any) -> list[str]:diff --git a/libs/python/cua-sandbox/tests/test_fleet_cloud_transport.py b/libs/python/cua-sandbox/tests/test_fleet_cloud_transport.pyindex 87b227741d..beaa05626e 100644--- a/libs/python/cua-sandbox/tests/test_fleet_cloud_transport.py+++ b/libs/python/cua-sandbox/tests/test_fleet_cloud_transport.py@@ -13,6 +13,7 @@ from fleet_sdk import (ResourceMetadata,Sandbox,SandboxTemplateRefBuilder,+ WarmPoolAutoscaling,)@@ -114,6 +115,59 @@ def test_pool_request_uses_the_single_sandbox_name_and_requested_replicas():assert request.spec.autoscaling is None+def test_pool_request_carries_the_requested_autoscaling():+ autoscaling = WarmPoolAutoscaling(min_pool_size=0, initial_pool_size=2, max_pool_size=10)++ request = FleetCloudTransport(+ image=Image.from_registry("registry.example/workspace@sha256:abc"),+ name="demo",+ autoscaling=autoscaling,+ )._pool_request()++ assert request.spec.autoscaling == autoscaling+++def test_pool_request_accepts_partial_autoscaling_bounds():+ autoscaling = WarmPoolAutoscaling(min_pool_size=None, initial_pool_size=None, max_pool_size=25)++ request = FleetCloudTransport(+ image=Image.from_registry("registry.example/workspace@sha256:abc"),+ name="demo",+ autoscaling=autoscaling,+ )._pool_request()++ assert request.spec.autoscaling == autoscaling+++def test_transport_rejects_untyped_autoscaling():+ with pytest.raises(TypeError, match="WarmPoolAutoscaling"):+ FleetCloudTransport(+ image=Image.from_registry("registry.example/workspace@sha256:abc"),+ name="demo",+ autoscaling={"min_pool_size": 0, "max_pool_size": 10},+ )+++ "autoscaling",+ [+ WarmPoolAutoscaling(min_pool_size=-1, initial_pool_size=None, max_pool_size=None),+ WarmPoolAutoscaling(min_pool_size=None, initial_pool_size=-1, max_pool_size=None),+ WarmPoolAutoscaling(min_pool_size=None, initial_pool_size=None, max_pool_size=0),+ WarmPoolAutoscaling(min_pool_size=True, initial_pool_size=None, max_pool_size=None),+ WarmPoolAutoscaling(min_pool_size="2", initial_pool_size=None, max_pool_size=None),+ WarmPoolAutoscaling(min_pool_size=5, initial_pool_size=None, max_pool_size=2),+ ],+)+def test_transport_rejects_invalid_autoscaling_bounds(autoscaling):+ with pytest.raises(ValueError, match="autoscaling"):+ FleetCloudTransport(+ image=Image.from_registry("registry.example/workspace@sha256:abc"),+ name="demo",+ autoscaling=autoscaling,+ )++@pytest.mark.parametrize("pool_length", [57, 58, 63])def test_deterministic_claim_name_obeys_dns_label_boundary(pool_length):pool_name = "a" * pool_lengthdiff --git a/libs/python/cua-sandbox/tests/test_pool.py b/libs/python/cua-sandbox/tests/test_pool.pyindex 6cda02107e..286d8aea73 100644--- a/libs/python/cua-sandbox/tests/test_pool.py+++ b/libs/python/cua-sandbox/tests/test_pool.py@@ -27,7 +27,7 @@ from cua_sandbox.sync import Pool as SyncPoolfrom cua_sandbox.sync import Template as SyncTemplatefrom cua_sandbox.transport.fleet_cloud import _FleetClientfrom fleet_sdk import Sandbox as FleetSandbox-from fleet_sdk import SdkError+from fleet_sdk import SdkError, WarmPoolAutoscalingdef test_public_pool_schema_exports_runtime_kind() -> None:@@ -886,6 +886,72 @@ async def test_pool_apply_rolls_back_pool_when_template_reconcile_fails(monkeypaassert clients[2].deleted_templates == []+async def test_pool_apply_forwards_autoscaling_to_the_pool_request(monkeypatch):+ clients = [FakeFleetClient() for _ in range(2)]+ iterator = iter(clients)+ monkeypatch.setattr("cua_sandbox.pool._FleetClient", lambda: next(iterator))+ autoscaling = WarmPoolAutoscaling(min_pool_size=0, initial_pool_size=2, max_pool_size=10)++ await Pool.apply(+ Image.from_registry("registry.example/workspace:latest"),+ name="workspace",+ autoscaling=autoscaling,+ )++ assert clients[0].reconciled[0].spec.autoscaling == autoscaling+++async def test_pool_apply_without_autoscaling_leaves_the_pool_spec_static(monkeypatch):+ clients = [FakeFleetClient() for _ in range(2)]+ iterator = iter(clients)+ monkeypatch.setattr("cua_sandbox.pool._FleetClient", lambda: next(iterator))++ await Pool.apply(+ Image.from_registry("registry.example/workspace:latest"),+ name="workspace",+ )++ assert clients[0].reconciled[0].spec.autoscaling is None+++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))+ 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-")+++def test_sync_pool_apply_forwards_autoscaling(monkeypatch):+ clients = [FakeFleetClient() for _ in range(2)]+ iterator = iter(clients)+ monkeypatch.setattr("cua_sandbox.pool._FleetClient", lambda: next(iterator))+ autoscaling = WarmPoolAutoscaling(min_pool_size=1, initial_pool_size=1, max_pool_size=5)++ pool = SyncPool.apply(+ Image.from_registry("registry.example/workspace:latest"),+ name="workspace",+ autoscaling=autoscaling,+ )++ assert pool.name == "workspace"+ assert clients[0].reconciled[0].spec.autoscaling == autoscaling++@pytest.mark.asyncioasync def test_pool_apply_uses_stable_configuration_name(monkeypatch):from cua_sandbox import Image