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, on Linux, the static 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.12.1

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

Total release size: 287.1 MB

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

Download URL cua-0.12.1-py3-none-win_arm64.whl
Size 42.5 MB
Tags Python 3 Windows ARM64
SHA-256 checksum
How to use checksums
e3e4ea099c708fda32cc41873af8e158a38f2de969d347f9b726b7cb4b25ffd0
BLAKE2b-256 checksum
How to use checksums
475a9b4918be0186f30c36a5c9ba399b80162a0900d45b1cc78c8c52c7f75727
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.12.1-py3-none-win_amd64.whl

Download URL cua-0.12.1-py3-none-win_amd64.whl
Size 46.1 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
48974254f8d5dab8f9bd2573d0392391f3103cd0d6001654abb093d765db966f
BLAKE2b-256 checksum
How to use checksums
220dd5046dcdd829282db440723680d6db6e7be9a6a8403dd2892c0836b6e7c7
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.12.1-py3-none-manylinux_2_31_x86_64.whl

Download URL cua-0.12.1-py3-none-manylinux_2_31_x86_64.whl
Size 60.1 MB
Tags Linux glibc 2.31+ x86-64 Python 3
SHA-256 checksum
How to use checksums
5cb5680304b2bc826dca74df337dd53d38f6b475a60c6a38988437949149ac7b
BLAKE2b-256 checksum
How to use checksums
c2cf94a5afa2f2e260b9950f0a11dc763284c2a5bc0f31afdf053566d34c78cc
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.12.1-py3-none-manylinux_2_31_aarch64.whl

Download URL cua-0.12.1-py3-none-manylinux_2_31_aarch64.whl
Size 54.6 MB
Tags Linux glibc 2.31+ ARM64 Python 3
SHA-256 checksum
How to use checksums
dd93eff2401d87da1189b6e8d1168e010c7efde423cb74bd8e1472e765db7262
BLAKE2b-256 checksum
How to use checksums
d36c6c5cafd775b1ef23edbfcf1df6953659cdb705187becb8fe130235e817a9
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.12.1-py3-none-macosx_11_0_arm64.whl

Download URL cua-0.12.1-py3-none-macosx_11_0_arm64.whl
Size 39.8 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
5b2a5aabbcf0b02cb17b70fd9e4f4de37b5ea1df2825511831ba562b13c59e47
BLAKE2b-256 checksum
How to use checksums
b0e53be45edd4a04a5e72fc09d0f92a9036912222b492d4c228b5f3fa2b767af
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.12.1-py3-none-macosx_10_12_x86_64.whl

Download URL cua-0.12.1-py3-none-macosx_10_12_x86_64.whl
Size 43.9 MB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
a34ed80302c01bf2c61666953512c477c0eb61271463706cd68776f6b836b3d5
BLAKE2b-256 checksum
How to use checksums
b4c0a3371cf4c4663b67e2b8d8058face591be9f01deafb37a479c5f17a7171b
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.12.1

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