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

Total release size: 330.7 MB

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

Download URL cua-0.21.0-py3-none-win_arm64.whl
Size 53.8 MB
Tags Python 3 Windows ARM64
SHA-256 checksum
How to use checksums
ab7a6bfc8fc29bac396415fd73cb6888c8d2d91b72797fd7a4704ec6d7da6616
BLAKE2b-256 checksum
How to use checksums
03bb7f3f640af2c84170e3f05f05c94001ef80a3d00ed940901dafd5eac7fed0
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.21.0-py3-none-win_amd64.whl

Download URL cua-0.21.0-py3-none-win_amd64.whl
Size 58.1 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
2dca4dc20f795760d976dc093b6fea8d3980f4fec1165b7e2ffa38a84ee343d6
BLAKE2b-256 checksum
How to use checksums
96fdb0ae1d3c6f9e5e2247587d1a0995cfd1f3c05621f6374b5c5c9edf0ab4db
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.21.0-py3-none-manylinux_2_31_x86_64.whl

Download URL cua-0.21.0-py3-none-manylinux_2_31_x86_64.whl
Size 58.5 MB
Tags Linux glibc 2.31+ x86-64 Python 3
SHA-256 checksum
How to use checksums
4e4c0838bf687b53539f195712f57c48a3b7f7dc93eaa1fd6b8c035debf1dc03
BLAKE2b-256 checksum
How to use checksums
1872d255b3483fac8c87dfd0a428eaadbb8bb185b6725bcd5690cce8661365d3
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.21.0-py3-none-manylinux_2_31_aarch64.whl

Download URL cua-0.21.0-py3-none-manylinux_2_31_aarch64.whl
Size 53.4 MB
Tags Linux glibc 2.31+ ARM64 Python 3
SHA-256 checksum
How to use checksums
fff739ac2bd32b7692effc5d33b8d80f08ec36bd9409ad2aa9a2c51a2893b27e
BLAKE2b-256 checksum
How to use checksums
787cdd64bf4f12a95fbda5665d702c987c1f2c5169bb43a33b6011825003a806
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.21.0-py3-none-macosx_11_0_arm64.whl

Download URL cua-0.21.0-py3-none-macosx_11_0_arm64.whl
Size 51.0 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
3db7632094de071f92fe6d6d1e6efd9e92cca80aa00e428840923ff3e21b8daa
BLAKE2b-256 checksum
How to use checksums
7f5e9b8c51e5bca89701f7f0c86a9b21fe439a1e8a44c2ae244e8077c4c3e2f7
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.21.0-py3-none-macosx_10_12_x86_64.whl

Download URL cua-0.21.0-py3-none-macosx_10_12_x86_64.whl
Size 55.9 MB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
8ffe743ce377d5e654ce4f31a6c40c8b00d225d525b9a447b08fdebb6f2d3c15
BLAKE2b-256 checksum
How to use checksums
6190ca2d2b622c0ad26ea86c9c159c76aeeec42a463da976ecd8baa0f5ab6300
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.21.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