Auth and telemetry

Sign-in, the credential store the SDK, the CLI and the daemon share, and the telemetry switches.

cua.auth() signs in and reads the shared session. Cloud calls use it when no client credentials are configured.

Python programs usually use the high-level API instead: cua_sandbox.configure().

Auth#

Sign-in and the shared session.

Returned by Cua.auth.

Auth.access_token#

A valid access token (refreshed when it expires within a minute, or when force). Unauthenticated when not signed in.

async def access_token(self, force: bool) -> str

Returns String · Async · Raises CuaError (Unauthenticated)

Auth.begin_login#

Starts a sign-in. flow: auto (default: browser, else device code), browser or device.

async def begin_login(self, flow: Optional[str]) -> LoginAttempt

Returns LoginAttempt · Async · Raises CuaError

Auth.devices#

This device on relay_url (None = the relay cua uses: CUA_RELAY_URL, else this machine's host setup, else https://relay.cua.ai) as the signed-in account, shown as name (default: this computer's name).

def devices(self, relay_url: Optional[str], name: Optional[str]) -> Devices

Returns Devices · Raises CuaError

Auth.logout#

Revokes (best effort) and removes the session, and unlinks usage data from the account. Returns whether one existed.

async def logout(self) -> bool

Returns bool · Async · Raises CuaError

Auth.status#

The stored session (no network).

def status(self) -> AuthStatus

Returns AuthStatus · Raises CuaError

LoginAttempt#

A started sign-in. Show url (and user_code), then await wait().

Returned by Auth.begin_login.

LoginAttempt.wait#

Waits for the user, stores the session and returns who signed in. Only the first call waits; later calls fail.

This device then registers with the relay (the one cua uses: CUA_RELAY_URL, else this machine's host setup, else relay.cua.ai), creating its device key on first use, so the fresh sign-in enrolls or re-verifies it without an approval. That step is best effort and never fails the sign-in.

async def wait(self) -> AuthIdentity

Returns AuthIdentity · Async · Raises CuaError

AuthIdentity record#

Who is signed in (from token claims; display only).

Returned by LoginAttempt.wait.

AuthStatus record#

The stored session, read without network access.

Returned by Auth.status.

LoginMethod enum#

How a sign-in proceeds.

LoginMethod.BROWSER
LoginMethod.DEVICE

may_have_session#

Whether a cua auth login session may be stored, decided without reading the OS credential vault (the non-secret session marker, or the file store's file). Implicit callers (the default sandbox listing) check this before reading the session; an explicit read of a session stored before markers existed writes the marker.

def may_have_session() -> bool

Returns bool

Telemetry#

What is collected and never collected: Telemetry and privacy. These calls read and change the same switches as cua telemetry; the SDK records its own events.

telemetry_status#

Telemetry state, and exactly what every event carries.

def telemetry_status() -> TelemetryStatus

Returns TelemetryStatus

telemetry_set_enabled#

Turns usage telemetry on or off for this machine ($CUA_HOME/config.toml, the same switch as cua telemetry off and the Spaces app setting). The environment (DO_NOT_TRACK, CUA_TELEMETRY) still wins.

def telemetry_set_enabled(enabled: bool) -> TelemetryStatus

Returns TelemetryStatus · Raises CuaError

telemetry_show_last#

The last limit events queued or sent from this machine, exactly as sent, as JSON ([{status, payload}]).

def telemetry_show_last(limit: int) -> str

Returns String

telemetry_schema_json#

Every event and property that may be sent, as JSON.

def telemetry_schema_json() -> str

Returns String

telemetry_reset_id#

Deletes the anonymous install id and its salt.

def telemetry_reset_id() -> None

Raises CuaError

StreamStatsReport record#

One stream session's aggregate stats (sampled).

TelemetryLinkNotice record#

The one-time notice for machines that saw the older "anonymous" wording, shown before anything is linked to the account. Both buttons close it; the second also turns usage data off.

Returned by telemetry_link_notice.

TelemetryStatus record#

Telemetry state.

Returned by telemetry_set_enabled, telemetry_status.

telemetry_acknowledge_link_notice#

The person closed the linking notice (either button). Linking starts with the app's next launch, never in the process that showed it.

def telemetry_acknowledge_link_notice() -> None

telemetry_acknowledge_notice#

Records that the first-run notice was shown in the app's UI (nothing is sent from a machine before that). Apps that show the notice themselves call telemetry_use_app_notice first so the SDK does not print it.

def telemetry_acknowledge_notice() -> None

telemetry_flush#

Sends queued events now, waiting at most timeout_ms; anything left is kept on disk for a later process.

def telemetry_flush(timeout_ms: int) -> None

telemetry_link_notice#

The one-time linking notice's words.

def telemetry_link_notice() -> TelemetryLinkNotice

Returns TelemetryLinkNotice

telemetry_link_notice_due#

Whether the app should show the one-time linking notice now: usage data is on, the account offered linking, and this machine has not shown it.

def telemetry_link_notice_due() -> bool

Returns bool

telemetry_link_state#

Where linking stands: off, not_offered, notice_due or linked.

def telemetry_link_state() -> str

Returns String

telemetry_notice_text#

The first-run notice text (an app shows it in its own UI, then calls telemetry_acknowledge_notice).

def telemetry_notice_text() -> str

Returns String

telemetry_record_bench_run#

Records a finished cua-bench run: the taskset (catalog name, else custom), the aggregate success rate (0 to 1, bucketed), the task count (bucketed) and the outcome (ok, error, cancelled).

def telemetry_record_bench_run(taskset: str, success_rate: Optional[float], task_count: int, outcome: str) -> bool

Returns bool

telemetry_record_feature#

Records use of a Spaces app feature (fixed names: space_create_local, teleport_drop, ... see the docs). Returns whether it was queued; unknown names are dropped.

def telemetry_record_feature(feature: str) -> bool

Returns bool

telemetry_record_onboarding_step#

Records an install or onboarding funnel step (fixed names: onboarding_shown, signed_in, first_space_created, ...; first_* steps count once per install). Returns whether it was queued.

def telemetry_record_onboarding_step(step: str, ok: bool) -> bool

Returns bool

telemetry_record_stream_stats#

Records one stream session's aggregate stats (bucketed and sampled).

def telemetry_record_stream_stats(stats: StreamStatsReport) -> bool

Returns bool

telemetry_set_surface#

Names the SDK surface events are attributed to. Bindings call it at import: sdk_python, sdk_typescript, sdk_swift, sdk_kotlin; apps pass their own product (spaces_app). Unknown names are ignored.

def telemetry_set_surface(surface: str, version: str) -> None

telemetry_sync_account#

Asks the Spaces API for the signed-in account's opaque id and hands it to telemetry (none unlinks). Call at launch and after a sign-in; the SDK's own sign-in already does. Returns the link state. Best effort: offline or signed out, nothing changes.

async def telemetry_sync_account() -> str

Returns String · Async

telemetry_use_app_notice#

The host app shows the first-run notice itself (no stderr notice).

def telemetry_use_app_notice() -> None