Skip to main content

cua (Python)

The cua SDK for Python: a thin, generated binding over the Rust cua-sdk crate (libs/cua/crates/cua-sdk). The same API runs embedded in your process or against a cua daemon that shares sandboxes, spacesd connections and credentials across processes.

import asyncio, cua

async def main():
    c = cua.embedded()
    sb = await c.sandboxes().connect_url("http://127.0.0.1:3211", "token", "dev")
    env = await sb.spacesd(None)
    print((await env.run(cua.SpacesdCommand(program="uname", args=["-a"]))).stdout.decode())
    png = await env.screenshot(None)

asyncio.run(main())

Sandboxes: any image, local or cloud

c = cua.embedded()
sb = await c.sandboxes().create(cua.SandboxCreateOptions(
    on="local",                                   # or "aws": same options
    image="python:3.12-slim",
    command=["python", "-m", "my_mcp", "--port", "8765"],
    env={"FOO": "bar"},
    services={"mcp": 8765},
    wait_for=[cua.ReadinessProbe(port=0, service="mcp", http_path="/health")],
    cloud=cua.CloudOptions(warm=True),            # optional, ignored locally
))
svc = sb.service("mcp")
r = await svc.request("POST", "/mcp", body, None, [cua.HttpHeader(name="accept", value="application/json, text/event-stream")])
url = await svc.url()                             # usable from this machine
share = await sb.public_url("mcp", 3600, None)    # shareable, expires
fwd = await sb.forward(8765)                      # loopback URL: fwd.url()
info = sb.info()  # id, phase, location, services, expires_at_unix, provider_details

public_url is a signed URL in the cloud and a loopback URL with its own token locally, served by the cua daemon (started on demand with the cua CLI, which pip install cua installs through its cua-cli dependency). await sb.mcp("mcp", None) is an MCP client for a server the sandbox serves and await sb.mcp_config("mcp", None) its URL and headers for any MCP client; neither needs cua-spacesd. cua.canonical_image("linux", None) returns ghcr.io/trycua/linux:24.04. Cloud env, sidecars (addressed by name, on gVisor and KubeVirt) and registry secrets work like local ones; cloud image layers (a remote build) are not available yet and fail with a clear error.

High-level API (optional extras)

cua replaces the former cua meta-package (0.1.x). Its convenience imports resolve lazily from optional extras:

pip install "cua[sandbox]"   # cua-sandbox: Sandbox, Image, QEMURuntime, ...
pip install "cua[agent]"     # cua-agent: ComputerAgent, cua.callbacks, cua.tools
pip install "cua[all]"       # both (the `cua` command is the Rust CLI in libs/cua)
pip install --no-deps cua    # the SDK alone, without the `cua` command (`cua-cli`)
from cua import Sandbox, Image            # cua_sandbox.Sandbox / Image
async with Sandbox.ephemeral(Image.linux(), local=True) as sb:
    print((await sb.shell.run("uname -a")).stdout)

With cua-sandbox installed, cua.Sandbox is the high-level cua_sandbox.Sandbox; the SDK's own handle type (what sandboxes().create() returns) is always cua.SandboxHandle.

  • cua._native is generated by libs/cua/scripts/generate-uniffi-bindings.mjs and must not be edited; --check fails CI when it drifts.
  • Wheels are platform wheels (build_wheel.py), one per OS/arch, each with the libcua_sdk library next to _native.py (and the static Linux cua-spacesd in cua/bin/). The cua CLI is a separate package, cua-cli (cli/), a dependency of cua; the cua command runs it with CUA_SPACESD_STATIC set to that cua-spacesd.
  • On PyPI, cua-cli is one thin py3-none-any wheel of a few KB (cli/build_thin_wheel.py). The first cua run downloads the signed CLI archive of the same GitHub release for its machine, checks the SHA-256 the wheel carries, and caches it. Offline or pinned installs: set CUA_CLI_BINARY to a cua binary, or CUA_CLI_DOWNLOAD_BASE to a mirror of the release archives; python -m cua_cli fetch downloads ahead of time (Docker images, CI). Local builds (build_wheel.py --cli) still put the binary inside the wheel.

Development

