Authenticate

One sign-in covers the CLI, the SDK, cua daemon and the Cua Spaces app: they share one credential store. Local sandboxes need no sign-in.

Sign in#

cua auth login              # browser (PKCE, loopback redirect)
cua auth login --remote     # device code, for SSH sessions
cua auth whoami             # the Fleet credential in use, checked against Fleet
cua auth status             # session and expiry, no network
cua auth logout             # revoke and remove the session

After an interactive login, cua auth login offers to set up your AI coding agents (skills plus the cua MCP server); --agents claude,codex, --yes, --skills-only, --mcp-only and --no-onboarding control it, and never is remembered in ~/.cua/config. Tokens refresh automatically and are never printed.

CUA_CREDENTIAL_STORE=file or keychain picks the store. A build from source is a new app to the Keychain every time it is rebuilt, so it uses the file and never asks for Keychain access.

Which credential Fleet uses#

The first that is set wins:

Legacy key_... keys belong to the retired VM API and do not work with Fleet.

API keys#

Create keys from a login session (an API key cannot manage keys: exit 6):

cua auth keys create ci-runner      # prints CUA_CLIENT_ID and CUA_CLIENT_SECRET once
cua auth keys ls
cua auth keys rm <id>

GitHub Actions#

cua wif-token github exchanges the job's OIDC identity for a Fleet token. It needs id-token: write and a Fleet trust policy for the repository:

permissions:
  id-token: write
  contents: read
 
steps:
  - name: Use a cloud sandbox
    run: |
      export FLEETS_TOKEN="$(cua wif-token github)"
      cua sb create linux --on cloud --name "run-$GITHUB_RUN_ID"
      cua sb exec "run-$GITHUB_RUN_ID" "uname -a"
      cua sb rm "run-$GITHUB_RUN_ID" --force

Targeting staging#

CUA_ENV=staging points the CLI, the SDK, cua daemon and the Cua Spaces app at the Cua staging deployment. Unset, or prod, is production. Any other value makes cua exit with code 2 rather than fall back to production.

export CUA_ENV=staging
cua auth login --remote     # device code against the staging realm
cua auth status             # starts with "Environment: staging (...)"

Each environment has its own session, host enrollment, Spaces registry and daemon, so signing in to staging never replaces or sends your production session, and the other way round. Fleet has no staging deployment: under CUA_ENV=staging the CLI does not send the staging session to https://run.cua.ai, so cloud sandboxes need CUA_FLEET_BASE_URL set to a non-production Fleet, or an API key.

Usage telemetry follows the environment too: staging events go to the staging PostHog project, never to production's. CUA_POSTHOG_KEY overrides the project key; CUA_TELEMETRY_ENDPOINT overrides the ingest URL.

Beta channel builds talk to staging by default. A cua compiled with CUA_DEFAULT_ENV=staging treats an unset CUA_ENV as staging, and the macOS app built with scripts/build-release.sh --channel beta carries CuaEnv=staging in its Info.plist and compiles its bundled cua the same way. CUA_ENV=prod still selects production in a beta build.

For the macOS app, launch it with the variable set: open -n --env CUA_ENV=staging -a "Cua Spaces". Quit the production app first. The host service (cua host setup) has one name on each machine, so pair a staging host on a separate machine or VM.

Other variables (CUA_FLEET_BASE_URL, CUA_OIDC_ISSUER, CUA_AUTH_FLOW, CUA_NO_BROWSER, ...) are listed in the CLI reference.