Python high-level API

The high-level Python API: cua_sandbox (Sandbox, Image, the computer interfaces, Pool) and the helpers the cua package adds. It is a thin layer over the Cua SDK objects: the cloud, the local runtimes and cua-spacesd all go through cua, whose generated binding (cua._native) those pages document.

configure() sets process-wide options; environment variables override it:

Pages#

The cua package#

The hand-written layer of cua: two module-level constructors, a canonical-image helper and lazy re-exports of the extras.

embedded#

def embedded(
    *,
    state_dir: Optional[str] = None,
    fleet: Optional[FleetSettings] = None,
    fleet_from_env: bool = True,
    fleet_from_session: bool = False,
    env_probe_timeout_ms: Optional[int] = None,
    spaces_home: Optional[str] = None,
    teleport_home: Optional[str] = None,
    fleet_pool_home: Optional[str] = None,
) -> Cua

An SDK runtime in this process (no I/O until the first call).

Fleet uses CUA_CLIENT_ID/CUA_CLIENT_SECRET (or FLEETS_TOKEN); fleet_from_session=True falls back to the cua auth login session (cua-sandbox's Sandbox does this by default). spaces_home is the Spaces registry directory (default ~/.cua); teleport_home makes teleport read app sessions under that directory with no host side effects (tests); fleet_pool_home is where managed Fleet pools keep their name cache and GC lock (default ~/.cua).

connect#

def connect(address: Optional[str] = None, token: Optional[str] = None) -> Cua

A client of a running cua daemon (socket path or loopback URL).

Image#

Without cua[sandbox], cua.Image is this helper. With it installed, cua.Image is the richer cua_sandbox Image.

class Image

Canonical image references (plain strings for sandboxes().create).

Example

from cua_sandbox import Image
 
img = Image.linux().apt_install("curl").pip_install("requests").env(DEBUG="1").expose(8080)
print(img.to_dict())
# {'os_type': 'linux', 'distro': 'ubuntu', 'version': '24.04', 'kind': None,
#  'layers': [{'type': 'apt_install', 'packages': ['curl']},
#             {'type': 'pip_install', 'packages': ['requests']}],
#  'env': {'DEBUG': '1'}, 'ports': [8080]}

Image.linux#

@staticmethod
def linux(version: Optional[str] = None, tier: Optional[str] = None) -> str

slim or full (the default).

Image.windows#

@staticmethod
def windows(version: Optional[str] = None, tier: Optional[str] = None) -> str

Image.macos#

@staticmethod
def macos(version: Optional[str] = None, tier: Optional[str] = None) -> str

slim, full (the default), xcode or xcode-<X.Y>.

Image.omarchy#

@staticmethod
def omarchy(channel: Optional[str] = None) -> str

Omarchy (Arch Linux, Hyprland) with cua-spacesd: an amd64 VM (ghcr.io/trycua/omarchy:edge; emulated on arm64 hosts).

Image.from_registry#

@staticmethod
def from_registry(reference: str) -> str

Image.resolve#

@staticmethod
def resolve(
    reference: str,
    backend: str = 'local',
    arch: Optional[str] = None,
) -> ResolvedImage

Names from the extras#

cua resolves these names lazily from the optional extras. Install the extra to use them.

cua.runtime#

cua.runtime: sandbox runtime backends.

Exports: Runtime, RuntimeInfo, DockerRuntime, QEMURuntime, QEMUDockerRuntime, QEMUBaremetalRuntime, QEMUWSL2Runtime, LumeRuntime, HyperVRuntime, AndroidEmulatorRuntime, TartRuntime.

cua.tools#

cua.tools: agent tool classes and registry.

Exports: BaseTool, BaseComputerTool, register_tool, get_registered_tools, get_tool, TOOL_REGISTRY, BrowserTool, ToolError, IllegalArgumentError.

cua.callbacks#

cua.callbacks: agent lifecycle callback handlers.

Exports: AsyncCallbackHandler, ImageRetentionCallback, LoggingCallback, TrajectorySaverCallback, BudgetManagerCallback, TelemetryCallback, OtelCallback, OtelErrorCallback, OperatorNormalizerCallback, PromptInstructionsCallback.