Reference
The Cua SDK reference: every object with its signature in Python, TypeScript, Swift, Kotlin and Rust.
The Cua SDK in Python, TypeScript, Swift, Kotlin and Rust, all generated from the Rust cua-sdk crate. Each page covers one module, with signatures in every language.
| Language | Package | Import |
|---|---|---|
| Python | pip install cua (cua[sandbox] adds the high-level API; --no-deps skips the cua CLI) | import cua |
| TypeScript (Node) | npm install @trycua/cua | import { embedded } from '@trycua/cua' |
| Browser | @trycua/cua/browser (a WebAssembly subset) | import { Cua } from '@trycua/cua/browser' |
| Swift | Cua (macOS 12+, iOS 15+; not yet released) | import Cua |
| Kotlin | ai.cua.sdk (JNA; not yet released) | import ai.cua.sdk.* |
| Rust | cua-sdk from git (see Rust crates) | use cua_sdk::*; |
Sandboxes#
| Page | Covers |
|---|---|
| Cua client and local runtimes | The Cua handle (embedded or daemon client, configuration, SDK version) and the local container and VM runtimes. |
| Runtime per kind | Which program runs containers, virtual machines and microVMs on this machine, and what a given binary is. |
| Repo cache | What the repo cache holds and what it saved, and clearing it. |
| Sandbox | Create, find, connect to and control sandboxes, and their lifecycle: wait, suspend, resume, restart, detach and delete. |
| Lifecycle | Wait for, keep alive, give a lifetime to, suspend, resume, restart, resize, detach and delete a sandbox. |
| Checkpoints and forks | Save a local sandbox's state as a named checkpoint and start new sandboxes from it. |
| Batched forks | Fork checkpoints many times at once, on this machine or across your machines, each fork streamed as it is ready. |
| Bake a Compose stack | Save a running Docker Compose stack as a checkpoint that forks start from with their containers already up. |
| Shares | Links to a port, a file or a folder that open on your other signed-in devices. |
| Images and create options | Canonical images, image references, build layers, registry credentials, and the options Sandboxes.create takes. |
| Image catalog details | The canonical images, their variants per backend and architecture. |
| What's installed | The apps, tools and simulator runtimes in each image tier, as the strict doctor measured them. |
| Services | Named services, port forwards, public URLs and MCP clients of a sandbox. |
| Runtime support | Which images run on which local runtime and in the cloud. |
Inside a sandbox#
| Page | Covers |
|---|---|
| Spacesd client and processes | SpacesdClient: the cua-spacesd client, running processes in a sandbox, and sandboxes without cua-spacesd. |
| Processes | Run, spawn and attach to processes in a sandbox through cua-spacesd. |
| Files | Upload, download, list and remove files in a sandbox through cua-spacesd. |
| Computer and media | Screenshots, pointer, keyboard, clipboard and displays of a sandbox desktop, and its video and audio streams. |
| Coding agents and setup | Run coding agents (Claude Code, Codex, Gemini CLI, OpenCode, ...) inside any sandbox, and set them up on this machine. |
| Agent setup | Detect coding agents, install cua skills and configure their MCP servers. |
Spaces#
| Page | Covers |
|---|---|
| Spaces | The Spaces registry: create, add, resolve, delete and remove Spaces, their create options, and agent runs in a Space. |
| Space records | What a Space listing returns, and the Spaces tools cua mcp serves with the typed method that covers each. |
| Network settings | What a Space can reach: its network preset, the allow and deny lists, and deleting a Space together with its children. |
| Child Spaces | Let a Space make Spaces of its own, set the budget of its tree and list orphans. |
| Kept commands | Keep a command running in a Space: restarts, health checks, start on boot and logs. |
| Power and resize | Stop, suspend and start a Space, and change a local VM's CPU, memory or disk while keeping its files. |
| Lifetime and egress | How long a Space lives and which destinations it may reach, set after it exists. |
| Space | A connected Space: shell, files, tools, windows, icons, displays, the hotspot and teleport. |
| Sharing, leaving and bulk delete | Give another person access to a Space, see who owns a Space and who else has it, leave Spaces shared with you, and delete several at once. |
| Relay registration | Register a Space with the relay so other devices reach it, and unregister it. |
| Elastic pool and prewarm | Plan where Spaces go and what it costs, add and remove cloud hosts, set the budget, and keep Spaces ready. |
| Build an image | Build a Dockerfile or steps in a Space as pinned checkpoints that Spaces fork from, with a content-hash layer cache. |
| Channel | Which way a Space's calls go, and port forwards over its own connection. |
| Cua Volume | The versioned volume every Space and agent shares: files, history, grants, requests, audit, storage and sync. |
| Joining presence | Join a Space's presence, or the presence of a window another Space shows, so each viewer is one avatar and one cursor. |
| Streams and presence | Media sessions of a Space and presence (who is connected, and their cursors). |
| Processor, memory and disk | What this Mac, its extra Spaces and your other computers use: one snapshot, a stream of changes and the low-disk warning. |
| The list and its changes | The Space list Spaces.list reads, and hearing when it changed so it is read again then instead of on a timer. |
| Agents in a Space | Start, follow, message and stop coding-agent runs inside a Space. |
| Persistent agents and your cloud | Named agents whose memory outlives their Space: homes in the Cua Volume, routines, notifications, pause and resume, access to your computers, and Spaces in your own AWS, Google Cloud or Modal account. |
| Default Space | The account's default Space, the order to try when it is offline, and where a new task runs now. |
| Host, relay and devices | Unattended host setup, the cua-relay directory client, and this device's enrollment on the relay. |
Account#
| Page | Covers |
|---|---|
| Auth and telemetry | Sign-in, the credential store the SDK, the CLI and the daemon share, and the telemetry switches. |
Errors and types#
| Page | Covers |
|---|---|
| Errors | Every CuaError variant: message, cause and fix. |
| Types | The type notation in each language, and every item in one list. |
Language packages#
| Page | Covers |
|---|---|
| Python high-level API | cua_sandbox: Sandbox, Image, the computer interfaces, runtimes and configuration. |
| TypeScript additions | What @trycua/cua adds in TypeScript: embedded(), Image, helpers, and the Spaces modules. |
| Rust crates | The public crates (cua-sdk, cua-spacesd-client, cua-sandbox-core, cua-spaces), with stability tiers. |
Protocol#
| Page | Covers |
|---|---|
| Protocol | The gRPC contracts of cua-spacesd (cua.env.v1) and the cua daemon (cua.daemon.v1). |
372 items, 466 methods. The Types page lists them.