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(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.mdx
index 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 names
The defaults use the same value for the pool and claim. Override either name
diff --git a/libs/python/cua-sandbox/README.md b/libs/python/cua-sandbox/README.md
index 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__.py
index 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 TemplateResource
from 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.py
index 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__.py
index 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 _AsyncLocalhost
from cua_sandbox.pool import Pool as _AsyncPool
from cua_sandbox.pool import Template as _AsyncTemplate
from 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.py
index 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 = image
self._name = name
self._explicit_pool = pool_name is not None
@@ -401,6 +424,7 @@ class FleetCloudTransport(FleetTransport):
self._server_port = server_port
self._replicas = replicas
self._services = dict(services) if services is not None else None
+ self._autoscaling = autoscaling
self._provisioned = False
self._owns_resources = image is not None or create_claim
self._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()
@staticmethod
def _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.py
index 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_length
diff --git a/libs/python/cua-sandbox/tests/test_pool.py b/libs/python/cua-sandbox/tests/test_pool.py
index 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 SyncPool
from cua_sandbox.sync import Template as SyncTemplate
from cua_sandbox.transport.fleet_cloud import _FleetClient
from fleet_sdk import Sandbox as FleetSandbox
-from fleet_sdk import SdkError
+from fleet_sdk import SdkError, WarmPoolAutoscaling
def test_public_pool_schema_exports_runtime_kind() -> None:
@@ -886,6 +886,72 @@ async def test_pool_apply_rolls_back_pool_when_template_reconcile_fails(monkeypa
assert 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.asyncio
async def test_pool_apply_uses_stable_configuration_name(monkeypatch):
from cua_sandbox import Image