# 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
```bash
pip install cua-client
```
## Quick Start
### 1. Set Environment Variables
```bash
export REMOTE_FUNCTION_URL="ws://your-server.com/ws"
export AGENT_ID="123"
export SECRET_KEY="your-secret-key"
```
### 2. Run the Client
```bash
# As a command-line tool
cua-client
# Or programmatically
python -m cua_client.main
```
### 3. Programmatic Usage
```python
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
```python
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
```python
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
```bash
# 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:
```bash
# 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
```bash
pytest
```
### Code Formatting
```bash
black src/
flake8 src/
mypy src/
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request
## License
MIT License - see LICENSE file for details.
## Support
- Report bugs: [GitHub Issues](https://github.com/168x/cua-client/issues)
- Documentation: [GitHub README](https://github.com/168x/cua-client#readme)
- Discussions: [GitHub Discussions](https://github.com/168x/cua-client/discussions)
## Changelog
### v0.1.0
- Initial release
- Basic remote function execution
- Computer use automation features
- WebSocket-based communication
- Environment-based configuration
Raw data
{
"_id": null,
"home_page": null,
"name": "cua-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "168x Project <admin@168x.com>",
"keywords": "automation, remote, computer-use, websocket, rpc",
"author": null,
"author_email": "168x Project <admin@168x.com>",
"download_url": "https://files.pythonhosted.org/packages/82/3f/0eee24fe57e6ad848676b824fbb301e045e3ab11bf13a0fc682541f2d038/cua_client-0.1.19.tar.gz",
"platform": null,
"description": "# CUA Client\n\n**Computer Use Automation (CUA) Client** - A Python package for remote function execution and computer automation tasks via WebSocket connections.\n\n## Features\n\n- **Remote Function Execution**: Connect to remote servers and execute functions over WebSocket\n- **Computer Use Automation**: Automate mouse, keyboard, and screen interactions\n- **Flexible Configuration**: Environment-based configuration with validation\n- **Async Support**: Built with asyncio for high-performance concurrent operations\n- **Extensible**: Easy to add custom functions and routers\n\n## Installation\n\n```bash\npip install cua-client\n```\n\n## Quick Start\n\n### 1. Set Environment Variables\n\n```bash\nexport REMOTE_FUNCTION_URL=\"ws://your-server.com/ws\"\nexport AGENT_ID=\"123\"\nexport SECRET_KEY=\"your-secret-key\"\n```\n\n### 2. Run the Client\n\n```bash\n# As a command-line tool\ncua-client\n\n# Or programmatically\npython -m cua_client.main\n```\n\n### 3. Programmatic Usage\n\n```python\nimport asyncio\nfrom cua_client import RemoteFunctionClient, RemoteFunctionRouter\n\n# Create a custom router\nmy_router = RemoteFunctionRouter(tags=[\"custom\"])\n\n@my_router.function(\"greet\")\ndef greet(name: str) -> str:\n return f\"Hello, {name}!\"\n\n# Set up the client\nasync def main():\n client = RemoteFunctionClient(\n remote_function_url=\"ws://your-server.com/ws\",\n agent_id=123,\n secret_key=\"your-secret-key\"\n )\n \n # Add your custom router\n client.include_router(my_router)\n \n # Run the client\n await client.run()\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n## Configuration\n\nThe client requires three environment variables:\n\n- `REMOTE_FUNCTION_URL`: WebSocket server URL (e.g., `ws://localhost:8000/ws`)\n- `AGENT_ID`: Unique identifier for the client agent (integer)\n- `SECRET_KEY`: Authentication secret key\n\n## Built-in Functions\n\n### Computer Use Functions\n\nThe client comes with built-in computer automation capabilities:\n\n- **Screen capture**: Take screenshots and analyze screen content\n- **Mouse control**: Click, drag, and move mouse cursor\n- **Keyboard input**: Type text and send key combinations\n- **Window management**: Focus windows and manage applications\n\n### Basic Functions\n\n- `print`: Simple message printing function for testing\n\n## Advanced Usage\n\n### Custom Function Registration\n\n```python\nfrom cua_client import RemoteFunctionClient\n\nclient = RemoteFunctionClient(url, agent_id, secret_key)\n\n# Register a single function\ndef my_function(param: str) -> str:\n return f\"Processed: {param}\"\n\nclient.register_function(\"my_func\", my_function)\n\n# Or use a router for organized function groups\nrouter = RemoteFunctionRouter(tags=[\"data\"])\n\n@router.function(\"process_data\")\ndef process_data(data: dict) -> dict:\n # Your processing logic here\n return {\"result\": \"processed\", \"original\": data}\n\nclient.include_router(router)\n```\n\n### Error Handling\n\n```python\ntry:\n await client.run()\nexcept ConnectionError:\n print(\"Failed to connect to server\")\nexcept KeyboardInterrupt:\n print(\"Client stopped by user\")\nexcept Exception as e:\n print(f\"Unexpected error: {e}\")\n```\n\n## Security Considerations\n\n- Always use secure WebSocket connections (`wss://`) in production\n- Keep your `SECRET_KEY` confidential and rotate it regularly\n- Validate all inputs in your custom functions\n- Run the client with minimal required permissions\n\n## Dependencies\n\n- `pydantic>=1.8.0`: Data validation and configuration\n- `websockets>=10.0`: WebSocket client implementation\n- `pynput>=1.7.0`: Mouse and keyboard control\n- `Pillow>=8.0.0`: Image processing for screenshots\n- `pyautogui>=0.9.50`: GUI automation utilities\n\n## Development\n\n### Installation for Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/168x/cua-client.git\ncd cua-client\n\n# Install in development mode\npip install -e .[dev]\n```\n\n### Building and Publishing\n\nUse the provided script to build and publish the package:\n\n```bash\n# Make the script executable\nchmod +x publish.sh\n\n# Run the interactive publish script\n./publish.sh\n```\n\nThe script will:\n- Show current version and suggest increments\n- Update version in all necessary files\n- Build the package\n- Validate the build\n- Optionally publish to PyPI or Test PyPI\n\nSee `PUBLISH_USAGE.md` for detailed usage instructions.\n\n### Running Tests\n\n```bash\npytest\n```\n\n### Code Formatting\n\n```bash\nblack src/\nflake8 src/\nmypy src/\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass\n6. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Support\n\n- Report bugs: [GitHub Issues](https://github.com/168x/cua-client/issues)\n- Documentation: [GitHub README](https://github.com/168x/cua-client#readme)\n- Discussions: [GitHub Discussions](https://github.com/168x/cua-client/discussions)\n\n## Changelog\n\n### v0.1.0\n\n- Initial release\n- Basic remote function execution\n- Computer use automation features\n- WebSocket-based communication\n- Environment-based configuration \n",
"bugtrack_url": null,
"license": null,
"summary": "Computer Use Automation (CUA) client for remote function execution",
"version": "0.1.19",
"project_urls": {
"Documentation": "https://github.com/168x/cua-client#readme",
"Homepage": "https://github.com/168x/cua-client",
"Issues": "https://github.com/168x/cua-client/issues",
"Repository": "https://github.com/168x/cua-client"
},
"split_keywords": [
"automation",
" remote",
" computer-use",
" websocket",
" rpc"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7a4835f0fcbdfc46bf393a20ccbaec728cc8c00f5e28dd3ee9956367b2ea62f8",
"md5": "ea63e1efd860ab6ebc54e20d7ef1d766",
"sha256": "02a42e9b1534b5cd680a23af6f5b266a504d80b67dc142afd67fc2ae2a7c6623"
},
"downloads": -1,
"filename": "cua_client-0.1.19-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ea63e1efd860ab6ebc54e20d7ef1d766",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 22188,
"upload_time": "2025-07-09T19:46:24",
"upload_time_iso_8601": "2025-07-09T19:46:24.821547Z",
"url": "https://files.pythonhosted.org/packages/7a/48/35f0fcbdfc46bf393a20ccbaec728cc8c00f5e28dd3ee9956367b2ea62f8/cua_client-0.1.19-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "823f0eee24fe57e6ad848676b824fbb301e045e3ab11bf13a0fc682541f2d038",
"md5": "609eb7a48ec216dd19b6777db36d80a7",
"sha256": "6b7e60271e75584e39d7fff1593c5e96f5d31e17b4dc7ad29745e9295dc6e82d"
},
"downloads": -1,
"filename": "cua_client-0.1.19.tar.gz",
"has_sig": false,
"md5_digest": "609eb7a48ec216dd19b6777db36d80a7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 20079,
"upload_time": "2025-07-09T19:46:25",
"upload_time_iso_8601": "2025-07-09T19:46:25.798401Z",
"url": "https://files.pythonhosted.org/packages/82/3f/0eee24fe57e6ad848676b824fbb301e045e3ab11bf13a0fc682541f2d038/cua_client-0.1.19.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 19:46:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "168x",
"github_project": "cua-client#readme",
"github_not_found": true,
"lcname": "cua-client"
}
JSON
