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._nativeis generated bylibs/cua/scripts/generate-uniffi-bindings.mjsand must not be edited;--checkfails CI when it drifts.- Wheels are platform wheels (
build_wheel.py), one per OS/arch, each with thelibcua_sdklibrary next to_native.py(and the static Linux cua-spacesd incua/bin/). ThecuaCLI is a second platform wheel,cua-cli(cli/), a dependency ofcuathat installscua_cli/bin/cua[.exe]; thecuacommand runs it withCUA_SPACESD_STATICset 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.16.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| cua-0.16.0-py3-none-win_arm64.whl | Python 3 | none | Windows ARM64 | Details for cua-0.16.0-py3-none-win_arm64.whl |
| cua-0.16.0-py3-none-win_amd64.whl | Python 3 | none | Windows x86-64 | Details for cua-0.16.0-py3-none-win_amd64.whl |
| cua-0.16.0-py3-none-manylinux_2_31_x86_64.whl | Python 3 | none | Linux glibc 2.31+ x86-64 | Details for cua-0.16.0-py3-none-manylinux_2_31_x86_64.whl |
| cua-0.16.0-py3-none-manylinux_2_31_aarch64.whl | Python 3 | none | Linux glibc 2.31+ ARM64 | Details for cua-0.16.0-py3-none-manylinux_2_31_aarch64.whl |
| cua-0.16.0-py3-none-macosx_11_0_arm64.whl | Python 3 | none | macOS 11.0+ ARM64 | Details for cua-0.16.0-py3-none-macosx_11_0_arm64.whl |
| cua-0.16.0-py3-none-macosx_10_12_x86_64.whl | Python 3 | none | macOS 10.12+ x86-64 | Details for cua-0.16.0-py3-none-macosx_10_12_x86_64.whl |
Total release size: 339.6 MB
Release files / cua-0.16.0-py3-none-win_arm64.whl
| Download URL | cua-0.16.0-py3-none-win_arm64.whl |
|---|---|
| Size | 55.1 MB |
| Tags | Python 3 Windows ARM64 |
|
SHA-256 checksum How to use checksums |
26695c880f019ef74fe314762ccaec6891a0ec41f75744d6d12b496587bebdf5
|
|
BLAKE2b-256 checksum How to use checksums |
fd73c914766591962117d1ef6520f96a5a552c63491e6196f5bb7245eeb2c134
|
| 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.16.0-py3-none-win_amd64.whl
| Download URL | cua-0.16.0-py3-none-win_amd64.whl |
|---|---|
| Size | 59.6 MB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
1eb5e0ef740f8e62fc4a9911bef404314c8c88f29c713a5818f9ef3c76141294
|
|
BLAKE2b-256 checksum How to use checksums |
f3273e597fab1a3245a2cbd74466ac6d2cbe6fbd98fdc0c7e8fbc7996f25f240
|
| 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.16.0-py3-none-manylinux_2_31_x86_64.whl
| Download URL | cua-0.16.0-py3-none-manylinux_2_31_x86_64.whl |
|---|---|
| Size | 60.4 MB |
| Tags | Linux glibc 2.31+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
ec59ade1ab197868900706d694cbf957260b5ed5945b1a044aa33d966e99c21c
|
|
BLAKE2b-256 checksum How to use checksums |
3a5d03e76c1a62f4f95254725a27793866e3b7e04fa89f6a7dcbdff7cf94959d
|
| 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.16.0-py3-none-manylinux_2_31_aarch64.whl
| Download URL | cua-0.16.0-py3-none-manylinux_2_31_aarch64.whl |
|---|---|
| Size | 54.8 MB |
| Tags | Linux glibc 2.31+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
f8de9d868e2a0e837cfbeb837bbab9a26d95b79a466d77c421cd2c708808b5e9
|
|
BLAKE2b-256 checksum How to use checksums |
53f1c4b45b158620116499c1fda8436bee5e030aecfd059d0a73ddad34cdd2d5
|
| 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.16.0-py3-none-macosx_11_0_arm64.whl
| Download URL | cua-0.16.0-py3-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 52.4 MB |
| Tags | Python 3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
0582d4a25adb850c22231af72f15fe01ee80a5835bf585c5052357b2dc8fd09b
|
|
BLAKE2b-256 checksum How to use checksums |
2262f85e4bae6b8e8b92134d01ac314684621761385765971138714178e5ded8
|
| 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.16.0-py3-none-macosx_10_12_x86_64.whl
| Download URL | cua-0.16.0-py3-none-macosx_10_12_x86_64.whl |
|---|---|
| Size | 57.4 MB |
| Tags | Python 3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
5ca75a299ac6f121eb3e4ca70120f45c3d203d344fbcf41137afb8df634fdd9b
|
|
BLAKE2b-256 checksum How to use checksums |
16015c34588c6a5631e76f6f3f0517a22186b631ab19f792e95a3b5b4fa209c5
|
| 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.16.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.