Python high-level API

cua_sandbox and the cua package helpers: packages, configuration, and the page for each class.

The high-level Python API: cua_sandbox (Sandbox, Image, the computer interfaces) and the helpers the cua package adds. It is a thin layer over the Cua SDK objects: 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,
    account_from_session: bool = False,
    env_probe_timeout_ms: Optional[int] = None,
    spaces_home: Optional[str] = None,
    teleport_home: Optional[str] = None,
) -> Cua

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

account_from_session=True uses the cua auth login session for the relay account the runtime lists "My machines" with. 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).

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, full (the default) or docker (a VM with dockerd).

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.