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 second platform wheel, cua-cli (cli/), a dependency of cua that installs cua_cli/bin/cua[.exe]; the cua command runs it with CUA_SPACESD_STATIC set to that cua-spacesd. PyPI caps each file at 100 MB and the two together are over it.

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

Total release size: 339.6 MB

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

Download URL cua-0.16.0-py3-none-win_arm64.whl
Size 55.1 MB
Tags Python 3 Windows ARM64
SHA-256 checksum
How to use checksums
26695c880f019ef74fe314762ccaec6891a0ec41f75744d6d12b496587bebdf5
BLAKE2b-256 checksum
How to use checksums
fd73c914766591962117d1ef6520f96a5a552c63491e6196f5bb7245eeb2c134
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.16.0-py3-none-win_amd64.whl

Download URL cua-0.16.0-py3-none-win_amd64.whl
Size 59.6 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
1eb5e0ef740f8e62fc4a9911bef404314c8c88f29c713a5818f9ef3c76141294
BLAKE2b-256 checksum
How to use checksums
f3273e597fab1a3245a2cbd74466ac6d2cbe6fbd98fdc0c7e8fbc7996f25f240
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.16.0-py3-none-manylinux_2_31_x86_64.whl

Download URL cua-0.16.0-py3-none-manylinux_2_31_x86_64.whl
Size 60.4 MB
Tags Linux glibc 2.31+ x86-64 Python 3
SHA-256 checksum
How to use checksums
ec59ade1ab197868900706d694cbf957260b5ed5945b1a044aa33d966e99c21c
BLAKE2b-256 checksum
How to use checksums
3a5d03e76c1a62f4f95254725a27793866e3b7e04fa89f6a7dcbdff7cf94959d
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.16.0-py3-none-manylinux_2_31_aarch64.whl

Download URL cua-0.16.0-py3-none-manylinux_2_31_aarch64.whl
Size 54.8 MB
Tags Linux glibc 2.31+ ARM64 Python 3
SHA-256 checksum
How to use checksums
f8de9d868e2a0e837cfbeb837bbab9a26d95b79a466d77c421cd2c708808b5e9
BLAKE2b-256 checksum
How to use checksums
53f1c4b45b158620116499c1fda8436bee5e030aecfd059d0a73ddad34cdd2d5
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.16.0-py3-none-macosx_11_0_arm64.whl

Download URL cua-0.16.0-py3-none-macosx_11_0_arm64.whl
Size 52.4 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
0582d4a25adb850c22231af72f15fe01ee80a5835bf585c5052357b2dc8fd09b
BLAKE2b-256 checksum
How to use checksums
2262f85e4bae6b8e8b92134d01ac314684621761385765971138714178e5ded8
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.16.0-py3-none-macosx_10_12_x86_64.whl

Download URL cua-0.16.0-py3-none-macosx_10_12_x86_64.whl
Size 57.4 MB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
5ca75a299ac6f121eb3e4ca70120f45c3d203d344fbcf41137afb8df634fdd9b
BLAKE2b-256 checksum
How to use checksums
16015c34588c6a5631e76f6f3f0517a22186b631ab19f792e95a3b5b4fa209c5
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.16.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