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

Total release size: 253.9 MB

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

Download URL cua-0.9.0-py3-none-win_arm64.whl
Size 37.3 MB
Tags Python 3 Windows ARM64
SHA-256 checksum
How to use checksums
2295bb6b8fae560cd0fde311abd091eb4c009c82237de9ad3c98cc5bca3979be
BLAKE2b-256 checksum
How to use checksums
ae1e32bc68dcf73630ea54120736132795495705f0eb5e57c22e92cad2037dcd
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.9.0-py3-none-win_amd64.whl

Download URL cua-0.9.0-py3-none-win_amd64.whl
Size 40.4 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
309b427dd38f9db1dc78838f0652ec44796ac9a14ebf1e931d7a204fa1ab418d
BLAKE2b-256 checksum
How to use checksums
b780097e908848ea8b0b835a617e15e166ba1484196a89eb51aef0767f13adc8
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.9.0-py3-none-manylinux_2_31_x86_64.whl

Download URL cua-0.9.0-py3-none-manylinux_2_31_x86_64.whl
Size 53.7 MB
Tags Linux glibc 2.31+ x86-64 Python 3
SHA-256 checksum
How to use checksums
38578102c97920211d50e43998dc9b95287b55e898f0461da118fd441ff925a5
BLAKE2b-256 checksum
How to use checksums
d6e0a82902ce5836fc7b7dbbcf4936834d1aac21acf452764aab5bc2b436b154
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.9.0-py3-none-manylinux_2_31_aarch64.whl

Download URL cua-0.9.0-py3-none-manylinux_2_31_aarch64.whl
Size 48.9 MB
Tags Linux glibc 2.31+ ARM64 Python 3
SHA-256 checksum
How to use checksums
f73178139ca17360787c53f119298804fa4d702f414f9fead9d614516ff30ba9
BLAKE2b-256 checksum
How to use checksums
7b98ea629680e5234d62b612e509a0c5143d083a95ae272a40cca21e7e3f5ff3
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.9.0-py3-none-macosx_11_0_arm64.whl

Download URL cua-0.9.0-py3-none-macosx_11_0_arm64.whl
Size 35.0 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
cf5d3b186224c5f1d34f457958f9067d4d475d1231047789f8420b5b0150905b
BLAKE2b-256 checksum
How to use checksums
f55436bc11152aed3d6d5f81a23951d8ca4d8903e869fa4595bf6a2fe204efb0
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.9.0-py3-none-macosx_10_12_x86_64.whl

Download URL cua-0.9.0-py3-none-macosx_10_12_x86_64.whl
Size 38.6 MB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
d106cf6856d844dc8c0e621e84c0c5f7139fcfbffaab84ef768053e547bec37d
BLAKE2b-256 checksum
How to use checksums
ce2cd22810cd7d08a9b7869e1cada49b4ae13dfa0fbaf4378516723bb9c22b17
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.9.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