CUA Client

Computer Use Automation (CUA) Client - A Python package for remote function execution and computer automation tasks via WebSocket connections.

Features

Remote Function Execution: Connect to remote servers and execute functions over WebSocket
Computer Use Automation: Automate mouse, keyboard, and screen interactions
Flexible Configuration: Environment-based configuration with validation
Async Support: Built with asyncio for high-performance concurrent operations
Extensible: Easy to add custom functions and routers

Installation

pip install cua-client

Quick Start

1. Set Environment Variables

export REMOTE_FUNCTION_URL="ws://your-server.com/ws"
export AGENT_ID="123"
export SECRET_KEY="your-secret-key"

2. Run the Client

# As a command-line tool
cua-client

# Or programmatically
python -m cua_client.main

3. Programmatic Usage

import asyncio
from cua_client import RemoteFunctionClient, RemoteFunctionRouter

# Create a custom router
my_router = RemoteFunctionRouter(tags=["custom"])

@my_router.function("greet")
def greet(name: str) -> str:
    return f"Hello, {name}!"

# Set up the client
async def main():
    client = RemoteFunctionClient(
        remote_function_url="ws://your-server.com/ws",
        agent_id=123,
        secret_key="your-secret-key"
    )
    
    # Add your custom router
    client.include_router(my_router)
    
    # Run the client
    await client.run()

if __name__ == "__main__":
    asyncio.run(main())

Configuration

The client requires three environment variables:

REMOTE_FUNCTION_URL: WebSocket server URL (e.g., ws://localhost:8000/ws)
AGENT_ID: Unique identifier for the client agent (integer)
SECRET_KEY: Authentication secret key

Built-in Functions

Computer Use Functions

The client comes with built-in computer automation capabilities:

Screen capture: Take screenshots and analyze screen content
Mouse control: Click, drag, and move mouse cursor
Keyboard input: Type text and send key combinations
Window management: Focus windows and manage applications

Basic Functions

print: Simple message printing function for testing

Advanced Usage

Custom Function Registration

from cua_client import RemoteFunctionClient

client = RemoteFunctionClient(url, agent_id, secret_key)

# Register a single function
def my_function(param: str) -> str:
    return f"Processed: {param}"

client.register_function("my_func", my_function)

# Or use a router for organized function groups
router = RemoteFunctionRouter(tags=["data"])

@router.function("process_data")
def process_data(data: dict) -> dict:
    # Your processing logic here
    return {"result": "processed", "original": data}

client.include_router(router)

Error Handling

try:
    await client.run()
except ConnectionError:
    print("Failed to connect to server")
except KeyboardInterrupt:
    print("Client stopped by user")
except Exception as e:
    print(f"Unexpected error: {e}")

Security Considerations

Always use secure WebSocket connections (wss://) in production
Keep your SECRET_KEY confidential and rotate it regularly
Validate all inputs in your custom functions
Run the client with minimal required permissions

Dependencies

pydantic>=1.8.0: Data validation and configuration
websockets>=10.0: WebSocket client implementation
pynput>=1.7.0: Mouse and keyboard control
Pillow>=8.0.0: Image processing for screenshots
pyautogui>=0.9.50: GUI automation utilities

Development

Installation for Development

# Clone the repository
git clone https://github.com/168x/cua-client.git
cd cua-client

# Install in development mode
pip install -e .[dev]

Building and Publishing

Use the provided script to build and publish the package:

# Make the script executable
chmod +x publish.sh

# Run the interactive publish script
./publish.sh

The script will:

Show current version and suggest increments
Update version in all necessary files
Build the package
Validate the build
Optionally publish to PyPI or Test PyPI

See PUBLISH_USAGE.md for detailed usage instructions.

Running Tests

pytest

Code Formatting

black src/
flake8 src/
mypy src/

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
Submit a pull request

License

MIT License - see LICENSE file for details.

Support

Report bugs: GitHub Issues
Documentation: GitHub README
Discussions: GitHub Discussions

Changelog

v0.1.0

Initial release
Basic remote function execution
Computer use automation features
WebSocket-based communication
Environment-based configuration

Metadata

Release files for cua-client 0.3.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cua-client 0.3.5
File	Size	Uploaded
cua_client-0.3.5.tar.gz	33.0 kB	Oct 13, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for cua-client 0.3.5
File	Interpreter	ABI	Platform	Reset
cua_client-0.3.5-py3-none-any.whl 38.8 kB Oct 13, 2025	Python 3	none	any	Details

Total release size: 71.8 kB

Release files / cua_client-0.3.5.tar.gz

Download URL	cua_client-0.3.5.tar.gz
Size	33.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`33d23c7ec24fb2c82343387fb716f28d51416d8e25c5659be3afbabd52ed052a`
BLAKE2b-256 checksum How to use checksums	`3a43c4f7bfc57b0526f88315f7bd499de68dae277767525f9e914900623c56dd`
Upload date	Oct 13, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.7`

Release files / cua_client-0.3.5-py3-none-any.whl

Download URL	cua_client-0.3.5-py3-none-any.whl
Size	38.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f95a7a54ae4eb118cb45588dca2d697cce9c5e32d194ed16fd33166b92d93119`
BLAKE2b-256 checksum How to use checksums	`d37a5fdfd2314c1d6db9ba37b1f5acc5a1f2bdcf499683d11c6d699c6415eac6`
Upload date	Oct 13, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.7`