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
refactor(cua-sandbox): use generated Cyclops SDK for Fleet cloud transport (#2398)
r33drichards3df76b1ce5ef
diff --git a/libs/python/cua-sandbox/README.md b/libs/python/cua-sandbox/README.mdindex 5ee5e6d824..899a1c8741 100644--- a/libs/python/cua-sandbox/README.md+++ b/libs/python/cua-sandbox/README.md@@ -77,3 +77,27 @@ async with Localhost.connect() as host:await host.shell.run("echo hello")await host.screenshot()```+++## Cloud sandbox++Fleet is the OAuth cloud backend. Configure OAuth credentials once; Fleet uses `https://run.cua.ai` by default and can be overridden with `configure(fleet_base_url=...)` or `CUA_FLEET_BASE_URL`. The legacy API-key VM API continues to use `https://api.cua.ai`. Cloud images must use a registry reference; `expose()` declares additional Fleet services.++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.++```python+import os++import cua_sandbox as cua+from cua_sandbox import Image, Sandbox++cua.configure(+ client_id=os.environ["CUA_CLIENT_ID"],+ client_secret=os.environ["CUA_CLIENT_SECRET"],+)++async with Sandbox.ephemeral(+ Image.from_registry("registry.example/desktop-workspace@sha256:...").expose(3000)+) as sb:+ await sb.shell.run("uname -a")+```diff --git a/libs/python/cua-sandbox/cua_sandbox/_config.py b/libs/python/cua-sandbox/cua_sandbox/_config.pyindex 0f9872a559..14baa298b0 100644--- a/libs/python/cua-sandbox/cua_sandbox/_config.py+++ b/libs/python/cua-sandbox/cua_sandbox/_config.py@@ -1,7 +1,4 @@-"""Global configuration — configure(api_key, base_url).--Auth priority: per-call > configure() > ~/.cua/credentials > CUA_API_KEY env var.-"""+"""Global configuration for cloud sandbox provisioning."""from __future__ import annotations@@ -9,11 +6,19 @@ import osfrom dataclasses import dataclassfrom typing import Optional+_DEFAULT_BASE_URL = "https://api.cua.ai"+_DEFAULT_FLEET_BASE_URL = "https://run.cua.ai"+_DEFAULT_TOKEN_URL = "https://auth.cua.ai/realms/cyclops-cs/protocol/openid-connect/token"+@dataclassclass _Config:api_key: Optional[str] = None- base_url: str = "https://api.cua.ai"+ base_url: str = _DEFAULT_BASE_URL+ fleet_base_url: str = _DEFAULT_FLEET_BASE_URL+ token_url: str = _DEFAULT_TOKEN_URL+ client_id: Optional[str] = None+ client_secret: Optional[str] = None_global_config = _Config()@@ -23,29 +28,39 @@ def configure(*,api_key: Optional[str] = None,base_url: Optional[str] = None,+ fleet_base_url: Optional[str] = None,+ token_url: Optional[str] = None,+ client_id: Optional[str] = None,+ client_secret: Optional[str] = None,) -> None:- """Set global configuration for the CUA SDK.+ """Set global configuration for cloud sandboxes.- Args:- api_key: API key for cloud sandboxes.- base_url: Base URL for the CUA cloud API.+ API-key cloud operations use ``base_url``. Fleet uses ``fleet_base_url`` and+ OAuth client credentials."""if api_key is not None:_global_config.api_key = api_keyif base_url is not None:_global_config.base_url = base_url+ if fleet_base_url is not None:+ _global_config.fleet_base_url = fleet_base_url+ if token_url is not None:+ _global_config.token_url = token_url+ if client_id is not None:+ _global_config.client_id = client_id+ if client_secret is not None:+ _global_config.client_secret = client_secretdef get_api_key(override: Optional[str] = None) -> Optional[str]:- """Resolve API key with priority: override > configure() > credentials file > env."""+ """Resolve a legacy API key with per-call configuration taking priority."""if override:return overrideif _global_config.api_key:return _global_config.api_key- # Try credentials file- cred = _read_credentials_key()- if cred:- return cred+ credential = _read_credentials_key()+ if credential:+ return credentialreturn os.environ.get("CUA_API_KEY")@@ -53,12 +68,29 @@ def get_base_url() -> str:return os.environ.get("CUA_BASE_URL") or _global_config.base_url+def get_fleet_base_url() -> str:+ """Return the Fleet API endpoint without changing legacy VM API routing."""+ return os.environ.get("CUA_FLEET_BASE_URL") or _global_config.fleet_base_url+++def get_token_url() -> str:+ return os.environ.get("CUA_TOKEN_URL") or _global_config.token_url+++def get_client_id(override: Optional[str] = None) -> Optional[str]:+ return override or _global_config.client_id or os.environ.get("CUA_CLIENT_ID")+++def get_client_secret(override: Optional[str] = None) -> Optional[str]:+ return override or _global_config.client_secret or os.environ.get("CUA_CLIENT_SECRET")++def _read_credentials_key() -> Optional[str]:- """Read API key from ~/.cua/credentials if it exists."""- cred_path = os.path.join(os.path.expanduser("~"), ".cua", "credentials")+ """Read a legacy API key from ``~/.cua/credentials`` when present."""+ credential_path = os.path.join(os.path.expanduser("~"), ".cua", "credentials")try:- with open(cred_path) as f:- for line in f:+ with open(credential_path) as credential_file:+ for line in credential_file:line = line.strip()if line.startswith("api_key="):return line[len("api_key=") :]diff --git a/libs/python/cua-sandbox/cua_sandbox/interfaces/tunnel.py b/libs/python/cua-sandbox/cua_sandbox/interfaces/tunnel.pyindex 7d7f27a136..e3f66b8b5d 100644--- a/libs/python/cua-sandbox/cua_sandbox/interfaces/tunnel.py+++ b/libs/python/cua-sandbox/cua_sandbox/interfaces/tunnel.py@@ -28,15 +28,18 @@ from cua_sandbox.transport.base import Transportclass TunnelInfo:"""A single forwarded port."""- def __init__(self, host: str, port: int, sandbox_port: int) -> None:+ def __init__(+ self, host: str, port: int, sandbox_port: int, *, url: Optional[str] = None+ ) -> None:self.host = hostself.port = port # host-side portself.sandbox_port = sandbox_port # original port inside sandbox+ self._url = urlself._closer: Optional[object] = None # Callable[[TunnelInfo], Coroutine]@propertydef url(self) -> str:- return f"http://{self.host}:{self.port}"+ return self._url or f"http://{self.host}:{self.port}"async def close(self) -> None:"""Close this tunnel (no-op if already closed or inside a context manager)."""diff --git a/libs/python/cua-sandbox/cua_sandbox/sandbox.py b/libs/python/cua-sandbox/cua_sandbox/sandbox.pyindex 76043b17fa..5335b18fb9 100644--- a/libs/python/cua-sandbox/cua_sandbox/sandbox.py+++ b/libs/python/cua-sandbox/cua_sandbox/sandbox.py@@ -56,6 +56,7 @@ except ImportError:pass+from cua_sandbox._config import get_client_id, get_client_secretfrom cua_sandbox.image import Imagefrom cua_sandbox.interfaces import (Apps,@@ -72,6 +73,7 @@ from cua_sandbox.interfaces import ()from cua_sandbox.transport.base import Transportfrom cua_sandbox.transport.cloud import CloudTransport+from cua_sandbox.transport.fleet_cloud import FleetCloudTransportfrom cua_sandbox.transport.http import HTTPTransportfrom cua_sandbox.transport.websocket import WebSocketTransport@@ -272,7 +274,7 @@ class Sandbox:async def _connect(self) -> None:await self._transport.connect()# Update name from transport (e.g. CloudTransport resolves name after creating a VM)- if self.name is None and isinstance(self._transport, CloudTransport):+ if self.name is None and isinstance(self._transport, (CloudTransport, FleetCloudTransport)):self.name = self._transport.nameasync def disconnect(self) -> None:@@ -294,7 +296,7 @@ class Sandbox:"""from cua_sandbox.transport.cloud import CloudTransport- if not isinstance(self._transport, CloudTransport):+ if not isinstance(self._transport, (CloudTransport, FleetCloudTransport)):raise NotImplementedError("Snapshots are only supported for cloud sandboxes")image_desc = await self._transport.create_snapshot(name=name, stateful=stateful)@@ -333,7 +335,7 @@ class Sandbox:await self._transport.disconnect()except Exception:logger.warning("Failed to disconnect transport for sandbox %r", self.name)- if isinstance(self._transport, CloudTransport):+ if isinstance(self._transport, (CloudTransport, FleetCloudTransport)):try:await self._transport.delete_vm()except Exception:@@ -420,15 +422,16 @@ class Sandbox:Args:image: Image to run (e.g. ``Image.desktop("ubuntu")``).name: Optional name to assign to the sandbox.- api_key: CUA API key for cloud sandboxes.+ api_key: Legacy CUA API key. Providing one uses the legacy VM API;+ Fleet cloud sandboxes use OAuth client credentials instead.local: Use a local runtime instead of cloud.runtime: Explicit runtime backend (DockerRuntime, QEMURuntime, etc.).cpu: Number of CPUs for the cloud sandbox.memory_mb: Memory in MB for the cloud sandbox.- disk_gb: Disk size in GB for the cloud sandbox.- region: Cloud region (default ``"us-east-1"``).- time_to_start: Max seconds to wait for the VM to become reachable- (default 600). Only applies to cloud sandboxes.+ disk_gb: Unsupported by Fleet; API-key legacy cloud only.+ region: Fleet currently supports only ``"us-east-1"``.+ time_to_start: Max seconds to wait for Fleet provisioning and+ service readiness (default 600).request_timeout: Default HTTP request timeout in seconds forcommands sent to the computer-server (default 30, cloud only).Individual commands with a server-side timeout automatically@@ -540,15 +543,16 @@ class Sandbox:Args:image: Image to run (e.g. ``Image.desktop("ubuntu")``).name: Optional name to assign to the sandbox.- api_key: CUA API key for cloud sandboxes.+ api_key: Legacy CUA API key. Providing one uses the legacy VM API;+ Fleet cloud sandboxes use OAuth client credentials instead.local: Use a local runtime instead of cloud.runtime: Explicit runtime backend (DockerRuntime, QEMURuntime, etc.).cpu: Number of CPUs for the cloud sandbox.memory_mb: Memory in MB for the cloud sandbox.- disk_gb: Disk size in GB for the cloud sandbox.- region: Cloud region (default ``"us-east-1"``).- time_to_start: Max seconds to wait for the VM to become reachable- (default 600). Only applies to cloud sandboxes.+ disk_gb: Unsupported by Fleet; API-key legacy cloud only.+ region: Fleet currently supports only ``"us-east-1"``.+ time_to_start: Max seconds to wait for Fleet provisioning and+ service readiness (default 600).request_timeout: Default HTTP request timeout in seconds forcommands sent to the computer-server (default 30, cloud only).Individual commands with a server-side timeout automatically@@ -690,24 +694,45 @@ class Sandbox:)return results+ @staticmethod+ def _uses_fleet(api_key: Optional[str]) -> bool:+ """Choose Fleet only for OAuth-configured calls without an explicit API key."""+ return api_key is None and bool(get_client_id() and get_client_secret())+@classmethodasync def _list_cloud(cls, *, api_key: Optional[str] = None) -> "list[SandboxInfo]":- from cua_sandbox.transport.cloud import cloud_list_vms+ if not cls._uses_fleet(api_key):+ from cua_sandbox.transport.cloud import cloud_list_vms- vms = await cloud_list_vms(api_key=api_key)- results = []- for vm in vms:- raw_status = vm.get("status", "unknown")- results.append(+ vms = await cloud_list_vms(api_key=api_key)+ return [SandboxInfo(name=vm.get("name", ""),- status=raw_status,+ status=vm.get("status", "unknown"),source="cloud",os_type=vm.get("os_type") or vm.get("os"),created_at=vm.get("created_at"),)- )- return results+ for vm in vms+ ]++ pools = await FleetCloudTransport.list_sandboxes()+ return [cls._fleet_sandbox_info(pool) for pool in pools]++ @staticmethod+ def _fleet_sandbox_info(pool: dict[str, Any]) -> SandboxInfo:+ metadata = pool.get("metadata") or {}+ spec = pool.get("spec") or {}+ status = pool.get("status") or {}+ replicas = spec.get("replicas", 1)+ available = status.get("availableCount", 0)+ state = "suspended" if replicas == 0 else "running" if available else "provisioning"+ return SandboxInfo(+ name=metadata.get("name", ""),+ status=state,+ source="fleet",+ created_at=metadata.get("creationTimestamp"),+ )@classmethodasync def get_info(@@ -747,16 +772,18 @@ class Sandbox:),)raise ValueError(f"Local sandbox '{name}' not found.")- from cua_sandbox.transport.cloud import cloud_get_vm-- vm = await cloud_get_vm(name, api_key=api_key)- return SandboxInfo(- name=vm.get("name", name),- status=vm.get("status", "unknown"),- source="cloud",- os_type=vm.get("os_type") or vm.get("os"),- created_at=vm.get("created_at"),- )+ if not cls._uses_fleet(api_key):+ from cua_sandbox.transport.cloud import cloud_get_vm++ vm = await cloud_get_vm(name, api_key=api_key)+ return SandboxInfo(+ name=vm.get("name", name),+ status=vm.get("status", "unknown"),+ source="cloud",+ os_type=vm.get("os_type") or vm.get("os"),+ created_at=vm.get("created_at"),+ )+ return cls._fleet_sandbox_info(await FleetCloudTransport.get_sandbox_info(name))@classmethodasync def suspend(@@ -781,9 +808,12 @@ class Sandbox:if local:await cls._suspend_local(name)return- from cua_sandbox.transport.cloud import cloud_vm_action+ if not cls._uses_fleet(api_key):+ from cua_sandbox.transport.cloud import cloud_vm_action- await cloud_vm_action(name, "stop", api_key=api_key)+ await cloud_vm_action(name, "stop", api_key=api_key)+ return+ await FleetCloudTransport.suspend_sandbox(name)@classmethodasync def _suspend_local(cls, name: str) -> None:@@ -832,10 +862,13 @@ class Sandbox:"""if local:return await cls._resume_local(name)- from cua_sandbox.transport.cloud import cloud_vm_action+ if not cls._uses_fleet(api_key):+ from cua_sandbox.transport.cloud import cloud_vm_action- await cloud_vm_action(name, "run", api_key=api_key)- # Connect to the now-running cloud sandbox+ await cloud_vm_action(name, "run", api_key=api_key)+ else:+ await FleetCloudTransport.resume_sandbox(name)+ # Connect to the now-running cloud sandbox.sb = await cls._create(name=name, ephemeral=False, api_key=api_key)return sb@@ -849,14 +882,12 @@ class Sandbox:raise ValueError(f"No local sandbox named '{name}' found in state files.")runtime_type = state.get("runtime_type")if runtime_type == "lume":- from cua_sandbox.image import Imagefrom cua_sandbox.runtime.lume import LumeRuntimeimage = Image.from_dict(state["image"])rt = LumeRuntime()rt_info = await rt.resume(image, name)elif runtime_type == "qemu-baremetal":- from cua_sandbox.image import Imagefrom cua_sandbox.runtime.qemu import QEMUBaremetalRuntimeimage = Image.from_dict(state["image"])@@ -910,9 +941,12 @@ class Sandbox:if local:await cls._suspend_local(name)return await cls._resume_local(name)- from cua_sandbox.transport.cloud import cloud_vm_action+ if not cls._uses_fleet(api_key):+ from cua_sandbox.transport.cloud import cloud_vm_action- await cloud_vm_action(name, "restart", api_key=api_key)+ await cloud_vm_action(name, "restart", api_key=api_key)+ else:+ await FleetCloudTransport.restart_sandbox(name)sb = await cls._create(name=name, ephemeral=False, api_key=api_key)return sb@@ -937,9 +971,12 @@ class Sandbox:if local:await cls._delete_local(name)return- from cua_sandbox.transport.cloud import cloud_vm_action+ if not cls._uses_fleet(api_key):+ from cua_sandbox.transport.cloud import cloud_vm_action- await cloud_vm_action(name, "delete", api_key=api_key)+ await cloud_vm_action(name, "delete", api_key=api_key)+ return+ await FleetCloudTransport.delete_sandbox(name)@classmethodasync def _delete_local(cls, name: str) -> None:@@ -996,7 +1033,7 @@ class Sandbox:ephemeral = bool(image)rt_info = None- if image and image.kind is None and image._registry:+ if image and image.kind is None and image._registry and local:from cua_sandbox.registry.resolve import resolve_image_kindimage = resolve_image_kind(image)@@ -1044,11 +1081,10 @@ class Sandbox:runtime = _auto_runtime(image)if image and not runtime and not local:# image without runtime and not local → cloud creation- if not any([ws_url, http_url]):- transport = CloudTransport(- name=name,- api_key=api_key,+ if not any([ws_url, http_url]) and not api_key:+ transport = FleetCloudTransport(image=image,+ name=name or _random_name(),cpu=cpu,memory_mb=memory_mb,disk_gb=disk_gb,@@ -1080,6 +1116,23 @@ class Sandbox:sb, image=image, local=False, ephemeral=bool(ephemeral), t_start=_t_start)return sb+ if api_key and not any([ws_url, http_url]):+ transport = _make_transport(+ api_key=api_key,+ name=name,+ cpu=cpu,+ memory_mb=memory_mb,+ disk_gb=disk_gb,+ region=region,+ )+ sb = cls(+ transport, name=name, _ephemeral=ephemeral, _telemetry_enabled=telemetry_enabled+ )+ await sb._connect()+ _record_sandbox_create(+ sb, image=image, local=False, ephemeral=bool(ephemeral), t_start=_t_start+ )+ return sbruntime = _auto_runtime(image)if image and runtime:sb_name = name or _random_name()@@ -1153,17 +1206,27 @@ class Sandbox:container_name=container_name,)else:- transport = _make_transport(- ws_url=ws_url,- http_url=http_url,- api_key=api_key,- container_name=container_name,- name=name,- cpu=cpu,- memory_mb=memory_mb,- disk_gb=disk_gb,- region=region,- )+ if name and cls._uses_fleet(api_key) and not ws_url and not http_url:+ transport = FleetCloudTransport(+ image=None,+ name=name,+ cpu=cpu,+ memory_mb=memory_mb,+ disk_gb=disk_gb,+ region=region,+ )+ else:+ transport = _make_transport(+ ws_url=ws_url,+ http_url=http_url,+ api_key=api_key,+ container_name=container_name,+ name=name,+ cpu=cpu,+ memory_mb=memory_mb,+ disk_gb=disk_gb,+ region=region,+ )# Write persistent state for local (non-ephemeral) sandboxesif not ephemeral and rt_info and local:from cua_sandbox import sandbox_statediff --git a/libs/python/cua-sandbox/cua_sandbox/transport/__init__.py b/libs/python/cua-sandbox/cua_sandbox/transport/__init__.pyindex 8339174d02..6dc01eaa15 100644--- a/libs/python/cua-sandbox/cua_sandbox/transport/__init__.py+++ b/libs/python/cua-sandbox/cua_sandbox/transport/__init__.py@@ -1,6 +1,7 @@from cua_sandbox.transport.adb import ADBTransportfrom cua_sandbox.transport.base import Transportfrom cua_sandbox.transport.cloud import CloudTransport+from cua_sandbox.transport.fleet import FleetTransportfrom cua_sandbox.transport.http import HTTPTransportfrom cua_sandbox.transport.local import LocalTransportfrom cua_sandbox.transport.osworld import OSWorldTransport@@ -16,6 +17,7 @@ __all__ = ["WebSocketTransport","HTTPTransport","CloudTransport",+ "FleetTransport","QMPTransport","OSWorldTransport","ADBTransport",diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/computer_server.py b/libs/python/cua-sandbox/cua_sandbox/transport/computer_server.pynew file mode 100644index 0000000000..2571cc4b2c--- /dev/null+++ b/libs/python/cua-sandbox/cua_sandbox/transport/computer_server.py@@ -0,0 +1,53 @@+"""Shared response handling for computer-server HTTP transports."""++from __future__ import annotations++import base64+import json+from typing import Any, Dict+++def parse_command_response(text: str) -> Dict[str, Any]:+ """Extract and validate the first JSON data frame from an SSE response."""+ for line in text.splitlines():+ if not line.startswith("data: "):+ continue+ payload = json.loads(line[6:])+ if isinstance(payload, dict) and not payload.get("success", True):+ if "error" in payload:+ raise RuntimeError(f"Remote error: {payload['error']}")+ parts = []+ return_code = payload.get("return_code")+ if return_code is not None:+ parts.append(f"return_code={return_code}")+ stderr = (payload.get("stderr") or "").strip()+ if stderr:+ parts.append(f"stderr={stderr!r}")+ stdout = (payload.get("stdout") or "").strip()+ if stdout and not stderr:+ parts.append(f"stdout={stdout!r}")+ detail = ", ".join(parts) or "no detail"+ raise RuntimeError(f"Remote error: {detail}")+ return payload+ raise RuntimeError(f"No SSE data frame in response: {text[:200]}")+++def decode_screenshot_response(payload: Dict[str, Any]) -> bytes:+ """Decode computer-server's accepted screenshot response shapes."""+ encoded = payload.get("image_data", payload.get("base64_image", payload.get("result", "")))+ if isinstance(encoded, dict):+ encoded = encoded.get("image_data", encoded.get("base64_image", encoded.get("base64", "")))+ return base64.b64decode(encoded)+++def normalize_screen_size(payload: Dict[str, Any]) -> Dict[str, int]:+ """Normalize nested computer-server screen-size response shapes."""+ data: Any = payload+ if isinstance(data, dict):+ data = data.get("size", data.get("result", data))+ if isinstance(data, dict):+ width = data.get("width") or data.get("screen_width") or data.get("w")+ height = data.get("height") or data.get("screen_height") or data.get("h")+ if width is not None and height is not None:+ return {"width": int(width), "height": int(height)}+ raise KeyError(f"Cannot extract screen size from response: {payload}")diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/cyclops_http_client.py b/libs/python/cua-sandbox/cua_sandbox/transport/cyclops_http_client.pynew file mode 100644index 0000000000..f3c6de6c6e--- /dev/null+++ b/libs/python/cua-sandbox/cua_sandbox/transport/cyclops_http_client.py@@ -0,0 +1,36 @@+"""httpx bridge for the generated Cyclops SDK callback interface."""++from __future__ import annotations++import httpx+from cyclops_sdk import HttpClient, HttpError, HttpHeader, HttpRequest, HttpResponse+++class CyclopsHttpClient(HttpClient):+ """Execute SDK requests with one shared async httpx client."""++ def __init__(self, client: httpx.AsyncClient | None = None) -> None:+ self._client = client or httpx.AsyncClient(timeout=30.0)+ self._owns_client = client is None++ async def execute(self, request: HttpRequest) -> HttpResponse:+ try:+ response = await self._client.request(+ request.method,+ request.url,+ headers={header.name: header.value for header in request.headers},+ content=request.body,+ )+ except httpx.TransportError as error:+ raise HttpError.Transport(str(error)) from error+ return HttpResponse(+ status=response.status_code,+ headers=[+ HttpHeader(name=name, value=value) for name, value in response.headers.multi_items()+ ],+ body=response.content,+ )++ async def aclose(self) -> None:+ if self._owns_client:+ await self._client.aclose()diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/fleet.py b/libs/python/cua-sandbox/cua_sandbox/transport/fleet.pynew file mode 100644index 0000000000..e6a955d7c7--- /dev/null+++ b/libs/python/cua-sandbox/cua_sandbox/transport/fleet.py@@ -0,0 +1,137 @@+"""Computer-server transport routed through Cyclops named services."""++from __future__ import annotations++import asyncio+import json+from typing import Any, Dict, Optional++import httpx+from cua_sandbox.transport.base import Transport+from cua_sandbox.transport.computer_server import (+ decode_screenshot_response,+ normalize_screen_size,+ parse_command_response,+)+from cyclops_sdk import HttpHeader, HttpRequest++_CMD_MAX_RETRIES = 3+_CMD_RETRY_BACKOFF_S = 0.5+++class FleetTransport(Transport):+ """Route computer-server requests through ``CyclopsClient.service_request``."""++ def __init__(+ self,+ *,+ sdk: Any,+ bound: Any,+ service_name: str = "api",+ timeout: float = 30.0,+ **_: Any,+ ) -> None:+ self._sdk = sdk+ self._bound = bound+ self._service_name = service_name+ self._timeout = timeout+ self._connected = False++ async def connect(self) -> None:+ if self._service_name not in self._bound.services:+ raise ValueError(f"Fleet sandbox does not expose service {self._service_name!r}")+ self._connected = True++ async def disconnect(self) -> None:+ self._connected = False++ async def _request(self, method: str, path: str, *, json_body: Any = None) -> httpx.Response:+ assert self._connected, "Transport not connected"+ body = None if json_body is None else json.dumps(json_body).encode()+ headers = (+ [] if body is None else [HttpHeader(name="content-type", value="application/json")]+ )+ result = await self._sdk.service_request(+ self._bound,+ self._service_name,+ path,+ HttpRequest(+ method=method, url=f"https://service.invalid{path}", headers=headers, body=body+ ),+ )+ request = httpx.Request(method, f"https://service.invalid{path}")+ return httpx.Response(+ result.status,+ headers={header.name: header.value for header in result.headers},+ content=result.body,+ request=request,+ )++ async def _cmd(self, command: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:+ body: Dict[str, Any] = {"command": command}+ if params:+ body["params"] = params+ response = None+ for attempt in range(_CMD_MAX_RETRIES):+ response = await self._request("POST", "/cmd", json_body=body)+ if response.status_code < 500 or attempt == _CMD_MAX_RETRIES - 1:+ break+ await asyncio.sleep(_CMD_RETRY_BACKOFF_S * (2**attempt))+ assert response is not None+ response.raise_for_status()+ return parse_command_response(response.text)++ async def send(self, action: str, **params: Any) -> Any:+ result = await self._cmd(action, params if params else None)+ return result.get("result", result)++ async def screenshot(self, format: str = "png", quality: int = 95) -> bytes:+ params = None if format == "png" else {"format": format, "quality": quality}+ return decode_screenshot_response(await self._cmd("screenshot", params))++ async def get_screen_size(self) -> Dict[str, int]:+ return normalize_screen_size(await self._cmd("get_screen_size"))++ async def get_environment(self) -> str:+ try:+ response = await self._request("GET", "/status")+ response.raise_for_status()+ payload = response.json()+ return payload.get("os_type", payload.get("platform", "linux"))+ except Exception:+ return "linux"++ async def pty_create(+ self,+ command: Optional[str] = None,+ cols: int = 120,+ rows: int = 40,+ cwd: Optional[str] = None,+ envs: Optional[Dict[str, str]] = None,+ ) -> Dict[str, Any]:+ body: Dict[str, Any] = {"cols": cols, "rows": rows}+ if command is not None:+ body["command"] = command+ if cwd is not None:+ body["cwd"] = cwd+ if envs is not None:+ body["envs"] = envs+ response = await self._request("POST", "/pty", json_body=body)+ response.raise_for_status()+ return response.json()++ async def pty_send(self, pid: int, data: str) -> None:+ response = await self._request("POST", f"/pty/{pid}/stdin", json_body={"data": data})+ response.raise_for_status()++ async def pty_kill(self, pid: int) -> bool:+ response = await self._request("DELETE", f"/pty/{pid}")+ response.raise_for_status()+ return bool(response.json().get("killed", True))++ async def pty_info(self, pid: int) -> Optional[Dict[str, Any]]:+ response = await self._request("GET", f"/pty/{pid}")+ if response.status_code == 404:+ return None+ response.raise_for_status()+ return response.json()diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/fleet_cloud.py b/libs/python/cua-sandbox/cua_sandbox/transport/fleet_cloud.pynew file mode 100644index 0000000000..633d85cba3--- /dev/null+++ b/libs/python/cua-sandbox/cua_sandbox/transport/fleet_cloud.py@@ -0,0 +1,387 @@+"""Fleet-backed implementation of the public cloud sandbox transport."""++from __future__ import annotations++import asyncio+import json+import logging+from typing import TYPE_CHECKING, Any, Optional+from urllib.parse import urlparse++from cua_sandbox._config import (+ get_client_id,+ get_client_secret,+ get_fleet_base_url,+ get_token_url,+)+from cua_sandbox.image import Image+from cua_sandbox.transport.cyclops_http_client import CyclopsHttpClient+from cua_sandbox.transport.fleet import FleetTransport+from cyclops_sdk import (+ ClaimSpec,+ CreateClaimRequest,+ CreatePoolRequest,+ CyclopsClient,+ CyclopsConfiguration,+ CyclopsCredentials,+ HttpRequest,+ PoolSpec,+ PoolTemplate,+ PreservedJson,+ SandboxService,+ SandboxTemplateRef,+ ServiceProtocol,+)++if TYPE_CHECKING:+ from cua_sandbox.interfaces.tunnel import TunnelInfo++logger = logging.getLogger(__name__)+++class _FleetClient:+ """Thin async facade over the generated Cyclops SDK."""++ def __init__(self) -> None:+ client_id = get_client_id()+ client_secret = get_client_secret()+ if not client_id or not client_secret:+ raise ValueError(+ "Fleet cloud sandboxes require CUA_CLIENT_ID and CUA_CLIENT_SECRET, "+ "or cua.configure(client_id=..., client_secret=...)."+ )+ self._base_url = get_fleet_base_url().rstrip("/")+ self._http_client = CyclopsHttpClient()+ configuration = CyclopsConfiguration(+ base_url=self._base_url,+ token_url=get_token_url(),+ credentials=CyclopsCredentials(client_id, client_secret),+ pool_poll_interval_ms=2000,+ pool_poll_limit=300,+ claim_poll_interval_ms=2000,+ claim_poll_limit=300,+ )+ self._client = CyclopsClient.connect(configuration, self._http_client)++ async def close(self) -> None:+ await self._http_client.aclose()++ async def create_pool(self, request: CreatePoolRequest) -> Any:+ return await self._client.create_pool(request)++ async def create_claim(self, request: CreateClaimRequest) -> Any:+ return await self._client.create_claim(request)++ async def wait_pool(self, pool: Any, timeout: float = 900.0, poll_interval: float = 5.0) -> Any:+ deadline = asyncio.get_running_loop().time() + timeout+ while True:+ pools = await self._client.list_pools(pool.metadata.namespace)+ for current_pool in pools:+ if current_pool.metadata.name != pool.metadata.name:+ continue+ if current_pool.status and (current_pool.status.available_count or 0) >= 1:+ return current_pool+ break+ if asyncio.get_running_loop().time() >= deadline:+ raise TimeoutError(+ f"Timed out waiting for Fleet pool {pool.metadata.name!r} to warm up"+ )+ await asyncio.sleep(poll_interval)++ async def wait_claim(self, claim: Any) -> Any:+ return await self._client.wait_claim(claim)++ async def delete_claim(self, claim: Any) -> None:+ await self._client.delete_claim(claim)++ async def delete_pool(self, pool: Any) -> None:+ await self._client.delete_pool(pool)++ async def service_request(+ self, sandbox: Any, service: str, path: str, request: HttpRequest+ ) -> Any:+ return await self._client.service_request(sandbox, service, path, request)++ async def get_pool(self, name: str) -> Any:+ for pool in await self.list_pools():+ if pool.metadata.name == name:+ return pool+ raise LookupError(f"Fleet pool {name!r} was not found")++ async def get_claim(self, pool: Any) -> Any:+ expected = f"{pool.metadata.name}-claim"+ for claim in await self._client.list_claims(pool.metadata.namespace):+ if claim.metadata.name == expected:+ return claim+ raise LookupError(f"Fleet claim {expected!r} was not found")++ async def list_pools(self) -> list[Any]:+ response = await self._http_client.execute(+ HttpRequest(method="GET", url=f"{self._base_url}/api/namespaces", headers=[], body=None)+ )+ if not 200 <= response.status < 300:+ raise RuntimeError(f"Fleet namespace listing failed with HTTP {response.status}")+ payload = json.loads(response.body)+ items = payload if isinstance(payload, list) else payload.get("items", [])+ namespaces = [+ (+ item+ if isinstance(item, str)+ else item.get("name") or item.get("metadata", {}).get("name")+ )+ for item in items+ ]+ pools = await asyncio.gather(+ *(self._client.list_pools(namespace) for namespace in namespaces if namespace)+ )+ return [pool for namespace_pools in pools for pool in namespace_pools]++ async def set_pool_replicas(self, pool: Any, replicas: int) -> Any:+ pool.spec.replicas = replicas+ return await self._client.update_pool(pool)++ async def wait_service_ready(+ self, sandbox: Any, service: str, time_to_start: Optional[float] = None+ ) -> None:+ timeout = time_to_start if time_to_start is not None else 600.0+ deadline = asyncio.get_running_loop().time() + timeout+ while True:+ response = await self.service_request(+ sandbox,+ service,+ "/status",+ HttpRequest(+ method="GET", url="https://service.invalid/status", headers=[], body=None+ ),+ )+ if 200 <= response.status < 500:+ return+ if asyncio.get_running_loop().time() >= deadline:+ raise TimeoutError(+ f"Fleet service {service!r} did not become ready within {timeout} seconds"+ )+ await asyncio.sleep(2)++ def service_url(self, sandbox: Any, service: str) -> str:+ if service not in sandbox.services:+ raise ValueError(f"Fleet sandbox does not expose service {service!r}")+ return f"{self._base_url}/api/svc/{sandbox.namespace}/{sandbox.name}-{service}/"+++class FleetCloudTransport(FleetTransport):+ """Provision and manage registry-image sandboxes through Fleet."""++ def __init__(+ self,+ *,+ image: Optional[Image],+ name: str,+ cpu: Optional[int] = None,+ memory_mb: Optional[int] = None,+ disk_gb: Optional[int] = None,+ region: str = "us-east-1",+ time_to_start: Optional[float] = None,+ request_timeout: Optional[float] = None,+ ) -> None:+ if disk_gb is not None:+ raise ValueError("disk_gb is not supported by the Fleet cloud transport")+ if region != "us-east-1":+ raise ValueError("Fleet cloud sandboxes currently support only region='us-east-1'")+ self._image = image+ self._name = name+ self._cpu = cpu+ self._memory_mb = memory_mb+ self._time_to_start = time_to_start if time_to_start is not None else 600.0+ self._request_timeout = request_timeout or 30.0+ self._provisioned = False+ self._owns_resources = image is not None+ self._pool: Any = None+ self._claim: Any = None+ self._sdk: Any = None++ @property+ def name(self) -> str:+ return self._name++ async def connect(self) -> None:+ if not self._provisioned:+ if self._sdk is None:+ self._sdk = _FleetClient()+ try:+ if self._pool is None:+ if self._image is None:+ self._pool = await self._sdk.get_pool(self._name)+ else:+ self._validate_image(self._image)+ self._pool = await self._sdk.create_pool(self._pool_request())+ self._pool = await self._sdk.wait_pool(self._pool)+ if self._claim is None:+ if self._image is None:+ self._claim = await self._sdk.get_claim(self._pool)+ else:+ self._claim = await self._sdk.create_claim(+ CreateClaimRequest(+ pool=self._pool,+ spec=ClaimSpec(+ sandbox_template_ref=SandboxTemplateRef(+ name=self._pool.metadata.name+ ),+ warmpool=None,+ bind_deadline=600,+ lifecycle=None,+ ),+ )+ )+ bound = await self._sdk.wait_claim(self._claim)+ await self._sdk.wait_service_ready(bound, "server", self._time_to_start)+ except BaseException as provisioning_error:+ try:+ if self._owns_resources:+ await self._cleanup_resources()+ except BaseException as cleanup_error:+ logger.warning(+ "Failed to clean up Fleet sandbox %r: %s", self._name, cleanup_error+ )+ raise provisioning_error from cleanup_error+ raise+ FleetTransport.__init__(+ self,+ sdk=self._sdk,+ bound=bound,+ service_name="server",+ timeout=self._request_timeout,+ )+ self._provisioned = True+ await FleetTransport.connect(self)++ async def create_snapshot(self, **_: Any) -> dict[str, Any]:+ raise NotImplementedError("Snapshots are not supported by the Fleet cloud transport")++ async def forward_tunnel(self, sandbox_port: int | str) -> "TunnelInfo":+ if not isinstance(sandbox_port, int):+ raise ValueError("Fleet services can only expose numeric TCP ports")+ if not self._provisioned:+ raise ValueError("Transport not connected")+ service = "server" if sandbox_port == 8000 else f"port-{sandbox_port}"+ from cua_sandbox.interfaces.tunnel import TunnelInfo++ endpoint = self._sdk.service_url(self._bound, service)+ parsed = urlparse(endpoint)+ return TunnelInfo(+ parsed.hostname or "",+ parsed.port or (443 if parsed.scheme == "https" else 80),+ sandbox_port,+ url=endpoint,+ )++ async def delete_vm(self) -> None:+ await self._cleanup_resources()++ async def _cleanup_resources(self) -> None:+ if self._claim is not None:+ await self._sdk.delete_claim(self._claim)+ self._claim = None+ if self._pool is not None:+ await self._sdk.delete_pool(self._pool)+ self._pool = None+ self._provisioned = False++ @classmethod+ async def list_sandboxes(cls) -> list[Any]:+ sdk = _FleetClient()+ try:+ return await sdk.list_pools()+ finally:+ await sdk.close()++ @classmethod+ async def get_sandbox_info(cls, name: str) -> Any:+ sdk = _FleetClient()+ try:+ return await sdk.get_pool(name)+ finally:+ await sdk.close()++ @classmethod+ async def suspend_sandbox(cls, name: str) -> None:+ sdk = _FleetClient()+ try:+ await sdk.set_pool_replicas(await sdk.get_pool(name), 0)+ finally:+ await sdk.close()++ @classmethod+ async def resume_sandbox(cls, name: str, time_to_start: Optional[float] = None) -> None:+ del time_to_start+ sdk = _FleetClient()+ try:+ await sdk.set_pool_replicas(await sdk.get_pool(name), 1)+ finally:+ await sdk.close()++ @classmethod+ async def restart_sandbox(cls, name: str, time_to_start: Optional[float] = None) -> None:+ await cls.suspend_sandbox(name)+ await cls.resume_sandbox(name, time_to_start)++ @classmethod+ async def delete_sandbox(cls, name: str) -> None:+ sdk = _FleetClient()+ try:+ pool = await sdk.get_pool(name)+ await sdk.delete_claim(await sdk.get_claim(pool))+ await sdk.delete_pool(pool)+ finally:+ await sdk.close()++ def _pool_request(self) -> CreatePoolRequest:+ assert self._image is not None+ services = [SandboxService(name="server", target_port=8000, protocol=ServiceProtocol.TCP)]+ services.extend(+ SandboxService(name=f"port-{port}", target_port=port, protocol=ServiceProtocol.TCP)+ for port in self._image._ports+ if port != 8000+ )+ return CreatePoolRequest(+ namespace=self._name,+ spec=PoolSpec(+ replicas=1,+ services=services,+ template=PoolTemplate(+ runtime=None,+ runtime_class_name=None,+ node_selector=None,+ tolerations=None,+ command=None,+ container_disk_image=self._image._registry,+ image_pull_secret="ecr-credentials",+ cpu_cores=self._cpu,+ memory=None if self._memory_mb is None else f"{self._memory_mb}Mi",+ firmware=None,+ probes=PreservedJson.from_json(+ json.dumps({"readinessProbe": {"tcpSocket": {"port": 8000}}})+ ),+ oidc=None,+ ),+ autoscaling=None,+ ),+ )++ @staticmethod+ def _service_names(pool: Any) -> list[str]:+ return [service.name for service in pool.spec.services or []] or ["server"]++ @staticmethod+ def _validate_image(image: Image) -> None:+ if not image._registry:+ raise ValueError("Fleet cloud sandboxes require Image.from_registry(...)")+ if (+ image._layers+ or image._env+ or image._files+ or image._snapshot_source+ or image._disk_path+ ):+ raise ValueError(+ "Fleet cloud supports registry images with optional exposed services only"+ )diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/http.py b/libs/python/cua-sandbox/cua_sandbox/transport/http.pyindex 3d1ce479f9..1489ca284b 100644--- a/libs/python/cua-sandbox/cua_sandbox/transport/http.py+++ b/libs/python/cua-sandbox/cua_sandbox/transport/http.py@@ -7,13 +7,16 @@ and returns an SSE stream with a single ``data: {...}`` frame containing the resfrom __future__ import annotationsimport asyncio-import base64-import jsonimport loggingfrom typing import Any, Dict, Optionalimport httpxfrom cua_sandbox.transport.base import Transport+from cua_sandbox.transport.computer_server import (+ decode_screenshot_response,+ normalize_screen_size,+ parse_command_response,+)logger = logging.getLogger(__name__)@@ -112,55 +115,7 @@ class HTTPTransport(Transport):resp.raise_for_status()return self._parse_sse(resp.text)- @staticmethod- def _parse_sse(text: str) -> Dict[str, Any]:- """Extract the first ``data: {...}`` frame from an SSE response.-- The server returns one of two failure shapes when ``success`` is- false:-- 1. Generic handler error — ``{"success": false, "error": "<msg>"}``- 2. Shell-command shape — ``{"success": false, "stdout": "...",- "stderr": "...", "return_code": <n>}`` (no ``error`` key)-- The old code stringified ``payload.get('error', 'unknown')`` for- both shapes, which turned every shell-command failure into- ``Remote error: unknown`` and hid the actual ``stderr`` + exit- code. That masking made ``Command timed out after 10s``,- ``UI hierchary dump failed``, and similar concrete failures- indistinguishable from a genuine internal error — the common- pattern where ``await sb.shell.run(cmd)`` returned non-zero- became a debugging dead end.-- This rewrite preserves the ``error``-key path verbatim and falls- back to a composite ``return_code=...`` / ``stderr=...`` /- ``stdout=...`` string when no ``error`` key is present.- """- for line in text.splitlines():- if line.startswith("data: "):- payload = json.loads(line[6:])- if isinstance(payload, dict) and not payload.get("success", True):- if "error" in payload:- raise RuntimeError(f"Remote error: {payload['error']}")- # Shell-command shape: surface return_code/stderr/stdout.- parts = []- rc = payload.get("return_code")- if rc is not None:- parts.append(f"return_code={rc}")- stderr = (payload.get("stderr") or "").strip()- if stderr:- parts.append(f"stderr={stderr!r}")- stdout = (payload.get("stdout") or "").strip()- if stdout and not stderr:- # Only surface stdout when there's nothing on- # stderr — saves bloating the message for noisy- # successful-output commands that happened to- # return non-zero.- parts.append(f"stdout={stdout!r}")- detail = ", ".join(parts) or "no detail"- raise RuntimeError(f"Remote error: {detail}")- return payload- raise RuntimeError(f"No SSE data frame in response: {text[:200]}")+ _parse_sse = staticmethod(parse_command_response)async def send(self, action: str, **params: Any) -> Any:result = await self._cmd(action, params if params else None)@@ -169,25 +124,11 @@ class HTTPTransport(Transport):async def screenshot(self, format: str = "png", quality: int = 95) -> bytes:params = None if format == "png" else {"format": format, "quality": quality}result = await self._cmd("screenshot", params)- # computer-server returns {"success": true, "image_data": "..."}- b64 = result.get("image_data", result.get("base64_image", result.get("result", "")))- if isinstance(b64, dict):- b64 = b64.get("image_data", b64.get("base64_image", b64.get("base64", "")))- return base64.b64decode(b64)+ return decode_screenshot_response(result)async def get_screen_size(self) -> Dict[str, int]:result = await self._cmd("get_screen_size")- # Flatten nested responses and normalize key names- data = result- if isinstance(data, dict):- # Unwrap nested: {"result": {...}}, {"size": {...}}- data = data.get("size", data.get("result", data))- if isinstance(data, dict):- w = data.get("width") or data.get("screen_width") or data.get("w")- h = data.get("height") or data.get("screen_height") or data.get("h")- if w is not None and h is not None:- return {"width": int(w), "height": int(h)}- raise KeyError(f"Cannot extract screen size from response: {result}")+ return normalize_screen_size(result)# ── PTY over dedicated /pty_* routes ────────────────────────────────async def pty_create(diff --git a/libs/python/cua-sandbox/hatch_build.py b/libs/python/cua-sandbox/hatch_build.pynew file mode 100644index 0000000000..cd63132064--- /dev/null+++ b/libs/python/cua-sandbox/hatch_build.py@@ -0,0 +1,40 @@+import platform+import subprocess+from pathlib import Path++from hatchling.builders.hooks.plugin.interface import BuildHookInterface+++class CustomBuildHook(BuildHookInterface):+ repository_root = Path(__file__).resolve().parents[3]+ native_target_dir = repository_root / "target" / "cyclops-sdk-bindings-native"++ def initialize(self, version, build_data):+ mirror_root = self.repository_root / "libs" / "fleet"+ subprocess.run(+ [+ "cargo",+ "build",+ "--locked",+ "--manifest-path",+ str(mirror_root / "Cargo.toml"),+ "--package",+ "cyclops-sdk",+ "--target-dir",+ str(self.native_target_dir),+ ],+ check=True,+ )++ suffix = {"Darwin": ".dylib", "Linux": ".so"}.get(platform.system())+ if suffix is None:+ raise RuntimeError(f"unsupported host for Cyclops SDK bindings: {platform.system()}")++ native_library = self.native_target_dir / "debug" / f"libcyclops_sdk{suffix}"+ if not native_library.is_file():+ raise RuntimeError(f"native Cyclops SDK library was not built: {native_library}")++ build_data["infer_tag"] = True+ force_include = build_data.setdefault("force_include", {})+ force_include[str(mirror_root / "sdk-bindings" / "python" / "cyclops_sdk")] = "cyclops_sdk"+ force_include[str(native_library)] = f"cyclops_sdk/{native_library.name}"diff --git a/libs/python/cua-sandbox/pyproject.toml b/libs/python/cua-sandbox/pyproject.tomlindex 27c5e2b6b0..603685db7e 100644--- a/libs/python/cua-sandbox/pyproject.toml+++ b/libs/python/cua-sandbox/pyproject.toml@@ -18,7 +18,6 @@ classifiers = ["Development Status :: 3 - Alpha","Intended Audience :: Developers","License :: OSI Approved :: MIT License",- "Operating System :: OS Independent","Programming Language :: Python :: 3","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12",@@ -96,3 +95,5 @@ dev = [[tool.uv.sources]cua-agent = { path = "../agent", editable = true }++[tool.hatch.build.hooks.custom]diff --git a/libs/python/cua-sandbox/tests/test_computer_server_transport.py b/libs/python/cua-sandbox/tests/test_computer_server_transport.pynew file mode 100644index 0000000000..b14cdcb14b--- /dev/null+++ b/libs/python/cua-sandbox/tests/test_computer_server_transport.py@@ -0,0 +1,46 @@+import base64++import pytest+from cua_sandbox.transport.computer_server import (+ decode_screenshot_response,+ normalize_screen_size,+ parse_command_response,+)+++def test_parse_command_response_returns_sse_payload():+ result = parse_command_response(+ 'event: result\ndata: {"success": true, "result": {"ok": 1}}\n\n'+ )++ assert result == {"success": True, "result": {"ok": 1}}+++def test_parse_command_response_raises_remote_error():+ with pytest.raises(RuntimeError, match="return_code=2"):+ parse_command_response(+ 'data: {"success": false, "return_code": 2, "stderr": "bad command"}\n\n'+ )+++def test_parse_command_response_requires_data_frame():+ with pytest.raises(RuntimeError, match="No SSE data frame"):+ parse_command_response("event: keepalive\n\n")+++def test_decode_screenshot_response_accepts_nested_payload():+ encoded = base64.b64encode(b"png-data").decode()++ assert decode_screenshot_response({"result": {"image_data": encoded}}) == b"png-data"+++def test_normalize_screen_size_accepts_nested_aliases():+ assert normalize_screen_size({"result": {"screen_width": "1280", "screen_height": 720}}) == {+ "width": 1280,+ "height": 720,+ }+++def test_normalize_screen_size_rejects_unknown_shape():+ with pytest.raises(KeyError, match="Cannot extract screen size"):+ normalize_screen_size({"result": {"unexpected": True}})diff --git a/libs/python/cua-sandbox/tests/test_config.py b/libs/python/cua-sandbox/tests/test_config.pyindex 5dc97fb6ac..fd16db5c3e 100644--- a/libs/python/cua-sandbox/tests/test_config.py+++ b/libs/python/cua-sandbox/tests/test_config.py@@ -1,12 +1,38 @@"""Unit tests for config and auth modules."""-from cua_sandbox._config import _global_config, configure, get_api_key, get_base_url+from cua_sandbox._config import (+ _global_config,+ configure,+ get_api_key,+ get_base_url,+ get_client_id,+ get_client_secret,+ get_fleet_base_url,+ get_token_url,+)class TestConfig:def setup_method(self):_global_config.api_key = None- _global_config.base_url = "https://api.trycua.com"+ _global_config.base_url = "https://api.cua.ai"+ _global_config.fleet_base_url = "https://run.cua.ai"+ _global_config.token_url = (+ "https://auth.cua.ai/realms/cyclops-cs/protocol/openid-connect/token"+ )+ _global_config.client_id = None+ _global_config.client_secret = None++ def test_configure_client_credentials_uses_fleet_defaults(self):+ configure(client_id="client-id", client_secret="client-secret")++ assert get_client_id() == "client-id"+ assert get_client_secret() == "client-secret"+ assert get_base_url() == "https://api.cua.ai"+ assert get_fleet_base_url() == "https://run.cua.ai"+ assert (+ get_token_url() == "https://auth.cua.ai/realms/cyclops-cs/protocol/openid-connect/token"+ )def test_configure_api_key(self):configure(api_key="sk-test-123")diff --git a/libs/python/cua-sandbox/tests/test_cyclops_sdk_packaging.py b/libs/python/cua-sandbox/tests/test_cyclops_sdk_packaging.pynew file mode 100644index 0000000000..0851e7dc02--- /dev/null+++ b/libs/python/cua-sandbox/tests/test_cyclops_sdk_packaging.py@@ -0,0 +1,76 @@+import importlib.util+import tempfile+import unittest+from pathlib import Path+from unittest.mock import patch++PROJECT_ROOT = Path(__file__).resolve().parents[1]+BUILD_HOOK_PATH = PROJECT_ROOT / "hatch_build.py"+++def load_build_hook():+ spec = importlib.util.spec_from_file_location("cua_sandbox_hatch_build", BUILD_HOOK_PATH)+ assert spec and spec.loader+ module = importlib.util.module_from_spec(spec)+ spec.loader.exec_module(module)+ return module.CustomBuildHook+++class CyclopsSdkPackagingTests(unittest.TestCase):+ def test_build_hook_stages_mirrored_cyclops_sdk(self):+ CustomBuildHook = load_build_hook()+ with tempfile.TemporaryDirectory() as temporary_directory:+ temporary_root = Path(temporary_directory)+ repository_root = temporary_root / "repository"+ mirror_root = repository_root / "libs" / "fleet"+ binding_root = mirror_root / "sdk-bindings" / "python" / "cyclops_sdk"+ binding_root.mkdir(parents=True)+ native_library = temporary_root / "native" / "debug" / "libcyclops_sdk.so"+ calls = []++ def fake_run(command, check):+ calls.append((command, check))+ native_library.parent.mkdir(parents=True)+ native_library.touch()++ with (+ patch("platform.system", return_value="Linux"),+ patch("subprocess.run", fake_run),+ patch.object(CustomBuildHook, "repository_root", repository_root),+ patch.object(CustomBuildHook, "native_target_dir", temporary_root / "native"),+ ):+ hook = object.__new__(CustomBuildHook)+ build_data = {"force_include": {}}+ hook.initialize("0.1.0", build_data)++ self.assertEqual(+ calls,+ [+ (+ [+ "cargo",+ "build",+ "--locked",+ "--manifest-path",+ str(mirror_root / "Cargo.toml"),+ "--package",+ "cyclops-sdk",+ "--target-dir",+ str(temporary_root / "native"),+ ],+ True,+ )+ ],+ )+ self.assertEqual(+ build_data["force_include"],+ {+ str(binding_root): "cyclops_sdk",+ str(native_library): "cyclops_sdk/libcyclops_sdk.so",+ },+ )+ self.assertTrue(build_data["infer_tag"])+++if __name__ == "__main__":+ unittest.main()diff --git a/libs/python/cua-sandbox/tests/test_fleet_cloud_client.py b/libs/python/cua-sandbox/tests/test_fleet_cloud_client.pynew file mode 100644index 0000000000..fced7e9be0--- /dev/null+++ b/libs/python/cua-sandbox/tests/test_fleet_cloud_client.py@@ -0,0 +1,52 @@+import pytest+from cua_sandbox.transport.fleet_cloud import _FleetClient+++async def test_list_pools_enumerates_namespaces(monkeypatch):+ client = _FleetClient.__new__(_FleetClient)++ class Http:+ async def execute(self, request):+ assert request.url.endswith("/api/namespaces")+ return type(+ "Response", (), {"status": 200, "body": b'{"items":[{"name":"one"},"two"]}'}+ )()++ class SDK:+ async def list_pools(self, namespace):+ return [namespace]++ client._base_url = "https://fleet.example"+ client._http_client = Http()+ client._client = SDK()+ assert await client.list_pools() == ["one", "two"]+++async def test_service_request_delegates_to_generated_client():+ client = _FleetClient.__new__(_FleetClient)+ calls = []++ class SDK:+ async def service_request(self, *args):+ calls.append(args)+ return "response"++ client._client = SDK()+ assert await client.service_request("sandbox", "server", "/status", "request") == "response"+ assert calls == [("sandbox", "server", "/status", "request")]+++async def test_pool_lookup_matches_sdk_resources():+ client = _FleetClient.__new__(_FleetClient)+ pool = type("Pool", (), {"metadata": type("Metadata", (), {"name": "demo"})()})()++ async def list_pools():+ return [pool]++ client.list_pools = list_pools+ assert await client.get_pool("demo") is pool+ with pytest.raises(LookupError):+ await client.get_pool("missing")diff --git a/libs/python/cua-sandbox/tests/test_fleet_cloud_transport.py b/libs/python/cua-sandbox/tests/test_fleet_cloud_transport.pynew file mode 100644index 0000000000..f6f79486fa--- /dev/null+++ b/libs/python/cua-sandbox/tests/test_fleet_cloud_transport.py@@ -0,0 +1,75 @@+import pytest+from cua_sandbox import Image+from cua_sandbox.transport.fleet_cloud import FleetCloudTransport+from cyclops_sdk import Sandbox+++def test_registry_image_becomes_typed_pool_request():+ request = FleetCloudTransport(+ image=Image.from_registry("registry.example/workspace@sha256:abc").expose(3000),+ name="demo",+ cpu=4,+ memory_mb=8192,+ )._pool_request()+ assert request.namespace == "demo"+ assert request.spec.template.container_disk_image == "registry.example/workspace@sha256:abc"+ assert request.spec.template.cpu_cores == 4+ assert request.spec.template.memory == "8192Mi"+ assert [(service.name, service.target_port) for service in request.spec.services] == [+ ("server", 8000),+ ("port-3000", 3000),+ ]+++ "image", [Image.linux(), Image.from_registry("example:latest").apt_install("curl")]+)+def test_rejects_unsupported_images(image):+ with pytest.raises(ValueError):+ FleetCloudTransport._validate_image(image)+++async def test_cleanup_stops_after_claim_failure():+ transport = FleetCloudTransport(image=Image.from_registry("example:latest"), name="demo")+ calls = []++ class Client:+ async def delete_claim(self, claim):+ calls.append(("claim", claim))+ raise RuntimeError("claim delete failed")++ async def delete_pool(self, pool):+ calls.append(("pool", pool))++ transport._sdk = Client()+ transport._claim = "claim"+ transport._pool = "pool"+ with pytest.raises(RuntimeError, match="claim delete failed"):+ await transport._cleanup_resources()+ assert calls == [("claim", "claim")]+++async def test_forward_tunnel_uses_named_service_url():+ transport = FleetCloudTransport(image=Image.from_registry("example:latest"), name="demo")+ transport._provisioned = True+ transport._bound = Sandbox(+ namespace="demo", claim="claim", name="sandbox", services=["port-3000"]+ )++ class Client:+ def service_url(self, sandbox, service):+ assert service == "port-3000"+ return "https://run.cua.ai/api/svc/demo/sandbox-port-3000/"++ transport._sdk = Client()+ tunnel = await transport.forward_tunnel(3000)+ assert tunnel.url == "https://run.cua.ai/api/svc/demo/sandbox-port-3000/"+++async def test_snapshot_is_unsupported():+ transport = FleetCloudTransport(image=Image.from_registry("example:latest"), name="demo")+ with pytest.raises(NotImplementedError, match="Snapshots"):+ await transport.create_snapshot()diff --git a/libs/python/cua-sandbox/tests/test_fleet_transport.py b/libs/python/cua-sandbox/tests/test_fleet_transport.pynew file mode 100644index 0000000000..c5af869e2b--- /dev/null+++ b/libs/python/cua-sandbox/tests/test_fleet_transport.py@@ -0,0 +1,65 @@+import base64+import json++import pytest+from cua_sandbox.transport.fleet import FleetTransport+from cyclops_sdk import HttpResponse, Sandbox+++class FakeSDK:+ def __init__(self, responses):+ self.responses = list(responses)+ self.calls = []++ async def service_request(self, sandbox, service, path, request):+ self.calls.append((sandbox, service, path, request))+ return self.responses.pop(0)+++def response(status=200, body=b"{}"):+ return HttpResponse(status=status, headers=[], body=body)+++def sandbox():+ return Sandbox(namespace="demo", claim="claim-demo", name="sandbox-demo", services=["api"])+++async def test_service_request_forwards_command_json():+ sdk = FakeSDK([response(body=b'data: {"success":true,"result":"ok"}\n\n')])+ transport = FleetTransport(sdk=sdk, bound=sandbox())+ await transport.connect()++ assert await transport.send("shell.run", timeout=15) == "ok"+ _, service, path, request = sdk.calls[0]+ assert (service, path, request.method) == ("api", "/cmd", "POST")+ assert json.loads(request.body) == {"command": "shell.run", "params": {"timeout": 15}}+++async def test_screenshot_and_pty_use_service_request():+ encoded = base64.b64encode(b"png-data").decode()+ sdk = FakeSDK(+ [+ response(body=f'data: {{"success":true,"image_data":"{encoded}"}}\n\n'.encode()),+ response(body=b'{"pid":42}'),+ response(body=b'{"killed":true}'),+ ]+ )+ transport = FleetTransport(sdk=sdk, bound=sandbox())+ await transport.connect()++ assert await transport.screenshot() == b"png-data"+ assert await transport.pty_create(command="bash") == {"pid": 42}+ assert await transport.pty_kill(42) is True+ assert [call[2] for call in sdk.calls] == ["/cmd", "/pty", "/pty/42"]+++async def test_connect_rejects_missing_service():+ transport = FleetTransport(+ sdk=FakeSDK([]),+ bound=Sandbox(namespace="demo", claim="claim", name="sandbox", services=[]),+ )+ with pytest.raises(ValueError, match="does not expose service"):+ await transport.connect()diff --git a/libs/python/cua-sandbox/tests/test_vm_cleanup.py b/libs/python/cua-sandbox/tests/test_vm_cleanup.pyindex e10a2b1cc9..92a1e86ccd 100644--- a/libs/python/cua-sandbox/tests/test_vm_cleanup.py+++ b/libs/python/cua-sandbox/tests/test_vm_cleanup.py@@ -1,6 +1,6 @@"""Unit tests for VM cleanup on connection failure and destroy() resilience.-These tests mock CloudTransport so they run without a real cloud API.+These tests mock FleetCloudTransport so they run without a real cloud API.They verify that:1. _create() cleans up a provisioned VM when _connect() fails.2. destroy() runs every cleanup step independently — a failure in one@@ -15,7 +15,7 @@ import httpximport pytestfrom cua_sandbox.image import Imagefrom cua_sandbox.sandbox import Sandbox-from cua_sandbox.transport.cloud import CloudTransport+from cua_sandbox.transport.fleet_cloud import FleetCloudTransportpytestmark = pytest.mark.asyncio@@ -25,9 +25,9 @@ pytestmark = pytest.mark.asyncio# ----------------------------------------------------------------------------def _make_cloud_transport(*, name: str = "test-vm") -> CloudTransport:- """Return a CloudTransport with internal state set as if _create_vm() succeeded."""- t = CloudTransport.__new__(CloudTransport)+def _make_cloud_transport(*, name: str = "test-vm") -> FleetCloudTransport:+ """Return a FleetCloudTransport with internal state set as if _create_vm() succeeded."""+ t = FleetCloudTransport.__new__(FleetCloudTransport)t._name = namet._api_key_override = "sk-fake"t._base_url = "https://api.example.com"@@ -41,7 +41,7 @@ def _make_cloud_transport(*, name: str = "test-vm") -> CloudTransport:return t-def _make_sandbox(transport: CloudTransport, **kwargs) -> Sandbox:+def _make_sandbox(transport: FleetCloudTransport, **kwargs) -> Sandbox:"""Return a Sandbox wrapping *transport* without calling _connect()."""return Sandbox(transport,@@ -66,12 +66,12 @@ class TestCreateCleansUpOnConnectFailure:transport.delete_vm = AsyncMock()with patch(- "cua_sandbox.sandbox.CloudTransport",+ "cua_sandbox.sandbox.FleetCloudTransport",return_value=transport,):with pytest.raises(httpx.ReadTimeout):await Sandbox._create(- image=Image.linux("ubuntu", "24.04"),+ image=Image.from_registry("registry.example/workspace:latest"),api_key="sk-fake",telemetry_enabled=False,)@@ -85,12 +85,12 @@ class TestCreateCleansUpOnConnectFailure:transport.delete_vm = AsyncMock()with patch(- "cua_sandbox.sandbox.CloudTransport",+ "cua_sandbox.sandbox.FleetCloudTransport",return_value=transport,):with pytest.raises(RuntimeError, match="unexpected"):await Sandbox._create(- image=Image.linux("ubuntu", "24.04"),+ image=Image.from_registry("registry.example/workspace:latest"),api_key="sk-fake",telemetry_enabled=False,)@@ -104,12 +104,12 @@ class TestCreateCleansUpOnConnectFailure:transport.delete_vm = AsyncMock(side_effect=httpx.ConnectError("api down"))with patch(- "cua_sandbox.sandbox.CloudTransport",+ "cua_sandbox.sandbox.FleetCloudTransport",return_value=transport,):with pytest.raises(TimeoutError, match="poll timeout"):await Sandbox._create(- image=Image.linux("ubuntu", "24.04"),+ image=Image.from_registry("registry.example/workspace:latest"),api_key="sk-fake",telemetry_enabled=False,)@@ -125,12 +125,12 @@ class TestCreateCleansUpOnConnectFailure:transport.delete_vm = AsyncMock()with patch(- "cua_sandbox.sandbox.CloudTransport",+ "cua_sandbox.sandbox.FleetCloudTransport",return_value=transport,):with pytest.raises(ValueError, match="no api key"):await Sandbox._create(- image=Image.linux("ubuntu", "24.04"),+ image=Image.from_registry("registry.example/workspace:latest"),api_key="sk-fake",telemetry_enabled=False,)@@ -144,12 +144,12 @@ class TestCreateCleansUpOnConnectFailure:transport.delete_vm = AsyncMock()with patch(- "cua_sandbox.sandbox.CloudTransport",+ "cua_sandbox.sandbox.FleetCloudTransport",return_value=transport,):with pytest.raises(KeyboardInterrupt):await Sandbox._create(- image=Image.linux("ubuntu", "24.04"),+ image=Image.from_registry("registry.example/workspace:latest"),api_key="sk-fake",telemetry_enabled=False,)@@ -231,14 +231,14 @@ class TestDestroyResilience:transport.delete_vm.assert_awaited_once()async def test_non_cloud_transport_skips_delete_vm(self):- """Non-CloudTransport sandboxes should not call delete_vm."""- transport = AsyncMock() # generic mock, not a CloudTransport instance+ """Non-FleetCloudTransport sandboxes should not call delete_vm."""+ transport = AsyncMock() # generic mock, not a FleetCloudTransport instancesb = Sandbox(transport, name="local-vm", _ephemeral=True, _telemetry_enabled=False)await sb.destroy()transport.disconnect.assert_awaited_once()- # delete_vm should not be called since transport is not CloudTransport+ # delete_vm should not be called since transport is not FleetCloudTransportassert not hasattr(transport, "delete_vm") or not transport.delete_vm.called@@ -259,18 +259,18 @@ class TestEphemeralCleanup:with (patch.object(- CloudTransport,+ FleetCloudTransport,"__init__",lambda self, **kw: None,),patch.object(- CloudTransport,+ FleetCloudTransport,"__new__",lambda cls, **kw: transport,),):async with Sandbox.ephemeral(- Image.linux("ubuntu", "24.04"),+ Image.from_registry("registry.example/workspace:latest"),api_key="sk-fake",telemetry_enabled=False,) as sb:@@ -287,19 +287,19 @@ class TestEphemeralCleanup:with (patch.object(- CloudTransport,+ FleetCloudTransport,"__init__",lambda self, **kw: None,),patch.object(- CloudTransport,+ FleetCloudTransport,"__new__",lambda cls, **kw: transport,),):with pytest.raises(AssertionError):async with Sandbox.ephemeral(- Image.linux("ubuntu", "24.04"),+ Image.from_registry("registry.example/workspace:latest"),api_key="sk-fake",telemetry_enabled=False,) as _sb:@@ -315,19 +315,19 @@ class TestEphemeralCleanup:with (patch.object(- CloudTransport,+ FleetCloudTransport,"__init__",lambda self, **kw: None,),patch.object(- CloudTransport,+ FleetCloudTransport,"__new__",lambda cls, **kw: transport,),):with pytest.raises(httpx.ReadTimeout):async with Sandbox.ephemeral(- Image.linux("ubuntu", "24.04"),+ Image.from_registry("registry.example/workspace:latest"),api_key="sk-fake",telemetry_enabled=False,) as _sb: