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, 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

Metadata

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

Total release size: 430.3 MB

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

Download URL cua-0.7.0-py3-none-win_arm64.whl
Size 62.4 MB
Tags Python 3 Windows ARM64
SHA-256 checksum
How to use checksums
d26de546ac9ef526520a1b6018d133ccc328aabe256a53987294231bb74cbc22
BLAKE2b-256 checksum
How to use checksums
39d0988eaab1fea9f948da754503d5cd9c10b27f8a7e3e8abf96cb2a3cfd75cb
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.7.0-py3-none-win_amd64.whl

Download URL cua-0.7.0-py3-none-win_amd64.whl
Size 67.4 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
4a22f4b9277c1eaf278f82dec9cbb891683df6230fb3a8e14146ff38734e44e6
BLAKE2b-256 checksum
How to use checksums
ed38396b06e870b924d686cc38e027b84244e2c8d739d7638eb961c9d78291c6
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.7.0-py3-none-manylinux_2_31_x86_64.whl

Download URL cua-0.7.0-py3-none-manylinux_2_31_x86_64.whl
Size 78.5 MB
Tags Linux glibc 2.31+ x86-64 Python 3
SHA-256 checksum
How to use checksums
eefa146dcfcb639f66052b88ca3393a736735bb175e7730327e50398dcdcfc36
BLAKE2b-256 checksum
How to use checksums
fce0c8cbb5aa2a7302bdb0ef1498dd099e8466919cdb65217215336a730c6e5e
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.7.0-py3-none-manylinux_2_31_aarch64.whl

Download URL cua-0.7.0-py3-none-manylinux_2_31_aarch64.whl
Size 79.8 MB
Tags Linux glibc 2.31+ ARM64 Python 3
SHA-256 checksum
How to use checksums
7659d811fac85f419d41d5b61ef56f7a26b131e540c932a24df77884e5144ef2
BLAKE2b-256 checksum
How to use checksums
ee3a0cc6d5f0a438edf74bd14e722543a89ba1258ac29042ba682c5ec2f1d65c
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.7.0-py3-none-macosx_11_0_arm64.whl

Download URL cua-0.7.0-py3-none-macosx_11_0_arm64.whl
Size 68.4 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
e64dfbb12a9e71205feaf0cab2e386e12331cb9c41618c93e557c99035741ab3
BLAKE2b-256 checksum
How to use checksums
994874a904598694feccba0e9244124caea96dc1d33dfff3d50d43f6e86ad98f
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.7.0-py3-none-macosx_10_12_x86_64.whl

Download URL cua-0.7.0-py3-none-macosx_10_12_x86_64.whl
Size 73.8 MB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
e4e3c269d733a4310c169e73510dc5147122cf633c4e0659e68f6f3beab10427
BLAKE2b-256 checksum
How to use checksums
476dbe0e3f913ad00b96f256a16a216ce21486c9f45f15c0dda280228aad5d35
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.7.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