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: clarify Fleet pool reuse, cleanup, and troubleshooting (#3593)
Francesco Bonacci50bd920252c8
diff --git a/docs/content/docs/how-to-guides/sandbox/create-pool-with-python.mdx b/docs/content/docs/how-to-guides/sandbox/create-pool-with-python.mdxindex 2802f339f2..215963076e 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@@ -33,13 +33,24 @@ endpoint.## Create and claim the pool+Set a globally unique pool name that you own before running the example:++```bash+export CUA_POOL_NAME="my-team-sandbox-pool"+export CUA_CLAIM_NAME="my-task"+```++The example uses `cua-sandbox==0.4.3`. Use `Pool.apply()` only when this script+owns the pool configuration. For a pool managed by another process or+Terraform, use [an existing pool](#use-an-existing-pool) instead.+Save the following script as `create_pool.py`:```python title="create_pool.py"# /// script# requires-python = ">=3.11,<3.14"# dependencies = [-# "cua-sandbox",+# "cua-sandbox==0.4.3",# ]# ///@@ -55,7 +66,7 @@ IMAGE = ("@sha256:c1e601dbb748fdc467c663136f7592e308a91a3c19c309b75261544432826a57")-POOL_NAME = os.environ.get("CUA_POOL_NAME", "cua-live-main-source-manual")+POOL_NAME = os.environ["CUA_POOL_NAME"]CLAIM_NAME = os.environ.get("CUA_CLAIM_NAME", POOL_NAME)@@ -106,14 +117,76 @@ uv run create_pool.pyIf the named pool already exists, it reconciles the pool to the image, replica,CPU, memory, and service configuration in the script.-`pool.claim()` creates or reconnects to the named claim and waits up to 900-seconds for the `server` service on port `8000`. Exiting the `async with` block+`pool.claim()` creates or reconnects to the named claim, waits for binding, then+waits up to 900 seconds for the `server` service on port `8000`. The service+timeout is separate from claim binding. Exiting the `async with` blockreleases the claim, but the pool and its one warm replica remain available forthe next claim.The script writes `sandbox.png` in the current directory and raises an error if`uname -a` does not complete successfully.+## Use an existing pool++Replace the `Pool.apply(...)` call with a lookup to keep the pool's image,+capacity, and services unchanged:++```python+pool = await Pool.get(POOL_NAME)+```++Keep the claim block from the example. Give concurrent tasks different claim+names, or omit `name=` to generate one. A named claim that still exists is+reused; once released, reusing its name creates a new claim. Reusing a pool or+claim name does not guarantee the same VM or preserve files from a released+claim. Copy results out before releasing it.++The claim context releases even an existing claim that it successfully attaches+to. Use it only when this task owns that claim's release. If acquisition fails,+the SDK attempts to release a claim it just created, but leaves a pre-existing+claim alone.++## Keep a claim between processes++To keep a claim after the connection closes, await the claim directly and save+its reference before disconnecting:++```python+import json++sandbox = await pool.claim(name=CLAIM_NAME, service="server", time_to_start=900)+try:+ Path("claim.json").write_text(json.dumps(sandbox.to_dict()))+ result = await sandbox.shell.run("uname -a")+ print(result.stdout)+finally:+ await sandbox.disconnect()+```++`disconnect()` closes the client transport and leaves the claim held. A later+process can reconnect using the saved reference without creating a pool or+claim:++```python+import json+from pathlib import Path+from cua_sandbox import Sandbox++reference = json.loads(Path("claim.json").read_text())+async with Sandbox.from_dict(reference) as sandbox:+ result = await sandbox.shell.run("uname -a")+ print(result.stdout)+```++This reconnect context only disconnects on exit. When the task is finished,+call `await sandbox.close()` to release its claim. A reference does not extend+an expiry deadline. Protect it as resource metadata and keep authenticating+with credentials authorized for that pool.++For Fleet claims, use these explicit pool and claim APIs. The legacy+`Sandbox.list()`, `Sandbox.suspend()`, and `Sandbox.resume()` methods are not+per-claim Fleet lifecycle controls.+## Scale the pool with claim demandInstead of a static `replicas` count, pass `autoscaling=` to let the pool grow@@ -149,8 +222,8 @@ fixed time after creation. See## Choose pool and claim names-The defaults use the same value for the pool and claim. Override either name-without editing the script:+`CUA_POOL_NAME` is required. If `CUA_CLAIM_NAME` is omitted, the script uses the+pool name for its claim. Override either name without editing the script:```bashexport CUA_POOL_NAME="my-sandbox-pool"@@ -158,8 +231,8 @@ export CUA_CLAIM_NAME="my-sandbox-claim"uv run create_pool.py```-Use stable names when later runs should reconcile the same pool and reuse the-same claim identity. Names must be lowercase DNS labels.+Use a stable pool name for shared capacity and a distinct claim name for each+independent task. Names must be lowercase DNS labels.## Pool names are globally unique@@ -173,8 +246,8 @@ pool = await Pool.apply(image, name="my-team-windows-pool")sandbox = await Sandbox.create(pool=pool, name="my-claim")```-If the name you pick already belongs to another account, the SDK raises-`PoolAccessDeniedError` explaining that the name is taken:+If the name belongs to another account, the SDK can raise+`PoolAccessDeniedError` with a name-collision hint:```textPoolAccessDeniedError: Fleet denied create pool on pool namespace@@ -184,11 +257,14 @@ try a new pool name. If that does not work, contact support on Discord:https://discord.gg/mVnXXpdE85```-Retrying does not help, and neither does claiming with fresh claim names: the-conflict is on the pool and its namespace, not the claim. Choose a different-pool name. Claim names never have this problem — they only need to be unique-inside your own pool's namespace, which is why the SDK generates random-`claim-<petname>` claims for you but never generates pool names.+For a confirmed name collision, choose another pool name; changing claim names+does not fix a pool namespace conflict. Claim names are scoped to their pool's+namespace. The SDK generates random `claim-<petname>` claim names when omitted.++The exception's name-collision hint is not a diagnosis for every HTTP 403.+Inspect the operation and response body: a payment requirement or template+policy denial needs a different action. See+[Troubleshoot Fleet pools and claims](/how-to-guides/sandbox/troubleshoot-fleet-pools).`Sandbox.ephemeral(image)` remains a one-liner: it creates a disposable poolunder a random `cua-eph-<hex>` name and deletes it on exit. Passing@@ -196,6 +272,18 @@ under a random `cua-eph-<hex>` name and deletes it on exit. Passing## Delete the pool-The example intentionally leaves the pool warm. If you no longer need it, call-`await pool.delete()` after the claim context exits. This deletes the pool and-the template created by that `Pool.apply()` call.+The example intentionally leaves the pool warm, consuming capacity after the+script exits. When you own the pool and all of its users have finished, call+`await pool.delete()` after releasing every claim. Pool deletion also deletes+the pool namespace and its remaining resources. Do not put it in a worker's+per-task cleanup for a shared pool.++`Pool.apply()` tracks its reconciled template for cleanup, including when that+template already existed. In `cua-sandbox==0.4.3`, a template reconciliation+failure also triggers an attempt to delete the reconciled pool. It is not a+transaction that preserves an existing pool on failure. Use `Pool.get()` when+you only need to consume existing capacity.++If a process exits before cleanup completes, follow+[Recover interrupted cleanup](/how-to-guides/sandbox/troubleshoot-fleet-pools#recover-interrupted-cleanup).+Do not rerun provisioning merely to obtain a handle to delete.diff --git a/docs/content/docs/how-to-guides/sandbox/create-pool-with-typescript.mdx b/docs/content/docs/how-to-guides/sandbox/create-pool-with-typescript.mdxindex 55bcb64de3..71d5c73342 100644--- a/docs/content/docs/how-to-guides/sandbox/create-pool-with-typescript.mdx+++ b/docs/content/docs/how-to-guides/sandbox/create-pool-with-typescript.mdx@@ -42,7 +42,7 @@ public.ecr.aws/k5j5w0x5/cua-ubuntu-24.04@sha256:c1e601dbb748fdc467c663136f7592e3Install the Fleet lifecycle SDK and a TypeScript runner:```bash-npm install @trycua/fleet+npm install @trycua/[email protected]npm install --save-dev tsx typescriptnpm pkg set type=module```@@ -155,6 +155,7 @@ try {console.log(`Reconciled template ${template.metadata.name}`);claim = await client.createClaim(new CreateClaimRequestBuilder().pool(pool).build());+ console.log(`Claim: ${claim.metadata.namespace}/${claim.metadata.name}`);const sandbox = await client.waitClaim(claim);const requestBody = await new Blob([JSON.stringify({ command: 'screenshot' })]).arrayBuffer();@@ -202,7 +203,7 @@ Create a Vite TypeScript project and install the browser SDK:npm create vite@latest fleet-browser -- --template vanilla-tscd fleet-browsernpm install-npm install @trycua/fleet+npm install @trycua/[email protected]```Create `.env.local` with temporary, narrowly scoped OAuth client credentials@@ -339,6 +340,7 @@ try {console.log(`Reconciled pool ${pool.metadata.name} with template ${template.metadata.name}`);claim = await client.createClaim(new CreateClaimRequestBuilder().pool(pool).build());+ console.log(`Claim: ${claim.metadata.namespace}/${claim.metadata.name}`);const sandbox = await client.waitClaim(claim);const requestBody = await new Blob([JSON.stringify({ command: 'screenshot' })]).arrayBuffer();@@ -402,28 +404,57 @@ URL guide.## Keep or delete the poolBoth examples release only the claim, so the one-replica pool remains warm for-the next task. This is the normal reusable-pool lifecycle.+the next task and continues consuming capacity. Each run creates a new claim;+the logged namespace and claim name identify it if cleanup is interrupted.+Copy results out before claim release. Reusing the pool does not guarantee the+same VM or preserve files from the previous claim.-The TypeScript SDK does not currently expose `pool.apply`. Instead,+The `@trycua/[email protected]` SDK does not expose `pool.apply`. Instead,`reconcilePool()` and `reconcileTemplate()` are the lower-level UniFFIreconciliation primitives that Python `Pool.apply` delegates to internally.They do not provide `Pool.apply`'s request derivation, validation, ownership,rollback, or cleanup. Each method looks up its named resource, updates theexisting resource's specification, or creates the resource when the lookupreturns HTTP 403 or 404. Calling both methods lets you rerun the complete example-without maintaining separate get-or-create branches.+without maintaining separate get-or-create branches. Use reconciliation only+when this application owns the pool and template configuration.-To remove the pool permanently, retain the `pool` and `template` values and run-the following after every claim has been released:+To use a pool managed by another process or Terraform, replace both+reconciliation calls and their resource-specific log statements with a lookup:++```ts+const pool = await client.getPool(POOL_NAME);+```++Keep the `createClaim`, `waitClaim`, and `deleteClaim` flow. This lookup does not+create or reconfigure the pool. Avoid `Sandbox.suspend` or `Sandbox.resume`+from other SDKs as a way to pause one Fleet claim: scaling shared capacity is+not a per-claim operation.++`client.uniffiDestroy()` only disposes of the local client. Remote claim release+requires `deleteClaim()`. The `finally` blocks attempt that release even if+claim readiness or the screenshot fails, provided `createClaim()` returned the+claim. An interrupted process or a lost create response still needs inventory+inspection; see [Recover interrupted cleanup](/how-to-guides/sandbox/troubleshoot-fleet-pools#recover-interrupted-cleanup).++To remove a pool you own permanently, retain its `pool` value and call the+following while the client is still open, after every user has released their+claims:```ts-await client.deleteTemplate(template);await client.deletePool(pool);```-Pool names are globally unique across Cua accounts. If reconciliation returns-HTTP 403, choose another pool name; changing the claim name does not resolve a-pool namespace conflict.+Pool deletion also deletes its namespace, including remaining templates and+claims. Do not use it as per-task cleanup for a shared pool. The examples leave+the pool in place if template reconciliation or later work fails; inspect what+exists before deciding whether to repair or remove a dedicated pool.++Pool names are globally unique across Cua accounts. For a confirmed namespace+collision, choose another pool name; changing the claim name does not resolve+it. HTTP 403 can also indicate a payment requirement, authorization, or a+template policy denial. Read the failing operation and response body before+choosing a fix in [Troubleshoot Fleet pools and claims](/how-to-guides/sandbox/troubleshoot-fleet-pools).## Use autoscaling instead of one replicadiff --git a/docs/content/docs/how-to-guides/sandbox/expire-pools-and-claims.mdx b/docs/content/docs/how-to-guides/sandbox/expire-pools-and-claims.mdxindex d79d02ae57..cf21bc75ad 100644--- a/docs/content/docs/how-to-guides/sandbox/expire-pools-and-claims.mdx+++ b/docs/content/docs/how-to-guides/sandbox/expire-pools-and-claims.mdx@@ -8,16 +8,17 @@ import { Callout } from 'fumadocs-ui/components/callout';Pools and claims accept an optional creation-age TTL. Pass`ttl_seconds_after_created=` (requires `cua-sandbox>=0.4.2`) and the resourceis deleted once it has existed that many seconds, whether or not it is in use.-Without the argument nothing is reaped — pools and claims live until you-delete them.+Without this argument, there is no creation-age TTL from this setting. Explicit+claim lifecycle deadlines, normal claim release, pool deletion, and platform+policies can still end resources.This guide assumes a pool created as in[Create a sandbox pool with Python](/how-to-guides/sandbox/create-pool-with-python).## Expire a pool-Pass the TTL to `Pool.apply()` to delete the whole pool — its warm replicas-and its template — a fixed time after the pool was first created:+Pass the TTL to `Pool.apply()` for a pool you own to request automatic deletion+a fixed time after the pool was first created:```pythonfrom cua_sandbox import Image, Pool@@ -46,14 +47,25 @@ async with pool.claim(```A claim TTL fills in the claim's lifecycle shutdown time with a `Delete`-policy; a claim that already carries an explicit lifecycle keeps it.+policy; a claim that already carries an explicit lifecycle keeps it. Exiting+the claim context still releases it immediately, even if its TTL has not+elapsed. Disconnecting alone does not release it or cancel its deadline.## The clock starts at creationThe TTL counts from the resource's original creation, not its last use:re-running `Pool.apply()` reconciles the existing pool without resetting itsage, and reconnecting to a named claim keeps the deadline set when the claim-was first created.+was first created. Passing a TTL when attaching to an existing named claim+does not replace that claim's spec or renew its deadline. A pool may therefore+expire shortly after a rerun if it is already near the end of its lifetime.++Use a TTL as a cleanup backstop for interrupted jobs, and still release claims+when work finishes. It is not an inactivity timeout or an automatic heartbeat.+Keep the pool lifetime longer than the intended work, including startup time,+and copy results out before the deadline. Controller-driven deletion is+asynchronous; verify resource absence after expiry instead of treating the+deadline as proof that cleanup has finished.## Hand-built claim specs@@ -77,8 +89,11 @@ async with pool.claim(spec=spec) as sandbox:## Pool expiry under live claims<Callout type="warn">- Treat a pool TTL that can expire while claims are held as a capacity event,- not just cleanup: deleting the pool drains its sandboxes, and a claim that- outlives its pool destroys its sandbox on release instead of returning it- to the pool.+ Treat a pool TTL that can expire while claims are held as a capacity event, not just cleanup:+ deleting the pool drains its sandboxes, and a claim that outlives its pool destroys its sandbox on+ release instead of returning it to the pool.</Callout>++If cleanup was interrupted, use the resource identities you recorded and+[inspect the remaining pool and claims](/how-to-guides/sandbox/troubleshoot-fleet-pools#recover-interrupted-cleanup).+Reapplying a pool is a configuration write, not a cleanup operation.diff --git a/docs/content/docs/how-to-guides/sandbox/meta.json b/docs/content/docs/how-to-guides/sandbox/meta.jsonindex e2464e10bc..6e31298571 100644--- a/docs/content/docs/how-to-guides/sandbox/meta.json+++ b/docs/content/docs/how-to-guides/sandbox/meta.json@@ -6,6 +6,7 @@"create-pool-with-typescript","run-cursor-cloud-agent-on-fleet","expire-pools-and-claims",+ "troubleshoot-fleet-pools","run-openclaw-on-cloud-fleet","run-omarchy-on-cloud-fleet","connect-to-omarchy-with-novnc",diff --git a/docs/content/docs/how-to-guides/sandbox/troubleshoot-fleet-pools.mdx b/docs/content/docs/how-to-guides/sandbox/troubleshoot-fleet-pools.mdxnew file mode 100644index 0000000000..a451bacf4b--- /dev/null+++ b/docs/content/docs/how-to-guides/sandbox/troubleshoot-fleet-pools.mdx@@ -0,0 +1,154 @@+---+title: Troubleshoot Fleet pools and claims+description: Diagnose Fleet pool errors and recover interrupted claim or pool cleanup without provisioning replacements.+---++Use this guide when a Fleet pool or claim fails to start, an existing pool+cannot be reused, or a process exits before releasing its resources. It applies+to the [Python pool guide](/how-to-guides/sandbox/create-pool-with-python) and+[TypeScript pool guide](/how-to-guides/sandbox/create-pool-with-typescript).++## Identify the failing operation++Record the SDK versions, pool namespace, claim name if known, failing+operation, HTTP status, and sanitized error body. Keep credentials, tokens,+signed URLs, and guest content out of shared logs.++Read the operation as well as the exception class. `PoolAccessDeniedError`+includes a name-collision hint, but HTTP 403 alone does not establish that the+name belongs to another account.++## Resolve authentication or access errors++If token exchange fails or the API returns HTTP 401, verify that the credential+has not expired or been revoked and that your process uses the intended Fleet+and token endpoints. Follow the credential setup in the guide for your SDK,+then retry an existing-resource lookup before attempting creation again.++For HTTP 403, inspect the response body and operation:++- If the body says a payment method is required, review the account's billing+ setup with its owner. A different pool name or repeated retries will not+ satisfy that requirement.+- If an initial pool creation is denied and ownership checks show that the+ namespace is unavailable to your account, choose a different globally unique+ pool name. A different claim name does not resolve this conflict.+- If access to a known pool is denied, verify that the credential belongs to+ an account authorized for that pool. Do not interpret 403 as proof that the+ resource is absent or that cleanup succeeded.+- If `create template` or `update template` is denied, inspect the image+ reference and image-pull configuration against the deployment's policy. A+ successful pool creation does not prove the template is permitted. Preserve+ the failing operation and sanitized response when asking for help.++For local validation errors about names, use lowercase DNS labels: lowercase+letters, digits, and hyphens, with a letter or digit at each end. Keep names at+most 63 characters. Use a distinct claim name for each concurrent task.++## Diagnose a claim that does not become ready++Check the pool, template, and claim in [Fleet](https://run.cua.ai) using the+recorded namespace and claim name. Separate these stages:++1. Verify that the pool and its referenced template exist. Inspect the template+ reference rather than assuming its name equals the pool name.+2. Inspect available capacity and the claim's binding status. A pool scaled to+ zero can require a cold start. A missing template, unavailable image, or+ exhausted capacity is not fixed by extending a guest-service timeout.+3. Once the claim is bound, verify that the selected service exists and the+ guest process listens on its configured port. The Python example expects+ `server` on port `8000` and a compatible computer-server image.+4. If the configuration is correct and startup is still progressing, adjust+ the relevant wait budget. Python's `time_to_start` controls the service+ readiness wait after binding; TypeScript's `claimPollIntervalMs` and+ `claimPollLimit` control claim polling. Neither setting extends a resource's+ TTL or lifecycle deadline.++An API connection, a created pool, and a bound claim are different checkpoints.+Verify a successful service request before treating the guest as usable. On a+readiness timeout, inspect whether the claim still exists before retrying:+Python attempts to release newly created claims on acquisition failure, while+a pre-existing named claim remains held. The TypeScript examples attempt+release in `finally` if creation returned a claim handle.++## Recover interrupted cleanup++Use lookups and deletion with the identities recorded before the failure.+Do not rerun `Pool.apply()`, `reconcilePool()`, or `createClaim()` to recover a+handle: they can create or modify resources. Disconnecting a client or closing+a browser tab does not prove that remote resources were released.++First, inspect the named pool and its claims in Fleet. If the pool is shared,+release only your task's claim. If a create response was lost before its claim+name was recorded, inspect inventory and establish ownership before deleting+anything. A timestamp or similar-looking name alone is not proof of ownership.++For scripted recovery, initialize the TypeScript client using only the imports,+configuration, and `CyclopsClient.connect(...)` setup from the+[Node.js example](/how-to-guides/sandbox/create-pool-with-typescript). Do not run+its reconciliation or claim-creation block. The following snippets use that+open `client` and the exact `POOL_NAME` you recorded.++List claim identities without waiting for a guest to become ready:++```ts+const claims = await client.listClaims(POOL_NAME);+for (const claim of claims) {+ console.log(`${claim.metadata.namespace}/${claim.metadata.name}`);+}+```++After identifying a claim that your task owns, set `CUA_CLAIM_NAME` to that+exact name and release it. This does not create a replacement claim or wait for+service readiness:++```ts+const claimName = process.env.CUA_CLAIM_NAME;+if (!claimName) throw new Error('Set CUA_CLAIM_NAME to the claim you own');+const claims = await client.listClaims(POOL_NAME);+const claim = claims.find((item) => item.metadata.name === claimName);+if (claim) await client.deleteClaim(claim);+const remaining = await client.listClaims(POOL_NAME);+if (remaining.some((item) => item.metadata.name === claimName)) {+ throw new Error('Claim deletion is still pending; inspect again');+}+```++If you own the entire pool and all users have finished, fetch and delete it:++```ts+const pool = await client.getPool(POOL_NAME);+await client.deletePool(pool);+```++This deletes the pool namespace and its remaining resources, including other+claims and templates. Use this operation only for a pool you intend to remove+completely. In Python, the equivalent is+`pool = await Pool.get(POOL_NAME)` followed by `await pool.delete()`.++If the pool lookup returns 404 but namespace inventory still shows the exact+dedicated namespace, inspect its remaining claims and templates. Once you have+confirmed that all remaining resources belong to the cleanup task, delete the+namespace directly:++```ts+await client.deleteNamespace(POOL_NAME);+```++In `@trycua/[email protected]`, namespace deletion accepts an already-absent namespace+as success, so the same exact deletion can be retried after interruption.+Close the local client with `client.uniffiDestroy()` in a `finally` block when+the recovery script ends.++## Verify cleanup finished++After claim-only cleanup, verify that the claim is absent and the shared pool+still exists. After whole-pool cleanup, check namespace inventory again until+the namespace and its resources are absent. An accepted DELETE can precede+asynchronous removal. If a request returns 403, resolve authorization before+claiming cleanup is complete.++For future disposable work, configure a+[creation-age TTL](/how-to-guides/sandbox/expire-pools-and-claims) as a backstop+and retain explicit cleanup. A TTL does not replace copying out results or+checking that resources were removed.