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): document credential acquisition and first authentication (#3556)
Francesco Bonacci4a416b3d81c8
diff --git a/docs/content/docs/how-to-guides/sandbox/configure-pool-with-terraform.mdx b/docs/content/docs/how-to-guides/sandbox/configure-pool-with-terraform.mdxindex 296ee575cb..014e12a4fd 100644--- a/docs/content/docs/how-to-guides/sandbox/configure-pool-with-terraform.mdx+++ b/docs/content/docs/how-to-guides/sandbox/configure-pool-with-terraform.mdx@@ -22,15 +22,39 @@ For OpenTofu, run the same commands with `tofu` in place of `terraform`.## Authentication-The provider three OAuth user-key+The provider accepts either `CYCLOPS_ACCESS_TOKEN` or all three OAuth user-keyvariables: `CYCLOPS_CLIENT_ID`, `CYCLOPS_CLIENT_SECRET`, and-`CYCLOPS_TOKEN_URL`. Configure the run.cua.ai endpoint separately:+`CYCLOPS_TOKEN_URL`. First, [create a Fleet user API key and check access](/reference/cua-cli/authentication#fleet-pools-need-their-own-credentials).+That setup covers account access, payment-method requirements, and revocation.++Use the same key with the provider's variable names:++```bash+export CYCLOPS_ENDPOINT="https://run.cua.ai"+export CYCLOPS_CLIENT_ID="<your-client-id>"+export CYCLOPS_CLIENT_SECRET="<your-client-secret>"+export CYCLOPS_TOKEN_URL="https://auth.cua.ai/realms/cyclops-cs/protocol/openid-connect/token"+unset CYCLOPS_ACCESS_TOKEN+```++`CYCLOPS_CLIENT_ID` and `CYCLOPS_CLIENT_SECRET` are **Client ID** and+**Client Secret** from Fleet's **API key created** dialog. The token endpoint+above is for `run.cua.ai`. Unlike the Sandbox SDK, the provider requires an+explicit token URL when using client credentials.++For a short-lived workflow with an existing Fleet access token, use:```bashexport CYCLOPS_ENDPOINT="https://run.cua.ai"export CYCLOPS_ACCESS_TOKEN="<your-access-token>"```+`CYCLOPS_ACCESS_TOKEN` takes precedence over the client credentials. A pasted+token cannot renew itself; replace it when it expires before running Terraform+again. Provider arguments take precedence over their corresponding environment+variables. `cua auth login`, `CUA_CLIENT_ID`, `CUA_CLIENT_SECRET`, and+`FLEETS_TOKEN` do not configure the Terraform provider.+## Choose a sizing modeEvery `fleets_pool` must configure exactly one sizing mode:diff --git a/docs/content/docs/reference/cua-cli/authentication.mdx b/docs/content/docs/reference/cua-cli/authentication.mdxindex c7c697117b..d7c8b5c401 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: 'How the cua CLI logs in, where it stores tokens, how to authenticate on a headless host, and which environment variables take effect.'+description: 'Authenticate the cua CLI and Fleet SDK, create a Fleet user API key, and check access before provisioning.'---import { Callout } from 'fumadocs-ui/components/callout';@@ -9,6 +9,10 @@ import { Callout } from 'fumadocs-ui/components/callout';from the issuer `https://auth.cua.ai/realms/cyclops-cs`; authenticated cloudrequests then go to `https://run.cua.ai`.+For the Sandbox SDK, Terraform, or `cua sb launch --pool`, use the separate+[Fleet credential setup](#fleet-pools-need-their-own-credentials). A successful+CLI login does not export credentials for those clients.+## Logging in```bash@@ -215,28 +219,127 @@ takes precedence over the environment.## Fleet pools need their own credentials-`cua auth login` covers the CLI's own cloud calls, but it does not cover Fleet.-`cua sb launch --pool` invokes the SDK without passing the interactive session-through, and the SDK resolves Fleet credentials only from `FLEETS_TOKEN`, or-from `CUA_CLIENT_ID` and `CUA_CLIENT_SECRET`. With a perfectly valid session and-none of those exported, the command fails:+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-sandboxError: Fleet cloud sandboxes require CUA_CLIENT_ID and CUA_CLIENT_SECRET, or cua.configure(client_id=..., client_secret=...).```-`cua auth status` still reports a live session at that point, so the message is-easy to misread as an authentication failure. It is not — it is a different-credential for a different API. Export a client id and secret for interactive-use, or use `cua wif-token github` in CI:+### 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=...-export CUA_CLIENT_SECRET=...-cua sb launch --pool my-pool --name my-sandbox+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](#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).+## GitHub Actions`cua wif-token github` exchanges the job's GitHub OIDC identity for a Fleetsdiff --git a/docs/content/docs/tutorials/your-first-cloud-fleet.mdx b/docs/content/docs/tutorials/your-first-cloud-fleet.mdxindex 19b631300b..526c529197 100644--- a/docs/content/docs/tutorials/your-first-cloud-fleet.mdx+++ b/docs/content/docs/tutorials/your-first-cloud-fleet.mdx@@ -23,23 +23,24 @@ active desktop as a claim on that pool.## 1. Authenticate with Fleet-The SDK connects to `https://run.cua.ai` by default. Export a Fleet access-token:+First, [create a Fleet user API key and check access](/reference/cua-cli/authentication#fleet-pools-need-their-own-credentials).+That setup explains account access, the **API keys** page, payment-method+requirements, and a read-only check that does not provision cloud resources.+Complete it before continuing.-```bash-export FLEETS_TOKEN="<your-access-token>"-```--Or export OAuth client credentials:+The SDK connects to `https://run.cua.ai` by default. In the same shell, use the+**Client ID** and **Client Secret** from your Fleet key:```bashexport 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```-`cua auth login` does not supply credentials to the Fleet SDK. See-[Authentication](/reference/cua-cli/authentication#fleet-pools-need-their-own-credentials)-for the supported Fleet credential paths.+`cua auth login` does not supply credentials to the Fleet SDK. If you already+have a valid Fleet access token, you can set `FLEETS_TOKEN` instead; it takes+precedence over the client credentials and must remain valid through cleanup.## 2. Choose a unique Fleet name