Configuration and errors

Process-wide settings, sign-in helpers, transports and the typed errors of cua-sandbox.

Configuration and sign-in#

configure#

def configure(
    *,
    api_key: Optional[str] = None,
    base_url: Optional[str] = None,
    fleet_base_url: Optional[str] = None,
    token_url: Optional[str] = None,
    client_id: Optional[str] = None,
    client_secret: Optional[str] = None,
    fleet_token: Optional[str] = None,
) -> None

Set global configuration for cloud sandboxes.

API-key cloud operations use base_url. Fleet uses fleet_base_url and OAuth client credentials.

fleet_auth_source#

def fleet_auth_source(*, read_session: bool = True) -> Optional[str]

Where Fleet credentials come from, in the order the SDK uses them.

"FLEETS_TOKEN" (a workload token), "client credentials" (CUA_CLIENT_ID/CUA_CLIENT_SECRET), "cua auth login session" (the stored session, refreshed by the SDK while it is used) or None when nothing is configured. A stored session is only looked up when neither of the first two is set. read_session=False decides that from the non-secret session marker alone, without reading the OS credential vault (for dashboards and other implicit checks).

login#

def login(*, base_url: Optional[str] = None) -> None

Open the CUA login page in a browser and store credentials.

This initiates a Clerk-based browser authentication flow. The user completes login in their browser, and the resulting API key is stored in ~/.cua/credentials.

whoami#

def whoami(*, api_key: Optional[str] = None) -> Dict[str, Any]

Return info about the authenticated user.

Returns: Dict with user info (id, email, etc.) from the CUA API.

Errors#

SpacesdNotAvailable#

class SpacesdNotAvailable(RuntimeError)

The sandbox has no reachable cua-spacesd.

Sandboxes are daemon-agnostic: creating, listing and deleting them never needs a guest agent. The computer interfaces (screen, mouse, shell, files ...) need cua-spacesd, or one of the agentless transports (QMP, VNC, SSH, ADB) the runtime exposes.

InvalidArgument#

class InvalidArgument(ValueError)

Contradictory or invalid options (the native SDK's CuaError.InvalidArgument), for example local=True together with cloud=CloudOptions(...).

InvalidPlacement#

class InvalidPlacement(InvalidArgument)

A location, kind and runtime that do not go together (the native SDK's CuaError.InvalidPlacement), for example kind="container" with runtime="qemu", or runtime="kubevirt" locally. The message lists the valid values.

Unsupported#

class Unsupported(NotImplementedError)

The operation is not supported for this sandbox, image or provider (the native SDK's CuaError.Unsupported). A NotImplementedError, so older except NotImplementedError handlers still catch it.

Transports#

CloudTransport#

class CloudTransport(Transport)

Compatibility shim for the removed API-key cloud transport.

Constructing it still works (and keeps the requested image), so code that builds one fails at connect() with a message pointing to Fleet.

CloudTransport.connect#

async def connect() -> None

CloudTransport.disconnect#

async def disconnect() -> None

CloudTransport.delete_vm#

async def delete_vm() -> None

Delete an existing API-key VM through the platform API.

CloudTransport.create_snapshot#

async def create_snapshot(name: str | None = None, stateful: bool = False) -> dict

CloudTransport.send#

async def send(action: str, **params: Any) -> Any

CloudTransport.screenshot#

async def screenshot(format: str = 'png', quality: int = 95) -> bytes

CloudTransport.get_screen_size#

async def get_screen_size() -> Dict[str, int]

CloudTransport.get_environment#

async def get_environment() -> str

EnvTransport#

class EnvTransport(Transport)

Drives a sandbox through cua-spacesd.

EnvTransport.connect#

async def connect() -> None

EnvTransport.disconnect#

async def disconnect() -> None

EnvTransport.spacesd#

async def spacesd() -> Any

The raw cua.SpacesdClient (typed client escape hatch).

EnvTransport.send#

async def send(action: str, **params: Any) -> Any

EnvTransport.screenshot#

async def screenshot(format: str = 'png', quality: int = 95) -> bytes

EnvTransport.get_screen_size#

async def get_screen_size() -> Dict[str, int]

EnvTransport.get_environment#

async def get_environment() -> str

EnvTransport.get_display_url#

async def get_display_url(*, share: bool = False) -> str

A browser URL for the sandbox's display.

With cua-spacesd (an env or viewer service), a link to its HTML5 viewer carrying a scoped, expiring viewer ticket; the same link serves share=True. For images without cua-spacesd, the page of the first declared legacy web display service (novnc, display, web; a raw RFB port 59xx is skipped, and share=True returns its expiring public link), then the agentless fallback's VNC address.

EnvTransport.request_service#

async def request_service(
    name: str,
    *,
    method: str,
    path: str,
    json_body: Any = None,
    headers: Any = None,
) -> Any

EnvTransport.native_handle#

async def native_handle() -> Any

The cua.Sandbox handle behind this transport (services, forwards, public URLs).

EnvTransport.native_service#

async def native_service(name: str) -> Any

EnvTransport.forward_tunnel#

async def forward_tunnel(sandbox_port: int | str) -> 'TunnelInfo'

EnvTransport.close_tunnel#

async def close_tunnel(info: 'TunnelInfo') -> None

EnvTransport.pty_create#

async def pty_create(
    command: Optional[str] = None,
    cols: int = 120,
    rows: int = 40,
    cwd: Optional[str] = None,
    envs: Optional[Dict[str, str]] = None,
) -> Dict[str, Any]

EnvTransport.pty_send#

async def pty_send(pid: int, data: str) -> None

EnvTransport.pty_kill#

async def pty_kill(pid: int) -> bool

EnvTransport.pty_info#

async def pty_info(pid: int) -> Optional[Dict[str, Any]]