c/ua (pronounced "koo-ah") enables AI agents to control full operating systems in high-performance virtual containers with near-native speed on Apple Silicon.
vibe-photoshop.mp4
π Quick Start
Get started with a Computer-Use Agent UI and a VM with a single command:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/scripts/playground.sh)"This script will:
- Install Lume CLI for VM management (if needed)
- Pull the latest macOS CUA image (if needed)
- Set up Python environment and install/update required packages
- Launch the Computer-Use Agent UI
Supported Agent Loops
- UITARS-1.5 - Run locally on Apple Silicon with MLX, or use cloud providers
- OpenAI CUA - Use OpenAI's Computer-Use Preview model
- Anthropic CUA - Use Anthropic's Computer-Use capabilities
- OmniParser-v2.0 - Control UI with Set-of-Marks prompting using any vision model
System Requirements
- Mac with Apple Silicon (M1/M2/M3/M4 series)
- macOS 15 (Sequoia) or newer
- Disk space for VM images (30GB+ recommended)
π» For Developers
Step 1: Install Lume CLI
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"Lume CLI manages high-performance macOS/Linux VMs with near-native speed on Apple Silicon.
Step 2: Pull the macOS CUA Image
lume pull macos-sequoia-cua:latest
The macOS CUA image contains the default Mac apps and the Computer Server for easy automation.
Step 3: Install Python SDK
pip install "cua-computer[all]" "cua-agent[all]"
Alternatively, see the Developer Guide for building from source.
Step 4: Use in Your Code
from computer import Computer from agent import ComputerAgent, LLM async def main(): # Start a local macOS VM with a 1024x768 display async with Computer(os_type="macos", display="1024x768") as computer: # Example: Direct control of a macOS VM with Computer await computer.interface.left_click(100, 200) await computer.interface.type_text("Hello, world!") screenshot_bytes = await computer.interface.screenshot() # Example: Create and run an agent locally using mlx-community/UI-TARS-1.5-7B-6bit agent = ComputerAgent( computer=computer, loop="UITARS", model=LLM(provider="MLXVLM", name="mlx-community/UI-TARS-1.5-7B-6bit") ) await agent.run("Find the trycua/cua repository on GitHub and follow the quick start guide") main()
For ready-to-use examples, check out our Notebooks collection.
Lume CLI Reference
# Install Lume CLI and background service curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh | bash # List all VMs lume ls # Pull a VM image lume pull macos-sequoia-cua:latest # Create a new VM lume create my-vm --os macos --cpu 4 --memory 8GB --disk-size 50GB # Run a VM (creates and starts if it doesn't exist) lume run macos-sequoia-cua:latest # Stop a VM lume stop macos-sequoia-cua_latest # Delete a VM lume delete macos-sequoia-cua_latest
Lumier CLI Reference
For advanced container-like virtualization, check out Lumier - a Docker interface for macOS and Linux VMs.
# Install Lume CLI and background service curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh | bash # Run macOS in a Docker container docker run -it --rm \ --name lumier-vm \ -p 8006:8006 \ -v $(pwd)/storage:/storage \ -v $(pwd)/shared:/shared \ -e VM_NAME=lumier-vm \ -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \ -e CPU_CORES=4 \ -e RAM_SIZE=8192 \ -e HOST_STORAGE_PATH=$(pwd)/storage \ -e HOST_SHARED_PATH=$(pwd)/shared \ trycua/lumier:latest
Resources
- How to use the MCP Server with Claude Desktop or other MCP clients - One of the easiest ways to get started with C/ua
- How to use OpenAI Computer-Use, Anthropic, OmniParser, or UI-TARS for your Computer-Use Agent
- How to use Lume CLI for managing desktops
- Training Computer-Use Models: Collecting Human Trajectories with C/ua (Part 1)
- Build Your Own Operator on macOS (Part 1)
Modules
| Module | Description | Installation |
|---|---|---|
| Lume | VM management for macOS/Linux using Apple's Virtualization.Framework | curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh | bash |
| Lumier | Docker interface for macOS and Linux VMs | docker pull trycua/lumier:latest |
| Computer | Interface for controlling virtual machines | pip install "cua-computer[all]" |
| Agent | AI agent framework for automating tasks | pip install "cua-agent[all]" |
| MCP Server | MCP server for using CUA with Claude Desktop | pip install cua-mcp-server |
| SOM | Self-of-Mark library for Agent | pip install cua-som |
| PyLume | Python bindings for Lume | pip install pylume |
| Computer Server | Server component for Computer | pip install cua-computer-server |
| Core | Core utilities | pip install cua-core |
Computer Interface Reference
For complete examples, see computer_examples.py or computer_nb.ipynb
# Mouse Actions await computer.interface.left_click(x, y) # Left click at coordinates await computer.interface.right_click(x, y) # Right click at coordinates await computer.interface.double_click(x, y) # Double click at coordinates await computer.interface.move_cursor(x, y) # Move cursor to coordinates await computer.interface.drag_to(x, y, duration) # Drag to coordinates await computer.interface.get_cursor_position() # Get current cursor position # Keyboard Actions await computer.interface.type_text("Hello") # Type text await computer.interface.press_key("enter") # Press a single key await computer.interface.hotkey("command", "c") # Press key combination # Screen Actions await computer.interface.screenshot() # Take a screenshot await computer.interface.get_screen_size() # Get screen dimensions # Clipboard Actions await computer.interface.set_clipboard(text) # Set clipboard content await computer.interface.copy_to_clipboard() # Get clipboard content # File System Operations await computer.interface.file_exists(path) # Check if file exists await computer.interface.directory_exists(path) # Check if directory exists await computer.interface.run_command(cmd) # Run shell command # Accessibility await computer.interface.get_accessibility_tree() # Get accessibility tree
ComputerAgent Reference
For complete examples, see agent_examples.py or agent_nb.ipynb
# Import necessary components from agent import ComputerAgent, LLM, AgentLoop, LLMProvider # UI-TARS-1.5 agent for local execution with MLX ComputerAgent(loop=AgentLoop.UITARS, model=LLM(provider=LLMProvider.MLXVLM, name="mlx-community/UI-TARS-1.5-7B-6bit")) # OpenAI Computer-Use agent using OPENAI_API_KEY ComputerAgent(loop=AgentLoop.OPENAI, model=LLM(provider=LLMProvider.OPENAI, name="computer-use-preview")) # Anthropic Claude agent using ANTHROPIC_API_KEY ComputerAgent(loop=AgentLoop.ANTHROPIC, model=LLM(provider=LLMProvider.ANTHROPIC)) # OmniParser loop for UI control using Set-of-Marks (SOM) prompting and any vision LLM ComputerAgent(loop=AgentLoop.OMNI, model=LLM(provider=LLMProvider.OLLAMA, name="gemma3:12b-it-q4_K_M")) # OpenRouter example using OAICOMPAT provider ComputerAgent( loop=AgentLoop.OMNI, model=LLM( provider=LLMProvider.OAICOMPAT, name="openai/gpt-4o-mini", provider_base_url="https://openrouter.ai/api/v1" ), api_key="your-openrouter-api-key" )
Demos
Check out these demos of the Computer-Use Agent in action:
MCP Server: Work with Claude Desktop and Tableau
mcp-claude-tableau.mp4
AI-Gradio: Multi-app workflow with browser, VS Code and terminal
ai-gradio-clone.mp4
Notebook: Fix GitHub issue in Cursor
notebook-github-cursor.mp4
Community
Join our Discord community to discuss ideas, get assistance, or share your demos!
License
Cua is open-sourced under the MIT License - see the LICENSE file for details.
Microsoft's OmniParser, which is used in this project, is licensed under the Creative Commons Attribution 4.0 International License (CC-BY-4.0) - see the OmniParser LICENSE file for details.
Contributing
We welcome contributions to CUA! Please refer to our Contributing Guidelines for details.
Trademarks
Apple, macOS, and Apple Silicon are trademarks of Apple Inc. Ubuntu and Canonical are registered trademarks of Canonical Ltd. Microsoft is a registered trademark of Microsoft Corporation. This project is not affiliated with, endorsed by, or sponsored by Apple Inc., Canonical Ltd., or Microsoft Corporation.
Stargazers
Thank you to all our supporters!