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

Total release size: 430.0 MB

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

Download URL cua-0.6.0-py3-none-win_arm64.whl
Size 62.4 MB
Tags Python 3 Windows ARM64
SHA-256 checksum
How to use checksums
561bffa752cb442371ddf6c733a7e688ae080cdead2ddd04f14f75822068291d
BLAKE2b-256 checksum
How to use checksums
452714161b16e3af190781cea584d2bab6d4dfbbd811dcf8438c0c6b45b82570
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.6.0-py3-none-win_amd64.whl

Download URL cua-0.6.0-py3-none-win_amd64.whl
Size 67.4 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
e2d3533a59022ae5fdb05e4072483a4c4d6041bad8c14ea4ecb8b7ce0a12fc59
BLAKE2b-256 checksum
How to use checksums
0c8a6108f52e6630826292d9da60a0c3e9769ea51988be4bb4ae1163a37edbf3
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.6.0-py3-none-manylinux_2_31_x86_64.whl

Download URL cua-0.6.0-py3-none-manylinux_2_31_x86_64.whl
Size 78.4 MB
Tags Linux glibc 2.31+ x86-64 Python 3
SHA-256 checksum
How to use checksums
bb0b170e1f3a9a869b6b8ded4038042252f030a82334faa0f20872dd86cc58fc
BLAKE2b-256 checksum
How to use checksums
725804555067187b9d8438fff6cf3208c731f558e93f9fde167307fa692c297f
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.6.0-py3-none-manylinux_2_31_aarch64.whl

Download URL cua-0.6.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
9e295c1ac847484a7d9549e4e847562d5812c9092dfe8d2f7acea5b2baf3f365
BLAKE2b-256 checksum
How to use checksums
7083ef3eefbd1101aeaa3151c50d162487de4bd8edd1d3aeca32fb6b8e32c40d
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.6.0-py3-none-macosx_11_0_arm64.whl

Download URL cua-0.6.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
c2c539dbfcd221c936f477755ca35600f55fdeb0ef281dd5dbfe10ee5cfdf0a5
BLAKE2b-256 checksum
How to use checksums
ce515a48b9e30e8e69e6faf2c23e8452df6792c1e3923d58d2df56c56d029b8b
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.6.0-py3-none-macosx_10_12_x86_64.whl

Download URL cua-0.6.0-py3-none-macosx_10_12_x86_64.whl
Size 73.7 MB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
a8fd747cadb194032bf6fa09421a1f464b1e762465397bab94f00f5f39d05407
BLAKE2b-256 checksum
How to use checksums
ea1b06c6ff9739245d62403f9ce06b98521ee0c17d1e9b1d62ad1b29dca2ffd3
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.6.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