cd libs/cua
cargo build --release -p cua-sdk-native
scripts/build-test-fixtures.sh
node scripts/stage-uniffi-library.mjs          # copies the library here
cd python && uv run --with pytest pytest -q    # smoke tests against fixtures

Metadata

Release files for cua 0.27.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for cua 0.27.5
File Actions
cua-0.27.5-py3-none-win_arm64.whl Python 3 none Windows ARM64 Details for cua-0.27.5-py3-none-win_arm64.whl
cua-0.27.5-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for cua-0.27.5-py3-none-win_amd64.whl
cua-0.27.5-py3-none-manylinux_2_31_x86_64.whl Python 3 none Linux glibc 2.31+ x86-64 Details for cua-0.27.5-py3-none-manylinux_2_31_x86_64.whl
cua-0.27.5-py3-none-manylinux_2_31_aarch64.whl Python 3 none Linux glibc 2.31+ ARM64 Details for cua-0.27.5-py3-none-manylinux_2_31_aarch64.whl
cua-0.27.5-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for cua-0.27.5-py3-none-macosx_11_0_arm64.whl
cua-0.27.5-py3-none-macosx_10_12_x86_64.whl Python 3 none macOS 10.12+ x86-64 Details for cua-0.27.5-py3-none-macosx_10_12_x86_64.whl

Total release size: 331.6 MB

Release files / cua-0.27.5-py3-none-win_arm64.whl

Download URL cua-0.27.5-py3-none-win_arm64.whl
Size 54.0 MB
Tags Python 3 Windows ARM64
SHA-256 checksum
How to use checksums
e2c46730543ceb1102774584187b46a33e37d7018bd89c569f0ed93859e88ff2
BLAKE2b-256 checksum
How to use checksums
a5521ecec861cfde5322f4aae7af7fb35f3bead97eb53e163ba16c2b49d7c06a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / cua-0.27.5-py3-none-win_amd64.whl

Download URL cua-0.27.5-py3-none-win_amd64.whl
Size 58.4 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
ebd5ec72696dc96bf90b51db3e3a34537ba47eeeeb54069109a24990a7044420
BLAKE2b-256 checksum
How to use checksums
84ecb2b9a6c5a05bdd19efa3cd712b145d4c3b4c7c292fa0df51771436e6ff8c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / cua-0.27.5-py3-none-manylinux_2_31_x86_64.whl

Download URL cua-0.27.5-py3-none-manylinux_2_31_x86_64.whl
Size 58.2 MB
Tags Linux glibc 2.31+ x86-64 Python 3
SHA-256 checksum
How to use checksums
550c998d21fbe886f45c8e02a6baa963bc1ebaf518b7405c4c3426b1684e97e6
BLAKE2b-256 checksum
How to use checksums
e5901d1c4cf4e3be061fe6126d54f759e27ae6d693bd7b9901f4f5024889f18c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / cua-0.27.5-py3-none-manylinux_2_31_aarch64.whl

Download URL cua-0.27.5-py3-none-manylinux_2_31_aarch64.whl
Size 53.6 MB
Tags Linux glibc 2.31+ ARM64 Python 3
SHA-256 checksum
How to use checksums
1eca934e00714526092d2b97c207bf9e1fa005ec8356fef76973c0bb6071c76e
BLAKE2b-256 checksum
How to use checksums
901d575fd99aaaff312afc893d64df73ecd42c8a1caee8a30b8bf1e3c500bbf2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / cua-0.27.5-py3-none-macosx_11_0_arm64.whl

Download URL cua-0.27.5-py3-none-macosx_11_0_arm64.whl
Size 51.2 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
0ec9e44f1241d4cf4cc1bb26b89092b1406bd307c3287c402433aeeb49d1c3d3
BLAKE2b-256 checksum
How to use checksums
577fd7799afda788468e6e7283012e5e8182895021bb8fd5ad08acef623349dd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / cua-0.27.5-py3-none-macosx_10_12_x86_64.whl

Download URL cua-0.27.5-py3-none-macosx_10_12_x86_64.whl
Size 56.2 MB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
f9d6939921e23ca8a53102b631a4fec272023b232564e17a7d1339172b9c19cb
BLAKE2b-256 checksum
How to use checksums
0685e8b0e27bc4870ac3ed8032589aec7d23dcd6a6b025dc045653a08a94dcc1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Security for cua 0.27.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page