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
docs(fleet): pin first tutorial and scope cleanup to its run (#3595)
Francesco Bonacci4c50bbe30a7b
diff --git a/.github/workflows/docs-fleet-first-run-smoke.yml b/.github/workflows/docs-fleet-first-run-smoke.ymlnew file mode 100644index 0000000000..07407647fb--- /dev/null+++ b/.github/workflows/docs-fleet-first-run-smoke.yml@@ -0,0 +1,31 @@+name: "Docs: Fleet first-run smoke"++on:+ pull_request:+ paths:+ - docs/content/docs/tutorials/your-first-cloud-fleet.mdx+ - docs/scripts/tests/test_first_cloud_fleet_tutorial.py+ - .github/workflows/docs-fleet-first-run-smoke.yml+ merge_group:+ workflow_dispatch:++# Public PR code runs only on a disposable GitHub-hosted runner, without secrets.+permissions:+ contents: read++jobs:+ first-run:+ runs-on: ubuntu-24.04+ timeout-minutes: 10+ steps:+ - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4+ with:+ ref: ${{ github.sha }}+ persist-credentials: false+ - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5+ with:+ python-version: "3.13"+ - name: Install the tutorial's published SDK versions+ run: python -m pip install "cua-sandbox==0.4.3" "cua-fleet==0.1.14"+ - name: Test tutorial snippets with mocked Fleet calls+ run: python -m unittest discover -s docs/scripts/tests -p test_first_cloud_fleet_tutorial.py -vdiff --git a/docs/content/docs/tutorials/your-first-cloud-fleet.mdx b/docs/content/docs/tutorials/your-first-cloud-fleet.mdxindex 526c529197..334955b244 100644--- a/docs/content/docs/tutorials/your-first-cloud-fleet.mdx+++ b/docs/content/docs/tutorials/your-first-cloud-fleet.mdx@@ -17,8 +17,8 @@ active desktop as a claim on that pool.<Callout type="warn">A pool with `replicas=1` keeps one cloud sandbox warm until you delete the pool. Cloud resources- can incur usage charges. The script deletes the pool in a `finally` block; the cleanup section- also shows how to delete it after an interrupted run.+ can incur usage charges. The script requests deletion in a `finally` block and sets a one-hour+ pool TTL as a fallback. Keep the local run record until cleanup is confirmed.</Callout>## 1. Authenticate with Fleet@@ -42,17 +42,20 @@ unset FLEETS_TOKENhave a valid Fleet access token, you can set `FLEETS_TOKEN` instead; it takesprecedence over the client credentials and must remain valid through cleanup.-## 2. Choose a unique Fleet name+## 2. Prepare a directory for this run-Pool names are lowercase DNS labels and are globally unique across Cua-accounts. Choose a name that identifies you or your team:+Use a separate directory for the script and its output:```bash-export CUA_POOL_NAME="<unique-lowercase-name>"+mkdir first-cloud-fleet+cd first-cloud-fleet```-If the name belongs to another account, `Pool.apply()` returns-`PoolAccessDeniedError`. Choose another name and run the script again.+The script reserves a new, randomly named namespace before creating its pool.+Reservation refuses an existing name instead of modifying an existing pool.+It saves the namespace name and creation timestamp in `cloud-fleet-run.json`.+Do not edit that record or reuse the namespace for other work: cleanup deletes+the namespace and its resources.## 3. Create the Fleet script@@ -62,37 +65,114 @@ Save the following script as `first_cloud_fleet.py`:# /// script# requires-python = ">=3.11,<3.14"# dependencies = [-# "cua-sandbox",+# "cua-sandbox==0.4.3",+# "cua-fleet==0.1.14",# ]# ///import asyncio+import jsonimport os+import sysfrom pathlib import Path+from uuid import uuid4from cua_sandbox import Image, Pool+from fleet_sdk import (+ CyclopsClient,+ CyclopsConfiguration,+ CyclopsCredentials,+ CyclopsTokenProviderConfiguration,+)IMAGE = ("public.ecr.aws/k5j5w0x5/cua-ubuntu-24.04""@sha256:c1e601dbb748fdc467c663136f7592e308a91a3c19c309b75261544432826a57")+RECORD = Path("cloud-fleet-run.json")-async def main() -> None:- pool_name = os.environ["CUA_POOL_NAME"]- print(f"Provisioning Cloud Fleet: {pool_name}")-- pool = await Pool.apply(- Image.from_registry(IMAGE),- name=pool_name,- replicas=1,- cpu=4,- memory_mb=4096,- services={"server": 8000},+def fleet_client():+ configuration = dict(+ base_url=os.environ.get("CUA_FLEET_BASE_URL", "https://run.cua.ai"),+ pool_poll_interval_ms=2000,+ pool_poll_limit=300,+ claim_poll_interval_ms=2000,+ claim_poll_limit=300,)-+ token = os.environ.get("FLEETS_TOKEN")+ if token:+ return CyclopsClient.connect_with_access_token_and_native_http_client(+ CyclopsTokenProviderConfiguration(**configuration), token+ )+ return CyclopsClient.connect_with_native_http_client(CyclopsConfiguration(+ **configuration,+ token_url=os.environ["CUA_TOKEN_URL"],+ credentials=CyclopsCredentials(+ os.environ["CUA_CLIENT_ID"], os.environ["CUA_CLIENT_SECRET"]+ ),+ ))+++async def find_namespace(client, name):+ # A direct lookup outside an owned namespace can return 403, even when+ # the resource does not exist. Use a successful account inventory instead.+ namespaces = await client.list_namespaces()+ return next((item for item in namespaces if item.name == name), None)+++async def delete_namespace(client, name, created_at):+ current = await find_namespace(client, name)+ if current is None:+ print(f"Namespace no longer in account inventory: {name}")+ return+ if not created_at or current.created_at != created_at:+ raise RuntimeError("Namespace identity changed; refusing cleanup.")+ await client.delete_namespace(name)+ for _ in range(60):+ if await find_namespace(client, name) is None:+ print(f"Namespace no longer in account inventory: {name}")+ return+ await asyncio.sleep(2)+ raise TimeoutError("Namespace is still visible. Retry cleanup after it terminates.")+++async def cleanup():+ record = json.loads(RECORD.read_text())+ if not record.get("created_at"):+ raise RuntimeError(+ "Creation was not confirmed. Check this run's name in Fleet before deleting anything."+ )+ await delete_namespace(fleet_client(), record["name"], record["created_at"])+++async def run():+ pool_name = f"first-fleet-{uuid4().hex}"+ # Exclusive creation prevents overwriting an earlier run's cleanup record.+ with RECORD.open("x") as output:+ json.dump({"name": pool_name, "created_at": None}, output)+ client = fleet_client()+ # Only HTTP 201 confirms reservation. A collision (409) or denied request+ # stops here, without reconciling or deleting another namespace's resources.+ namespace = await client.create_namespace(pool_name)try:+ RECORD.write_text(json.dumps({+ "name": pool_name,+ "created_at": namespace.created_at,+ }))+ if not namespace.created_at:+ raise RuntimeError("Namespace creation timestamp missing; inspect Fleet before cleanup.")+ print(f"Provisioning Cloud Fleet: {pool_name}")+ pool = await Pool.apply(+ Image.from_registry(IMAGE),+ name=pool_name,+ replicas=1,+ cpu=4,+ memory_mb=4096,+ services={"server": 8000},+ ttl_seconds_after_created=3600,+ )async with pool.claim(name="first-claim",service="server",@@ -110,19 +190,26 @@ async def main() -> None:print(f"Screenshot saved to {screenshot.resolve()}")finally:print(f"Deleting Cloud Fleet: {pool_name}")- await pool.delete()+ await delete_namespace(client, pool_name, namespace.created_at)-asyncio.run(main())+if __name__ == "__main__":+ if sys.argv[1:] == ["run"]:+ asyncio.run(run())+ elif sys.argv[1:] == ["cleanup"]:+ asyncio.run(cleanup())+ else:+ raise SystemExit("Usage: first_cloud_fleet.py run|cleanup")```## 4. Run itRun the script from the same directory. `uv` reads the inline metadata and-installs `cua-sandbox` in an isolated environment:+installs `cua-sandbox==0.4.3` and its required Fleet SDK,+`cua-fleet==0.1.14`, in an isolated environment:```bash-uv run first_cloud_fleet.py+uv run first_cloud_fleet.py run```The first run can take several minutes while Fleet provisions the Linux@@ -130,31 +217,53 @@ sandbox. The script prints the sandbox name and Linux kernel information, thenwrites `cloud-fleet.png` in the current directory.When the claim block exits, the SDK releases the claimed sandbox. The `finally`-block then deletes the pool and its template, so the warm cloud capacity does-not remain running.+block requests deletion of the reserved namespace, which includes the pool,+template, and sandbox resources. It polls successful account-inventory responses+until that namespace is absent. It does not interpret a `403` as absence.+If cleanup fails or times out, follow the next section and check the Fleet UI+for this run's resources. A deletion request alone does not prove that all+resources have finished terminating.## Clean up an interrupted runIf the process is killed or loses connectivity after provisioning, the-`finally` block might not reach Fleet. Keep `CUA_POOL_NAME` set and rerun the-same script when connectivity returns:+`finally` block might not reach Fleet. Restore connectivity and valid Fleet+credentials for the same account, then run the deletion-only command from the+same directory:```bash-uv run first_cloud_fleet.py+uv run first_cloud_fleet.py cleanup```-`Pool.apply()` reconciles the existing named pool instead of creating a second-one. The script then uses the Fleet and reaches the same deletion path. Deleting-the pool destroys its sandboxes and their state, so save any files you need-before cleanup.+This command reads `cloud-fleet-run.json`, checks that the recorded namespace+still has the same creation timestamp, and deletes it. It does not call+`Pool.apply()`, claim a sandbox, or repeat the workload. It also handles a run+that reserved a namespace but failed before creating a pool. Keep using the+same account: absence from another account's inventory is not cleanup proof.+The script confirms account-inventory absence, not an independent inspection+of the underlying guest's termination. Save any+remote files you need before cleanup; deletion destroys the sandboxes and+their state.++If the record has no creation timestamp, namespace reservation was not confirmed.+This can happen after a name collision, denied request, or interrupted response. The+command refuses deletion. Find the exact recorded name in the Fleet UI and+verify whether this run created any resources before removing them. Do not+delete an existing pool to resolve an access or billing error.++Keep `cloud-fleet.png` as the local result. For another run, use a new directory+so the earlier cleanup record remains available.## What you built-`Pool.apply()` created or reconciled a named Fleet pool and its Linux sandbox-template. `pool.claim()` reserved one sandbox and connected the SDK to its-`server` service. The shell and screenshot calls operated on that cloud desktop,-not on your local machine. Exiting the claim released the sandbox, and-`pool.delete()` removed the Fleet resources.+The Fleet SDK reserved a namespace exclusively for this run. `Pool.apply()`+created a named Fleet pool and its Linux sandbox template inside it.+`pool.claim()` reserved one sandbox and connected the SDK to its+`server` service on port `8000`. This service is the sandbox computer server;+it is not a Cua Driver MCP endpoint. The shell and screenshot calls target the+claimed cloud desktop. This script checks the connection and saves an image;+it does not run an AI agent or connect a local Cua Driver session. Exiting the+claim releases the sandbox, and namespace deletion requests resource removal.## Next stepsdiff --git a/docs/scripts/tests/test_first_cloud_fleet_tutorial.py b/docs/scripts/tests/test_first_cloud_fleet_tutorial.pynew file mode 100644index 0000000000..5e2e648a85--- /dev/null+++ b/docs/scripts/tests/test_first_cloud_fleet_tutorial.py@@ -0,0 +1,302 @@+"""Run the tutorial snippets with released SDK imports and mocked Fleet calls.++Install cua-sandbox==0.4.3 (requires cua-fleet==0.1.14), then run this file.+No credentials, cloud provisioning, or local desktop actions are used.+"""++import asyncio+import importlib.metadata+import inspect+import json+import os+from pathlib import Path+import re+import tempfile+from types import SimpleNamespace+import unittest+from unittest.mock import AsyncMock, Mock, patch++from cua_sandbox import Pool+from fleet_sdk import SdkError+++PAGE = Path(__file__).resolve().parents[2] / "content/docs/tutorials/your-first-cloud-fleet.mdx"+SOURCE = re.search(r'```python title="first_cloud_fleet.py"\n(.*?)\n```', PAGE.read_text(), re.S)[1]+CREATED_AT = "2026-01-01T00:00:00Z"+POOL_NAME = "first-fleet-" + "1" * 32+++def missing():+ return SdkError.Status(operation="get pool", status=404, body="not found")+++class TutorialTests(unittest.TestCase):+ def setUp(self):+ self.directory = tempfile.TemporaryDirectory()+ self.addCleanup(self.directory.cleanup)+ self.root = Path(self.directory.name)+ self.namespace = {"__name__": "tutorial_test"}+ exec(compile(SOURCE, str(PAGE), "exec"), self.namespace)+ self.namespace["RECORD"] = self.root / "cloud-fleet-run.json"+ self.namespace["uuid4"] = lambda: SimpleNamespace(hex="1" * 32)+ self.namespace["Path"] = lambda name: self.root / name+ self.sandbox = SimpleNamespace(+ name="tutorial-guest",+ shell=SimpleNamespace(+ run=AsyncMock(+ return_value=SimpleNamespace(+ success=True,+ stdout="Linux tutorial-guest\n",+ stderr="",+ )+ )+ ),+ screenshot=AsyncMock(return_value=b"synthetic screenshot"),+ )+ self.claim = AsyncMock()+ self.claim.__aenter__.return_value = self.sandbox+ self.claim.__aexit__.return_value = False+ self.pool = SimpleNamespace(+ name=POOL_NAME,+ resource=SimpleNamespace(metadata=SimpleNamespace(creation_timestamp=CREATED_AT)),+ claim=Mock(return_value=self.claim),+ delete=AsyncMock(),+ )+ self.api = SimpleNamespace(+ get=AsyncMock(side_effect=missing()),+ apply=AsyncMock(return_value=self.pool),+ )+ self.namespace["Pool"] = self.api+ self.make_client = self.namespace["fleet_client"]+ self.reservation = SimpleNamespace(name=POOL_NAME, created_at=CREATED_AT)+ self.client = SimpleNamespace(+ create_namespace=AsyncMock(return_value=self.reservation),+ list_namespaces=AsyncMock(side_effect=[[self.reservation], []]),+ delete_namespace=AsyncMock(),+ )+ self.namespace["fleet_client"] = lambda: self.client++ def record(self, created_at=CREATED_AT):+ self.namespace["RECORD"].write_text(+ json.dumps(+ {+ "name": POOL_NAME,+ "created_at": created_at,+ }+ )+ )++ def test_released_versions_and_public_signatures(self):+ self.assertEqual(importlib.metadata.version("cua-sandbox"), "0.4.3")+ self.assertEqual(importlib.metadata.version("cua-fleet"), "0.1.14")+ self.assertIn('"cua-sandbox==0.4.3"', SOURCE)+ self.assertIn('"cua-fleet==0.1.14"', SOURCE)+ inspect.signature(Pool.apply).bind(+ self.namespace["Image"].from_registry(self.namespace["IMAGE"]),+ name=POOL_NAME,+ replicas=1,+ cpu=4,+ memory_mb=4096,+ services={"server": 8000},+ ttl_seconds_after_created=3600,+ )+ inspect.signature(Pool.get).bind(POOL_NAME)+ inspect.signature(Pool.claim).bind(+ self.pool,+ name="first-claim",+ service="server",+ time_to_start=900,+ )++ def test_success_saves_result_releases_claim_and_deletes(self):+ asyncio.run(self.namespace["run"]())+ self.assertEqual((self.root / "cloud-fleet.png").read_bytes(), b"synthetic screenshot")+ self.sandbox.shell.run.assert_awaited_once_with("uname -a")+ self.claim.__aexit__.assert_awaited_once()+ self.client.create_namespace.assert_awaited_once_with(POOL_NAME)+ self.client.delete_namespace.assert_awaited_once_with(POOL_NAME)+ self.api.get.assert_not_awaited()+ record = json.loads(self.namespace["RECORD"].read_text())+ self.assertEqual(record, {"name": POOL_NAME, "created_at": CREATED_AT})+ self.assertEqual(self.api.apply.call_args.kwargs["ttl_seconds_after_created"], 3600)++ def test_existing_record_cannot_be_overwritten(self):+ self.record()+ before = self.namespace["RECORD"].read_bytes()+ with self.assertRaises(FileExistsError):+ asyncio.run(self.namespace["run"]())+ self.assertEqual(self.namespace["RECORD"].read_bytes(), before)+ self.api.get.assert_not_awaited()+ self.api.apply.assert_not_awaited()+ self.client.create_namespace.assert_not_awaited()++ def test_name_collision_does_not_apply_claim_or_delete(self):+ self.client.create_namespace.side_effect = SdkError.Status(+ operation="create namespace", status=409, body="synthetic collision"+ )+ with self.assertRaises(SdkError.Status):+ asyncio.run(self.namespace["run"]())+ self.api.apply.assert_not_awaited()+ self.pool.claim.assert_not_called()+ self.client.delete_namespace.assert_not_awaited()++ def test_reservation_access_denial_is_not_absence(self):+ self.client.create_namespace.side_effect = SdkError.Status(+ operation="create namespace",+ status=403,+ body="synthetic denial",+ )+ with self.assertRaises(SdkError.Status):+ asyncio.run(self.namespace["run"]())+ self.api.apply.assert_not_awaited()+ self.client.delete_namespace.assert_not_awaited()++ def test_admission_failure_deletes_only_confirmed_reservation(self):+ self.api.apply.side_effect = RuntimeError("synthetic admission denial")+ with self.assertRaisesRegex(RuntimeError, "admission denial"):+ asyncio.run(self.namespace["run"]())+ self.pool.claim.assert_not_called()+ self.pool.delete.assert_not_awaited()+ self.client.delete_namespace.assert_awaited_once_with(POOL_NAME)++ def test_unconfirmed_reservation_refuses_cleanup(self):+ self.record(created_at=None)+ with self.assertRaisesRegex(RuntimeError, "not confirmed"):+ asyncio.run(self.namespace["cleanup"]())+ self.client.list_namespaces.assert_not_awaited()+ self.client.delete_namespace.assert_not_awaited()++ def test_claim_failure_deletes_created_pool(self):+ self.claim.__aenter__.side_effect = TimeoutError("synthetic readiness timeout")+ with self.assertRaises(TimeoutError):+ asyncio.run(self.namespace["run"]())+ self.client.delete_namespace.assert_awaited_once_with(POOL_NAME)++ def test_workload_failure_releases_claim_and_deletes(self):+ self.sandbox.shell.run.return_value = SimpleNamespace(+ success=False,+ stdout="",+ stderr="synthetic command failure",+ )+ with self.assertRaisesRegex(RuntimeError, "command failure"):+ asyncio.run(self.namespace["run"]())+ self.claim.__aexit__.assert_awaited_once()+ self.client.delete_namespace.assert_awaited_once_with(POOL_NAME)+ self.sandbox.screenshot.assert_not_awaited()++ def test_screenshot_failure_still_deletes(self):+ self.sandbox.screenshot.side_effect = RuntimeError("synthetic screenshot failure")+ with self.assertRaisesRegex(RuntimeError, "screenshot failure"):+ asyncio.run(self.namespace["run"]())+ self.claim.__aexit__.assert_awaited_once()+ self.client.delete_namespace.assert_awaited_once_with(POOL_NAME)++ def test_cleanup_deletes_only_recorded_namespace_without_running_workload(self):+ self.record()+ asyncio.run(self.namespace["cleanup"]())+ self.client.delete_namespace.assert_awaited_once_with(POOL_NAME)+ self.api.apply.assert_not_awaited()+ self.pool.claim.assert_not_called()+ self.api.get.assert_not_awaited()++ def test_repeated_cleanup_of_absent_namespace_is_safe(self):+ self.record()+ self.client.list_namespaces.side_effect = None+ self.client.list_namespaces.return_value = []+ asyncio.run(self.namespace["cleanup"]())+ asyncio.run(self.namespace["cleanup"]())+ self.client.delete_namespace.assert_not_awaited()+ self.api.apply.assert_not_awaited()++ def test_cleanup_refuses_a_replacement_namespace(self):+ self.record(created_at="2025-01-01T00:00:00Z")+ with self.assertRaisesRegex(RuntimeError, "identity changed"):+ asyncio.run(self.namespace["cleanup"]())+ self.client.delete_namespace.assert_not_awaited()++ def test_cleanup_error_retains_record_for_retry(self):+ self.record()+ self.client.delete_namespace.side_effect = RuntimeError("synthetic connection loss")+ with self.assertRaisesRegex(RuntimeError, "connection loss"):+ asyncio.run(self.namespace["cleanup"]())+ self.assertTrue(self.namespace["RECORD"].exists())++ def test_deletion_poll_is_bounded_and_reports_timeout(self):+ self.record()+ self.client.list_namespaces.side_effect = None+ self.client.list_namespaces.return_value = [self.reservation]+ with patch.object(asyncio, "sleep", new_callable=AsyncMock) as sleep:+ with self.assertRaises(TimeoutError):+ asyncio.run(self.namespace["cleanup"]())+ self.assertEqual(sleep.await_count, 60)+ self.assertTrue(self.namespace["RECORD"].exists())++ def test_inventory_denial_is_not_successful_cleanup(self):+ self.record()+ self.client.list_namespaces.side_effect = SdkError.Status(+ operation="list namespaces", status=403, body="synthetic denial"+ )+ with self.assertRaises(SdkError.Status):+ asyncio.run(self.namespace["cleanup"]())+ self.client.delete_namespace.assert_not_awaited()++ def test_inventory_failure_after_delete_is_not_absence(self):+ self.record()+ self.client.list_namespaces.side_effect = [+ [self.reservation],+ SdkError.Status(operation="list namespaces", status=403, body="synthetic denial"),+ ]+ with self.assertRaises(SdkError.Status):+ asyncio.run(self.namespace["cleanup"]())+ self.client.delete_namespace.assert_awaited_once_with(POOL_NAME)++ def test_unrelated_namespaces_are_not_deleted(self):+ self.record()+ other = SimpleNamespace(name="another-project", created_at=CREATED_AT)+ self.client.list_namespaces.side_effect = [[other, self.reservation], [other]]+ asyncio.run(self.namespace["cleanup"]())+ self.client.delete_namespace.assert_awaited_once_with(POOL_NAME)++ def test_client_credentials_use_the_documented_endpoint(self):+ sdk = self.namespace["CyclopsClient"]+ credentials = Mock(wraps=self.namespace["CyclopsCredentials"])+ with (+ patch.dict(+ os.environ,+ {+ "CUA_CLIENT_ID": "synthetic-client",+ "CUA_CLIENT_SECRET": "synthetic-secret",+ "CUA_TOKEN_URL": "https://auth.example/token",+ },+ clear=True,+ ),+ patch.object(sdk, "connect_with_native_http_client") as connect,+ patch.dict(self.namespace, {"CyclopsCredentials": credentials}),+ ):+ self.assertIs(self.make_client(), connect.return_value)+ configuration = connect.call_args.args[0]+ self.assertEqual(configuration.base_url, "https://run.cua.ai")+ self.assertEqual(configuration.token_url, "https://auth.example/token")+ credentials.assert_called_once_with("synthetic-client", "synthetic-secret")++ def test_static_token_takes_precedence_for_namespace_operations(self):+ sdk = self.namespace["CyclopsClient"]+ with (+ patch.dict(+ os.environ,+ {+ "FLEETS_TOKEN": "synthetic-token",+ "CUA_FLEET_BASE_URL": "https://fleet.example",+ },+ clear=True,+ ),+ patch.object(sdk, "connect_with_access_token_and_native_http_client") as connect,+ ):+ self.assertIs(self.make_client(), connect.return_value)+ configuration, token = connect.call_args.args+ self.assertEqual(configuration.base_url, "https://fleet.example")+ self.assertEqual(token, "synthetic-token")+++if __name__ == "__main__":+ unittest.main()