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 bundled CLI). 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, Pool, 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)
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.

Development

cd libs/cua
cargo build --release -p cua-sdk
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
CUA_E2E_FLEET=1 uv run --with pytest pytest -q tests/test_live_fleet.py  # live Fleet

Metadata

Release files for cua 0.5.0

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.5.0
File Actions
cua-0.5.0-py3-none-win_arm64.whl Python 3 none Windows ARM64 Details for cua-0.5.0-py3-none-win_arm64.whl
cua-0.5.0-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for cua-0.5.0-py3-none-win_amd64.whl
cua-0.5.0-py3-none-manylinux_2_31_x86_64.whl Python 3 none Linux glibc 2.31+ x86-64 Details for cua-0.5.0-py3-none-manylinux_2_31_x86_64.whl
cua-0.5.0-py3-none-manylinux_2_31_aarch64.whl Python 3 none Linux glibc 2.31+ ARM64 Details for cua-0.5.0-py3-none-manylinux_2_31_aarch64.whl
cua-0.5.0-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for cua-0.5.0-py3-none-macosx_11_0_arm64.whl
cua-0.5.0-py3-none-macosx_10_12_x86_64.whl Python 3 none macOS 10.12+ x86-64 Details for cua-0.5.0-py3-none-macosx_10_12_x86_64.whl

Total release size: 453.4 MB

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

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

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

Download URL cua-0.5.0-py3-none-win_amd64.whl
Size 71.3 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
54583bccc9f7d0e72f31f778fcf0712b6fd73d2fce306abec0687a31b002b21d
BLAKE2b-256 checksum
How to use checksums
cc7eb1b20852b1be8f5c8a5995eee600df1b49cb03332fb97c6b2cf985ac3f8f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

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

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

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

Download URL cua-0.5.0-py3-none-manylinux_2_31_aarch64.whl
Size 83.9 MB
Tags Linux glibc 2.31+ ARM64 Python 3
SHA-256 checksum
How to use checksums
f7ae88c3e00af0800587fe15380e87669c9db89a5e45cb7a44f90cd81d98924a
BLAKE2b-256 checksum
How to use checksums
88cee86abf1fb6d87ef0a71f2c40f38c35a8f152dc04b211df4838ba489c88d5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

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

Download URL cua-0.5.0-py3-none-macosx_11_0_arm64.whl
Size 71.9 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
d5a208a443dbae80e441186ce308fb801b37bf0689a4be32a2346f9730f9785b
BLAKE2b-256 checksum
How to use checksums
97837d1031bf1ac4680f6ed5bff17d3bdb7891c16d97ce17077819ac22c72738
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

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

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

Security for cua 0.5.0

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