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: separate sandbox setup, lifecycle, and image tasks
Francesco Bonaccib331f9084572
diff --git a/docs/content/docs/concepts/how-sandboxes-work.mdx b/docs/content/docs/concepts/how-sandboxes-work.mdxindex fba13b73fe..1af5e13f0f 100644--- a/docs/content/docs/concepts/how-sandboxes-work.mdx+++ b/docs/content/docs/concepts/how-sandboxes-work.mdx@@ -66,7 +66,7 @@ Sandbox lifetime is separate from agent connection lifetime. An ephemeral sandboA persistent or named sandbox is created once, identified by name, and can survive process exits. A later process can reconnect to the same sandbox and continue from the state it already has.-Connect mode attaches to an already-running sandbox. It does not create a sandbox and it does not delete one. Disconnecting drops the control connection. Deleting destroys the machine and its state. Those are different operations, and the distinction matters when the sandbox contains work that should survive the current process. [Sandbox lifecycle](/concepts/sandbox-lifecycle) shows the SDK patterns for each lifetime.+Connect mode attaches to an already-running sandbox. It does not create a sandbox and it does not delete one. Disconnecting drops the control connection. Deleting destroys the machine and its state. Those are different operations, and the distinction matters when the sandbox contains work that should survive the current process. [Sandbox lifecycle](/concepts/sandbox-lifecycle) explains local ownership and Fleet capacity; [Manage local sandbox lifecycle](/how-to-guides/sandbox/manage-local-lifecycle) shows the local SDK patterns.## Snapshots and forksdiff --git a/docs/content/docs/concepts/sandbox-lifecycle.mdx b/docs/content/docs/concepts/sandbox-lifecycle.mdxindex 46accb451d..bb7f537b54 100644--- a/docs/content/docs/concepts/sandbox-lifecycle.mdx+++ b/docs/content/docs/concepts/sandbox-lifecycle.mdx@@ -1,109 +1,64 @@---title: Sandbox lifecycle-description: Choose the right Sandbox SDK lifecycle pattern for temporary, persistent, and reconnectable sandboxes.+description: How connection lifetime, local sandbox lifetime, and Fleet pool capacity differ.----import { Callout } from 'fumadocs-ui/components/callout';+A connection, a local sandbox, and a Fleet pool have separate lifetimes.+Choose who owns each resource before deciding when to disconnect or clean up.-Use the **lifecycle pattern** that matches whether you want the sandbox _deleted after the job_, _kept for later_, or _attached to while it is already running_.+## Local machine and connection lifetime-The examples below use local execution. Fleet uses managed pools and claims, whose-release behavior differs from deleting a local VM. See [Your first Cloud Fleet](/tutorials/your-first-cloud-fleet)-for a pool-and-claim workflow and [Sandbox runtime support](/reference/sandbox-sdk/runtime-support)-for image and transport limits.+An ephemeral local sandbox belongs to one block of work. Its context manager+calls cleanup when the block exits. A persistent local sandbox outlives the+creating script until you delete it. Give it a name so another process can+reconnect later.++`Sandbox.connect` attaches to an existing running local sandbox. Closing that+connection leaves the sandbox running; deleting the sandbox discards its state.+Save results before deleting it. The [local lifecycle guide](/how-to-guides/sandbox/manage-local-lifecycle)+shows creation, reconnection, and cleanup patterns.++## Fleet claims and pool capacityOn Fleet, `disconnect()` drops the connection without releasing the claim.Exiting a `pool.claim()` context releases the claim, but the pool can keep warmcapacity available and incur cloud usage charges. Deleting the pool is a-separate operation that removes its capacity and state. See the [Pool reference](/reference/sandbox-sdk/pool)-for exact ownership and release behavior, and [Expire pools and claims automatically](/how-to-guides/sandbox/expire-pools-and-claims)-for cleanup deadlines.--## Create and auto-destroy a sandbox+separate operation that removes its capacity and state.-Use `Sandbox.ephemeral` for scripts, CI, and one-off tasks.+The [Pool reference](/reference/sandbox-sdk/pool) defines ownership and release+behavior. [Expire pools and claims automatically](/how-to-guides/sandbox/expire-pools-and-claims)+explains cleanup deadlines. Keep claim cleanup inside each workload and delete+a pool only when you own its lifecycle; a shared pool can serve other callers.-```python-import asyncio-from cua import Sandbox, Image+## Runtime limits-async def main():- async with Sandbox.ephemeral(Image.linux(), local=True) as sb:- result = await sb.shell.run('echo hello')- print(result.stdout) # 'hello\n'- # sandbox deleted here+Local execution and Fleet share SDK concepts, but that does not make their+lifecycle operations interchangeable. See [Sandbox runtime support](/reference/sandbox-sdk/runtime-support)+for versioned image and transport limits. In `cua-sandbox` 0.4.3,+`Sandbox.snapshot()` is not implemented for local sandboxes or Fleet creation+paths, and Fleet rejects snapshot-derived images.-asyncio.run(main())-```+## Create and auto-destroy a sandbox-`Sandbox.ephemeral` is **auto-destroyed** when the `async with` block exits. Its context manager tears the sandbox down automatically.+See [Create and auto-destroy a sandbox](/how-to-guides/sandbox/manage-local-lifecycle#create-and-auto-destroy-a-sandbox)+for the local SDK pattern.## Create a persistent sandbox-Use `Sandbox.create` when the sandbox **must outlive the script**. Call `await sb.disconnect()` to drop the connection while the sandbox keeps running.--```python-sb = await Sandbox.create(Image.linux(), name='my-dev-sandbox', local=True)-await sb.shell.run('apt-get install -y vim')-await sb.disconnect() # sandbox keeps running-```--Delete the sandbox when you are done with it.--```python-async with Sandbox.connect('my-dev-sandbox', local=True) as sb:- await sb.destroy()-```--| Method | Effect | When |-| ---------------------------- | ------------------------------------------- | --------------- |-| `await sb.disconnect()` | keeps running | reconnect later |-| `await sb.destroy()` | permanently destroyed | done with it |-| `await Sandbox.delete(name)` | permanently destroyed (by name, no connect) | classmethod |+See [Create a persistent sandbox](/how-to-guides/sandbox/manage-local-lifecycle#create-a-persistent-sandbox)+for the local SDK pattern.## Reconnect to a running sandbox-Use `Sandbox.connect` to attach to an already-running sandbox.--<Callout type="info">- Sandbox.connect never starts or stops the sandbox. It only manages the network connection.-</Callout>--Reconnect by name.--```python-async with Sandbox.connect('my-dev-sandbox', local=True) as sb:- result = await sb.shell.run('vim --version')- print(result.stdout)-```--`Sandbox.connect` supports both `await` and `async with`. Its context manager calls `disconnect()` automatically, so the sandbox keeps running after the connection closes.--```python-async with Sandbox.connect('my-sandbox', local=True) as sb:- await sb.shell.run('echo reconnected')-# connection dropped, sandbox keeps running-```+See [Reconnect to a running sandbox](/how-to-guides/sandbox/manage-local-lifecycle#reconnect-to-a-running-sandbox)+for the local SDK pattern.## List running sandboxes-List available sandboxes, then filter to local runtimes when needed.--```python-sandboxes = await Sandbox.list(local=True)-for info in sandboxes:- print(info.name, info.os_type, info.status)-```+See [List running sandboxes](/how-to-guides/sandbox/manage-local-lifecycle#list-running-sandboxes)+for the local SDK pattern.## Choose a local runtime-Pass `local=True` to use a runtime on your own machine. Cua selects a local runtime from the image type: Docker for Linux containers, QEMU for Linux VMs, Lume for macOS VMs, and QEMU or Hyper-V for Windows VMs. Selection still requires a compatible host and usable image; it is not a boot check. See the [runtime support reference](/reference/sandbox-sdk/runtime-support#operating-systems-and-image-kinds) before choosing a backend.--```python-# local Docker desktop container-async with Sandbox.ephemeral(- Image.linux(kind='container'),- local=True,-) as sb:- ...-```+See [Choose a local runtime](/how-to-guides/sandbox/manage-local-lifecycle#choose-a-local-runtime)+for the local SDK pattern.diff --git a/docs/content/docs/how-to-guides/driver/connect-your-agent.mdx b/docs/content/docs/how-to-guides/driver/connect-your-agent.mdxindex ae60ac24d9..38f9647504 100644--- a/docs/content/docs/how-to-guides/driver/connect-your-agent.mdx+++ b/docs/content/docs/how-to-guides/driver/connect-your-agent.mdx@@ -57,10 +57,10 @@ directly, and it applies only to a runtime this command launches. An agent cannowiden any of this from a tool call.<Callout type="warn">- A `standard`-mode runtime allows input against every application on the- desktop. If an agent should reach only a reviewed set of apps, origins, and- directories, register it against a `bounded` runtime instead — see [Write a- capability manifest](/how-to-guides/driver/write-a-bounded-manifest).+ A `standard`-mode runtime allows input against every application on the desktop. If an agent+ should reach only a reviewed set of apps, origins, and directories, register it against a+ `bounded` runtime instead — see [Write a capability+ manifest](/how-to-guides/driver/write-a-bounded-manifest).</Callout>## Generate the client config@@ -222,23 +222,14 @@ Two valid setups:## Clients without a dedicated preset-Some MCP clients can run Cua Driver directly even though `mcp-config` does not yet have a named-preset for them. Resolve the absolute executable path first with `command -v cua-driver`, then use-the client's native command:+Some MCP clients can run Cua Driver directly even though `mcp-config` does not+have a named preset for them. After completing the installation and permission+steps on this page, use the client-specific registration and verification steps:-```bash-# Grok Build (xAI coding CLI, not Grok Bot)-grok mcp add cua-driver -- /absolute/path/to/cua-driver mcp-grok mcp doctor cua-driver--# Kimi Code CLI-kimi mcp add cua-driver -- /absolute/path/to/cua-driver mcp-kimi mcp test cua-driver-```--These commands use each client's documented stdio MCP interface and the standard `cua-driver mcp`-entry point. See the focused guides for [Grok Build](/use-cua-with/grok-build) and [Kimi-Code](/use-cua-with/kimi-code).+- [Grok Build](/use-cua-with/grok-build), xAI's coding CLI, uses stdio MCP.+ [Grok Bot](/use-cua-with/grok-bot) is a separate local-command integration.+- [Kimi Code](/use-cua-with/kimi-code) uses stdio MCP through its native CLI or+ configuration file.T3 Code is a control plane for other coding agents rather than a separate MCP client. Configure CuaDriver in the underlying harness, then launch that harness from [T3 Code](/use-cua-with/t3-code).diff --git a/docs/content/docs/how-to-guides/sandbox/choose-an-image.mdx b/docs/content/docs/how-to-guides/sandbox/choose-an-image.mdxnew file mode 100644index 0000000000..39d98cf38f--- /dev/null+++ b/docs/content/docs/how-to-guides/sandbox/choose-an-image.mdx@@ -0,0 +1,24 @@+---+title: Choose a sandbox image+description: Choose between a published Fleet image, local image customization, and preparing a Fleet boot artifact.+---++Choose an image workflow based on where the sandbox will run and whether a+published artifact already contains the software you need.++| Your task | Start here | What you get |+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |+| Run a Fleet workload using an existing image | [Choose a published Fleet image](/how-to-guides/sandbox/images#choose-a-published-fleet-image) | A registry artifact reference for a pool. |+| Add packages, files, or setup commands for local execution | [Choose a local base image](/how-to-guides/sandbox/images#choose-a-base-image) | An image specification whose builder steps run locally. |+| Run a Fleet workload that needs a custom guest | [Prepare and reference a Fleet image](/how-to-guides/sandbox/prepare-and-reference-a-fleet-image) | A bootable guest disk packaged and published as a containerDisk artifact. |++Before choosing an artifact, check the [OS and image catalog](/reference/sandbox-sdk/os-image-catalog)+for architecture, guest services, and verification limits. A registry reference+does not prove that the guest is accessible, bootable, or ready for your client.+Declaring a service port does not install the service.++In `cua-sandbox` 0.4.3, Fleet rejects SDK builder customization and+snapshot-derived image inputs. Local builder methods do not publish an artifact+or run during a Fleet claim. See [Sandbox runtime support](/reference/sandbox-sdk/runtime-support#image-customization)+for the versioned contract and [How Fleet images work](/concepts/how-fleet-images-work)+for the published-artifact model.diff --git a/docs/content/docs/how-to-guides/sandbox/images.mdx b/docs/content/docs/how-to-guides/sandbox/images.mdxindex 861b59d934..7836b0a65e 100644--- a/docs/content/docs/how-to-guides/sandbox/images.mdx+++ b/docs/content/docs/how-to-guides/sandbox/images.mdx@@ -7,15 +7,21 @@ import { Callout } from 'fumadocs-ui/components/callout';Use an **Image** to define the OS and software environment for a sandbox before you start it.+Start with [Choose a sandbox image](/how-to-guides/sandbox/choose-an-image) if you+need to decide between using a published Fleet artifact, customizing a local+image, or publishing a Fleet artifact.+For Fleet, [choose a published image](#choose-a-published-fleet-image). For localexecution, [choose a base image](#choose-a-base-image) and add the setup steps below.<Callout type="warn">- **SDK builder customization is local-only in `cua-sandbox` 0.4.3.** `apt_install()`, `pip_install()`, `env()`,- `run()`, `copy()` and the other builder methods are applied when you boot the image- locally (`local=True`). Fleet runs a prebuilt registry artifact and rejects- a customized one with `NotImplementedError: Fleet cloud supports registry images with- optional exposed services only`. For Fleet customization, [prepare and publish the guest image first](/how-to-guides/sandbox/prepare-and-reference-a-fleet-image). See [Sandbox runtime support](/reference/sandbox-sdk/runtime-support) for versioned acceptance and verification limits.+ **SDK builder customization is local-only in `cua-sandbox` 0.4.3.** `apt_install()`,+ `pip_install()`, `env()`, `run()`, `copy()` and the other builder methods are applied when you+ boot the image locally (`local=True`). Fleet runs a prebuilt registry artifact and rejects a+ customized one with `NotImplementedError: Fleet cloud supports registry images with optional+ exposed services only`. For Fleet customization, [prepare and publish the guest image+ first](/how-to-guides/sandbox/prepare-and-reference-a-fleet-image). See [Sandbox runtime+ support](/reference/sandbox-sdk/runtime-support) for versioned acceptance and verification limits.</Callout>## Choose a published Fleet image@@ -63,7 +69,7 @@ Fleet artifact or run during a Fleet claim.## Choose a base image-An Image describes the OS and software environment. Images are *immutable* and *chainable*. Each builder method returns a new Image.+An Image describes the OS and software environment. Images are _immutable_ and _chainable_. Each builder method returns a new Image.Start with the built-in constructor that matches the operating system and isolation level you need.@@ -117,10 +123,9 @@ RuntimeError: Image.linux() is a VM and needs QEMU, which was not found on this`Image.linux(kind='container')` is the Docker path instead, and needs no QEMU.<Callout type="warn">- Passing `runtime=QEMURuntime()` explicitly selects `mode='docker'`, which wraps- QEMU in a container and does **not** boot the pinned containerDisk. Use- `QEMURuntime(mode='bare-metal')` if you are naming a runtime by hand, or leave- `runtime=` off and let the default pick it.+ Passing `runtime=QEMURuntime()` explicitly selects `mode='docker'`, which wraps QEMU in a+ container and does **not** boot the pinned containerDisk. Use `QEMURuntime(mode='bare-metal')` if+ you are naming a runtime by hand, or leave `runtime=` off and let the default pick it.</Callout>## Install packages@@ -151,7 +156,7 @@ Image.linux().env(DATABASE_URL='postgres://localhost/mydb', LOG_LEVEL='debug')```Variables are baked in as `/etc/profile.d/cua-env.sh` on Linux and macOS, and as-machine-scoped `setx` variables on Windows. On Linux that file is read by *login*+machine-scoped `setx` variables on Windows. On Linux that file is read by _login_shells, so a bare `sb.shell.run()` does not see them — ask for a login shell:```python@@ -160,7 +165,8 @@ await sb.shell.run("bash -lc 'echo $MY_TOKEN'") # abc123```<Callout type="warn">- Avoid putting real secrets in .env() because anyone who can read the Image spec can see the values.+ Avoid putting real secrets in .env() because anyone who can read the Image spec can see the+ values.</Callout>## Run setup commands@@ -188,10 +194,10 @@ Image.linux().expose(8080).expose(5432)```<Callout type="warn">- In 0.4.3, bare-metal QEMU forwards exposed ports at startup and reports their- host ports in `sb.exposed_ports`. Other local backends can differ. Fleet creates- named services instead. `expose()` does not make `tunnel.forward()` available- on every transport; see [ports and transports](/reference/sandbox-sdk/runtime-support#ports-and-transports).+ In 0.4.3, bare-metal QEMU forwards exposed ports at startup and reports their host ports in+ `sb.exposed_ports`. Other local backends can differ. Fleet creates named services instead.+ `expose()` does not make `tunnel.forward()` available on every transport; see [ports and+ transports](/reference/sandbox-sdk/runtime-support#ports-and-transports).</Callout>## Chain builder calls@@ -248,10 +254,10 @@ async with Sandbox.ephemeral(img, local=True, runtime=QEMURuntime(mode='bare-met```<Callout type="warn">- Replace the example reference with an artifact you published. `Image.from_registry()`- defaults to `os_type='linux'`; set `os_type='windows', kind='vm'` for a Windows VM- disk. The registry reference does not prove that the artifact is accessible or- bootable. Local pull authentication and Fleet registry access are separate requirements.+ Replace the example reference with an artifact you published. `Image.from_registry()` defaults to+ `os_type='linux'`; set `os_type='windows', kind='vm'` for a Windows VM disk. The registry+ reference does not prove that the artifact is accessible or bootable. Local pull authentication+ and Fleet registry access are separate requirements.</Callout>## Use a local disk imagediff --git a/docs/content/docs/how-to-guides/sandbox/manage-local-lifecycle.mdx b/docs/content/docs/how-to-guides/sandbox/manage-local-lifecycle.mdxnew file mode 100644index 0000000000..851f33e004--- /dev/null+++ b/docs/content/docs/how-to-guides/sandbox/manage-local-lifecycle.mdx@@ -0,0 +1,103 @@+---+title: Manage local sandbox lifecycle+description: Create, reconnect to, list, and clean up local sandboxes with the Sandbox SDK.+---++import { Callout } from 'fumadocs-ui/components/callout';++These patterns run on your own machine with `local=True`. Choose a+[compatible host and runtime](/reference/sandbox-sdk/runtime-support#operating-systems-and-image-kinds)+before running them. They are operation patterns, not a complete installation tutorial.++For the ownership model, read [Sandbox lifecycle](/concepts/sandbox-lifecycle).+For Fleet, use [Create a sandbox pool with Python](/how-to-guides/sandbox/create-pool-with-python):+releasing a claim and deleting pool capacity are separate operations.++## Create and auto-destroy a sandbox++Use `Sandbox.ephemeral` for scripts, CI, and one-off tasks.++```python+import asyncio+from cua import Sandbox, Image++async def main():+ async with Sandbox.ephemeral(Image.linux(), local=True) as sb:+ result = await sb.shell.run('echo hello')+ print(result.stdout) # 'hello\n'+ # sandbox deleted here++asyncio.run(main())+```++`Sandbox.ephemeral` is **auto-destroyed** when the `async with` block exits. Its context manager tears the sandbox down automatically.++## Create a persistent sandbox++Use `Sandbox.create` when the sandbox **must outlive the script**. Call `await sb.disconnect()` to drop the connection while the sandbox keeps running.++```python+sb = await Sandbox.create(Image.linux(), name='my-dev-sandbox', local=True)+await sb.shell.run('apt-get install -y vim')+await sb.disconnect() # sandbox keeps running+```++Delete the sandbox when you are done with it.++```python+async with Sandbox.connect('my-dev-sandbox', local=True) as sb:+ await sb.destroy()+```++| Method | Effect | When |+| ---------------------------- | ------------------------------------------- | --------------- |+| `await sb.disconnect()` | keeps running | reconnect later |+| `await sb.destroy()` | permanently destroyed | done with it |+| `await Sandbox.delete(name)` | permanently destroyed (by name, no connect) | classmethod |++## Reconnect to a running sandbox++Use `Sandbox.connect` to attach to an already-running sandbox.++<Callout type="info">+ Sandbox.connect never starts or stops the sandbox. It only manages the network connection.+</Callout>++Reconnect by name.++```python+async with Sandbox.connect('my-dev-sandbox', local=True) as sb:+ result = await sb.shell.run('vim --version')+ print(result.stdout)+```++`Sandbox.connect` supports both `await` and `async with`. Its context manager calls `disconnect()` automatically, so the sandbox keeps running after the connection closes.++```python+async with Sandbox.connect('my-sandbox', local=True) as sb:+ await sb.shell.run('echo reconnected')+# connection dropped, sandbox keeps running+```++## List running sandboxes++List available sandboxes, then filter to local runtimes when needed.++```python+sandboxes = await Sandbox.list(local=True)+for info in sandboxes:+ print(info.name, info.os_type, info.status)+```++## Choose a local runtime++Pass `local=True` to use a runtime on your own machine. Cua selects a local runtime from the image type: Docker for Linux containers, QEMU for Linux VMs, Lume for macOS VMs, and QEMU or Hyper-V for Windows VMs. Selection still requires a compatible host and usable image; it is not a boot check. See the [runtime support reference](/reference/sandbox-sdk/runtime-support#operating-systems-and-image-kinds) before choosing a backend.++```python+# local Docker desktop container+async with Sandbox.ephemeral(+ Image.linux(kind='container'),+ local=True,+) as sb:+ ...+```diff --git a/docs/content/docs/how-to-guides/sandbox/meta.json b/docs/content/docs/how-to-guides/sandbox/meta.jsonindex 6e31298571..64f1481b0e 100644--- a/docs/content/docs/how-to-guides/sandbox/meta.json+++ b/docs/content/docs/how-to-guides/sandbox/meta.json@@ -1,6 +1,9 @@{"title": "Sandbox","pages": [+ "set-up-fleet-credentials",+ "choose-an-image",+ "manage-local-lifecycle","configure-pool-with-terraform","create-pool-with-python","create-pool-with-typescript",diff --git a/docs/content/docs/how-to-guides/sandbox/set-up-fleet-credentials.mdx b/docs/content/docs/how-to-guides/sandbox/set-up-fleet-credentials.mdxnew file mode 100644index 0000000000..fcc4d5a921--- /dev/null+++ b/docs/content/docs/how-to-guides/sandbox/set-up-fleet-credentials.mdx@@ -0,0 +1,125 @@+---+title: Set up Fleet credentials+description: Create a Fleet user API key, configure the Sandbox SDK, and check access before provisioning.+---++The Fleet SDK accepts an OAuth user API key or a Fleet bearer access token.+`cua auth login` stores an interactive CLI session in the credential vault;+it does not export either credential for the SDK. `cua sb launch --pool` also+uses the SDK's separate credential configuration. Without it, even a logged-in+CLI can fail with:++```console+$ cua sb launch --pool my-pool --name my-sandbox+Error: Fleet cloud sandboxes require CUA_CLIENT_ID and CUA_CLIENT_SECRET, or cua.configure(client_id=..., client_secret=...).+```++## Create a Fleet user API key++You need an account that can sign in to [Cua Fleet](https://run.cua.ai) and+access **API keys**. Create the key while signed in as the account that will+own the pools. User keys act on behalf of their owner; creating a key does not+grant access to another account's pools or bypass pool admission rules.++1. Sign in to [Cua Fleet](https://run.cua.ai), then select **API keys** in the+ navigation, or open the [API keys page](https://run.cua.ai/user-keys).+2. Under **Create API key**, enter a descriptive **Name**, such as+ `first-fleet-tutorial`. For the first-Fleet tutorial, leave+ **Allowed Namespaces (optional)** at its default,+ **All namespaces (no restriction)**, because the tutorial creates a new+ pool namespace.+3. Select **Create key**. In **API key created**, copy **Client ID** and+ **Client Secret** into your secret manager before selecting+ **I have copied the credentials**. The secret is shown only once.++If you cannot sign in, the page reports **API keys are unavailable**, or key+creation is denied, contact [Cua support on Discord](https://discord.gg/mVnXXpdE85)+to check account access before continuing. `cua auth login` is not a substitute+for this key-creation step.++Pool creation can also require a payment method. If Fleet shows+**Payment method required**, open **Settings** and use **Add payment method**+under **Payment method**. Review the applicable pricing and terms before+adding a payment method or creating billable resources. The read-only access+check below does not create a pool or claim.++## Configure the Sandbox SDK++Set `CUA_CLIENT_ID` to **Client ID** and `CUA_CLIENT_SECRET` to **Client Secret**.+The token endpoint below is the default for `run.cua.ai`; the dashboard's+credential dialog does not display it:++```bash+export CUA_CLIENT_ID="<your-client-id>"+export CUA_CLIENT_SECRET="<your-client-secret>"+export CUA_TOKEN_URL="https://auth.cua.ai/realms/cyclops-cs/protocol/openid-connect/token"+unset FLEETS_TOKEN+```++`FLEETS_TOKEN` takes precedence over these client credentials, so unset it when+switching to a user key. Inject secrets through your secret manager where+possible; do not commit them or paste them into shared logs.++## Check access before provisioning++With [uv](https://docs.astral.sh/uv/) installed, run this check in the same+shell. It exchanges the user key for a short-lived access token and sends+`GET /api/namespaces`. It prints only the number of namespaces returned:++```bash+uv run --with 'httpx>=0.27,<1' python - <<'PY'+import os++import httpx++with httpx.Client(timeout=30) as client:+ token_response = client.post(+ os.environ["CUA_TOKEN_URL"],+ auth=(os.environ["CUA_CLIENT_ID"], os.environ["CUA_CLIENT_SECRET"]),+ data={"grant_type": "client_credentials"},+ )+ token_response.raise_for_status()+ access_token = token_response.json()["access_token"]+ response = client.get(+ "https://run.cua.ai/api/namespaces",+ headers={"Authorization": f"Bearer {access_token}"},+ )+ response.raise_for_status()+ print(f"Fleet access verified: {len(response.json())} namespace(s).")+PY+```++A successful response with zero namespaces is valid for an account with no+pools. This verifies authentication and namespace listing; pool creation still+depends on account permissions, admission rules, and resource availability.+If the token request fails, check the client ID, secret, and token endpoint. If+the Fleet request returns `401` or `403`, resolve the account access problem+before provisioning; contact support if the credentials are correct.++## Credential lifetime and revocation++A user API key is the client ID and secret used to request access tokens.+Access-token lifetime comes from the issuer's `expires_in` response; do not+assume a fixed duration. The key-creation form does not offer an expiration+setting. When you finish using a key, return to **API keys**, select **Revoke**+for that key, and confirm **Revoke** in **Revoke API key?**. Revocation removes+the OAuth client so it cannot obtain new tokens. Already-issued access tokens+can remain usable until they expire.++`cua auth logout` revokes the CLI session's refresh token and clears its local+vault entry. It does not revoke a Fleet user API key or unset environment+variables. Remove your local secret references after revoking the key.++## Existing access tokens and GitHub Actions++If you already have a valid Fleet bearer token, the Sandbox SDK also accepts:++```bash+export FLEETS_TOKEN="<your-access-token>"+```++A pasted token is not an OAuth client secret and cannot renew itself. Replace+it when it expires and restart clients that hold it. For GitHub Actions, use+the [workload identity flow](/reference/cua-cli/authentication#github-actions) instead of copying an interactive+CLI session token. Terraform uses different variable names; see+[Configure a sandbox pool with Terraform](/how-to-guides/sandbox/configure-pool-with-terraform#authentication).diff --git a/docs/content/docs/reference/cua-cli/authentication.mdx b/docs/content/docs/reference/cua-cli/authentication.mdxindex d7c8b5c401..0a244af7c5 100644--- a/docs/content/docs/reference/cua-cli/authentication.mdx+++ b/docs/content/docs/reference/cua-cli/authentication.mdx@@ -1,6 +1,6 @@----title: Authentication-description: 'Authenticate the cua CLI and Fleet SDK, create a Fleet user API key, and check access before provisioning.'+title: CLI authentication+description: 'Authenticate the cua CLI, choose credential storage, and configure workload identity.'---import { Callout } from 'fumadocs-ui/components/callout';@@ -76,11 +76,10 @@ is not limited to `login`: `cua auth status` and every authenticated commandraise the same error, because reading the vault fails the same way writing does.<Callout type="warn">- **What is at stake is a refresh token, not just an access token.** The stored- credential re-mints access tokens on demand, so it stays useful long after any- access token it produced has expired, and automatic refresh keeps rewriting it- so it never goes stale on its own. Whoever reads it holds your Cua session- until it is revoked. Choose the storage backend accordingly, and prefer an+ **What is at stake is a refresh token, not just an access token.** The stored credential re-mints+ access tokens on demand, so it stays useful long after any access token it produced has expired,+ and automatic refresh keeps rewriting it so it never goes stale on its own. Whoever reads it holds+ your Cua session until it is revoked. Choose the storage backend accordingly, and prefer anencrypted one wherever the host outlives the job.</Callout>@@ -146,11 +145,10 @@ on its own once installed. Set it anyway: it pins the choice, so installinganother backend later cannot silently move where your tokens are kept.<Callout type="warn">- **`PlaintextKeyring` does not encrypt anything.** Values are base64-encoded,- which is an encoding and not a protection — anyone who can read the file can- recover the token with one command. File permissions are the only real barrier,- and they do not survive a backup, a snapshot, a stray `tar`, or another user- with root. Prefer Option 1 whenever the host persists.+ **`PlaintextKeyring` does not encrypt anything.** Values are base64-encoded, which is an encoding+ and not a protection — anyone who can read the file can recover the token with one command. File+ permissions are the only real barrier, and they do not survive a backup, a snapshot, a stray+ `tar`, or another user with root. Prefer Option 1 whenever the host persists.</Callout>### Option 3: a real keyring@@ -170,32 +168,32 @@ See [GitHub Actions](#github-actions) below.The CLI itself reads only these:-| Variable | Effect |-|----------|--------|-| `FLEETS_TOKEN` | Fleet workload token. When set, it takes precedence over the interactive session for Fleet operations. |-| `CUA_MCP_PERMISSIONS` | Default permission list for `cua serve-mcp`, overridden by `--permissions`. |-| `CUA_SANDBOX` | Default sandbox for MCP computer tools, overridden by `--sandbox`. |-| `ANTHROPIC_API_KEY` | Used by `cua do snapshot` and by `cua skills record --provider anthropic`. |-| `OPENAI_API_KEY` | Used by `cua skills record --provider openai`. |-| `PYTHON_KEYRING_BACKEND` | Read by the `keyring` library to select where credentials are stored. |-| `XDG_DATA_HOME`, `XDG_STATE_HOME` | Move `~/.local/share/cua` and `~/.local/state/cua`. |+| Variable | Effect |+| --------------------------------- | ------------------------------------------------------------------------------------------------------ |+| `FLEETS_TOKEN` | Fleet workload token. When set, it takes precedence over the interactive session for Fleet operations. |+| `CUA_MCP_PERMISSIONS` | Default permission list for `cua serve-mcp`, overridden by `--permissions`. |+| `CUA_SANDBOX` | Default sandbox for MCP computer tools, overridden by `--sandbox`. |+| `ANTHROPIC_API_KEY` | Used by `cua do snapshot` and by `cua skills record --provider anthropic`. |+| `OPENAI_API_KEY` | Used by `cua skills record --provider openai`. |+| `PYTHON_KEYRING_BACKEND` | Read by the `keyring` library to select where credentials are stored. |+| `XDG_DATA_HOME`, `XDG_STATE_HOME` | Move `~/.local/share/cua` and `~/.local/state/cua`. |The Sandbox SDK reads a further set. These apply when you import `cua_sandbox`in your own code:-| Variable | Effect |-|----------|--------|-| `CUA_API_KEY` | API key for cloud sandboxes. |-| `CUA_BASE_URL` | Base URL for the older VM API. Its default, `https://api.cua.ai`, is a retired host — set this explicitly if you use that API. |-| `CUA_FLEET_BASE_URL` | Base URL for the Fleet API. Defaults to `https://run.cua.ai`. |-| `CUA_TOKEN_URL` | OAuth token endpoint for client-credentials auth. |-| `CUA_CLIENT_ID`, `CUA_CLIENT_SECRET` | OAuth client credentials for Fleet. |-| `FLEETS_TOKEN` | Static Fleet workload token, checked before client credentials. |+| Variable | Effect |+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |+| `CUA_API_KEY` | API key for cloud sandboxes. |+| `CUA_BASE_URL` | Base URL for the older VM API. Its default, `https://api.cua.ai`, is a retired host — set this explicitly if you use that API. |+| `CUA_FLEET_BASE_URL` | Base URL for the Fleet API. Defaults to `https://run.cua.ai`. |+| `CUA_TOKEN_URL` | OAuth token endpoint for client-credentials auth. |+| `CUA_CLIENT_ID`, `CUA_CLIENT_SECRET` | OAuth client credentials for Fleet. |+| `FLEETS_TOKEN` | Static Fleet workload token, checked before client credentials. |<Callout type="info">- `CUA_BASE_URL` has no effect on `cua` commands. The CLI overwrites it at- startup so that cloud requests always go to `https://run.cua.ai`, whatever the- environment says. Set it only for direct SDK use.+ `CUA_BASE_URL` has no effect on `cua` commands. The CLI overwrites it at startup so that cloud+ requests always go to `https://run.cua.ai`, whatever the environment says. Set it only for direct+ SDK use.</Callout>Fleet requests — the `--pool` path and everything `cua wif-token` feeds — go to@@ -204,13 +202,11 @@ cloud API. `CUA_BASE_URL` addresses the older VM API instead, and its defaulthost is retired.<Callout type="warn">- **`CUA_API_KEY` is not a way to skip logging in, and setting it makes things- worse rather than better.** The SDK picks its transport with- `_uses_fleet(api_key)`, which is true only when **no** API key is supplied. So- providing one routes the call away from Fleet and onto the older VM API —- whose host is retired — and it will fail there no matter how valid the key is.- `FLEETS_TOKEN` is the environment variable that actually reaches a working- API.+ **`CUA_API_KEY` is not a way to skip logging in, and setting it makes things worse rather than+ better.** The SDK picks its transport with `_uses_fleet(api_key)`, which is true only when **no**+ API key is supplied. So providing one routes the call away from Fleet and onto the older VM API —+ whose host is retired — and it will fail there no matter how valid the key is. `FLEETS_TOKEN` is+ the environment variable that actually reaches a working API.</Callout>`CUA_API_KEY` is not an authentication path for the CLI either: `cua` passes its@@ -219,126 +215,29 @@ takes precedence over the environment.## Fleet pools need their own credentials-The Fleet SDK accepts an OAuth user API key or a Fleet bearer access token.-`cua auth login` stores an interactive CLI session in the credential vault;-it does not export either credential for the SDK. `cua sb launch --pool` also-uses the SDK's separate credential configuration. Without it, even a logged-in-CLI can fail with:--```console-$ cua sb launch --pool my-pool --name my-sandbox-Error: Fleet cloud sandboxes require CUA_CLIENT_ID and CUA_CLIENT_SECRET, or cua.configure(client_id=..., client_secret=...).-```+CLI login does not configure the Sandbox SDK or `cua sb launch --pool`.+Follow [Set up Fleet credentials](/how-to-guides/sandbox/set-up-fleet-credentials)+for the complete procedure.### Create a Fleet user API key-You need an account that can sign in to [Cua Fleet](https://run.cua.ai) and-access **API keys**. Create the key while signed in as the account that will-own the pools. User keys act on behalf of their owner; creating a key does not-grant access to another account's pools or bypass pool admission rules.--1. Sign in to [Cua Fleet](https://run.cua.ai), then select **API keys** in the- navigation, or open the [API keys page](https://run.cua.ai/user-keys).-2. Under **Create API key**, enter a descriptive **Name**, such as- `first-fleet-tutorial`. For the first-Fleet tutorial, leave- **Allowed Namespaces (optional)** at its default,- **All namespaces (no restriction)**, because the tutorial creates a new- pool namespace.-3. Select **Create key**. In **API key created**, copy **Client ID** and- **Client Secret** into your secret manager before selecting- **I have copied the credentials**. The secret is shown only once.--If you cannot sign in, the page reports **API keys are unavailable**, or key-creation is denied, contact [Cua support on Discord](https://discord.gg/mVnXXpdE85)-to check account access before continuing. `cua auth login` is not a substitute-for this key-creation step.--Pool creation can also require a payment method. If Fleet shows-**Payment method required**, open **Settings** and use **Add payment method**-under **Payment method**. Review the applicable pricing and terms before-adding a payment method or creating billable resources. The read-only access-check below does not create a pool or claim.+See [Create a Fleet user API key](/how-to-guides/sandbox/set-up-fleet-credentials#create-a-fleet-user-api-key).### Configure the Sandbox SDK-Set `CUA_CLIENT_ID` to **Client ID** and `CUA_CLIENT_SECRET` to **Client Secret**.-The token endpoint below is the default for `run.cua.ai`; the dashboard's-credential dialog does not display it:--```bash-export CUA_CLIENT_ID="<your-client-id>"-export CUA_CLIENT_SECRET="<your-client-secret>"-export CUA_TOKEN_URL="https://auth.cua.ai/realms/cyclops-cs/protocol/openid-connect/token"-unset FLEETS_TOKEN-```--`FLEETS_TOKEN` takes precedence over these client credentials, so unset it when-switching to a user key. Inject secrets through your secret manager where-possible; do not commit them or paste them into shared logs.+See [Configure the Sandbox SDK](/how-to-guides/sandbox/set-up-fleet-credentials#configure-the-sandbox-sdk).### Check access before provisioning-With [uv](https://docs.astral.sh/uv/) installed, run this check in the same-shell. It exchanges the user key for a short-lived access token and sends-`GET /api/namespaces`. It prints only the number of namespaces returned:--```bash-uv run --with 'httpx>=0.27,<1' python - <<'PY'-import os--import httpx--with httpx.Client(timeout=30) as client:- token_response = client.post(- os.environ["CUA_TOKEN_URL"],- auth=(os.environ["CUA_CLIENT_ID"], os.environ["CUA_CLIENT_SECRET"]),- data={"grant_type": "client_credentials"},- )- token_response.raise_for_status()- access_token = token_response.json()["access_token"]- response = client.get(- "https://run.cua.ai/api/namespaces",- headers={"Authorization": f"Bearer {access_token}"},- )- response.raise_for_status()- print(f"Fleet access verified: {len(response.json())} namespace(s).")-PY-```--A successful response with zero namespaces is valid for an account with no-pools. This verifies authentication and namespace listing; pool creation still-depends on account permissions, admission rules, and resource availability.-If the token request fails, check the client ID, secret, and token endpoint. If-the Fleet request returns `401` or `403`, resolve the account access problem-before provisioning; contact support if the credentials are correct.+See [Check access before provisioning](/how-to-guides/sandbox/set-up-fleet-credentials#check-access-before-provisioning).### Credential lifetime and revocation-A user API key is the client ID and secret used to request access tokens.-Access-token lifetime comes from the issuer's `expires_in` response; do not-assume a fixed duration. The key-creation form does not offer an expiration-setting. When you finish using a key, return to **API keys**, select **Revoke**-for that key, and confirm **Revoke** in **Revoke API key?**. Revocation removes-the OAuth client so it cannot obtain new tokens. Already-issued access tokens-can remain usable until they expire.--`cua auth logout` revokes the CLI session's refresh token and clears its local-vault entry. It does not revoke a Fleet user API key or unset environment-variables. Remove your local secret references after revoking the key.+See [Credential lifetime and revocation](/how-to-guides/sandbox/set-up-fleet-credentials#credential-lifetime-and-revocation).### Existing access tokens and GitHub Actions-If you already have a valid Fleet bearer token, the Sandbox SDK also accepts:--```bash-export FLEETS_TOKEN="<your-access-token>"-```--A pasted token is not an OAuth client secret and cannot renew itself. Replace-it when it expires and restart clients that hold it. For GitHub Actions, use-the [workload identity flow](#github-actions) instead of copying an interactive-CLI session token. Terraform uses different variable names; see-[Configure a sandbox pool with Terraform](/how-to-guides/sandbox/configure-pool-with-terraform#authentication).+See [Existing access tokens and GitHub Actions](/how-to-guides/sandbox/set-up-fleet-credentials#existing-access-tokens-and-github-actions).## GitHub Actions@@ -373,7 +272,6 @@ releases the claim while preserving the reconciled one-replica pool, template,and namespace for the next claim.<Callout type="info">- Under `FLEETS_TOKEN`, `cua sb ls` exits with- `Listing Fleet sandboxes is not supported; use 'cua sb info NAME'.` Address- Fleet sandboxes by name.+ Under `FLEETS_TOKEN`, `cua sb ls` exits with `Listing Fleet sandboxes is not supported; use 'cua+ sb info NAME'.` Address Fleet sandboxes by name.</Callout>diff --git a/docs/content/docs/tutorials/your-first-cloud-fleet.mdx b/docs/content/docs/tutorials/your-first-cloud-fleet.mdxindex 334955b244..25b41362aa 100644--- a/docs/content/docs/tutorials/your-first-cloud-fleet.mdx+++ b/docs/content/docs/tutorials/your-first-cloud-fleet.mdx@@ -23,7 +23,7 @@ active desktop as a claim on that pool.## 1. Authenticate with Fleet-First, [create a Fleet user API key and check access](/reference/cua-cli/authentication#fleet-pools-need-their-own-credentials).+First, [create a Fleet user API key and check access](/how-to-guides/sandbox/set-up-fleet-credentials).That setup explains account access, the **API keys** page, payment-methodrequirements, and a read-only check that does not provision cloud resources.Complete it before continuing.@@ -270,4 +270,5 @@ claim releases the sandbox, and namespace deletion requests resource removal.- [Create a reusable sandbox pool with Python](/how-to-guides/sandbox/create-pool-with-python)- [Configure a sandbox pool with Terraform](/how-to-guides/sandbox/configure-pool-with-terraform)- [Expire pools and claims automatically](/how-to-guides/sandbox/expire-pools-and-claims)+- [Choose a sandbox image](/how-to-guides/sandbox/choose-an-image)- [Sandbox SDK API reference](/reference/sandbox-sdk)