Skip to content

Navigation Menu

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings
/ cua Public

c/ua is the Docker Container for Computer-Use AI Agents.

License

Notifications You must be signed in to change notification settings

trycua/cua

Repository files navigation

Cua logo

Python Swift macOS Discord
trycua%2Fcua | Trendshift

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

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

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!

Stargazers over time

Contributors

f-trycua
f-trycua

💻
Pedro Piñera Buendía
Pedro Piñera Buendía

💻
Amit Kumar
Amit Kumar

💻
Dung Duc Huynh (Kaka)
Dung Duc Huynh (Kaka)

💻
Zayd Krunz
Zayd Krunz

💻
Prashant Raj
Prashant Raj

💻
Leland Takamine
Leland Takamine

💻
ddupont
ddupont

💻
Ethan Gutierrez
Ethan Gutierrez

💻
Ricter Zheng
Ricter Zheng

💻
Rahul Karajgikar
Rahul Karajgikar

💻
trospix
trospix

💻
Ikko Eltociear Ashimine
Ikko Eltociear Ashimine

💻
한석호(MilKyo)
한석호(MilKyo)

💻
Rahim Nathwani
Rahim Nathwani

💻
Matt Speck
Matt Speck

💻
FinnBorge
FinnBorge

💻
Jakub Klapacz
Jakub Klapacz

💻
Morty Proxy This is a proxified and sanitized view of the page, visit original site.