Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

added compat matrix to readme

Dillon DuPont22a56c449147
diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md
new file mode 100644
index 0000000000..2ff8e5a6b4
--- /dev/null
+++ b/COMPATIBILITY.md
@@ -0,0 +1,119 @@
+# C/ua Compatibility Matrix
+
+## Table of Contents
+- [Host OS Compatibility](#host-os-compatibility)
+ - [macOS Host](#macos-host)
+ - [Ubuntu/Linux Host](#ubuntulinux-host)
+ - [Windows Host](#windows-host)
+- [VM Emulation Support](#vm-emulation-support)
+- [Installation Method Details](#installation-method-details)
+
+---
+
+## Host OS Compatibility
+
+*This section shows compatibility based on your **host operating system** (the OS you're running C/ua on).*
+
+### macOS Host
+
+| Installation Method | Requirements | Lume | Cloud | Notes |
+|-------------------|-------------|------|-------|-------|
+| **playground-docker.sh** | Docker Desktop | ✅ Full | ✅ Full | Recommended for quick setup |
+| **Dev Container** | VS Code/WindSurf + Docker | ✅ Full | ✅ Full | Best for development |
+| **PyPI packages** | Python 3.12+ | ✅ Full | ✅ Full | Most flexible |
+
+**macOS Host Requirements:**
+- macOS 15+ (Sequoia) for local VM support
+- Apple Silicon (M1/M2/M3/M4) recommended for best performance
+- Docker Desktop for containerized installations
+
+---
+
+### Ubuntu/Linux Host
+
+| Installation Method | Requirements | Lume | Cloud | Notes |
+|-------------------|-------------|------|-------|-------|
+| **playground-docker.sh** | Docker Engine | ✅ Full | ✅ Full | Recommended for quick setup |
+| **Dev Container** | VS Code/WindSurf + Docker | ✅ Full | ✅ Full | Best for development |
+| **PyPI packages** | Python 3.12+ | ✅ Full | ✅ Full | Most flexible |
+
+**Ubuntu/Linux Host Requirements:**
+- Ubuntu 20.04+ or equivalent Linux distribution
+- Docker Engine or Docker Desktop
+- Python 3.12+ for PyPI installation
+
+---
+
+### Windows Host
+
+| Installation Method | Requirements | Lume | Winsandbox | Cloud | Notes |
+|-------------------|-------------|------|------------|-------|-------|
+| **playground-docker.sh** | Docker Desktop + WSL2 | ❌ Not supported | ❌ Not supported | ✅ Full | Requires WSL2 |
+| **Dev Container** | VS Code/WindSurf + Docker + WSL2 | ❌ Not supported | ❌ Not supported | ✅ Full | Requires WSL2 |
+| **PyPI packages** | Python 3.12+ | ❌ Not supported | ✅ Limited | ✅ Full | WSL for .sh scripts |
+
+**Windows Host Requirements:**
+- Windows 10/11 with WSL2 enabled for shell script execution
+- Docker Desktop with WSL2 backend
+- Windows Sandbox feature enabled (for Winsandbox support)
+- Python 3.12+ installed in WSL2 or Windows
+- **Note**: Lume CLI is not available on Windows - use Cloud or Winsandbox providers
+
+---
+
+## VM Emulation Support
+
+*This section shows which **virtual machine operating systems** each provider can emulate.*
+
+| Provider | macOS VM | Ubuntu/Linux VM | Windows VM | Notes |
+|----------|----------|-----------------|------------|-------|
+| **Lume** | ✅ Full support | ⚠️ Limited support | ⚠️ Limited support | macOS: native; Ubuntu/Linux/Windows: need custom image |
+| **Cloud** | 🚧 Coming soon | ✅ Full support | 🚧 Coming soon | Currently Ubuntu only, macOS/Windows in development |
+| **Winsandbox** | ❌ Not supported | ❌ Not supported | ✅ Windows only | Windows Sandbox environments only |
+
+### VM Emulation Details
+
+#### Lume VM Support
+- **macOS VMs**: ✅ Full native support with official images
+- **Ubuntu/Linux VMs**: ⚠️ Limited support - requires custom image creation
+- **Windows VMs**: ⚠️ Limited support - requires custom image creation
+
+#### Cloud VM Support
+- **Ubuntu/Linux VMs**: ✅ Full support with managed cloud instances
+- **macOS VMs**: 🚧 Coming soon - in development
+- **Windows VMs**: 🚧 Coming soon - in development
+
+#### Windows Sandbox VM Support
+- **Windows VMs**: ✅ Full support for Windows Sandbox environments
+- **macOS/Linux VMs**: ❌ Not supported - Windows Sandbox only runs Windows
+
+---
+
+## Installation Method Details
+
+### playground-docker.sh
+- **Containerized setup** using Docker
+- Handles all dependencies automatically
+- Requires Docker Desktop (Windows/macOS) or Docker Engine (Linux)
+- **Windows note**: Must run in WSL2 environment
+
+### Dev Container
+- **Development-focused** setup for contributors
+- Integrates with VS Code and WindSurf IDEs
+- Provides consistent development environment
+- **Windows note**: Requires WSL2 backend for Docker
+
+### PyPI packages
+- **Manual installation** via pip
+- Most flexible installation method
+- Allows custom configurations and integrations
+- **Windows note**: Shell scripts require WSL2, but Python packages work natively
+
+---
+
+## Legend
+
+- ✅ **Full support**: All features work natively without limitations
+- ⚠️ **Partial support**: Requires additional setup (e.g., WSL2) or has limitations
+- ❌ **Not supported**: Feature/provider combination is not available
+- 🚧 **Coming soon**: Feature/provider combination is in development
diff --git a/README.md b/README.md
index 041de65e79..fa4c2282de 100644
--- a/README.md
+++ b/README.md
@@ -74,20 +74,26 @@ This repository includes a [Dev Container](./.devcontainer/README.md) configurat
2. **Open the repository in the Dev Container:**
- Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS)
- Select `Dev Containers: Clone Repository in Container Volume...` and paste the repository URL: `https://github.com/trycua/cua.git` (if not cloned) or `Dev Containers: Open Folder in Container...` (if already cloned). **Note**: On WindSurf, the post install hook might not run automatically. If so, run `/bin/bash .devcontainer/post-install.sh` manually.
-3. **Run the Agent UI example:** Click ![Run Agent UI](https://github.com/user-attachments/assets/7a61ef34-4b22-4dab-9864-f86bf83e290b)
+3. **Open the VS Code workspace:** Once the post-install.sh is done running, open the `.vscode/py.code-workspace` workspace and press "Open Workspace".
+4. **Run the Agent UI example:** Click ![Run Agent UI](https://github.com/user-attachments/assets/7a61ef34-4b22-4dab-9864-f86bf83e290b)
to start the Gradio UI. If prompted to install **debugpy (Python Debugger)** to enable remote debugging, select 'Yes' to proceed.
-4. **Access the Gradio UI:** The Gradio UI will be available at `http://localhost:7860` and will automatically forward to your host machine.
+5. **Access the Gradio UI:** The Gradio UI will be available at `http://localhost:7860` and will automatically forward to your host machine.
---
-*How it works: Computer module provides secure desktops (Lume CLI locally, [C/ua Cloud Containers](https://trycua.com) remotely), Agent module provides local/API agents with OpenAI AgentResponse format and [trajectory tracing](https://trycua.com/trajectory-viewer).*
-### Supported [Agent Loops](https://github.com/trycua/cua/blob/main/libs/agent/README.md#agent-loops)
+
+## Supported [Agent Loops](https://github.com/trycua/cua/blob/main/libs/agent/README.md#agent-loops)
- [UITARS-1.5](https://github.com/trycua/cua/blob/main/libs/agent/README.md#agent-loops) - Run locally on Apple Silicon with MLX, or use cloud providers
- [OpenAI CUA](https://github.com/trycua/cua/blob/main/libs/agent/README.md#agent-loops) - Use OpenAI's Computer-Use Preview model
- [Anthropic CUA](https://github.com/trycua/cua/blob/main/libs/agent/README.md#agent-loops) - Use Anthropic's Computer-Use capabilities
- [OmniParser-v2.0](https://github.com/trycua/cua/blob/main/libs/agent/README.md#agent-loops) - Control UI with [Set-of-Marks prompting](https://som-gpt4v.github.io/) using any vision model
+## 🖥️ OS Compatibility
+
+For detailed compatibility information including host OS support and VM emulation capabilities, see the [**Compatibility Matrix**](./COMPATIBILITY.md).
+<br/>
+<br/>
# 💻 Developer Guide