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

Total release size: 269.8 MB

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

Download URL cua-0.10.1-py3-none-win_arm64.whl
Size 39.9 MB
Tags Python 3 Windows ARM64
SHA-256 checksum
How to use checksums
c9dfcd10eb3dbb100bee73661c5e05e7a34d6a407c3af5451645be336995c24d
BLAKE2b-256 checksum
How to use checksums
150d438648757085fdc8dcbefa16e862ed877f96a2110c3069a320869eed7a28
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.10.1-py3-none-win_amd64.whl

Download URL cua-0.10.1-py3-none-win_amd64.whl
Size 43.2 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
554a4d1464763d219c979390fe051c7a71cb865772a3e656c32aa7d39955f39d
BLAKE2b-256 checksum
How to use checksums
dd36e2acb5550115265f120951ffe03ed38ac04d43b6fe703984b50864cf90c0
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.10.1-py3-none-manylinux_2_31_x86_64.whl

Download URL cua-0.10.1-py3-none-manylinux_2_31_x86_64.whl
Size 56.8 MB
Tags Linux glibc 2.31+ x86-64 Python 3
SHA-256 checksum
How to use checksums
c8feff215105f4790244d4ffa796b1acfb23f04dba8e51933b82a8660ee81916
BLAKE2b-256 checksum
How to use checksums
4e24ffc768f137c3461859df9247f551f1d25531cb2f930b0961c19b1313209c
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.10.1-py3-none-manylinux_2_31_aarch64.whl

Download URL cua-0.10.1-py3-none-manylinux_2_31_aarch64.whl
Size 51.5 MB
Tags Linux glibc 2.31+ ARM64 Python 3
SHA-256 checksum
How to use checksums
15c084eb38ec6c780898a234f4d4dabe0965b052a63a6def95ba250276758d12
BLAKE2b-256 checksum
How to use checksums
2b31b186bf3d5a625504569df32aadc28788dee9f2f608405749debb11abc829
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.10.1-py3-none-macosx_11_0_arm64.whl

Download URL cua-0.10.1-py3-none-macosx_11_0_arm64.whl
Size 37.3 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
b406f33a3890f10b1463349a34a621becdeb7f019f9263b974fac2689043151d
BLAKE2b-256 checksum
How to use checksums
370407496ebbacc6752324752d29988fcb609dcb05039f9ec9bbed80b98ef29e
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.10.1-py3-none-macosx_10_12_x86_64.whl

Download URL cua-0.10.1-py3-none-macosx_10_12_x86_64.whl
Size 41.1 MB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
282fedc17826e0d70ab73cc17252626cd03fe660686dcd8d592fce45d225d14e
BLAKE2b-256 checksum
How to use checksums
e80e66524a667c690f64eb4fb53141c2285d33702c98c3003cb3b4b86f2ec5ac
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.10.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