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.

refactor(docs): reorganize lume/cua docs and standardize READMEs (#752)

Francesco Bonacci0b8c3013286d
diff --git a/.github/workflows/ci-test-python.yml b/.github/workflows/ci-test-python.yml
index 4b493e7d7d..938c14fc06 100644
--- a/.github/workflows/ci-test-python.yml
+++ b/.github/workflows/ci-test-python.yml
@@ -27,7 +27,6 @@ jobs:
- computer
- computer-server
- mcp-server
- - pylume
- som
steps:
diff --git a/docs/content/docs/cua/guide/fundamentals/agent-loops.mdx b/docs/content/docs/cua/guide/fundamentals/agent-loops.mdx
index 4de934d5a0..062bb68270 100644
--- a/docs/content/docs/cua/guide/fundamentals/agent-loops.mdx
+++ b/docs/content/docs/cua/guide/fundamentals/agent-loops.mdx
@@ -4,11 +4,7 @@ description: Supported computer-using agent loops and models
---
<Callout>
- A corresponding{' '}
- <a href="https://github.com/trycua/cua/blob/main/notebooks/agent_nb.ipynb" target="_blank">
- Jupyter Notebook
- </a>{' '}
- is available for this documentation.
+ A corresponding <a href="https://github.com/trycua/cua/blob/main/notebooks/agent_nb.ipynb" target="_blank">Jupyter Notebook</a> is available for this documentation.
</Callout>
An **agent loop** runs iteratively until a task is complete:
diff --git a/docs/content/docs/cua/guide/integrations/hud.mdx b/docs/content/docs/cua/guide/integrations/hud.mdx
index ca20af1e39..9f96e40995 100644
--- a/docs/content/docs/cua/guide/integrations/hud.mdx
+++ b/docs/content/docs/cua/guide/integrations/hud.mdx
@@ -4,11 +4,7 @@ description: Use ComputerAgent with HUD for benchmarking and evaluation
---
<Callout>
- A corresponding{' '}
- <a href="https://github.com/trycua/cua/blob/main/notebooks/eval_osworld.ipynb" target="_blank">
- Jupyter Notebook
- </a>{' '}
- is available for this documentation.
+ A corresponding <a href="https://github.com/trycua/cua/blob/main/notebooks/eval_osworld.ipynb" target="_blank">Jupyter Notebook</a> is available for this documentation.
</Callout>
The HUD integration allows an agent to be benchmarked using the [HUD framework](https://www.hud.so/). Through the HUD integration, the agent controls a computer inside HUD, where tests are run to evaluate the success of each task.
diff --git a/docs/content/docs/cua/reference/cli-playbook/commands.mdx b/docs/content/docs/cua/reference/cloud-cli/commands.mdx
similarity index 100%
rename from docs/content/docs/cua/reference/cli-playbook/commands.mdx
rename to docs/content/docs/cua/reference/cloud-cli/commands.mdx
diff --git a/docs/content/docs/cua/reference/cli-playbook/index.mdx b/docs/content/docs/cua/reference/cloud-cli/index.mdx
similarity index 100%
rename from docs/content/docs/cua/reference/cli-playbook/index.mdx
rename to docs/content/docs/cua/reference/cloud-cli/index.mdx
diff --git a/docs/content/docs/cua/reference/cli-playbook/meta.json b/docs/content/docs/cua/reference/cloud-cli/meta.json
similarity index 100%
rename from docs/content/docs/cua/reference/cli-playbook/meta.json
rename to docs/content/docs/cua/reference/cloud-cli/meta.json
diff --git a/docs/content/docs/cua/reference/desktop-sandbox/index.mdx b/docs/content/docs/cua/reference/desktop-sandbox/index.mdx
new file mode 100644
index 0000000000..0c6ab59092
--- /dev/null
+++ b/docs/content/docs/cua/reference/desktop-sandbox/index.mdx
@@ -0,0 +1,59 @@
+---
+title: Desktop Sandbox
+description: Isolated desktop environments for Computer-Using Agents
+---
+
+Desktop sandbox environments provide isolated desktops for running Computer-Using Agents. Each environment includes a pre-installed computer-server for remote control via HTTP API.
+
+## Sandbox Options
+
+### [macOS Sandbox](/cua/reference/desktop-sandbox/macos)
+
+Native macOS virtual machines on Apple Silicon using Apple's Virtualization Framework. Near-native performance for macOS automation.
+
+- **Lume** - Native CLI for VM management
+- **Lumier** - Docker wrapper for containerized deployments
+
+### [Linux Container](/cua/reference/desktop-sandbox/linux-container)
+
+Docker containers running Linux desktops. Fast startup, low resource usage.
+
+| Container | Description |
+|-----------|-------------|
+| [Kasm](/cua/reference/desktop-sandbox/linux-container/kasm) | KasmWeb-based Ubuntu with XFCE |
+| [XFCE](/cua/reference/desktop-sandbox/linux-container/xfce) | Vanilla XFCE, minimal dependencies |
+
+### [QEMU Container](/cua/reference/desktop-sandbox/qemu-container)
+
+Full virtual machines running in Docker via QEMU/KVM. Complete OS isolation, supports Windows.
+
+| Container | OS | Description |
+|-----------|-----|-------------|
+| [Windows](/cua/reference/desktop-sandbox/qemu-container/windows) | Windows 11 | Windows desktop with KVM |
+| [Linux](/cua/reference/desktop-sandbox/qemu-container/linux) | Ubuntu 22.04 | Full Ubuntu VM |
+| [Android](/cua/reference/desktop-sandbox/qemu-container/android) | Android 11 | Android emulator |
+
+## Quick Comparison
+
+| Feature | macOS (Lume) | Linux Container | QEMU VM |
+|---------|--------------|-----------------|---------|
+| Performance | Near-native | Native | Virtualized |
+| Startup Time | Minutes | Seconds | 30s-2min |
+| Host Requirements | Apple Silicon | Docker | KVM support |
+| Windows Support | No | No | Yes |
+| Resource Usage | Medium | Low | High |
+| Memory Snapshots | Yes | No | Yes |
+| Filesystem Snapshots | Yes | Yes | Yes |
+
+### Snapshot Capabilities
+
+**macOS (Lume)** and **QEMU containers** support full memory snapshots, allowing you to save and restore the complete VM state including running processes and memory contents. This is useful for creating checkpoints during long-running tasks or reverting to a known state.
+
+**Linux containers** (Kasm, XFCE) only support filesystem snapshots via `docker commit`, which saves the disk state but not running processes or memory. The container must be restarted after restoring.
+
+## Common Access Points
+
+All environments expose:
+
+- **Computer Server API** - HTTP API for automation (port 5000 or 8000)
+- **VNC/noVNC** - Visual desktop access via browser (port 6901 or 8006)
diff --git a/docs/content/docs/cua/reference/desktop-sandbox/linux-container/kasm.mdx b/docs/content/docs/cua/reference/desktop-sandbox/linux-container/kasm.mdx
new file mode 100644
index 0000000000..47c8f88876
--- /dev/null
+++ b/docs/content/docs/cua/reference/desktop-sandbox/linux-container/kasm.mdx
@@ -0,0 +1,89 @@
+---
+title: Kasm Container
+description: Kasm-based Ubuntu desktop container for Computer-Using Agents
+---
+
+Containerized virtual desktop for Computer-Using Agents (Cua). Utilizes Kasm's MIT-licensed Ubuntu XFCE container as a base with computer-server pre-installed.
+
+## Features
+
+- Ubuntu 22.04 (Jammy) with XFCE desktop environment
+- Pre-installed computer-server for remote computer control
+- VNC access for visual desktop interaction
+- Python 3.11 with necessary libraries
+- Screen capture tools (gnome-screenshot, wmctrl, ffmpeg)
+- Clipboard utilities (xclip, socat)
+
+## Quick Start
+
+```bash
+docker pull trycua/cua-ubuntu:latest
+
+docker run --rm -it \
+ --shm-size=512m \
+ -p 6901:6901 \
+ -p 8000:8000 \
+ -e VNCOPTIONS=-disableBasicAuth \
+ trycua/cua-ubuntu:latest
+```
+
+**Access Points:**
+- **VNC Web Interface**: `http://localhost:6901`
+- **Computer Server API**: `http://localhost:8000`
+
+## Using with Cua
+
+```python
+from computer import Computer
+
+computer = Computer(
+ os_type="linux",
+ provider_type="docker",
+ image="trycua/cua-ubuntu:latest",
+ display="1024x768",
+ memory="4GB",
+ cpu="2"
+)
+
+async with computer:
+ screenshot = await computer.interface.screenshot()
+ await computer.interface.left_click(100, 100)
+ await computer.interface.type_text("Hello from Cua!")
+```
+
+## Configuration
+
+### Ports
+
+- **6901**: VNC web interface (noVNC)
+- **8000**: Computer-server API endpoint
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `VNC_PW` | `password` | VNC password |
+| `DISPLAY` | `:0` | X11 display |
+
+### Volumes
+
+- `/home/kasm-user/storage`: Persistent storage mount point
+- `/home/kasm-user/shared`: Shared folder mount point
+
+## Creating Snapshots
+
+Create a filesystem snapshot of the container:
+
+```bash
+docker commit <container_id> cua-ubuntu-snapshot:latest
+```
+
+Then run the snapshot:
+
+```bash
+docker run --rm -it --shm-size=512m -p 6901:6901 -p 8000:8000 -e VNCOPTIONS=-disableBasicAuth cua-ubuntu-snapshot:latest
+```
+
+## Building from Source
+
+To build the image manually, see the [kasm source code](https://github.com/trycua/cua/tree/main/libs/kasm).
diff --git a/docs/content/docs/cua/reference/desktop-sandbox/linux-container/meta.json b/docs/content/docs/cua/reference/desktop-sandbox/linux-container/meta.json
new file mode 100644
index 0000000000..acabd08737
--- /dev/null
+++ b/docs/content/docs/cua/reference/desktop-sandbox/linux-container/meta.json
@@ -0,0 +1,4 @@
+{
+ "title": "Linux Container",
+ "pages": ["kasm", "xfce"]
+}
diff --git a/docs/content/docs/cua/reference/desktop-sandbox/linux-container/xfce.mdx b/docs/content/docs/cua/reference/desktop-sandbox/linux-container/xfce.mdx
new file mode 100644
index 0000000000..e34892ff61
--- /dev/null
+++ b/docs/content/docs/cua/reference/desktop-sandbox/linux-container/xfce.mdx
@@ -0,0 +1,123 @@
+---
+title: XFCE Container
+description: Vanilla XFCE desktop container for Computer-Using Agents
+---
+
+Vanilla XFCE desktop container for Computer-Using Agents (Cua) with noVNC and computer-server. This is a lightweight alternative to the Kasm-based container with minimal dependencies.
+
+## Features
+
+- Ubuntu 22.04 (Jammy) with vanilla XFCE desktop environment
+- TigerVNC server for remote desktop access
+- noVNC for web-based VNC access (no client required)
+- Pre-installed computer-server for remote computer control
+- Python 3.11 with necessary libraries
+- Firefox browser with telemetry disabled
+
+## Quick Start
+
+```bash
+docker pull trycua/cua-xfce:latest
+
+docker run --rm -it \
+ --shm-size=512m \
+ -p 5901:5901 \
+ -p 6901:6901 \
+ -p 8000:8000 \
+ trycua/cua-xfce:latest
+```
+
+**Access Points:**
+- **noVNC Web Interface**: `http://localhost:6901` (no password required)
+- **VNC Client**: `localhost:5901` (no password required)
+- **Computer Server API**: `http://localhost:8000`
+
+### With Custom Resolution
+
+```bash
+docker run --rm -it \
+ --shm-size=512m \
+ -p 6901:6901 \
+ -p 8000:8000 \
+ -e VNC_RESOLUTION=1280x720 \
+ trycua/cua-xfce:latest
+```
+
+### With Persistent Storage
+
+```bash
+docker run --rm -it \
+ --shm-size=512m \
+ -p 6901:6901 \
+ -p 8000:8000 \
+ -v $(pwd)/storage:/home/cua/storage \
+ trycua/cua-xfce:latest
+```
+
+## Using with Cua
+
+```python
+from computer import Computer
+
+computer = Computer(
+ os_type="linux",
+ provider_type="docker",
+ image="trycua/cua-xfce:latest",
+ display="1024x768",
+ memory="4GB",
+ cpu="2"
+)
+
+async with computer:
+ screenshot = await computer.interface.screenshot()
+ await computer.interface.left_click(100, 100)
+ await computer.interface.type_text("Hello from Cua!")
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `VNC_RESOLUTION` | `1024x768` | Screen resolution |
+| `VNC_COL_DEPTH` | `24` | Color depth |
+| `VNC_PORT` | `5901` | VNC server port |
+| `NOVNC_PORT` | `6901` | noVNC web interface port |
+| `API_PORT` | `8000` | Computer-server API port |
+
+### Ports
+
+- **5901**: TigerVNC server
+- **6901**: noVNC web interface
+- **8000**: Computer-server WebSocket API
+
+### Volumes
+
+- `/home/cua/storage`: Persistent storage mount point
+- `/home/cua/shared`: Shared folder mount point
+
+### User Credentials
+
+- **Username**: `cua`
+- **Password**: `password` (for shell login only)
+- **Sudo access**: Enabled without password
+
+## Creating Snapshots
+
+```bash
+docker commit <container_id> cua-xfce-snapshot:latest
+```
+
+## Comparison with Kasm Container
+
+| Feature | Kasm Container | XFCE Container |
+|---------|----------------|----------------|
+| Base Image | KasmWeb Ubuntu | Vanilla Ubuntu |
+| VNC Server | KasmVNC | TigerVNC |
+| Dependencies | Higher | Lower |
+| Size | Larger | Smaller |
+
+## Building from Source
+
+To build the image manually, see the [xfce source code](https://github.com/trycua/cua/tree/main/libs/xfce).
diff --git a/docs/content/docs/cua/reference/desktop-sandbox/macos.mdx b/docs/content/docs/cua/reference/desktop-sandbox/macos.mdx
new file mode 100644
index 0000000000..40cc8806cc
--- /dev/null
+++ b/docs/content/docs/cua/reference/desktop-sandbox/macos.mdx
@@ -0,0 +1,81 @@
+---
+title: macOS Sandbox
+description: macOS virtual machines for Computer-Using Agents on Apple Silicon
+---
+
+macOS sandbox environments run native macOS virtual machines on Apple Silicon using Apple's Virtualization Framework. These provide near-native performance for running Computer-Using Agents on macOS.
+
+## Options
+
+| Option | Description | Best For |
+|--------|-------------|----------|
+| [Lume](/lume) | Native CLI for creating and managing macOS VMs | Direct VM management, development |
+| [Lumier](/lume/guide/advanced/lumier) | Docker wrapper around Lume | Containerized deployments |
+
+## Requirements
+
+- **Apple Silicon Mac** (M1, M2, M3, M4, etc.)
+- **macOS 13.0 or later**
+- At least 8GB RAM (16GB recommended)
+- At least 30GB free disk space
+
+## Quick Start with Lume
+
+```bash
+# Install Lume
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
+
+# Create and run a macOS VM
+lume create my-vm --os macos --ipsw latest
+lume run my-vm
+```
+
+## Quick Start with Lumier (Docker)
+
+```bash
+# Run macOS VM in Docker container
+docker run -it --rm \
+ --name macos-vm \
+ -p 8006:8006 \
+ -e VM_NAME=macos-vm \
+ -e CPU_CORES=4 \
+ -e RAM_SIZE=8192 \
+ trycua/lumier:latest
+```
+
+Access your VM at `http://localhost:8006`.
+
+## Using with Cua
+
+```python
+from computer import Computer
+
+# Create computer with macOS VM
+computer = Computer(
+ os_type="macos",
+ provider_type="lume",
+ display="1920x1080",
+ memory="8GB",
+ cpu="4"
+)
+
+async with computer:
+ screenshot = await computer.interface.screenshot()
+ await computer.interface.left_click(100, 100)
+ await computer.interface.type_text("Hello from Cua!")
+```
+
+## Comparison with Other Platforms
+
+| Feature | macOS (Lume) | Linux Container | QEMU VM |
+|---------|--------------|-----------------|---------|
+| Performance | Near-native | Native | Virtualized |
+| Host OS | macOS only | Any with Docker | Any with KVM |
+| Setup Time | Minutes | Seconds | 15-30 min (first run) |
+| Windows Support | No | No | Yes |
+
+## Related Documentation
+
+- [Lume Documentation](/lume) - Full Lume CLI reference
+- [Lumier Documentation](/lume/guide/advanced/lumier) - Docker-based macOS VMs
+- [Unattended Setup](/lume/guide/advanced/unattended-setup) - Automate macOS VM configuration
diff --git a/docs/content/docs/cua/reference/desktop-sandbox/meta.json b/docs/content/docs/cua/reference/desktop-sandbox/meta.json
new file mode 100644
index 0000000000..c51d5986c2
--- /dev/null
+++ b/docs/content/docs/cua/reference/desktop-sandbox/meta.json
@@ -0,0 +1,5 @@
+{
+ "title": "Desktop Sandbox",
+ "icon": "Container",
+ "pages": ["macos", "linux-container", "qemu-container"]
+}
diff --git a/docs/content/docs/cua/reference/desktop-sandbox/qemu-container/android.mdx b/docs/content/docs/cua/reference/desktop-sandbox/qemu-container/android.mdx
new file mode 100644
index 0000000000..c5700c25e0
--- /dev/null
+++ b/docs/content/docs/cua/reference/desktop-sandbox/qemu-container/android.mdx
@@ -0,0 +1,75 @@
+---
+title: QEMU Android
+description: Android emulator container with QEMU/KVM for Computer-Using Agents
+---
+
+Docker image that runs an Android emulator using QEMU/KVM with Cua Computer Server integration, enabling programmatic control of Android devices via HTTP API.
+
+## Features
+
+- Android 11 Emulator (based on budtmo/docker-android)
+- Cua Computer Server for automation via HTTP API
+- VNC access for visual interaction via web browser
+- Memory snapshots support
+
+## Requirements
+
+- Linux host with KVM support
+- Docker with `--device=/dev/kvm` access
+
+## Quick Start
+
+```bash
+docker pull trycua/cua-qemu-android:latest
+
+docker run -d \
+ -p 6080:6080 \
+ -p 8000:8000 \
+ -e EMULATOR_DEVICE="Samsung Galaxy S10" \
+ -e WEB_VNC=true \
+ --device /dev/kvm \
+ --name android-container \
+ trycua/cua-qemu-android:latest
+```
+
+**Access Points:**
+- **VNC Web UI**: `http://localhost:6080`
+- **Computer Server API**: `http://localhost:8000`
+- **API Documentation**: `http://localhost:8000/docs`
+
+## API Examples
+
+```bash
+# Get screen size
+curl -X POST http://localhost:8000/cmd \
+ -H "Content-Type: application/json" \
+ -d '{"command": "get_screen_size", "params": {}}'
+
+# Launch app
+curl -X POST http://localhost:8000/cmd \
+ -H "Content-Type: application/json" \
+ -d '{"command": "launch", "params": {"app": "com.android.settings"}}'
+
+# Set wallpaper
+curl -X POST http://localhost:8000/cmd \
+ -H "Content-Type: application/json" \
+ -d '{"command": "set_wallpaper", "params": {"path": "/sdcard/image.jpg", "target": "home"}}'
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `EMULATOR_DEVICE` | - | Device profile (e.g., "Samsung Galaxy S10") |
+| `WEB_VNC` | `true` | Enable VNC web interface |
+
+### Ports
+
+- **6080**: VNC web interface
+- **8000**: Computer Server API
+
+## Building from Source
+
+To build the image manually, see the [qemu-docker/android source code](https://github.com/trycua/cua/tree/main/libs/qemu-docker/android).
diff --git a/docs/content/docs/cua/reference/desktop-sandbox/qemu-container/linux.mdx b/docs/content/docs/cua/reference/desktop-sandbox/qemu-container/linux.mdx
new file mode 100644
index 0000000000..26ec7ff5ea
--- /dev/null
+++ b/docs/content/docs/cua/reference/desktop-sandbox/qemu-container/linux.mdx
@@ -0,0 +1,80 @@
+---
+title: QEMU Linux
+description: Ubuntu 22.04 container with QEMU/KVM for Computer-Using Agents
+---
+
+Containerized Ubuntu 22.04 LTS virtual desktop for Computer-Using Agents (Cua). Utilizes QEMU/KVM with Ubuntu Desktop and computer-server pre-installed for remote computer control.
+
+## Features
+
+- Ubuntu 22.04 LTS Desktop running in QEMU/KVM
+- Pre-installed Cua computer-server for remote computer control
+- noVNC access for visual desktop interaction
+- Memory snapshots support
+- Full VM isolation
+
+## Requirements
+
+- Linux host with KVM support
+- Docker with `--device=/dev/kvm` access
+
+## Quick Start
+
+```bash
+docker pull trycua/cua-qemu-linux:latest
+
+mkdir -p ./storage
+
+docker run -it --rm \
+ --device=/dev/kvm \
+ --cap-add NET_ADMIN \
+ -v $(pwd)/storage:/storage \
+ -p 8006:8006 \
+ -p 5000:5000 \
+ -e RAM_SIZE=8G \
+ -e CPU_CORES=4 \
+ trycua/cua-qemu-linux:latest
+```
+
+**Access Points:**
+- **Computer Server API**: `http://localhost:5000`
+- **noVNC Browser**: `http://localhost:8006`
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `RAM_SIZE` | `8G` | RAM allocated to Ubuntu VM |
+| `CPU_CORES` | `8` | CPU cores allocated to VM |
+| `DISK_SIZE` | `64G` | VM disk size (minimum: 32G) |
+
+### Ports
+
+- **5000**: Cua computer-server API endpoint
+- **8006**: noVNC web interface for visual desktop access
+
+### Volumes
+
+- `/storage`: Persistent VM storage (golden image, disk)
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Docker Container (Linux host) │
+│ │
+│ • Port forwarding: localhost:5000 → VM:5000 │
+│ • Exposes: 5000 (API), 8006 (noVNC) │
+│ │
+│ ┌────────────────────────────────────────────────────┐ │
+│ │ QEMU VM (Ubuntu 22.04) │ │
+│ │ • Cua computer-server listens on 5000 │ │
+│ └────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Building from Source
+
+To build the image manually (including creating a golden image from an Ubuntu ISO), see the [qemu-docker/linux source code](https://github.com/trycua/cua/tree/main/libs/qemu-docker/linux).
diff --git a/docs/content/docs/cua/reference/desktop-sandbox/qemu-container/meta.json b/docs/content/docs/cua/reference/desktop-sandbox/qemu-container/meta.json
new file mode 100644
index 0000000000..2d86ecef55
--- /dev/null
+++ b/docs/content/docs/cua/reference/desktop-sandbox/qemu-container/meta.json
@@ -0,0 +1,4 @@
+{
+ "title": "QEMU Container",
+ "pages": ["windows", "linux", "android"]
+}
diff --git a/docs/content/docs/cua/reference/desktop-sandbox/qemu-container/windows.mdx b/docs/content/docs/cua/reference/desktop-sandbox/qemu-container/windows.mdx
new file mode 100644
index 0000000000..10f4fc905a
--- /dev/null
+++ b/docs/content/docs/cua/reference/desktop-sandbox/qemu-container/windows.mdx
@@ -0,0 +1,80 @@
+---
+title: QEMU Windows
+description: Windows 11 container with QEMU/KVM for Computer-Using Agents
+---
+
+Containerized Windows 11 virtual desktop for Computer-Using Agents (Cua). Utilizes QEMU/KVM with Windows 11 and computer-server pre-installed for remote computer control.
+
+## Features
+
+- Windows 11 Enterprise running in QEMU/KVM
+- Pre-installed Cua computer-server for remote computer control
+- noVNC access for visual desktop interaction
+- Memory snapshots support
+- Essential tools pre-installed (Chrome, LibreOffice, VLC, GIMP, VSCode, Thunderbird)
+
+## Requirements
+
+- Linux host with KVM support
+- Docker with `--device=/dev/kvm` access
+
+## Quick Start
+
+```bash
+docker pull trycua/cua-qemu-windows:latest
+
+mkdir -p ./storage
+
+docker run -it --rm \
+ --device=/dev/kvm \
+ --cap-add NET_ADMIN \
+ -v $(pwd)/storage:/storage \
+ -p 8006:8006 \
+ -p 5000:5000 \
+ -e RAM_SIZE=8G \
+ -e CPU_CORES=4 \
+ trycua/cua-qemu-windows:latest
+```
+
+**Access Points:**
+- **Computer Server API**: `http://localhost:5000`
+- **noVNC Browser**: `http://localhost:8006`
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `RAM_SIZE` | `8G` | RAM allocated to Windows VM |
+| `CPU_CORES` | `8` | CPU cores allocated to VM |
+| `DISK_SIZE` | `30G` | VM disk size (minimum: 20G) |
+
+### Ports
+
+- **5000**: Cua computer-server API endpoint
+- **8006**: noVNC web interface for visual desktop access
+
+### Volumes
+
+- `/storage`: Persistent VM storage (golden image, disk, firmware)
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Docker Container (Linux host) │
+│ │
+│ • Port forwarding: localhost:5000 → VM:5000 │
+│ • Exposes: 5000 (API), 8006 (noVNC) │
+│ │
+│ ┌────────────────────────────────────────────────────┐ │
+│ │ QEMU VM (Windows 11) │ │
+│ │ • Cua computer-server listens on 5000 │ │
+│ └────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Building from Source
+
+To build the image manually (including creating a golden image from a Windows ISO), see the [qemu-docker/windows source code](https://github.com/trycua/cua/tree/main/libs/qemu-docker/windows).
diff --git a/docs/content/docs/cua/reference/macos-vm-cli-playbook/meta.json b/docs/content/docs/cua/reference/macos-vm-cli-playbook/meta.json
deleted file mode 100644
index 178f3acbb3..0000000000
--- a/docs/content/docs/cua/reference/macos-vm-cli-playbook/meta.json
+++ /dev/null
@@ -1,6 +0,0 @@
-{
- "title": "macOS VM CLI",
- "description": "CLI tools for macOS virtualization",
- "icon": "Terminal",
- "pages": ["lumier"]
-}
diff --git a/docs/content/docs/cua/reference/meta.json b/docs/content/docs/cua/reference/meta.json
index cc8d8d40b7..8658412b4e 100644
--- a/docs/content/docs/cua/reference/meta.json
+++ b/docs/content/docs/cua/reference/meta.json
@@ -2,5 +2,5 @@
"title": "Reference",
"description": "SDK and CLI API reference",
"icon": "FileText",
- "pages": ["computer-sdk", "agent-sdk", "mcp-server", "cli-playbook", "macos-vm-cli-playbook"]
+ "pages": ["desktop-sandbox", "computer-sdk", "agent-sdk", "mcp-server", "cloud-cli"]
}
diff --git a/docs/content/docs/cua/reference/macos-vm-cli-playbook/lumier/building-lumier.mdx b/docs/content/docs/lume/guide/advanced/lumier/building-lumier.mdx
similarity index 100%
rename from docs/content/docs/cua/reference/macos-vm-cli-playbook/lumier/building-lumier.mdx
rename to docs/content/docs/lume/guide/advanced/lumier/building-lumier.mdx
diff --git a/docs/content/docs/cua/reference/macos-vm-cli-playbook/lumier/docker-compose.mdx b/docs/content/docs/lume/guide/advanced/lumier/docker-compose.mdx
similarity index 100%
rename from docs/content/docs/cua/reference/macos-vm-cli-playbook/lumier/docker-compose.mdx
rename to docs/content/docs/lume/guide/advanced/lumier/docker-compose.mdx
diff --git a/docs/content/docs/cua/reference/macos-vm-cli-playbook/lumier/docker.mdx b/docs/content/docs/lume/guide/advanced/lumier/docker.mdx
similarity index 100%
rename from docs/content/docs/cua/reference/macos-vm-cli-playbook/lumier/docker.mdx
rename to docs/content/docs/lume/guide/advanced/lumier/docker.mdx
diff --git a/docs/content/docs/cua/reference/macos-vm-cli-playbook/lumier/index.mdx b/docs/content/docs/lume/guide/advanced/lumier/index.mdx
similarity index 94%
rename from docs/content/docs/cua/reference/macos-vm-cli-playbook/lumier/index.mdx
rename to docs/content/docs/lume/guide/advanced/lumier/index.mdx
index d21768f4c3..b6abdf5dc6 100644
--- a/docs/content/docs/cua/reference/macos-vm-cli-playbook/lumier/index.mdx
+++ b/docs/content/docs/lume/guide/advanced/lumier/index.mdx
@@ -1,6 +1,6 @@
---
title: Lumier
-description: Reference for the current version of the Lumier library.
+description: Docker interface for running macOS virtual machines with Lume
github:
- https://github.com/trycua/cua/tree/main/libs/lumier
---
diff --git a/docs/content/docs/cua/reference/macos-vm-cli-playbook/lumier/installation.mdx b/docs/content/docs/lume/guide/advanced/lumier/installation.mdx
similarity index 100%
rename from docs/content/docs/cua/reference/macos-vm-cli-playbook/lumier/installation.mdx
rename to docs/content/docs/lume/guide/advanced/lumier/installation.mdx
diff --git a/docs/content/docs/cua/reference/macos-vm-cli-playbook/lumier/meta.json b/docs/content/docs/lume/guide/advanced/lumier/meta.json
similarity index 79%
rename from docs/content/docs/cua/reference/macos-vm-cli-playbook/lumier/meta.json
rename to docs/content/docs/lume/guide/advanced/lumier/meta.json
index bfe2572455..4b2725b14b 100644
--- a/docs/content/docs/cua/reference/macos-vm-cli-playbook/lumier/meta.json
+++ b/docs/content/docs/lume/guide/advanced/lumier/meta.json
@@ -1,3 +1,4 @@
{
+ "title": "Lumier",
"pages": ["installation", "docker", "docker-compose", "building-lumier"]
}
diff --git a/docs/content/docs/lume/guide/advanced/meta.json b/docs/content/docs/lume/guide/advanced/meta.json
index 415efb1a9a..d52c8f4790 100644
--- a/docs/content/docs/lume/guide/advanced/meta.json
+++ b/docs/content/docs/lume/guide/advanced/meta.json
@@ -2,5 +2,5 @@
"title": "Advanced",
"description": "Advanced features and automation",
"icon": "Wrench",
- "pages": ["unattended-setup", "http-server", "faq"]
+ "pages": ["http-server", "lumier"]
}
diff --git a/docs/content/docs/lume/guide/fundamentals/meta.json b/docs/content/docs/lume/guide/fundamentals/meta.json
index 94055539e5..f64dc270b5 100644
--- a/docs/content/docs/lume/guide/fundamentals/meta.json
+++ b/docs/content/docs/lume/guide/fundamentals/meta.json
@@ -2,5 +2,5 @@
"title": "Fundamentals",
"description": "Core concepts and usage",
"icon": "Layers",
- "pages": ["prebuilt-images", "vm-management"]
+ "pages": ["vm-management", "unattended-setup"]
}
diff --git a/docs/content/docs/lume/guide/fundamentals/prebuilt-images.mdx b/docs/content/docs/lume/guide/fundamentals/prebuilt-images.mdx
deleted file mode 100644
index 55c3d9a242..0000000000
--- a/docs/content/docs/lume/guide/fundamentals/prebuilt-images.mdx
+++ /dev/null
@@ -1,66 +0,0 @@
----
-title: Prebuilt Images
-description: Available prebuilt VM images in the registry
----
-
-import { Callout } from 'fumadocs-ui/components/callout';
-
-Prebuilt images are available in the registry [ghcr.io/trycua](https://github.com/orgs/trycua/packages). These images come with an SSH server pre-configured and auto-login enabled.
-
-<Callout>
- The default password on prebuilt images is `lume`. For the security of your VM, change this
- password after your first login.
-</Callout>
-
-## Available Images
-
-The following prebuilt images are available to download via `lume pull`:
-
-| Image | Tag | Description | Logical Size |
-| ----------------------- | ------------------- | ----------------------------------------------------------------------------------------------- | ------------ |
-| `macos-sequoia-vanilla` | `latest`, `15.2` | macOS Sequoia 15.2 image | 20GB |
-| `macos-sequoia-xcode` | `latest`, `15.2` | macOS Sequoia 15.2 image with Xcode command line tools | 22GB |
-| `macos-sequoia-cua` | `latest`, `15.3` | macOS Sequoia 15.3 image compatible with the Computer interface | 24GB |
-| `ubuntu-noble-vanilla` | `latest`, `24.04.1` | [Ubuntu Server for ARM 24.04.1 LTS](https://ubuntu.com/download/server/arm) with Ubuntu Desktop | 20GB |
-
-## Using Prebuilt Images
-
-### Pull and Run
-
-```bash
-# Pull and run in one command
-lume run macos-sequoia-vanilla:latest
-
-# Or pull separately
-lume pull macos-sequoia-vanilla:latest --name my-vm
-lume run my-vm
-```
-
-### Pull to Specific Storage
-
-```bash
-# Pull to a specific storage location
-lume pull macos-sequoia-vanilla:latest --name my-vm --storage external-ssd
-```
-
-## Disk Space
-
-For additional disk space, resize the VM disk after pulling the image:
-
-```bash
-lume set my-vm --disk-size 100GB
-```
-
-Note that the actual disk space used by sparse images will be much lower than the logical size listed.
-
-<Callout>
- **Important Note (v0.2.0+):** Images are being re-uploaded with sparse file system optimizations
- enabled, resulting in significantly lower actual disk usage. Older images (without the `-sparse`
- suffix) are now **deprecated**. Starting from `v0.2.0`, lume will automatically pull images
- optimized with sparse file system support.
-</Callout>
-
-## Next Steps
-
-- [VM Management](/lume/guide/fundamentals/vm-management) - Managing your VMs
-- [CLI Reference](/lume/reference/cli-reference) - Full command reference
diff --git a/docs/content/docs/lume/guide/advanced/unattended-setup.mdx b/docs/content/docs/lume/guide/fundamentals/unattended-setup.mdx
similarity index 88%
rename from docs/content/docs/lume/guide/advanced/unattended-setup.mdx
rename to docs/content/docs/lume/guide/fundamentals/unattended-setup.mdx
index e91a136c50..7d97f5fd6c 100644
--- a/docs/content/docs/lume/guide/advanced/unattended-setup.mdx
+++ b/docs/content/docs/lume/guide/fundamentals/unattended-setup.mdx
@@ -1,15 +1,10 @@
---
-title: Unattended Setup (Preview)
+title: Unattended Setup
description: Automate macOS Setup Assistant with YAML configuration files
---
import { Callout } from 'fumadocs-ui/components/callout';
-<Callout type="info">
- **Preview Feature**: Unattended setup is an experimental feature. The API and behavior may change
- in future releases.
-</Callout>
-
Lume supports unattended setup automation to configure macOS VMs without manual interaction. This uses VNC-based automation with OCR (Optical Character Recognition) to navigate through the Setup Assistant and perform post-setup configuration.
<Callout type="warn">
@@ -251,70 +246,6 @@ health_check:
retry_delay: 10
```
-## Example: Enable SSH on Existing VM
-
-Run this on a VM that has already completed Setup Assistant:
-
-```yaml
-boot_wait: 30
-
-boot_commands:
- # Click desktop for focus
- - '<click_at 960,540>'
- - '<delay 1>'
-
- # Open Terminal via Spotlight
- - '<cmd+space>'
- - '<delay 2>'
- - "<type 'Terminal'>"
- - '<enter>'
- - '<delay 3>'
-
- # Enable SSH
- - "<type 'sudo launchctl load -w /System/Library/LaunchDaemons/ssh.plist'>"
- - '<enter>'
- - "<type 'lume'>" # Password
- - '<enter>'
- - '<delay 2>'
-
- # Enable auto-login
- - "<type 'sudo sysadminctl -autologin set -userName lume -password lume'>"
- - '<enter>'
- - '<delay 2>'
-
- # Enable full keyboard navigation for Tab to work everywhere
- - "<type 'defaults write NSGlobalDomain AppleKeyboardUIMode -int 3'>"
- - '<enter>'
- - '<delay 1>'
-
- # Close Terminal
- - '<cmd+q>'
-
- # Enable Full Disk Access for SSH via System Settings
- - '<cmd+space>'
- - "<type 'System Settings'>"
- - '<enter>'
- - '<delay 3>'
-
- - "<click 'Search'>"
- - "<type 'Remote'>"
- - '<delay 2>'
- - "<click 'Remote Login'>"
- - '<delay 2>'
-
- # Toggle "Allow full disk access"
- - '<tab>'
- - '<space>'
- - '<delay 2>'
-
- - '<cmd+q>'
-
-health_check:
- type: ssh
- user: lume
- password: lume
-```
-
## Debugging
Enable debug mode to save screenshots with OCR annotations:
diff --git a/docs/content/docs/lume/guide/advanced/faq.mdx b/docs/content/docs/lume/guide/getting-started/faq.mdx
similarity index 90%
rename from docs/content/docs/lume/guide/advanced/faq.mdx
rename to docs/content/docs/lume/guide/getting-started/faq.mdx
index 251ff574fc..e4fa5a30df 100644
--- a/docs/content/docs/lume/guide/advanced/faq.mdx
+++ b/docs/content/docs/lume/guide/getting-started/faq.mdx
@@ -3,6 +3,11 @@ title: FAQ
description: Frequently asked questions about Lume
---
+### What is the default VM password?
+
+- **Username**: `lume`
+- **Password**: `lume`
+
### Where are the VMs stored?
VMs are stored in `~/.lume` by default. You can configure additional storage locations using the `lume config` command.
@@ -82,6 +87,10 @@ No, macOS uses sparse files, which only allocate space as needed. For example, V
lume ipsw
```
+### Where can I download older macOS IPSW versions?
+
+Apple only provides the latest IPSW through official channels. For older versions, searching for "macOS IPSW download" will find community resources that archive previous releases. Make sure to download UniversalMac IPSW files (for Apple Silicon).
+
### How do I delete a VM?
```bash
diff --git a/docs/content/docs/lume/guide/getting-started/meta.json b/docs/content/docs/lume/guide/getting-started/meta.json
index 64af79d249..92c4579891 100644
--- a/docs/content/docs/lume/guide/getting-started/meta.json
+++ b/docs/content/docs/lume/guide/getting-started/meta.json
@@ -3,5 +3,5 @@
"description": "Get up and running with Lume",
"icon": "Rocket",
"defaultOpen": true,
- "pages": ["introduction", "installation", "quickstart"]
+ "pages": ["introduction", "installation", "quickstart", "faq"]
}
diff --git a/docs/content/docs/lume/guide/getting-started/quickstart.mdx b/docs/content/docs/lume/guide/getting-started/quickstart.mdx
index 8a5b67457a..37d04adbaa 100644
--- a/docs/content/docs/lume/guide/getting-started/quickstart.mdx
+++ b/docs/content/docs/lume/guide/getting-started/quickstart.mdx
@@ -7,24 +7,10 @@ import { Callout } from 'fumadocs-ui/components/callout';
This guide walks you through creating and running your first macOS VM with Lume.
-## Run a Prebuilt Image
-
-The fastest way to get started is with a prebuilt image:
-
-```bash
-# Pull and run a prebuilt macOS image
-lume run macos-sequoia-vanilla:latest
-```
-
-This command:
-
-1. Downloads the `macos-sequoia-vanilla:latest` image from the registry
-2. Creates a VM named `macos-sequoia-vanilla`
-3. Starts the VM with a display window
-
-<Callout title="Security Note">
- All prebuilt images use the default password `lume`. Change this immediately after your first
- login using the `passwd` command.
+<Callout type="warn">
+ **Registry Maintenance Notice**: The prebuilt images in the trycua registry are no longer actively
+ maintained. For new setups, we recommend building custom images using the [Unattended Setup](/lume/guide/advanced/unattended-setup) feature
+ to configure macOS VMs according to your specific needs.
</Callout>
## Create a Custom VM
@@ -91,5 +77,5 @@ lume clone my-vm my-vm-copy
## Next Steps
- [VM Management](/lume/guide/fundamentals/vm-management) - Learn more VM operations
-- [Prebuilt Images](/lume/guide/fundamentals/prebuilt-images) - Available images
+- [Unattended Setup](/lume/guide/advanced/unattended-setup) - Automate VM configuration
- [CLI Reference](/lume/reference/cli-reference) - Full command reference
diff --git a/docs/content/docs/lume/index.mdx b/docs/content/docs/lume/index.mdx
index 70358c8ded..9c2ed10690 100644
--- a/docs/content/docs/lume/index.mdx
+++ b/docs/content/docs/lume/index.mdx
@@ -15,9 +15,8 @@ Built on Apple's [Virtualization.Framework](https://developer.apple.com/document
- **Near-native performance** - Run macOS VMs at native speed using Apple's Virtualization Framework
- **Simple CLI** - Create, run, and manage VMs with intuitive commands
-- **Prebuilt images** - Get started quickly with ready-to-use macOS and Linux images
+- **Unattended setup** - Automate macOS installation and configuration with YAML files
- **HTTP API** - Integrate with your tools via the built-in REST API server
-- **Unattended setup** - Automate macOS installation with YAML configuration files
## Quick Start
@@ -25,8 +24,11 @@ Built on Apple's [Virtualization.Framework](https://developer.apple.com/document
# Install Lume
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
-# Pull and run a prebuilt macOS image
-lume run macos-sequoia-vanilla:latest
+# Create a custom macOS VM
+lume create my-vm --os macos --ipsw latest
+
+# Run the VM
+lume run my-vm
```
<Callout title="System Requirements">
@@ -38,6 +40,6 @@ lume run macos-sequoia-vanilla:latest
- [Installation Guide](/lume/guide/getting-started/installation) - Detailed installation options
- [Quickstart](/lume/guide/getting-started/quickstart) - Create your first VM
-- [Prebuilt Images](/lume/guide/fundamentals/prebuilt-images) - Available images in the registry
+- [Unattended Setup](/lume/guide/advanced/unattended-setup) - Automate VM configuration
- [CLI Reference](/lume/reference/cli-reference) - Full command reference
- [HTTP API Reference](/lume/reference/http-api) - REST API documentation
diff --git a/docs/src/app/(landing)/page.tsx b/docs/src/app/(landing)/page.tsx
index 1b349d3eeb..ef3f3babaf 100644
--- a/docs/src/app/(landing)/page.tsx
+++ b/docs/src/app/(landing)/page.tsx
@@ -1,7 +1,7 @@
-import Link from 'next/link';
-import Image from 'next/image';
-import { BookOpen, Code2, FileCode, Cloud, ArrowRight, ChevronRight } from 'lucide-react';
+import { ArrowRight, BookOpen, ChevronRight, Cloud, Code2, FileCode } from 'lucide-react';
import type { Metadata } from 'next';
+import Image from 'next/image';
+import Link from 'next/link';
export const metadata: Metadata = {
title: 'Cua Documentation',
@@ -158,7 +158,7 @@ export default function LandingPage() {
</section>
{/* Navigation Cards Section */}
- <section className="container mx-auto px-6 py-12 lg:px-8">
+ <section className="relative container mx-auto px-6 py-12 lg:px-8">
<div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
{navCards.map((card) => {
const Icon = card.icon;
@@ -193,7 +193,7 @@ export default function LandingPage() {
</section>
{/* Featured Examples Section */}
- <section className="container mx-auto px-6 py-12 lg:px-8">
+ <section className="relative container mx-auto px-6 py-12 lg:px-8">
<div className="mb-8 flex items-center justify-between">
<div>
<h2
@@ -266,7 +266,7 @@ export default function LandingPage() {
</section>
{/* Quick links section */}
- <section className="container mx-auto px-6 py-12 lg:px-8">
+ <section className="relative container mx-auto px-6 py-12 lg:px-8">
<div className="rounded-xl border border-fd-border bg-gradient-to-br from-fd-card/50 to-fd-card p-8 backdrop-blur-sm">
<div className="mx-auto max-w-2xl text-center">
<h2
diff --git a/examples/pylume_examples.py b/examples/pylume_examples.py
deleted file mode 100644
index 35e89ed62c..0000000000
--- a/examples/pylume_examples.py
+++ /dev/null
@@ -1,85 +0,0 @@
-import asyncio
-
-from pylume import ImageRef, PyLume, SharedDirectory, VMConfig, VMRunOpts, VMUpdateOpts
-
-
-async def main():
- """Example usage of PyLume."""
- async with PyLume(port=7777, use_existing_server=False, debug=True) as pylume:
-
- # Get latest IPSW URL
- print("\n=== Getting Latest IPSW URL ===")
- url = await pylume.get_latest_ipsw_url()
- print("Latest IPSW URL:", url)
-
- # Create a new VM
- print("\n=== Creating a new VM ===")
- vm_config = VMConfig(
- name="lume-vm-new",
- os="macOS",
- cpu=2,
- memory="4GB",
- disk_size="64GB", # type: ignore
- display="1024x768",
- ipsw="latest",
- )
- await pylume.create_vm(vm_config)
-
- # Get latest IPSW URL
- print("\n=== Getting Latest IPSW URL ===")
- url = await pylume.get_latest_ipsw_url()
- print("Latest IPSW URL:", url)
-
- # List available images
- print("\n=== Listing Available Images ===")
- images = await pylume.get_images()
- print("Available Images:", images)
-
- # List all VMs to verify creation
- print("\n=== Listing All VMs ===")
- vms = await pylume.list_vms()
- print("VMs:", vms)
-
- # Get specific VM details
- print("\n=== Getting VM Details ===")
- vm = await pylume.get_vm("lume-vm")
- print("VM Details:", vm)
-
- # Update VM settings
- print("\n=== Updating VM Settings ===")
- update_opts = VMUpdateOpts(cpu=8, memory="4GB")
- await pylume.update_vm("lume-vm", update_opts)
-
- # Pull an image
- image_ref = ImageRef(
- image="macos-sequoia-vanilla", tag="latest", registry="ghcr.io", organization="trycua"
- )
- await pylume.pull_image(image_ref, name="lume-vm-pulled")
-
- # Run with shared directory
- run_opts = VMRunOpts(
- no_display=False, # type: ignore
- shared_directories=[ # type: ignore
- SharedDirectory(host_path="~/shared", read_only=False) # type: ignore
- ],
- )
- await pylume.run_vm("lume-vm", run_opts)
-
- # Or simpler:
- await pylume.run_vm("lume-vm")
-
- # Clone VM
- print("\n=== Cloning VM ===")
- await pylume.clone_vm("lume-vm", "lume-vm-cloned")
-
- # Stop VM
- print("\n=== Stopping VM ===")
- await pylume.stop_vm("lume-vm")
-
- # Delete VM
- print("\n=== Deleting VM ===")
- await pylume.delete_vm("lume-vm-cloned")
-
-
-if __name__ == "__main__":
- asyncio.run(main())
diff --git a/libs/cua-bench/README.md b/libs/cua-bench/README.md
index 31db1f5cd4..cc292f4437 100644
--- a/libs/cua-bench/README.md
+++ b/libs/cua-bench/README.md
@@ -1,443 +1,5 @@
# cua-bench
-A toolkit for verifiable cross-platform computer-use RL environments and benchmarks. Create custom GUI tasks with HTML/CSS/JS or run tasks on real Windows, Linux, macOS environments.
+Framework for benchmarking Computer-Use Agents with verifiable cross-platform environments.
-## Installation
-
-```bash
-pip install cua-bench
-```
-
-Or install from source:
-
-```bash
-git clone https://github.com/trycua/cua.git
-cd cua/libs/cua-bench
-pip install -e .
-```
-
-## Quick Start
-
-### 1. Create a Base Image (Optional)
-
-For tasks requiring native environments (real OS), create a base image:
-
-```bash
-# Quick setup: Linux container (no KVM required)
-cb image create linux-docker
-
-# Windows VM (requires KVM, ~1-2 hours)
-cb image create windows-qemu --download-iso
-
-# Check available images
-cb image list
-```
-
-Most tasks use simulated environments (HTML/CSS/JS) and don't require base images.
-
-### 2. Run a Task
-
-```bash
-export ANTHROPIC_API_KEY=sk-....
-
-# Run a single task with an AI agent (async)
-cb run task tasks/click_button --agent cua-agent --model anthropic/claude-sonnet-4-20250514
-
-# Watch progress
-cb run watch <run_id>
-
-# View the trace
-cb trace view <run_id>
-```
-
-### 3. Explore Interactively
-
-```bash
-# Open task in browser for manual testing
-cb interact tasks/click_button --variant-id 0
-
-# Run with oracle solution
-cb interact tasks/click_button --oracle
-```
-
-## Running Tasks
-
-### Single Task
-
-Tasks run **asynchronously by default** and return immediately with a run ID:
-
-```bash
-# Run async (returns immediately)
-cb run task tasks/my_task --agent cua-agent --model anthropic/claude-sonnet-4-20250514
-
-# Monitor progress
-cb run watch <run_id>
-
-# Or wait for completion inline
-cb run task tasks/my_task --agent cua-agent --model anthropic/claude-sonnet-4-20250514 --wait
-
-# Run with oracle solution (reference implementation)
-cb run task tasks/my_task --oracle --wait
-```
-
-### Run a Dataset
-
-Run multiple tasks in parallel:
-
-```bash
-# Run entire dataset
-cb run dataset datasets/cua-bench-basic \
- --agent cua-agent \
- --model anthropic/claude-haiku-4-5 \
- --max-parallel 8 \
- --max-steps 10
-
-# Run with filtering
-cb run dataset datasets/cua-bench-basic \
- --task-filter "click*" \
- --max-variants 1
-```
-
-### Managing Runs
-
-```bash
-# List all runs
-cb run list
-
-# Watch a run in real-time
-cb run watch <run_id>
-
-# Check run status
-cb run info <run_id>
-
-# View logs
-cb run logs <run_id>
-
-# Stop a run
-cb run stop <run_id>
-```
-
-## Viewing Traces
-
-```bash
-# View traces from a run
-cb trace view <run_id>
-
-# Opens interactive viewer at http://127.0.0.1:55115/
-```
-
-## Creating Tasks
-
-### Generate a Task with AI
-
-```bash
-# AI-assisted task generation
-cb generate-task "2048 game" --output tasks/2048_game
-
-# Create empty task scaffold
-cb create-task tasks/my_task
-```
-
-### Task Structure
-
-Every task has a `main.py` with four decorated functions:
-
-```python
-import cua_bench as cb
-from pathlib import Path
-
-pid = None
-
[email protected]_config(split="train")
-def load():
- return [
- cb.Task(
- description='Click the "Submit" button.',
- metadata={"button_text": "Submit"},
- computer={
- "provider": "simulated", # or "native"
- "setup_config": {
- "os_type": "win11", # win11, macos (simulated) or linux, windows (native)
- "width": 1024,
- "height": 768
- }
- }
- )
- ]
-
[email protected]_task(split="train")
-async def start(task_cfg: cb.Task, session: cb.DesktopSession):
- global pid
- # Launch a window with HTML GUI
- pid = await session.launch_window(
- html=(Path(__file__).parent / "gui/index.html").read_text(),
- title="My App",
- width=800,
- height=600
- )
-
[email protected]_task(split="train")
-async def evaluate(task_cfg: cb.Task, session: cb.DesktopSession) -> list[float]:
- global pid
- if pid is None:
- return [0.0]
-
- # Read state from JavaScript
- submitted = await session.execute_javascript(pid, "window.__submitted")
- return [1.0] if submitted else [0.0]
-
[email protected]_task(split="train")
-async def solve(task_cfg: cb.Task, session: cb.DesktopSession):
- global pid
- if pid is None:
- return
-
- # Get element position and click it
- rect = await session.get_element_rect(pid, "#submit-btn")
- if rect:
- await session.click(rect["x"] + rect["width"] // 2, rect["y"] + rect["height"] // 2)
-
- # Or click via JavaScript
- # await session.execute_javascript(pid, 'document.querySelector("#submit-btn").click()')
-```
-
-## Programmatic Interface
-
-```python
-import cua_bench as cb
-
-# Load an environment
-env = cb.make("./tasks/my_task")
-
-# Reset to start a task
-screenshot, task_config = await env.reset(task_id=0)
-
-# Get the session
-session = env.session
-
-# Take actions
-await session.click(100, 200)
-await session.type("Hello, world!")
-await session.key("Enter")
-
-# Take screenshot
-screenshot_bytes = await session.screenshot()
-
-# Run oracle solution
-await env.solve()
-
-# Evaluate
-rewards = await env.evaluate()
-
-# Clean up
-await env.close()
-```
-
-### Session API
-
-```python
-# Mouse actions
-await session.click(x, y)
-await session.right_click(x, y)
-await session.double_click(x, y)
-await session.move_to(x, y)
-await session.drag(from_x, from_y, to_x, to_y)
-await session.scroll(direction="down", amount=100)
-
-# Keyboard actions
-await session.type("Hello, world!")
-await session.key("Enter")
-await session.hotkey(["ctrl", "c"])
-
-# Screenshots
-screenshot_bytes = await session.screenshot() # PNG bytes
-
-# Window management (for simulated tasks)
-pid = await session.launch_window(
- html="<h1>Hello</h1>",
- title="My Window",
- width=800,
- height=600
-)
-
-# Execute JavaScript in window
-result = await session.execute_javascript(pid, "document.title")
-
-# Get element position
-rect = await session.get_element_rect(pid, ".my-button")
-# Returns: {"x": 10, "y": 20, "width": 100, "height": 30}
-
-# Close all windows
-await session.close_all_windows()
-```
-
-## Base Images
-
-Base images are reproducible environments for running tasks on real operating systems.
-
-### Create Images
-
-```bash
-# Linux container (fast, no KVM)
-cb image create linux-docker
-
-# Linux VM with KVM
-cb image create linux-qemu
-
-# Windows 11 VM (~1-2 hours)
-cb image create windows-qemu --download-iso
-
-# Android VM
-cb image create android-qemu
-
-# macOS VM (Apple Silicon only)
-cb image create macos-lume
-```
-
-### Manage Images
-
-```bash
-# List all images
-cb image list
-
-# Show image details
-cb image info windows-qemu
-
-# Clone for customization
-cb image clone windows-qemu windows-custom
-
-# Interactive shell (read-only overlay)
-cb image shell windows-qemu
-
-# Interactive shell (modify golden image)
-cb image shell windows-qemu --writable
-
-# Delete an image
-cb image delete windows-custom
-```
-
-## Export Training Data
-
-Export agent trajectories to training datasets:
-
-```bash
-# Export with aguvis-stage-1 format (default)
-cb dataset build <run-id> --save-dir datasets/
-
-# Export with gui-r1 format
-cb dataset build <run-id> --mode gui-r1 --save-dir datasets/
-
-# Push to Hugging Face
-cb dataset build <run-id> --push-to-hub --repo-id username/my-dataset
-```
-
-**Available formats:**
-
-- **aguvis-stage-1** - Action augmentation dataset (AgUVis/smol2operator style)
-- **gui-r1** - Low-level click instructions (GUI-R1 format)
-
-## Platform Support
-
-### Simulated Desktop (HTML/CSS/JS)
-
-Fast, lightweight environments using Playwright. No Docker required.
-
-**Best for:**
-
-- Custom GUI tasks
-- Web app testing
-- Quick iteration
-- Cross-platform compatibility
-
-**Themes:**
-
-- `win11` - Windows 11 desktop simulation
-- `macos` - macOS desktop simulation
-
-### Native Desktop (Docker/QEMU)
-
-Real operating systems running in containers or VMs.
-
-**Best for:**
-
-- Real application testing
-- OS-specific tasks
-- Benchmarks requiring actual apps
-
-**Platforms:**
-
-- `linux-docker` - Linux container (XFCE)
-- `linux-qemu` - Linux VM with KVM
-- `windows-qemu` - Windows 11 VM
-- `android-qemu` - Android VM
-- `macos-lume` - macOS VM (Apple Silicon)
-
-## CLI Reference
-
-### Image Commands
-
-```bash
-cb image create <platform> # Create base image
-cb image list # List all images
-cb image info <name> # Show image details
-cb image clone <src> <dst> # Clone an image
-cb image delete <name> # Delete an image
-cb image shell <name> # Interactive shell (read-only overlay)
-```
-
-### Run Commands
-
-```bash
-cb run task <path> # Run a single task
-cb run dataset <path> # Run all tasks in dataset
-cb run list # List all runs
-cb run watch <id> # Watch run in real-time
-cb run info <id> # Show run details
-cb run logs <id> # View run logs
-cb run stop <id> # Stop a run
-```
-
-### Interact Commands
-
-```bash
-cb interact <task> # Interactive mode (manual testing)
-cb interact <task> --oracle # Run oracle solution
-cb interact <task> --variant-id <n> # Specific task variant
-```
-
-### Trace Commands
-
-```bash
-cb trace view <run-id> # View traces from a run
-cb trace list # List all traces
-```
-
-### Dataset Commands
-
-```bash
-cb dataset list # List available datasets
-cb dataset build <run-id> # Export training data
-```
-
-### Platform Commands
-
-```bash
-cb platform list # List available platforms
-cb status # Show system status
-```
-
-## Documentation
-
-- **Full Documentation**: https://cua.ai/docs/cuabench
-- **Getting Started**: https://cua.ai/docs/cuabench/guide/getting-started/introduction
-- **CLI Reference**: https://cua.ai/docs/cuabench/reference/cli-reference
-- **SDK Reference**: https://cua.ai/docs/cuabench/reference/sdk-reference
-- **Creating Tasks**: https://cua.ai/docs/cuabench/guide/examples/universal-task
-
-## Examples
-
-See the `tasks/` directory for example tasks and the documentation for detailed guides.
-
-## License
-
-Licensed under the Apache License 2.0. See [LICENSE](LICENSE) for details.
+**[Documentation](https://cua.ai/docs/cuabench)** - Installation, guides, and API reference.
diff --git a/libs/kasm/README.md b/libs/kasm/README.md
index 57613ed052..af515609d4 100644
--- a/libs/kasm/README.md
+++ b/libs/kasm/README.md
@@ -1,111 +1,5 @@
-# Cua Ubuntu Container
+# Cua Kasm Container
-Containerized virtual desktop for Computer-Using Agents (Cua). Utilizes Kasm's MIT-licensed Ubuntu XFCE container as a base with computer-server pre-installed.
+Kasm-based Ubuntu desktop container for Computer-Using Agents.
-## Features
-
-- Ubuntu 22.04 (Jammy) with XFCE desktop environment
-- Pre-installed computer-server for remote computer control
-- VNC access for visual desktop interaction
-- Python 3.11 with necessary libraries
-- Screen capture tools (gnome-screenshot, wmctrl, ffmpeg)
-- Clipboard utilities (xclip, socat)
-
-## Usage
-
-### Build and Push (multi-arch)
-
-Use Docker Buildx to build and push a multi-architecture image for both `linux/amd64` and `linux/arm64` in a single command. Replace `trycua` with your Docker Hub username or your registry namespace as needed.
-
-```bash
-# Login to your registry first (Docker Hub shown here)
-docker login
-
-# Build and push for amd64 and arm64 in one step
-docker buildx build \
- --platform linux/amd64,linux/arm64 \
- -t trycua/cua-ubuntu:latest \
- --push \
- .
-```
-
-### Running the Container Manually
-
-```bash
-docker run --rm -it --shm-size=512m -p 6901:6901 -p 8000:8000 -e VNCOPTIONS=-disableBasicAuth cua-ubuntu:latest
-```
-
-- **VNC Access**: Available at `http://localhost:6901`
-- **Computer Server API**: Available at `http://localhost:8000`
-
-### Using with Cua Docker Provider
-
-This container is designed to work with the Cua Docker provider for automated container management:
-
-```python
-from computer.providers.factory import VMProviderFactory
-
-# Create docker provider
-provider = VMProviderFactory.create_provider(
- provider_type="docker",
- image="cua-ubuntu:latest",
- port=8000, # computer-server API port
- noVNC_port=6901 # VNC port
-)
-
-# Run a container
-async with provider:
- vm_info = await provider.run_vm(
- image="cua-ubuntu:latest",
- name="my-cua-container",
- run_opts={
- "memory": "4GB",
- "cpu": 2,
- "vnc_port": 6901,
- "api_port": 8000
- }
- )
-```
-
-## Container Configuration
-
-### Ports
-
-- **6901**: VNC web interface (noVNC)
-- **8080**: Computer-server API endpoint
-
-### Environment Variables
-
-- `VNC_PW`: VNC password (default: "password")
-- `DISPLAY`: X11 display (set to ":0")
-
-### Volumes
-
-- `/home/kasm-user/storage`: Persistent storage mount point
-- `/home/kasm-user/shared`: Shared folder mount point
-
-## Creating Filesystem Snapshots
-
-You can create a filesystem snapshot of the container at any time:
-
-```bash
-docker commit <container_id> cua-ubuntu-snapshot:latest
-```
-
-Then run the snapshot:
-
-```bash
-docker run --rm -it --shm-size=512m -p 6901:6901 -p 8080:8080 -e VNCOPTIONS=-disableBasicAuth cua-ubuntu-snapshot:latest
-```
-
-Memory snapshots are available using the experimental `docker checkpoint` command. [Docker Checkpoint Documentation](https://docs.docker.com/reference/cli/docker/checkpoint/)
-
-## Integration with Cua System
-
-This container integrates seamlessly with the Cua computer provider system:
-
-- **Automatic Management**: Use the Docker provider for lifecycle management
-- **Resource Control**: Configure memory, CPU, and storage limits
-- **Network Access**: Automatic port mapping and IP detection
-- **Storage Persistence**: Mount host directories for persistent data
-- **Monitoring**: Real-time container status and health checking
+**[Documentation](https://cua.ai/docs/cua/reference/desktop-sandbox/linux-container/kasm)** - Setup and configuration.
diff --git a/libs/lume/README.md b/libs/lume/README.md
index 298e37eff9..a6045ffd00 100644
--- a/libs/lume/README.md
+++ b/libs/lume/README.md
@@ -1,76 +1,5 @@
-<div align="center">
-<h1>
- <div class="image-wrapper" style="display: inline-block;">
- <picture>
- <source media="(prefers-color-scheme: dark)" alt="logo" height="150" srcset="../../img/logo_white.png" style="display: block; margin: auto;">
- <source media="(prefers-color-scheme: light)" alt="logo" height="150" srcset="../../img/logo_black.png" style="display: block; margin: auto;">
- <img alt="Shows my svg">
- </picture>
- </div>
+# Lume
-[![Swift 6](https://img.shields.io/badge/Swift_6-F54A2A?logo=swift&logoColor=white&labelColor=F54A2A)](#)
-[![macOS](https://img.shields.io/badge/macOS-000000?logo=apple&logoColor=F0F0F0)](#)
-[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?&logo=discord&logoColor=white)](https://discord.com/invite/mVnXXpdE85)
+CLI and framework for macOS and Linux VMs using Apple Virtualization Framework.
-</h1>
-</div>
-
-**lume** is a lightweight Command Line Interface and local API server to create, run and manage macOS and Linux virtual machines (VMs) with near-native performance on Apple Silicon, using Apple's `Virtualization.Framework`.
-
-### Run prebuilt macOS images in just 1 step
-
-<div align="center">
-<img src="../../img/cli.png" alt="lume cli">
-</div>
-
-```bash
-lume run macos-sequoia-vanilla:latest
-```
-
-## Quickstart
-
-Install and run a prebuilt macOS VM in two commands:
-
-```bash
-# Install Lume
-/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
-# Pull & start a macOS image
-lume run macos-sequoia-vanilla:latest
-```
-
-<Callout title="Security Note">
-All prebuilt images use the default password `lume`. Change this immediately after your first login using the `passwd` command.
-</Callout>
-
-**System Requirements**:
-
-- Apple Silicon Mac (M1, M2, M3, etc.)
-- macOS 13.0 or later
-- At least 8GB of RAM (16GB recommended)
-- At least 30GB of free disk space
-
-## Development
-
-To get set up with Lume for development, read [these instructions](Development.md).
-
-## Docs
-
-- [Installation](https://cua.ai/docs/lume/guide/getting-started/installation)
-- [Prebuilt Images](https://cua.ai/docs/lume/guide/fundamentals/prebuilt-images)
-- [CLI Reference](https://cua.ai/docs/lume/reference/cli-reference)
-- [HTTP API](https://cua.ai/docs/lume/reference/http-api)
-- [FAQ](https://cua.ai/docs/lume/guide/advanced/faq)
-
-## Contributing
-
-We welcome and greatly appreciate contributions to lume! Whether you're improving documentation, adding new features, fixing bugs, or adding new VM images, your efforts help make lume better for everyone. For detailed instructions on how to contribute, please refer to our [Contributing Guidelines](CONTRIBUTING.md).
-
-Join our [Discord community](https://discord.com/invite/mVnXXpdE85) to discuss ideas or get assistance.
-
-## License
-
-lume is open-sourced under the MIT License - see the [LICENSE](../../LICENSE.md) file for details.
-
-## Trademarks
-
-Apple, macOS, and Apple Silicon are trademarks of Apple Inc. Ubuntu and Canonical are registered trademarks of Canonical Ltd. This project is not affiliated with, endorsed by, or sponsored by Apple Inc. or Canonical Ltd.
+**[Documentation](https://cua.ai/docs/lume)** - Installation, guides, and API reference.
diff --git a/libs/lumier/README.md b/libs/lumier/README.md
index 2d6d0af378..99a4b122e9 100644
--- a/libs/lumier/README.md
+++ b/libs/lumier/README.md
@@ -1,79 +1,5 @@
-<div align="center">
-<h1>
- <div class="image-wrapper" style="display: inline-block;">
- <picture>
- <source media="(prefers-color-scheme: dark)" alt="logo" height="150" srcset="../../img/logo_white.png" style="display: block; margin: auto;">
- <source media="(prefers-color-scheme: light)" alt="logo" height="150" srcset="../../img/logo_black.png" style="display: block; margin: auto;">
- <img alt="Shows my svg">
- </picture>
- </div>
-
-[![Swift 6](https://img.shields.io/badge/Swift_6-F54A2A?logo=swift&logoColor=white&labelColor=F54A2A)](#)
-[![macOS](https://img.shields.io/badge/macOS-000000?logo=apple&logoColor=F0F0F0)](#)
-[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?&logo=discord&logoColor=white)](https://discord.com/invite/mVnXXpdE85)
-
-</h1>
-</div>
+# Lumier
macOS and Linux virtual machines in a Docker container.
-<div align="center">
- <video src="https://github.com/user-attachments/assets/2ecca01c-cb6f-4c35-a5a7-69bc58bd94e2" width="800" controls></video>
-</div>
-
-## What is Lumier?
-
-**Lumier** is an interface for running macOS virtual machines with minimal setup. It uses Docker as a packaging system to deliver a pre-configured environment that connects to the `lume` virtualization service running on your host machine. With Lumier, you get:
-
-- A ready-to-use macOS or Linux virtual machine in minutes
-- Browser-based VNC access to your VM
-- Easy file sharing between your host and VM
-- Simple configuration through environment variables
-
-## Requirements
-
-Before using Lumier, make sure you have:
-
-1. **Docker for Apple Silicon** - download it [here](https://desktop.docker.com/mac/main/arm64/Docker.dmg) and follow the installation instructions.
-
-2. **Lume** - This is the virtualization CLI that powers Lumier. Install it with this command:
-
-```bash
-/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
-```
-
-## Getting Started
-
-```bash
-# Run the container with temporary storage (using pre-built image from Docker Hub)
-docker run -it --rm \
- --name macos-vm \
- -p 8006:8006 \
- -e VM_NAME=macos-vm \
- -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \
- -e CPU_CORES=4 \
- -e RAM_SIZE=8192 \
- trycua/lumier:latest
-```
-
-After running the command above, you can access your macOS VM through a web browser (e.g., http://localhost:8006).
-
-> **Note:** With the basic setup above, your VM will be reset when you stop the container (ephemeral mode). This means any changes you make inside the macOS VM will be lost. See [the documentation](https://cua.ai/docs/cua/reference/macos-vm-cli-playbook/lumier/docker) for how to save your VM state.
-
-## Docs
-
-- [Installation](https://cua.ai/docs/cua/reference/macos-vm-cli-playbook/lumier/installation)
-- [Docker](https://cua.ai/docs/cua/reference/macos-vm-cli-playbook/lumier/docker)
-- [Docker Compose](https://cua.ai/docs/cua/reference/macos-vm-cli-playbook/lumier/docker-compose)
-- [Building Lumier](https://cua.ai/docs/cua/reference/macos-vm-cli-playbook/lumier/building-lumier)
-
-## Credits
-
-This project was inspired by [dockur/windows](https://github.com/dockur/windows) and [dockur/macos](https://github.com/dockur/macos), which pioneered the approach of running Windows and macOS VMs in Docker containers.
-
-Main differences with dockur/macos:
-
-- Lumier is specifically designed for macOS virtualization
-- Lumier supports Apple Silicon (M1/M2/M3/M4) while dockur/macos only supports Intel
-- Lumier uses the Apple Virtualization Framework (Vz) through the `lume` CLI to create true virtual machines, while dockur relies on KVM.
-- Image specification is different, with Lumier and Lume relying on Apple Vz spec (disk.img and nvram.bin)
+**[Documentation](https://cua.ai/docs/lume/guide/advanced/lumier)** - Installation, guides, and configuration.
diff --git a/libs/python/agent/README.md b/libs/python/agent/README.md
index 6b747ad481..8d4e567b82 100644
--- a/libs/python/agent/README.md
+++ b/libs/python/agent/README.md
@@ -1,88 +1,5 @@
-<div align="center">
-<h1>
- <div class="image-wrapper" style="display: inline-block;">
- <picture>
- <source media="(prefers-color-scheme: dark)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_white.png" style="display: block; margin: auto;">
- <source media="(prefers-color-scheme: light)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_black.png" style="display: block; margin: auto;">
- <img alt="Shows my svg">
- </picture>
- </div>
+# Cua Agent
-[![Python](https://img.shields.io/badge/Python-333333?logo=python&logoColor=white&labelColor=333333)](#)
-[![macOS](https://img.shields.io/badge/macOS-000000?logo=apple&logoColor=F0F0F0)](#)
-[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?&logo=discord&logoColor=white)](https://discord.com/invite/mVnXXpdE85)
-[![PyPI](https://img.shields.io/pypi/v/cua-computer?color=333333)](https://pypi.org/project/cua-computer/)
+Computer-Use framework with liteLLM integration for running agentic workflows on macOS, Windows, and Linux sandboxes.
-</h1>
-</div>
-
-**cua-agent** is a general Computer-Use framework with liteLLM integration for running agentic workflows on macOS, Windows, and Linux sandboxes. It provides a unified interface for computer-use agents across multiple LLM providers with advanced callback system for extensibility.
-
-## Features
-
-- **Safe Computer-Use/Tool-Use**: Using Computer SDK for sandboxed desktops
-- **Multi-Agent Support**: Anthropic Claude, OpenAI computer-use-preview, UI-TARS, Omniparser + any LLM
-- **Multi-API Support**: Take advantage of liteLLM supporting 100+ LLMs / model APIs, including local models (`huggingface-local/`, `ollama_chat/`, `mlx/`)
-- **Cross-Platform**: Works on Windows, macOS, and Linux with cloud and local computer instances
-- **Extensible Callbacks**: Built-in support for image retention, cache control, PII anonymization, budget limits, and trajectory tracking
-
-## Install
-
-```bash
-pip install "cua-agent[all]"
-```
-
-## Quick Start
-
-```python
-import asyncio
-import os
-from agent import ComputerAgent
-from computer import Computer
-
-async def main():
- # Set up computer instance
- async with Computer(
- os_type="linux",
- provider_type="cloud",
- name=os.getenv("CUA_CONTAINER_NAME"),
- api_key=os.getenv("CUA_API_KEY")
- ) as computer:
-
- # Create agent
- agent = ComputerAgent(
- model="anthropic/claude-sonnet-4-5-20250929",
- tools=[computer],
- only_n_most_recent_images=3,
- trajectory_dir="trajectories",
- max_trajectory_budget=5.0 # $5 budget limit
- )
-
- # Run agent
- messages = [{"role": "user", "content": "Take a screenshot and tell me what you see"}]
-
- async for result in agent.run(messages):
- for item in result["output"]:
- if item["type"] == "message":
- print(item["content"][0]["text"])
-
-if __name__ == "__main__":
- asyncio.run(main())
-```
-
-## Docs
-
-- [Agent Loops](https://cua.ai/docs/cua/guide/fundamentals/agent-loops)
-- [Supported Agents](https://cua.ai/docs/cua/guide/get-started/what-is-computer-use-agent)
-- [Supported Models](https://cua.ai/docs/cua/guide/fundamentals/vlms)
-- [Chat History](https://cua.ai/docs/cua/guide/advanced/chat-history)
-- [Callbacks](https://cua.ai/docs/cua/guide/fundamentals/callbacks)
-- [Custom Tools](https://cua.ai/docs/cua/guide/advanced/custom-tools)
-- [Custom Computer Handlers](https://cua.ai/docs/cua/reference/computer-sdk)
-- [Prompt Caching](https://cua.ai/docs/cua/guide/advanced/prompt-caching)
-- [Usage Tracking](https://cua.ai/docs/cua/guide/advanced/telemetry)
-- [Benchmarks](https://cua.ai/docs/cua/guide/integrations/benchmarks)
-
-## License
-
-MIT License - see LICENSE file for details.
+**[Documentation](https://cua.ai/docs/cua/reference/agent-sdk)** - Installation, guides, and configuration.
diff --git a/libs/python/computer-server/README.md b/libs/python/computer-server/README.md
index 950c01fcc4..8016163565 100644
--- a/libs/python/computer-server/README.md
+++ b/libs/python/computer-server/README.md
@@ -1,43 +1,5 @@
-<div align="center">
-<h1>
- <div class="image-wrapper" style="display: inline-block;">
- <picture>
- <source media="(prefers-color-scheme: dark)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_white.png" style="display: block; margin: auto;">
- <source media="(prefers-color-scheme: light)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_black.png" style="display: block; margin: auto;">
- <img alt="Shows my svg">
- </picture>
- </div>
+# Cua Computer Server
-[![Python](https://img.shields.io/badge/Python-333333?logo=python&logoColor=white&labelColor=333333)](#)
-[![macOS](https://img.shields.io/badge/macOS-000000?logo=apple&logoColor=F0F0F0)](#)
-[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?&logo=discord&logoColor=white)](https://discord.com/invite/mVnXXpdE85)
-[![PyPI](https://img.shields.io/pypi/v/cua-computer-server?color=333333)](https://pypi.org/project/cua-computer-server/)
+Server component for the Computer-Use Interface (CUI) framework with WebSocket API.
-</h1>
-</div>
-
-**Computer Server** is the server component for the Computer-Use Interface (CUI) framework powering Cua for interacting with local macOS and Linux sandboxes, with cross-platform automation, and pluggable with any AI agent systems (Cua, Langchain, CrewAI, AutoGen).
-
-## Features
-
-- WebSocket API for computer-use
-- Cross-platform support (macOS, Linux)
-- Integration with Cua computer library for screen control, keyboard/mouse automation, and accessibility
-
-## Install
-
-To install the Computer-Use Interface (CUI):
-
-```bash
-pip install cua-computer-server
-```
-
-## Run
-
-Refer to this notebook for a step-by-step guide on how to use the Computer-Use Server on the host system or VM:
-
-- [Computer-Use Server](../../../notebooks/computer_server_nb.ipynb)
-
-## Docs
-
-- [Local Computer Server](https://cua.ai/docs/cua/guide/advanced/local-computer-server)
+**[Documentation](https://cua.ai/docs/cua/guide/advanced/local-computer-server)** - Installation, guides, and configuration.
diff --git a/libs/python/computer/README.md b/libs/python/computer/README.md
index 4a7e37d831..3a919982c5 100644
--- a/libs/python/computer/README.md
+++ b/libs/python/computer/README.md
@@ -1,72 +1,5 @@
-<div align="center">
-<h1>
- <div class="image-wrapper" style="display: inline-block;">
- <picture>
- <source media="(prefers-color-scheme: dark)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_white.png" style="display: block; margin: auto;">
- <source media="(prefers-color-scheme: light)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_black.png" style="display: block; margin: auto;">
- <img alt="Shows my svg">
- </picture>
- </div>
+# Cua Computer
-[![Python](https://img.shields.io/badge/Python-333333?logo=python&logoColor=white&labelColor=333333)](#)
-[![macOS](https://img.shields.io/badge/macOS-000000?logo=apple&logoColor=F0F0F0)](#)
-[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?&logo=discord&logoColor=white)](https://discord.com/invite/mVnXXpdE85)
-[![PyPI](https://img.shields.io/pypi/v/cua-computer?color=333333)](https://pypi.org/project/cua-computer/)
+Computer-Use Interface (CUI) framework for interacting with local macOS and Linux sandboxes.
-</h1>
-</div>
-
-**cua-computer** is a Computer-Use Interface (CUI) framework powering Cua for interacting with local macOS and Linux sandboxes, with cross-platform automation, and pluggable with any AI agent systems (Cua, Langchain, CrewAI, AutoGen). Computer relies on [Lume](https://github.com/trycua/lume) for creating and managing sandbox environments.
-
-### Get started with Computer
-
-<div align="center">
- <img src="https://raw.githubusercontent.com/trycua/cua/main/img/computer.png"/>
-</div>
-
-```python
-from computer import Computer
-
-computer = Computer(os_type="macos", display="1024x768", memory="8GB", cpu="4")
-try:
- await computer.run()
-
- screenshot = await computer.interface.screenshot()
- with open("screenshot.png", "wb") as f:
- f.write(screenshot)
-
- await computer.interface.move_cursor(100, 100)
- await computer.interface.left_click()
- await computer.interface.right_click(300, 300)
- await computer.interface.double_click(400, 400)
-
- await computer.interface.type_text("Hello, World!")
- await computer.interface.press_key("enter")
-
- await computer.interface.set_clipboard("Test clipboard")
- content = await computer.interface.copy_to_clipboard()
- print(f"Clipboard content: {content}")
-finally:
- await computer.stop()
-```
-
-## Install
-
-To install the Computer-Use Interface (CUI):
-
-```bash
-pip install "cua-computer[all]"
-```
-
-The `cua-computer` PyPi package pulls automatically the latest executable version of Lume through [pylume](https://github.com/trycua/pylume).
-
-## Run
-
-Refer to this notebook for a step-by-step guide on how to use the Computer-Use Interface (CUI):
-
-- [Computer-Use Interface (CUI)](https://github.com/trycua/cua/blob/main/notebooks/computer_nb.ipynb)
-
-## Docs
-
-- [Computer SDK](https://cua.ai/docs/cua/reference/computer-sdk)
-- [Sandboxed Python](https://cua.ai/docs/cua/guide/advanced/sandboxed-python)
+**[Documentation](https://cua.ai/docs/cua/reference/computer-sdk)** - Installation, guides, and configuration.
diff --git a/libs/python/computer/computer/providers/factory.py b/libs/python/computer/computer/providers/factory.py
index 8efd78cc41..fd8e28f5d2 100644
--- a/libs/python/computer/computer/providers/factory.py
+++ b/libs/python/computer/computer/providers/factory.py
@@ -61,8 +61,8 @@ class VMProviderFactory:
if not HAS_LUME:
raise ImportError(
- "The pylume package is required for LumeProvider. "
- "Please install it with 'pip install cua-computer[lume]'"
+ "LumeProvider requires curl and the Lume CLI. "
+ "Please install Lume from https://github.com/trycua/cua/tree/main/libs/lume"
)
return LumeProvider(
provider_port=provider_port,
@@ -74,8 +74,8 @@ class VMProviderFactory:
except ImportError as e:
logger.error(f"Failed to import LumeProvider: {e}")
raise ImportError(
- "The pylume package is required for LumeProvider. "
- "Please install it with 'pip install cua-computer[lume]'"
+ "LumeProvider requires curl and the Lume CLI. "
+ "Please install Lume from https://github.com/trycua/cua/tree/main/libs/lume"
) from e
elif provider_type == VMProviderType.LUMIER:
try:
diff --git a/libs/python/computer/computer/providers/lume/provider.py b/libs/python/computer/computer/providers/lume/provider.py
index 535e48ed0d..8a93f9332c 100644
--- a/libs/python/computer/computer/providers/lume/provider.py
+++ b/libs/python/computer/computer/providers/lume/provider.py
@@ -1,7 +1,6 @@
"""Lume VM provider implementation using curl commands.
-This provider uses direct curl commands to interact with the Lume API,
-removing the dependency on the pylume Python package.
+This provider uses direct curl commands to interact with the Lume API.
"""
import asyncio
@@ -32,8 +31,7 @@ logger = logging.getLogger(__name__)
class LumeProvider(BaseVMProvider):
"""Lume VM provider implementation using direct curl commands.
- This provider uses curl to interact with the Lume API server,
- removing the dependency on the pylume Python package.
+ This provider uses curl to interact with the Lume API server.
"""
def __init__(
diff --git a/libs/python/computer/computer/utils.py b/libs/python/computer/computer/utils.py
index 43c7efcdb5..27553ad467 100644
--- a/libs/python/computer/computer/utils.py
+++ b/libs/python/computer/computer/utils.py
@@ -104,7 +104,7 @@ def get_image_size(image_bytes: bytes) -> Tuple[int, int]:
def parse_vm_info(vm_info: Dict[str, Any]) -> Optional[Dict[str, Any]]:
- """Parse VM info from pylume response."""
+ """Parse VM info from Lume API response."""
if not vm_info:
return None
diff --git a/libs/python/mcp-server/README.md b/libs/python/mcp-server/README.md
index 98f571e6ad..52438199c6 100644
--- a/libs/python/mcp-server/README.md
+++ b/libs/python/mcp-server/README.md
@@ -1,163 +1,5 @@
-<div align="center">
-<h1>
- <div class="image-wrapper" style="display: inline-block;">
- <picture>
- <source media="(prefers-color-scheme: dark)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_white.png" style="display: block; margin: auto;">
- <source media="(prefers-color-scheme: light)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_black.png" style="display: block; margin: auto;">
- <img alt="Shows my svg">
- </picture>
- </div>
+# Cua MCP Server
-[![Python](https://img.shields.io/badge/Python-333333?logo=python&logoColor=white&labelColor=333333)](#)
-[![macOS](https://img.shields.io/badge/macOS-000000?logo=apple&logoColor=F0F0F0)](#)
-[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?&logo=discord&logoColor=white)](https://discord.com/invite/mVnXXpdE85)
-[![PyPI](https://img.shields.io/pypi/v/cua-computer?color=333333)](https://pypi.org/project/cua-computer/)
+MCP server for Computer-Use Agent (Cua), enabling Cua to run through MCP clients like Claude Desktop and Cursor.
-</h1>
-</div>
-
-# cua-mcp-server
-
-cua-mcp-server is an MCP server for the Computer-Use Agent (Cua). It enables Cua to run through MCP clients such as Claude Desktop and Cursor.
-
-## Prerequisites
-
-- Install lume: https://github.com/trycua/cua/blob/main/libs/lume/README.md#install
-- Python 3.10+
-- pip, venv, setuptools
-
-## Install
-
-Download and run the installation script:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/python/mcp-server/scripts/install_mcp_server.sh | bash
-```
-
-Add this to your MCP client configuration:
-
-```json
-{
- "mcpServers": {
- "cua-agent": {
- "command": "/usr/bin/env",
- "args": [
- "bash",
- "-lc",
- "export CUA_MODEL_NAME='anthropic/claude-sonnet-4-5-20250929'; ~/.cua/start_mcp_server.sh"
- ]
- }
- }
-}
-```
-
-## Development (run from a local checkout)
-
-Use an absolute path to the repository root in the arguments below.
-
-```json
-{
- "mcpServers": {
- "cua-agent": {
- "command": "/usr/bin/env",
- "args": [
- "bash",
- "-lc",
- "export CUA_MODEL_NAME='huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B'; /Users/your-username/Documents/GitHub/cua/libs/python/mcp-server/scripts/start_mcp_server.sh"
- ]
- }
- }
-}
-```
-
-Notes:
-
-- Replace `/Users/your-username/Documents/GitHub/cua` with the absolute path to your clone.
-- The script sets `PYTHONPATH` for local libs and runs the server module.
-
-## Quick Start
-
-After configuring your MCP client, restart it and invoke one of these tools:
-
-- Take a screenshot
-
-```json
-{
- "tool": "screenshot_cua",
- "args": {}
-}
-```
-
-- Run a task
-
-```json
-{
- "tool": "run_cua_task",
- "args": { "task": "Open Safari and search for University of Toronto" }
-}
-```
-
-Expected results:
-
-- Assistant messages streamed during execution
-- A final screenshot image
-
-## Desktop Extension
-
-Cua also provides a Claude Desktop Extension (`.mcpb` file) for easy one-click installation.
-
-### Building the Desktop Extension
-
-To build the desktop extension from source:
-
-```bash
-cd libs/python/mcp-server
-python3 build-extension.py
-```
-
-This creates `desktop-extension/cua-extension.mcpb` which can be installed directly in Claude Desktop.
-
-### Installing the Desktop Extension
-
-1. Build the extension (see above)
-2. Open Claude Desktop Settings
-3. Go to Extensions
-4. Drop the `cua-extension.mcpb` file into the window
-5. Follow the installation prompts
-
-See [desktop-extension/README.md](desktop-extension/README.md) for more details.
-
-## Documentation
-
-- Installation: https://cua.ai/docs/cua/reference/mcp-server/installation
-- Configuration: https://cua.ai/docs/cua/reference/mcp-server/configuration
-- Usage: https://cua.ai/docs/cua/reference/mcp-server/usage
-- Tools: https://cua.ai/docs/cua/reference/mcp-server/tools
-- Client Integrations: https://cua.ai/docs/cua/reference/mcp-server/client-integrations
-- LLM Integrations: https://cua.ai/docs/cua/reference/mcp-server/llm-integrations
-
-## Troubleshooting
-
-Server reports disconnected in MCP client:
-
-- Use an absolute path in the `args` command.
-- Launch via `/usr/bin/env bash -lc` so the shell initializes and expands paths.
-- Run the script manually to verify:
- ```bash
- /usr/bin/env bash -lc '/Users/your-username/Documents/GitHub/cua/libs/python/mcp-server/scripts/start_mcp_server.sh'
- ```
-
-pip not found in venv:
-
-```bash
-python3 -m ensurepip --upgrade
-python3 -m pip install -U pip setuptools wheel
-```
-
-Pydantic schema error related to Image:
-
-```bash
-python3 -m pip install -U "mcp>=1.2.0" "fastmcp>=0.4.7" "pydantic>=2.7,<2.12"
-```
-
-If issues persist, capture logs from your MCP client and the server startup script for diagnosis.
+**[Documentation](https://cua.ai/docs/cua/reference/mcp-server)** - Installation, guides, and configuration.
diff --git a/libs/python/pylume/tests/conftest.py b/libs/python/pylume/tests/conftest.py
deleted file mode 100644
index 66ff2deef8..0000000000
--- a/libs/python/pylume/tests/conftest.py
+++ /dev/null
@@ -1,23 +0,0 @@
-"""Pytest configuration for pylume tests.
-
-This module provides test fixtures for the pylume package.
-Note: This package has macOS-specific dependencies and will skip tests
-if the required modules are not available.
-"""
-
-from unittest.mock import Mock, patch
-
-import pytest
-
-
-def mock_subprocess():
- with patch("subprocess.run") as mock_run:
- mock_run.return_value = Mock(returncode=0, stdout="", stderr="")
- yield mock_run
-
-
-def mock_requests():
- with patch("requests.get") as mock_get, patch("requests.post") as mock_post:
- yield {"get": mock_get, "post": mock_post}
diff --git a/libs/python/pylume/tests/test_pylume.py b/libs/python/pylume/tests/test_pylume.py
deleted file mode 100644
index fa27eb0feb..0000000000
--- a/libs/python/pylume/tests/test_pylume.py
+++ /dev/null
@@ -1,38 +0,0 @@
-"""Unit tests for pylume package.
-
-This file tests ONLY basic pylume functionality.
-Following SRP: This file tests pylume module imports and basic operations.
-All external dependencies are mocked.
-"""
-
-import pytest
-
-
-class TestPylumeImports:
- """Test pylume module imports (SRP: Only tests imports)."""
-
- def test_pylume_module_exists(self):
- """Test that pylume module can be imported."""
- try:
- import pylume
-
- assert pylume is not None
- except ImportError:
- pytest.skip("pylume module not installed")
-
-
-class TestPylumeInitialization:
- """Test pylume initialization (SRP: Only tests initialization)."""
-
- def test_pylume_can_be_imported(self):
- """Basic smoke test: verify pylume components can be imported."""
- try:
- import pylume
-
- # Check for basic attributes
- assert pylume is not None
- except ImportError:
- pytest.skip("pylume module not available")
- except Exception as e:
- # Some initialization errors are acceptable in unit tests
- pytest.skip(f"pylume initialization requires specific setup: {e}")
diff --git a/libs/qemu-docker/README.md b/libs/qemu-docker/README.md
index 2ffc57c19c..1691296131 100644
--- a/libs/qemu-docker/README.md
+++ b/libs/qemu-docker/README.md
@@ -1,14 +1,5 @@
# QEMU Docker Containers
-Docker containers running desktop operating systems via QEMU/KVM for Computer-Using Agents (Cua).
+Docker containers running desktop operating systems via QEMU/KVM for Computer-Using Agents.
-## Structure
-
-```
-qemu-docker/
-└── windows/ # Windows 11 container with Cua computer-server
-```
-
-## Windows Container
-
-See [windows/README.md](windows/README.md) for complete documentation on the Windows 11 QEMU container.
+**[Documentation](https://cua.ai/docs/cua/reference/desktop-sandbox)** - Setup and configuration.
diff --git a/libs/qemu-docker/android/README.md b/libs/qemu-docker/android/README.md
index af3e191f75..5b96a6c9b9 100644
--- a/libs/qemu-docker/android/README.md
+++ b/libs/qemu-docker/android/README.md
@@ -1,79 +1,5 @@
-# QEMU Android
+# Cua Android Container
-Docker image that runs an Android emulator using QEMU/KVM with Cua Computer Server integration, enabling programmatic control of Android devices via HTTP API.
+Android emulator container with QEMU/KVM for Computer-Using Agents.
-## Features
-
-- **Android 11 Emulator** - Based on budtmo/docker-android
-- **Cua Computer Server** - HTTP API for automation, file operations, window management
-- **Custom Wallpaper Manager APK** - Programmatically set wallpapers without user interaction
-- **VNC Access** - View and interact with the Android screen via web browser
-
-## What's Inside
-
-- **wallpaper-manager/** - Custom Android APK that uses WallpaperManager API to set wallpapers
-- **entry.sh** - Container startup script that launches emulator and server
-- **Dockerfile** - Production build (installs cua-computer-server from PyPI)
-- **dev.Dockerfile** - Development build (uses local source code)
-
-## Quick Start
-
-### Production Build
-
-```bash
-docker build -t trycua/cua-qemu-android .
-docker run -d -p 6080:6080 -p 8000:8000 \
- -e EMULATOR_DEVICE="Samsung Galaxy S10" \
- -e WEB_VNC=true \
- --device /dev/kvm \
- --name android-container \
- trycua/cua-qemu-android
-```
-
-### Development Build
-
-```bash
-cd ../.. # Go to libs/ directory
-docker build -f qemu-docker/android/dev.Dockerfile -t trycua/cua-qemu-android:dev .
-docker run -d -p 6080:6080 -p 8000:8000 \
- -e EMULATOR_DEVICE="Samsung Galaxy S10" \
- -e WEB_VNC=true \
- --device /dev/kvm \
- --name android-container \
- trycua/cua-qemu-android:dev
-```
-
-## Access Points
-
-- **VNC Web UI**: http://localhost:6080
-- **Computer Server API**: http://localhost:8000
-- **API Documentation**: http://localhost:8000/docs
-
-## API Examples
-
-```bash
-# Get screen size
-curl -X POST http://localhost:8000/cmd \
- -H "Content-Type: application/json" \
- -d '{"command": "get_screen_size", "params": {}}'
-
-# Set wallpaper (automatically handles permissions)
-curl -X POST http://localhost:8000/cmd \
- -H "Content-Type: application/json" \
- -d '{"command": "set_wallpaper", "params": {"path": "/sdcard/image.jpg", "target": "home"}}'
-
-# Launch app
-curl -X POST http://localhost:8000/cmd \
- -H "Content-Type: application/json" \
- -d '{"command": "launch", "params": {"app": "com.android.settings"}}'
-```
-
-## Custom Wallpaper Solution
-
-Android doesn't provide native ADB commands for setting wallpapers. We solved this by:
-
-1. **Building a custom APK** (`wallpaper-manager`) that uses Android's WallpaperManager API
-2. **Multi-stage Docker build** - APK is compiled during image build
-3. **Auto-installation** - APK installs automatically on container startup
-4. **Permission handling** - Files are copied to `/data/local/tmp` where all apps have read access
-5. **Seamless integration** - `set_wallpaper()` API handles everything automatically
+**[Documentation](https://cua.ai/docs/cua/reference/desktop-sandbox/qemu-container/android)** - Setup and configuration.
diff --git a/libs/qemu-docker/linux/README.md b/libs/qemu-docker/linux/README.md
index 40490802c1..4cb8fd5e6b 100644
--- a/libs/qemu-docker/linux/README.md
+++ b/libs/qemu-docker/linux/README.md
@@ -1,146 +1,5 @@
# Cua Linux Container
-Containerized Ubuntu 22.04 LTS virtual desktop for Computer-Using Agents (Cua). Utilizes QEMU/KVM with Ubuntu Desktop and computer-server pre-installed for remote computer control.
+Ubuntu 22.04 virtual desktop container with QEMU/KVM for Computer-Using Agents.
-## Features
-
-- Ubuntu 22.04 LTS Desktop running in QEMU/KVM
-- Automated installation via cloud-init autoinstall
-- Pre-installed Cua computer-server for remote computer control
-- Support for custom OEM scripts during setup
-- noVNC access for visual desktop interaction
-
-## Quick Start
-
-### 1. Download Ubuntu Server ISO
-
-**Download Ubuntu 22.04 LTS Server ISO:**
-
-1. Visit & download the [server ISO](https://releases.ubuntu.com/22.04/ubuntu-22.04.5-live-server-amd64.iso)
-2. After downloading, rename the file to `setup.iso`
-3. Copy it to the directory `src/vm/image/`
-
-This ISO is used for automated Ubuntu installation with cloud-init on first run.
-
-### 2. Build the Image
-
-```bash
-docker build -t trycua/cua-qemu-linux:dev .
-```
-
-### 3. First Run - Create Golden Image
-
-On first run, the container will install Ubuntu from scratch and create a golden image. This takes 15-30 minutes.
-
-```bash
-# Create storage directory
-mkdir -p ./storage
-
-# Run with setup.iso to create golden image
-docker run -it --rm \
- --device=/dev/kvm \
- --name cua-qemu-linux \
- --mount type=bind,source=src/vm/image/setup.iso,target=/custom.iso \
- --cap-add NET_ADMIN \
- -v $(pwd)/storage:/storage \
- -p 8006:8006 \
- -p 5000:5000 \
- -e RAM_SIZE=8G \
- -e CPU_CORES=4 \
- -e DISK_SIZE=64G \
- trycua/cua-qemu-linux:dev
-```
-
-**What happens during first run:**
-
-1. Ubuntu 22.04 Server installs automatically using cloud-init autoinstall
-2. Minimal desktop environment is installed with auto-login enabled
-3. OEM setup scripts install Python 3, create venv, and install Cua computer-server
-4. systemd service created for Cua server (runs automatically on login)
-5. X11 access configured for GUI automation
-6. Golden image is saved to `/storage` directory
-7. Container exits after setup completes
-
-### 4. Subsequent Runs - Use Golden Image
-
-After the golden image is created, subsequent runs boot much faster (30 sec - 2 min):
-
-```bash
-# Run without setup.iso - uses existing golden image
-docker run -it --rm \
- --device=/dev/kvm \
- --name cua-qemu-linux \
- --cap-add NET_ADMIN \
- -v $(pwd)/storage:/storage \
- -p 8006:8006 \
- -p 5000:5000 \
- -e RAM_SIZE=8G \
- -e CPU_CORES=4 \
- trycua/cua-qemu-linux:dev
-```
-
-**Access points:**
-
-- **Computer Server API**: `http://localhost:5000`
-- **noVNC Browser**: `http://localhost:8006`
-
-## Container Configuration
-
-### Ports
-
-- **5000**: Cua computer-server API endpoint
-- **8006**: noVNC web interface for visual desktop access
-
-### Environment Variables
-
-- `RAM_SIZE`: RAM allocated to Ubuntu VM (default: "8G", recommended: "8G" for WSL2)
-- `CPU_CORES`: CPU cores allocated to VM (default: "8")
-- `DISK_SIZE`: VM disk size (default: "64G", minimum: "32G")
-
-### Volumes
-
-- `/storage`: Persistent VM storage (golden image, disk)
-- `/custom.iso`: Mount point for setup.iso (only needed for first run)
-- `/oem`: Optional mount point for custom OEM scripts (built-in scripts included in image)
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────┐
-│ Docker Container (Linux host) │
-│ │
-│ • Port forwarding: localhost:5000 → EMULATOR_IP:5000 │
-│ • Exposes: 5000 (API), 8006 (noVNC) │
-│ │
-│ ┌────────────────────────────────────────────────────┐ │
-│ │ QEMU VM (Ubuntu 22.04) │ │
-│ │ │ │
-│ │ • Cua computer-server listens on 5000 │ │
-│ │ │ │
-│ └────────────────────────────────────────────────────┘ │
-│ │
-└─────────────────────────────────────────────────────────┘
-```
-
-**Communication Flow:**
-
-1. External client → `localhost:5000` (host)
-2. Docker port mapping → Container's `localhost:5000`
-3. Container detects VM IP and waits for server to be ready
-4. Cua computer-server in Ubuntu VM processes request
-
-## Development
-
-### Modifying Setup Scripts
-
-Setup scripts are in `src/vm/setup/`:
-
-- `install.sh`: Entry point called after cloud-init installation (runs OEM setup)
-- `setup.sh`: Main setup orchestration (copies scripts to /opt/oem)
-- `setup-cua-server.sh`: Cua server installation with isolated venv and systemd service
-
-After modifying, rebuild the image:
-
-```bash
-docker build -t trycua/cua-qemu-linux:dev .
-```
+**[Documentation](https://cua.ai/docs/cua/reference/desktop-sandbox/qemu-container/linux)** - Setup and configuration.
diff --git a/libs/qemu-docker/windows/README.md b/libs/qemu-docker/windows/README.md
index 909d307714..6db8403fee 100644
--- a/libs/qemu-docker/windows/README.md
+++ b/libs/qemu-docker/windows/README.md
@@ -1,159 +1,5 @@
# Cua Windows Container
-Containerized Windows 11 virtual desktop for Computer-Using Agents (Cua). Utilizes QEMU/KVM with Windows 11 and computer-server pre-installed for remote computer control.
+Windows 11 virtual desktop container with QEMU/KVM for Computer-Using Agents.
-## Features
-
-- Windows 11 Enterprise running in QEMU/KVM
-- Pre-installed Cua computer-server for remote computer control
-- Caddy reverse proxy (port 9222 → 1337) for browser automation
-- noVNC access for visual desktop interaction
-- Automated setup via unattended installation
-- Support for both dev (shared folder) and azure (OEM folder) deployment modes
-- Python 3.12 with isolated virtual environment for Cua computer-server
-- Services run hidden in background via Windows scheduled tasks
-- Essential tools pre-installed (Chrome, LibreOffice, VLC, GIMP, VSCode, Thunderbird)
-
-## Quick Start
-
-### 1. Download and Prepare setup.iso
-
-**Download Windows 11 Evaluation ISO:**
-
-1. Visit [Microsoft Evaluation Center](https://info.microsoft.com/ww-landing-windows-11-enterprise.html)
-2. Accept the Terms of Service
-3. Download **Windows 11 Enterprise Evaluation (90-day trial, English, United States)** ISO file [~6GB]
-4. After downloading, rename the file to `setup.iso`
-5. Copy it to the directory `src/vm/image/`
-
-This ISO is used for automated Windows installation on first run.
-
-### 2. Build the Image
-
-```bash
-docker build -t trycua/cua-qemu-windows:dev .
-```
-
-### 3. First Run - Create Golden Image
-
-On first run, the container will install Windows from scratch and create a golden image. This takes 15-30 minutes.
-
-```bash
-# Create storage directory
-mkdir -p ./storage
-
-# Run with setup.iso to create golden image
-docker run -it --rm \
- --device=/dev/kvm \
- --platform linux/amd64 \
- --name cua-qemu-windows \
- --mount type=bind,source=$(pwd)/src/vm/image/setup.iso,target=/custom.iso \
- --cap-add NET_ADMIN \
- -v $(pwd)/storage:/storage \
- -p 8006:8006 \
- -p 5000:5000 \
- -e RAM_SIZE=8G \
- -e CPU_CORES=4 \
- -e DISK_SIZE=20G \
- trycua/cua-qemu-windows:dev
-```
-
-**What happens during first run:**
-
-1. Windows 11 installs automatically using unattended configuration
-2. Setup scripts install Python 3.12, Git, and Cua computer-server in isolated venv
-3. Windows scheduled tasks created for Cua server and Caddy proxy (run hidden in background)
-4. Golden image is saved to `/storage` directory
-5. Container exits after setup completes
-
-### 4. Subsequent Runs - Use Golden Image
-
-After the golden image is created, subsequent runs boot much faster (30 sec - 2 min):
-
-```bash
-# Run without setup.iso - uses existing golden image
-docker run -it --rm \
- --device=/dev/kvm \
- --platform linux/amd64 \
- --name cua-qemu-windows \
- --cap-add NET_ADMIN \
- -v $(pwd)/storage:/storage \
- -p 8006:8006 \
- -p 5000:5000 \
- -e RAM_SIZE=8G \
- -e CPU_CORES=4 \
- trycua/cua-qemu-windows:dev
-```
-
-**Access points:**
-
-- **Computer Server API**: `http://localhost:5000`
-- **noVNC Browser**: `http://localhost:8006`
-
-## Container Configuration
-
-### Ports
-
-- **5000**: Cua computer-server API endpoint
-- **8006**: noVNC web interface for visual desktop access
-
-### Environment Variables
-
-- `RAM_SIZE`: RAM allocated to Windows VM (default: "8G", recommended: "8G" for WSL2)
-- `CPU_CORES`: CPU cores allocated to VM (default: "8")
-- `DISK_SIZE`: VM disk size (default: "30G", minimum: "20G")
-- `VERSION`: Windows version (default: "win11x64-enterprise-eval")
-
-### Volumes
-
-- `/storage`: Persistent VM storage (golden image, disk, firmware)
-- `/custom.iso`: Mount point for setup.iso (only needed for first run)
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────┐
-│ Docker Container (Linux host) │
-│ │
-│ • Port forwarding: localhost:5000 → EMULATOR_IP:5000 │
-│ • Exposes: 5000 (API), 8006 (noVNC) │
-│ │
-│ ┌────────────────────────────────────────────────────┐ │
-│ │ QEMU VM (Windows 11) │ │
-│ │ │ │
-│ │ • Cua computer-server listens on 5000 │ │
-│ │ │ │
-│ └────────────────────────────────────────────────────┘ │
-│ │
-└─────────────────────────────────────────────────────────┘
-```
-
-**Communication Flow:**
-
-1. External client → `localhost:5000` (host)
-2. Docker port mapping → Container's `localhost:5000`
-3. socat port forwarding → `20.20.20.21:5000` (VM)
-4. Cua computer-server in Windows VM processes request
-
-## Development
-
-### Modifying Setup Scripts
-
-Setup scripts are in `src/vm/setup/`:
-
-- `install.bat`: Entry point called by Windows setup
-- `setup.ps1`: Main setup orchestration (installs software, configures Windows)
-- `setup-cua-server.ps1`: Cua server installation with isolated venv
-- `on-logon.ps1`: Runs on user logon (starts scheduled tasks)
-- `setup-utils.psm1`: Helpers functions for setup
-
-After modifying, rebuild the image:
-
-```bash
-docker build -t trycua/cua-qemu-windows:dev .
-```
-
-## Credits
-
-- Built on [Dockur Windows](https://github.com/dockur/windows) base image
-- Inspired by [Windows Agent Arena](https://github.com/microsoft/WindowsAgentArena)
+**[Documentation](https://cua.ai/docs/cua/reference/desktop-sandbox/qemu-container/windows)** - Setup and configuration.
diff --git a/libs/typescript/agent/README.md b/libs/typescript/agent/README.md
index d1aadb4d55..450191d3f1 100644
--- a/libs/typescript/agent/README.md
+++ b/libs/typescript/agent/README.md
@@ -1,217 +1,5 @@
# @trycua/agent
-TypeScript SDK for Cua agent interaction. Connect to Cua agent proxies via HTTP/HTTPS or peer-to-peer (WebRTC) connections.
+TypeScript SDK for Cua agent interaction via HTTP/HTTPS or peer-to-peer (WebRTC) connections.
-## Installation
-
-```bash
-npm install @trycua/agent
-# or
-pnpm add @trycua/agent
-# or
-yarn add @trycua/agent
-```
-
-## Usage
-
-### Basic Usage
-
-```typescript
-import AgentClient from '@trycua/agent';
-
-// Connect to local HTTP server
-const client = new AgentClient('https://localhost:8000');
-
-// Connect to a cloud container (port 8443 over HTTPS)
-const cloud = new AgentClient('https://m-linux-96lcxd2c2k.containers.cloud.trycua.com:8443', {
- apiKey: process.env.NEXT_PUBLIC_CUA_API_KEY || '',
-});
-
-// Connect to peer
-const peerClient = new AgentClient('peer://my-agent-proxy');
-
-// Send a simple text request
-const response = await client.responses.create({
- model: 'anthropic/claude-sonnet-4-5-20250929',
- input: 'Write a one-sentence bedtime story about a unicorn.',
- // Optional per-request env overrides
- env: {
- OPENAI_API_KEY: 'sk-...',
- },
-});
-
-console.log(response.output);
-```
-
-### Multi-modal Requests
-
-```typescript
-const response = await client.responses.create({
- model: 'anthropic/claude-sonnet-4-5-20250929',
- input: [
- {
- role: 'user',
- content: [
- { type: 'input_text', text: 'What is in this image?' },
- {
- type: 'input_image',
- image_url: 'https://example.com/image.jpg',
- },
- ],
- },
- ],
- env: { OPENROUTER_API_KEY: 'sk-...' },
-});
-```
-
-### Advanced Configuration
-
-```typescript
-const client = new AgentClient('https://localhost:8000', {
- timeout: 60000, // 60 second timeout
- retries: 5, // 5 retry attempts
- apiKey: 'cua_...', // sent as X-API-Key header when using HTTP/HTTPS
-});
-
-const response = await client.responses.create({
- model: 'anthropic/claude-sonnet-4-5-20250929',
- input: 'Hello, world!',
- agent_kwargs: {
- save_trajectory: true,
- verbosity: 20,
- },
- computer_kwargs: {
- os_type: 'linux',
- provider_type: 'cloud',
- },
- // Per-request env overrides
- env: {
- ANTHROPIC_API_KEY: 'sk-...',
- OPENROUTER_API_KEY: 'sk-...',
- },
-});
-```
-
-### Health Check
-
-```typescript
-const health = await client.health();
-console.log(health.status); // 'healthy', 'unhealthy', 'unreachable', 'connected', 'disconnected'
-```
-
-### Cleanup
-
-```typescript
-// Clean up peer connections when done
-await client.disconnect();
-```
-
-## API Reference
-
-### AgentClient
-
-#### Constructor
-
-```typescript
-new AgentClient(url: string, options?: AgentClientOptions)
-```
-
-- `url`: Connection URL. Supports `http://`, `https://`, or `peer://` protocols
-- `options`: Optional configuration object
-
-#### Methods
-
-##### responses.create(request: AgentRequest): Promise<AgentResponse>
-
-Send a request to the agent and get a response.
-
-##### health(): Promise<{status: string}>
-
-Check the health/connection status of the agent.
-
-##### disconnect(): Promise<void>
-
-Clean up resources and close connections.
-
-### Types
-
-#### AgentRequest
-
-```typescript
-interface AgentRequest {
- model: string;
- input: string | AgentMessage[];
- agent_kwargs?: {
- save_trajectory?: boolean;
- verbosity?: number;
- [key: string]: any;
- };
- computer_kwargs?: {
- os_type?: string;
- provider_type?: string;
- [key: string]: any;
- };
- // Optional per-request environment overrides
- env?: Record<string, string>;
-}
-```
-
-#### AgentResponse
-
-```typescript
-interface AgentResponse {
- output: AgentMessage[];
- usage: Usage;
-}
-
-interface Usage {
- prompt_tokens: number;
- completion_tokens: number;
- total_tokens: number;
- response_cost: number;
-}
-```
-
-The `output` array contains the conversation history including:
-
-- User messages
-- Agent reasoning/thinking
-- Computer actions and their results
-- Final agent responses
-
-The `usage` object provides token counts and cost information for the request.
-
-## Connection Types
-
-### HTTP/HTTPS
-
-Connect to a Cua agent proxy server:
-
-```typescript
-// Local
-const client = new AgentClient('https://my-agent-server.com:8000', { apiKey: 'cua_...' });
-
-// Cloud container (port 8443)
-const cloud = new AgentClient('https://m-linux-96lcxd2c2k.containers.cloud.trycua.com:8443', {
- apiKey: 'cua_...',
-});
-```
-
-Notes:
-
-- The client sends the API key as `X-API-Key` for HTTP/HTTPS connections.
-- Cloud containers listen on `:8443` with HTTPS.
-
-### Peer-to-Peer (WebRTC)
-
-Connect directly to another peer using WebRTC:
-
-```typescript
-const client = new AgentClient('peer://agent-proxy-peer-id');
-```
-
-The client uses PeerJS with default configuration for peer connections.
-
-## License
-
-MIT
+**[Documentation](https://cua.ai/docs/cua/reference/agent-sdk)** - Installation, guides, and configuration.
diff --git a/libs/typescript/computer/README.md b/libs/typescript/computer/README.md
index 09aa3dbc64..79b03ba828 100644
--- a/libs/typescript/computer/README.md
+++ b/libs/typescript/computer/README.md
@@ -1,83 +1,5 @@
-<div align="center">
-<h1>
- <div class="image-wrapper" style="display: inline-block;">
- <picture>
- <source media="(prefers-color-scheme: dark)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_white.png" style="display: block; margin: auto;">
- <source media="(prefers-color-scheme: light)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_black.png" style="display: block; margin: auto;">
- <img alt="Shows my svg">
- </picture>
- </div>
+# @trycua/computer
-[![TypeScript](https://img.shields.io/badge/TypeScript-333333?logo=typescript&logoColor=white&labelColor=333333)](#)
-[![macOS](https://img.shields.io/badge/macOS-000000?logo=apple&logoColor=F0F0F0)](#)
-[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?&logo=discord&logoColor=white)](https://discord.com/invite/mVnXXpdE85)
-[![NPM](https://img.shields.io/npm/v/@trycua/computer?color=333333)](https://www.npmjs.com/package/@trycua/computer)
+Computer-Use Interface (CUI) framework for interacting with local macOS and Linux sandboxes.
-</h1>
-</div>
-
-**@trycua/computer** is a Computer-Use Interface (CUI) framework powering Cua for interacting with local macOS and Linux sandboxes, Playwright-compatible, and pluggable with any AI agent systems (Cua, Langchain, CrewAI, AutoGen). Computer relies on [Lume](https://github.com/trycua/lume) for creating and managing sandbox environments.
-
-### Get started with Computer
-
-<div align="center">
- <img src="https://raw.githubusercontent.com/trycua/cua/main/img/computer.png"/>
-</div>
-
-```typescript
-import { Computer, OSType } from '@trycua/computer';
-
-// Create a new computer instance
-const computer = new Computer({
- osType: OSType.LINUX,
- name: 's-linux-vm_id',
- apiKey: 'your-api-key',
-});
-
-// Start the computer
-await computer.run();
-
-// Get the computer interface for interaction
-const computerInterface = computer.interface;
-
-// Take a screenshot
-const screenshot = await computerInterface.getScreenshot();
-// In a Node.js environment, you might save it like this:
-// import * as fs from 'fs';
-// fs.writeFileSync('screenshot.png', Buffer.from(screenshot));
-
-// Click at coordinates
-await computerInterface.click(500, 300);
-
-// Type text
-await computerInterface.typeText('Hello, world!');
-
-// Stop the computer
-await computer.stop();
-```
-
-## Install
-
-To install the Computer-Use Interface (CUI):
-
-```bash
-npm install @trycua/computer
-# or
-pnpm add @trycua/computer
-```
-
-The `@trycua/computer` package provides the TypeScript library for interacting with computer interfaces.
-
-## Run
-
-Refer to this example for a step-by-step guide on how to use the Computer-Use Interface (CUI):
-
-- [Computer-Use Interface (CUI)](https://github.com/trycua/cua/tree/main/examples/computer-example-ts)
-
-## Docs
-
-- [Computer SDK](https://cua.ai/docs/cua/reference/computer-sdk)
-
-## License
-
-[MIT](./LICENSE) License 2025 [Cua](https://github.com/trycua)
+**[Documentation](https://cua.ai/docs/cua/reference/computer-sdk)** - Installation, guides, and configuration.
diff --git a/libs/typescript/cua-cli/README.md b/libs/typescript/cua-cli/README.md
index c30ac3bb4e..c127c0fb83 100644
--- a/libs/typescript/cua-cli/README.md
+++ b/libs/typescript/cua-cli/README.md
@@ -1,103 +1,5 @@
-# Cua CLI (Bun)
+# Cua CLI
-## Install
+Command-line tool for managing cloud sandboxes and authentication.
-```bash
-bun install
-bun link # register package globally
-bun link cua-cli # install the global binary `cua`
-```
-
-If you want to run without linking:
-
-```bash
-bun run ./index.ts -- --help
-```
-
-## Commands
-
-- **Auth**
-
- The CLI supports both **flat** and **grouped** command styles:
-
- ```bash
- # Grouped style (explicit)
- cua auth login
- cua auth env
- cua auth logout
-
- # Flat style (quick)
- cua login
- cua env
- cua logout
- ```
-
- **Available Commands:**
- - `login` – opens browser to authorize; stores API key locally
- - `--api-key sk-...` – stores provided key directly
- - `env` – writes/updates `.env` with `CUA_API_KEY`
- - `logout` – clears stored API key
-
-- **Sandboxes**
-
- The CLI supports both **flat** and **grouped** command styles:
-
- ```bash
- # Flat style (quick & concise)
- cua list
- cua create --os linux --size small --region north-america
- cua start <name>
- cua stop <name>
-
- # Grouped style (explicit & clear)
- cua sb list # or: cua sandbox list
- cua sb create # or: cua sandbox create
- cua sb start # or: cua sandbox start
- cua sb stop # or: cua sandbox stop
- ```
-
- **Available Commands:**
- - `list` (aliases: `ls`, `ps`) – list all sandboxes
- - `--show-passwords` – include passwords in output
- - `create` – create a new sandbox
- - `--os`: `linux`, `windows`, `macos`
- - `--size`: `small`, `medium`, `large`
- - `--region`: `north-america`, `europe`, `asia-pacific`, `south-america`
- - `get <name>` – get detailed information about a specific sandbox
- - `--json` – output in JSON format
- - `--show-passwords` – include password in output
- - `--show-vnc-url` – include computed NoVNC URL
- - `delete <name>` – delete a sandbox
- - `start <name>` – start a stopped sandbox
- - `stop <name>` – stop a running sandbox
- - `restart <name>` – restart a sandbox
- - `suspend <name>` – suspend a sandbox (preserves memory state)
- - `vnc <name>` (alias: `open`) – open VNC desktop in your browser
-
-## Auth Flow (Dynamic Callback Port)
-
-- CLI starts a small local HTTP server using `Bun.serve({ port: 0 })` which picks an available port.
-- Browser is opened to `https://cua.ai/cli-auth?callback_url=http://127.0.0.1:<port>/callback`.
-- After you click "Authorize CLI", the browser redirects to the local server with `?token=...`.
-- The CLI saves the API key in `~/.config/cua/cli.sqlite`.
-
-> Note: If the browser cannot be opened automatically, copy/paste the printed URL.
-
-## Project Structure
-
-- `index.ts` – entry point (shebang + start CLI)
-- `src/cli.ts` – yargs bootstrapping
-- `src/commands/auth.ts` – auth/login/pull/logout commands
-- `src/commands/sandbox.ts` – sandbox list/start/stop/restart commands
-- `src/auth.ts` – browser flow + local callback server (dynamic port)
-- `src/http.ts` – HTTP helper
-- `src/storage.ts` – SQLite-backed key-value storage
-- `src/config.ts` – constants and paths
-- `src/util.ts` – table printing, .env writer
-
-## Notes
-
-- Stored API key lives at `~/.config/cua/cli.sqlite` under `kv(api_key)`.
-- Public API base defaults to `https://api.cua.ai`.
-- Website base defaults to `https://cua.ai`.
-- Authorization header: `Authorization: Bearer <api_key>`.
+**[Documentation](https://cua.ai/docs/cua/reference/cloud-cli)** - Installation, guides, and configuration.
diff --git a/libs/xfce/README.md b/libs/xfce/README.md
index 6952ed2668..0834edd4e1 100644
--- a/libs/xfce/README.md
+++ b/libs/xfce/README.md
@@ -1,275 +1,5 @@
-# Cua Docker XFCE Container
+# Cua XFCE Container
-Vanilla XFCE desktop container for Computer-Using Agents (Cua) with noVNC and computer-server. This is a lightweight alternative to the Kasm-based container with minimal dependencies.
+Vanilla XFCE desktop container for Computer-Using Agents.
-## Features
-
-- Ubuntu 22.04 (Jammy) with vanilla XFCE desktop environment
-- TigerVNC server for remote desktop access
-- noVNC for web-based VNC access (no client required)
-- Pre-installed computer-server for remote computer control
-- Python 3.11 with necessary libraries
-- Screen capture tools (gnome-screenshot, wmctrl, ffmpeg)
-- Clipboard utilities (xclip, socat)
-- Firefox browser with telemetry disabled
-
-## Architecture
-
-```
-┌─────────────────────────────────────────┐
-│ Docker Container (Ubuntu 22.04) │
-├─────────────────────────────────────────┤
-│ XFCE Desktop Environment │
-│ ├── Firefox │
-│ ├── XFCE Terminal │
-│ └── Desktop utilities │
-├─────────────────────────────────────────┤
-│ TigerVNC Server (Port 5901) │
-│ └── X11 Display :1 │
-├─────────────────────────────────────────┤
-│ noVNC Web Interface (Port 6901) │
-│ └── WebSocket proxy to VNC │
-├─────────────────────────────────────────┤
-│ Cua Computer Server (Port 8000) │
-│ └── WebSocket API for automation │
-└─────────────────────────────────────────┘
-```
-
-## Building the Container
-
-```bash
-docker build -t cua-xfce:latest .
-```
-
-### Build and Push (multi-arch)
-
-Use Docker Buildx to build and push a multi-architecture image for both `linux/amd64` and `linux/arm64` in a single command. Replace `trycua` with your Docker Hub username or your registry namespace as needed.
-
-```bash
-# Login to your registry first (Docker Hub shown here)
-docker login
-
-# Build and push for amd64 and arm64 in one step
-docker buildx build \
- --platform linux/amd64,linux/arm64 \
- -t trycua/cua-xfce:latest \
- --push \
- .
-```
-
-## Running the Container Manually
-
-### Basic Usage
-
-```bash
-docker run --rm -it \
- --shm-size=512m \
- -p 5901:5901 \
- -p 6901:6901 \
- -p 8000:8000 \
- cua-xfce:latest
-```
-
-### With Custom Resolution
-
-```bash
-docker run --rm -it \
- --shm-size=512m \
- -p 5901:5901 \
- -p 6901:6901 \
- -p 8000:8000 \
- -e VNC_RESOLUTION=1280x720 \
- cua-xfce:latest
-```
-
-### With Persistent Storage
-
-```bash
-docker run --rm -it \
- --shm-size=512m \
- -p 5901:5901 \
- -p 6901:6901 \
- -p 8000:8000 \
- -v $(pwd)/storage:/home/cua/storage \
- cua-xfce:latest
-```
-
-## Accessing the Container
-
-- **noVNC Web Interface**: Open `http://localhost:6901` in your browser (no password required)
-- **VNC Client**: Connect to `localhost:5901` (no password required)
-- **Computer Server API**: Available at `http://localhost:8000`
-
-## Using with Cua Docker Provider
-
-This container is designed to work with the Cua Docker provider. Simply specify the xfce image:
-
-```python
-from computer import Computer
-
-# Create computer with xfce container
-computer = Computer(
- os_type="linux",
- provider_type="docker",
- image="trycua/cua-xfce:latest", # Use xfce instead of Kasm
- display="1024x768",
- memory="4GB",
- cpu="2"
-)
-
-# Use the computer
-async with computer:
- # Take a screenshot
- screenshot = await computer.interface.screenshot()
-
- # Click and type
- await computer.interface.left_click(100, 100)
- await computer.interface.type_text("Hello from Cua!")
-
- # Run commands
- result = await computer.interface.run_command("ls -la")
- print(result.stdout)
-```
-
-### Switching between Kasm and xfce
-
-The Docker provider automatically detects which image you're using:
-
-```python
-# Use Kasm-based container (default for Linux)
-computer_kasm = Computer(
- os_type="linux",
- provider_type="docker",
- image="trycua/cua-ubuntu:latest", # Kasm image
-)
-
-# Use xfce container (vanilla XFCE)
-computer_xfce = Computer(
- os_type="linux",
- provider_type="docker",
- image="trycua/cua-xfce:latest", # xfce image
-)
-```
-
-Both provide the same API and functionality - the provider automatically configures the correct paths and settings based on the image.
-
-## Environment Variables
-
-| Variable | Default | Description |
-| ---------------- | ---------- | ------------------------ |
-| `VNC_RESOLUTION` | `1024x768` | Screen resolution |
-| `VNC_COL_DEPTH` | `24` | Color depth |
-| `VNC_PORT` | `5901` | VNC server port |
-| `NOVNC_PORT` | `6901` | noVNC web interface port |
-| `API_PORT` | `8000` | Computer-server API port |
-| `DISPLAY` | `:1` | X11 display number |
-
-## Exposed Ports
-
-- **5901**: TigerVNC server
-- **6901**: noVNC web interface
-- **8000**: Computer-server WebSocket API
-
-## Volume Mount Points
-
-- `/home/cua/storage`: Persistent storage mount point
-- `/home/cua/shared`: Shared folder mount point
-
-## User Credentials
-
-- **Username**: `cua`
-- **Password**: `password` (for shell login only)
-- **Sudo access**: Enabled without password
-- **VNC access**: No password required
-
-## Creating Snapshots
-
-### Filesystem Snapshot
-
-```bash
-docker commit <container_id> cua-xfce-snapshot:latest
-```
-
-### Running from Snapshot
-
-```bash
-docker run --rm -it \
- --shm-size=512m \
- -p 6901:6901 \
- -p 8000:8000 \
- cua-xfce-snapshot:latest
-```
-
-## Comparison with Kasm Container
-
-| Feature | Kasm Container | Docker XFCE Container |
-| ------------- | --------------- | --------------------- |
-| Base Image | KasmWeb Ubuntu | Vanilla Ubuntu |
-| VNC Server | KasmVNC | TigerVNC |
-| Dependencies | Higher | Lower |
-| Configuration | Pre-configured | Minimal |
-| Size | Larger | Smaller |
-| Maintenance | Depends on Kasm | Independent |
-
-## Process Management
-
-The container uses `supervisord` to manage three main processes:
-
-1. **VNC Server** (Priority 10): TigerVNC with XFCE desktop
-2. **noVNC** (Priority 20): WebSocket proxy for browser access
-3. **Computer Server** (Priority 30): Cua automation API
-
-All processes are automatically restarted on failure.
-
-## Troubleshooting
-
-### VNC server won't start
-
-Check if X11 lock files exist:
-
-```bash
-docker exec <container_id> rm -rf /tmp/.X1-lock /tmp/.X11-unix/X1
-```
-
-### noVNC shows black screen
-
-Ensure VNC server is running:
-
-```bash
-docker exec <container_id> supervisorctl status vncserver
-```
-
-### Computer-server not responding
-
-Check if X server is accessible:
-
-```bash
-docker exec <container_id> env DISPLAY=:1 xdpyinfo
-```
-
-### View logs
-
-```bash
-docker exec <container_id> tail -f /var/log/supervisor/supervisord.log
-docker exec <container_id> supervisorctl status
-```
-
-## Integration with Cua System
-
-This container provides the same functionality as the Kasm container but with:
-
-- **Reduced dependencies**: No reliance on KasmWeb infrastructure
-- **Smaller image size**: Minimal base configuration
-- **Full control**: Direct access to all components
-- **Easy customization**: Simple to modify and extend
-
-The container integrates seamlessly with:
-
-- Cua Computer library (via WebSocket API)
-- Docker provider for lifecycle management
-- Standard VNC clients for debugging
-- Web browsers for visual monitoring
-
-## License
-
-MIT License - See LICENSE file for details
+**[Documentation](https://cua.ai/docs/cua/reference/desktop-sandbox/linux-container/xfce)** - Setup and configuration.