cua-driver Python SDK
Rust-backed Python SDK and bundled executable for Cua Driver.
Product boundary
This package is for client applications importing Cua Driver as an SDK:
from cua_driver import CuaDriver
It does not contain a Python MCP client. Agents already have runtime-neutral MCP clients and should configure the bundled server directly:
cua-driver mcp
The removed pre-release MCP facade used CuaDriver.stdio(),
AsyncCuaDriver, *Args, and transport classes. Application code imports the
typed Rust-backed SDK shown below; agent code supplies cua-driver mcp to its
agent SDK.
Installation
Install and usage docs live at https://cua.ai/docs/how-to-guides/driver/install and https://cua.ai/docs/reference/cua-driver/mcp-tools.
The wheel contains generated UniFFI bindings, a platform-specific Rust SDK
library, and the cua-driver executable. CuaDriver.create() loads the runtime
in the importing process and does not require the executable or daemon.
SDK example
import asyncio
from cua_driver import (
CaptureScope,
CuaDriver,
EndSessionInput,
GetDesktopStateInput,
StartSessionInput,
)
async def main() -> None:
driver = CuaDriver.create()
await driver.start_session(
StartSessionInput(session="demo", capture_scope=CaptureScope.DESKTOP)
)
try:
desktop = await driver.get_desktop_state(
GetDesktopStateInput(session="demo", screenshot_out_file=None)
)
print(desktop.images[0].mime_type)
finally:
await driver.end_session(EndSessionInput(session="demo"))
await driver.shutdown()
asyncio.run(main())
SDK operations are asynchronous. Desktop calls return a typed ToolResult with
text, images, verification/error metadata, and structured_json / raw_json
for platform-extensible results. Session lifecycle calls return dedicated
generated records.
CuaDriver.connect(socket_path) remains available while existing applications
migrate. It exposes the same methods over the installed daemon, but it does not
provide a second SDK contract.
shutdown() closes admission, waits for already admitted operations to finish,
and is idempotent. Calls started after shutdown fail with DriverError.Shutdown.
Destroying a binding handle releases native resources, but orderly applications
should still await shutdown().
Daemon-backed MCP host
Applications that must also expose MCP to an external agent can own a private daemon child. The child provides a stable permission identity and session lifetime for short-lived or external clients:
import asyncio
from cua_driver import CuaDriver, EmbeddedCuaDriverHost, get_binary_path
async def main() -> None:
host = EmbeddedCuaDriverHost(
binary_path=str(get_binary_path()),
host_bundle_id="com.example.your-app",
)
connection = await host.start()
driver = CuaDriver.connect(connection.socket_path)
try:
# Application calls use driver. An agent runtime can launch
# connection.mcp.command with connection.mcp.args and environment.
print(await driver.metadata())
finally:
del driver
await host.stop()
asyncio.run(main())
start() coalesces concurrent callers, stop() cancels startup and is
idempotent, and restart() returns a new generation/PID/endpoint. Destroy SDK
clients and MCP proxies before stopping or restarting, then reconnect from the
new connection. wait_for_exit(connection.generation) observes unexpected
termination. Dropping the host closes its parent-liveness pipe and kills the
child as a fallback, but orderly applications should still await stop().
Binary wrapper
The package also exposes the bundled executable:
from cua_driver import get_binary_path, run_cua_driver
print(get_binary_path())
exit_code = run_cua_driver(["mcp"])
Platform support
| Platform | Architecture | Status |
|---|---|---|
| macOS 13+ | Universal (ARM64 + x86_64) | Supported |
| Linux | x86_64 | Supported |
| Windows | x86_64 | Supported |
| Windows | ARM64 | Supported |
License
MIT License — see LICENSE.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file cua_driver-0.12.4-py3-none-win_arm64.whl.
File metadata
- Download URL: cua_driver-0.12.4-py3-none-win_arm64.whl
- Upload date:
- Size: 20.2 MB
- Tags: Python 3, Windows ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.12.3
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
948009305c1d6d8c7516caebf9a5c2de197c4943175c912707364d7a514cb772
|
|
| MD5 |
f9fb0d6cba7ff9328beffa10cbce9ccb
|
|
| BLAKE2b-256 |
b34fb9d3ee52f4150dae89c593af3875c073937847af1fb5e0034f9a9a5c1e57
|
File details
Details for the file cua_driver-0.12.4-py3-none-win_amd64.whl.
File metadata
- Download URL: cua_driver-0.12.4-py3-none-win_amd64.whl
- Upload date:
- Size: 21.8 MB
- Tags: Python 3, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.12.3
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
af809d1f0ac1319aa0692ae86800f671b68bb73cd82d34427335119a4d5289d5
|
|
| MD5 |
a96b6f9424d619a34ee0a4560b13bc9e
|
|
| BLAKE2b-256 |
e89a4b4735e08ae396f7754607b1f5755ac243acc0a97b56dab827155f2ddc37
|
File details
Details for the file cua_driver-0.12.4-py3-none-manylinux_2_31_x86_64.whl.
File metadata
- Download URL: cua_driver-0.12.4-py3-none-manylinux_2_31_x86_64.whl
- Upload date:
- Size: 22.9 MB
- Tags: Python 3, manylinux: glibc 2.31+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.12.3
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
2e5d4aeee632d15cdcfdbb3bbeb0706dcc5e80b61809783ccd8da23406bf388b
|
|
| MD5 |
2a48b08a581946d0c2cac7f42a69bead
|
|
| BLAKE2b-256 |
5f1387946cb4ad881ad760257ad867c584144fa112f46c1a0d7274152833f9b4
|
File details
Details for the file cua_driver-0.12.4-py3-none-manylinux_2_31_aarch64.whl.
File metadata
- Download URL: cua_driver-0.12.4-py3-none-manylinux_2_31_aarch64.whl
- Upload date:
- Size: 23.0 MB
- Tags: Python 3, manylinux: glibc 2.31+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.12.3
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
3f45b45ea5c0124657505d866ba8944432bea9394a1a7c767c76883f05680c97
|
|
| MD5 |
11d97e330660f3040e6ebecf4eeaeee8
|
|
| BLAKE2b-256 |
084ee3c42a260f164440b9a15d3e502b94036d81bb3aa87cef75f87be7eb507b
|
File details
Details for the file cua_driver-0.12.4-py3-none-macosx_13_0_universal2.whl.
File metadata
- Download URL: cua_driver-0.12.4-py3-none-macosx_13_0_universal2.whl
- Upload date:
- Size: 32.1 MB
- Tags: Python 3, macOS 13.0+ universal2 (ARM64, x86-64)
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.12.3
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
940f493c67c6c38a441d9e90e3dccfefde414a0d2bed2a3bebdcede62564e82c
|
|
| MD5 |
244f20c4560d9afcac6cc33c76ff72a9
|
|
| BLAKE2b-256 |
2cae409453b8a7edbd064abac7d41965e650e81179d4ff812194db1d0d3c34c1
|
