Cua client

Every program starts from one Cua handle, embedded in the process or connected to a running cua daemon, with the same API either way. Its accessors return the other objects. The config_* functions read and write the user defaults in $CUA_HOME/config.toml (cua config).

connect() without an address reads ~/.cua/daemon.json, then the socket ~/.cua/cua.sock. The connection is lazy: the first call fails with Transport when no daemon runs (cua daemon start). An embedded client reads Fleet credentials from FLEETS_TOKEN, or CUA_CLIENT_ID and CUA_CLIENT_SECRET (with CUA_FLEET_BASE_URL and CUA_TOKEN_URL), unless fleet_from_env is off.

Cua#

The entry point of the SDK: create one with Cua::embedded or Cua::connect, then reach sandboxes, Fleet, Spaces and the rest through its accessors.

Cua.auto#

The default topology: the cua daemon this machine runs when one accepts connections (so the CLI, MCP clients and apps share sandboxes and Spaces), else the runtime in this process with config. A discovery file (~/.cua/daemon.json) or socket left by a daemon that exited is not a running daemon: the files are removed when their pid is provably dead, and this falls back to embedded. A daemon that is starting (~/.cua/daemon.starting) is waited for, up to 30 s. Probes with a local connect only (no RPC), except in a process inside an app bundle that ships its own cua: it uses only that build's daemon, and fails with CuaError.DaemonNotRunning naming the running one (another app's, or its own before a rebuild or update) rather than silently use it; <bundle>/Contents/MacOS/cua daemon start replaces it.

@classmethod
def auto(cls, config: CuaConfig) -> Cua

Returns Cua · Raises CuaError (DaemonNotRunning)

Cua.connect#

Connects to a running cua daemon. address is a socket path (unix: prefix optional) or a loopback URL (then token is required unless the discovery file has it); None uses ~/.cua/daemon.json, then ~/.cua/cua.sock. Connects lazily: the first call fails with DaemonNotRunning when no daemon runs; use Cua.info to check, or Cua.auto to fall back to the runtime in this process.

@classmethod
def connect(cls, address: Optional[str], token: Optional[str]) -> Cua

Returns Cua · Raises CuaError (DaemonNotRunning)

Cua.embedded#

Runs the SDK runtime in this process. Performs no I/O beyond reading the credential store when fleet_from_session is set.

@classmethod
def embedded(cls, config: CuaConfig) -> Cua

Returns Cua · Raises CuaError

Example

import cua
 
c = cua.embedded()  # the SDK runs in this process; cua.connect() uses a running `cua daemon`
print(c.mode())

Cua.fleet#

Fleet pools, templates, claims and images. Always talks to Fleet from this process with this SDK's credentials (in daemon mode, from the environment).

def fleet(self) -> Fleet

Returns Fleet · Raises CuaError

Cua.info#

SDK (and daemon) identity. In daemon mode this is the connectivity check.

async def info(self) -> CuaInfo

Returns CuaInfo · Async · Raises CuaError

Cua.shutdown_daemon#

Asks a connected daemon to stop (daemon mode only).

async def shutdown_daemon(self) -> None

Async · Raises CuaError

Cua.spacesd#

Connects to cua-spacesd at url (host:port, http(s)://…, a Fleet service URL or a relay URL) without a sandbox.

async def spacesd(self, url: str, token: Optional[str]) -> SpacesdClient

Returns SpacesdClient · Async · Raises CuaError

CuaConfig record#

Configuration of an embedded SDK runtime.

FleetSettings record#

Fleet credentials and endpoints. Unset fields fall back to the environment (CUA_FLEET_BASE_URL, CUA_TOKEN_URL, CUA_CLIENT_ID, CUA_CLIENT_SECRET, FLEETS_TOKEN) when CuaConfig.fleet_from_env.

CuaInfo record#

Identity of the SDK (and daemon, when connected).

Returned by Cua.info.

CuaMode enum#

Where the SDK runtime lives.

CuaMode.EMBEDDED
CuaMode.DAEMON

cua_sdk_version#

Version of the SDK library.

def cua_sdk_version() -> str

Returns String

config_list#

Every setting with its effective value and source.

def config_list() -> List[ConfigEntry]

Returns Vec<ConfigEntry> · Raises CuaError

config_get#

One setting's effective value and source.

def config_get(key: str) -> ConfigEntry

Returns ConfigEntry · Raises CuaError

config_set#

Writes a setting to the config file (checked and normalised: default.on takes local, cloud or a provider). Returns its effective value, which an environment variable may still override.

def config_set(key: str, value: str) -> ConfigEntry

Returns ConfigEntry · Raises CuaError

config_unset#

Removes a setting from the config file. Returns its effective value afterwards (the environment variable or the built-in default).

def config_unset(key: str) -> ConfigEntry

Returns ConfigEntry · Raises CuaError

config_path#

The config file's path ($CUA_HOME/config.toml).

def config_path() -> str

Returns String

ConfigEntry record#

One setting's effective value.

Returned by config_get, config_list, config_set, config_unset.

locations#

Every location with the kinds and runtimes it offers (for pickers and help text).

def locations() -> List[LocationInfo]

Returns Vec<LocationInfo>

LocationInfo record#

The locations on accepts: local, cloud, then registered providers.

Returned by locations.

check_placement#

Checks a location, kind and runtime against each other without creating anything: InvalidPlacement (listing the valid values) when the combination does not exist. Empty strings are auto; an empty on is the user default.

def check_placement(on: str, kind: str, runtime: str) -> None

Raises CuaError (InvalidPlacement)

error_doc_url#

A link to the errors-reference entry of a CuaError variant, by name (InvalidArgument, case-insensitive). An unknown name links to the page itself. The bindings' doc_url / docUrl on CuaError use it.

def error_doc_url(variant: str) -> str

Returns String