Metadata-Version: 2.5
Name: cua
Version: 0.2.0
Summary: The cua SDK: sandboxes (Fleet, local, direct), cua-spacesd, media streaming and the cua daemon, on a Rust core
Project-URL: Homepage, https://github.com/trycua/cua
Project-URL: Repository, https://github.com/trycua/cua
Project-URL: Issues, https://github.com/trycua/cua/issues
Author-email: TryCua <hello@trycua.com>
License: MIT
Keywords: agents,automation,computer-use,sandbox,sdk,vm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Provides-Extra: agent
Requires-Dist: cua-agent[cloud]>=0.8.0; (python_version >= '3.11') and extra == 'agent'
Provides-Extra: all
Requires-Dist: cua-agent[all]>=0.8.0; (python_version >= '3.11') and extra == 'all'
Requires-Dist: cua-sandbox>=0.8.0; (python_version >= '3.11') and extra == 'all'
Provides-Extra: sandbox
Requires-Dist: cua-sandbox>=0.8.0; (python_version >= '3.11') and extra == 'sandbox'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Provides-Extra: ui
Requires-Dist: cua-agent[ui]>=0.8.0; (python_version >= '3.11') and extra == 'ui'
Description-Content-Type: text/markdown

# 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.

```python
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

```python
c = cua.embedded()
sb = await c.sandboxes().create(cua.SandboxCreateOptions(
    on="local",                                   # or "cloud": 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:

```bash
pip install "cua[sandbox]"   # cua-sandbox: Sandbox, Image, Pool, 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)
```

```python
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

```bash
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
CUA_E2E_FLEET=1 uv run --with pytest pytest -q tests/test_live_fleet.py  # live Fleet
```
