Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
Replace text in READMEs with links to Cua documentations
James Murdzad2500a2c47be
diff --git a/libs/lume/docs/Development.md b/libs/lume/Development.mdsimilarity index 76%rename from libs/lume/docs/Development.mdrename to libs/lume/Development.mdindex cbaa4df573..0ddf8c5e33 100644--- a/libs/lume/docs/Development.md+++ b/libs/lume/Development.md@@ -10,6 +10,14 @@ Lume development requires:- macOS Sequoia 15.2 or higher- (Optional) VS Code with Swift extension+If you're working on Lume in the context of the Cua monorepo, we recommend using the dedicated VS Code workspace configuration:++```bash+# Open VS Code workspace from the root of the monorepo+code .vscode/lume.code-workspace+```+This workspace is preconfigured with Swift language support, build tasks, and debug configurations.+## Setting Up the Repository Locally1. **Fork the Repository**: Create your own fork of lumediff --git a/libs/lume/README.md b/libs/lume/README.mdindex ac4257e0f2..c90c250a76 100644--- a/libs/lume/README.md+++ b/libs/lume/README.md@@ -23,174 +23,42 @@<img src="../../img/cli.png" alt="lume cli"></div>-```bashlume run macos-sequoia-vanilla:latest```-## Development Environment+## Quickstart-If you're working on Lume in the context of the CUA monorepo, we recommend using the dedicated VS Code workspace configuration:--```bash-# Open VS Code workspace from the root of the monorepo-code .vscode/lume.code-workspace-```-This workspace is preconfigured with Swift language support, build tasks, and debug configurations.--## Usage--```bash-lume <command>--Commands:- lume create <name> Create a new macOS or Linux VM- lume run <name> Run a VM- lume ls List all VMs- lume get <name> Get detailed information about a VM- lume set <name> Modify VM configuration- lume stop <name> Stop a running VM- lume delete <name> Delete a VM- lume pull <image> Pull a macOS image from container registry- lume push <name> <image:tag> Push a VM image to a container registry- lume clone <name> <new-name> Clone an existing VM- lume config Get or set lume configuration- lume images List available macOS images in local cache- lume ipsw Get the latest macOS restore image URL- lume prune Remove cached images- lume serve Start the API server--Options:- --help Show help [boolean]- --version Show version number [boolean]--Command Options:- create:- --os <os> Operating system to install (macOS or linux, default: macOS)- --cpu <cores> Number of CPU cores (default: 4)- --memory <size> Memory size, e.g., 8GB (default: 4GB)- --disk-size <size> Disk size, e.g., 50GB (default: 40GB)- --display <res> Display resolution (default: 1024x768)- --ipsw <path> Path to IPSW file or 'latest' for macOS VMs- --storage <name> VM storage location to use-- run:- --no-display Do not start the VNC client app- --shared-dir <dir> Share directory with VM (format: path[:ro|rw])- --mount <path> For Linux VMs only, attach a read-only disk image- --registry <url> Container registry URL (default: ghcr.io)- --organization <org> Organization to pull from (default: trycua)- --vnc-port <port> Port to use for the VNC server (default: 0 for auto-assign)- --recovery-mode <boolean> For MacOS VMs only, start VM in recovery mode (default: false)- --storage <name> VM storage location to use-- set:- --cpu <cores> New number of CPU cores (e.g., 4)- --memory <size> New memory size (e.g., 8192MB or 8GB)- --disk-size <size> New disk size (e.g., 40960MB or 40GB)- --display <res> New display resolution in format WIDTHxHEIGHT (e.g., 1024x768)- --storage <name> VM storage location to use-- delete:- --force Force deletion without confirmation- --storage <name> VM storage location to use-- pull:- --registry <url> Container registry URL (default: ghcr.io)- --organization <org> Organization to pull from (default: trycua)- --storage <name> VM storage location to use-- push:- --additional-tags <tags...> Additional tags to push the same image to- --registry <url> Container registry URL (default: ghcr.io)- --organization <org> Organization/user to push to (default: trycua)- --storage <name> VM storage location to use- --chunk-size-mb <size> Chunk size for disk image upload in MB (default: 512)- --verbose Enable verbose logging- --dry-run Prepare files and show plan without uploading- --reassemble Verify integrity by reassembling chunks (requires --dry-run)-- get:- -f, --format <format> Output format (json|text)- --storage <name> VM storage location to use-- stop:- --storage <name> VM storage location to use-- clone:- --source-storage <name> Source VM storage location- --dest-storage <name> Destination VM storage location-- config:- get Get current configuration- storage Manage VM storage locations- add <name> <path> Add a new VM storage location- remove <name> Remove a VM storage location- list List all VM storage locations- default <name> Set the default VM storage location- cache Manage cache settings- get Get current cache directory- set <path> Set cache directory- caching Manage image caching settings- get Show current caching status- set <boolean> Enable or disable image caching-- serve:- --port <port> Port to listen on (default: 7777)-```--## Install--Install with a single command:+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```-By default, Lume is installed as a background service that starts automatically on login. If you prefer to start the Lume API service manually when needed, you can use the `--no-background-service` option:--```bash-/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh) --no-background-service"-```--**Note:** With this option, you'll need to manually start the Lume API service by running `lume serve` in your terminal whenever you need to use tools or libraries that rely on the Lume API (such as the Computer-Use Agent).--You can also download the `lume.pkg.tar.gz` archive from the [latest release](https://github.com/trycua/lume/releases), extract it, and install the package manually.--## Prebuilt Images--Pre-built images are available in the registry [ghcr.io/trycua](https://github.com/orgs/trycua/packages).--**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**. The last version of `lume` fully supporting the non-sparse images was `v0.1.x`. Starting from `v0.2.0`, lume will automatically pull images optimized with sparse file system support.+<Callout title="Security Note">+All prebuilt images use the default password `lume`. Change this immediately after your first login using the `passwd` command.+</Callout>-These images come with an SSH server pre-configured and auto-login enabled.+**System Requirements**:+- Apple Silicon Mac (M1, M2, M3, etc.)+- macOS 13.0 or later+- At least 8GB of RAM (16GB recommended)+- At least 50GB of free disk space-For the security of your VM, change the default password `lume` immediately after your first login.--| 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 |--For additional disk space, resize the VM disk after pulling the image using the `lume set <name> --disk-size <size>` command. Note that the actual disk space used by sparse images will be much lower than the logical size listed.--## Local API Server--`lume` exposes a local HTTP API server that listens on `http://localhost:7777/lume`, enabling automated management of VMs.--```bash-lume serve-```+## Development-For detailed API documentation, please refer to [API Reference](docs/API-Reference.md).+To get set up with Lume for development, read [these instructions](Development.md).## Docs-- [API Reference](docs/API-Reference.md)-- [Development](docs/Development.md)-- [FAQ](docs/FAQ.md)+- [Installation](https://trycua.com/docs/libraries/lume/installation)+- [Prebuilt Images](https://trycua.com/docs/libraries/lume/prebuilt-images)+- [CLI Reference](https://trycua.com/docs/libraries/lume/cli-reference)+- [HTTP API](https://trycua.com/docs/libraries/lume/http-api)+- [FAQ](https://trycua.com/docs/libraries/lume/faq)## Contributingdiff --git a/libs/lume/docs/API-Reference.md b/libs/lume/docs/API-Reference.mddeleted file mode 100644index 5af09cdf29..0000000000--- a/libs/lume/docs/API-Reference.md+++ /dev/null@@ -1,387 +0,0 @@-## API Reference--<details open>-<summary><strong>Create VM</strong> - POST /vms</summary>--```bash-curl --connect-timeout 6000 \- --max-time 5000 \- -X POST \- -H "Content-Type: application/json" \- -d '{- "name": "lume_vm",- "os": "macOS",- "cpu": 2,- "memory": "4GB",- "diskSize": "64GB",- "display": "1024x768",- "ipsw": "latest",- "storage": "ssd"- }' \- http://localhost:7777/lume/vms-```-</details>--<details open>-<summary><strong>Run VM</strong> - POST /vms/:name/run</summary>--```bash-# Basic run-curl --connect-timeout 6000 \- --max-time 5000 \- -X POST \- http://localhost:7777/lume/vms/my-vm-name/run--# Run with VNC client started and shared directory-curl --connect-timeout 6000 \- --max-time 5000 \- -X POST \- -H "Content-Type: application/json" \- -d '{- "noDisplay": false,- "sharedDirectories": [- {- "hostPath": "~/Projects",- "readOnly": false- }- ],- "recoveryMode": false,- "storage": "ssd"- }' \- http://localhost:7777/lume/vms/lume_vm/run-```-</details>--<details open>-<summary><strong>List VMs</strong> - GET /vms</summary>--```bash-curl --connect-timeout 6000 \- --max-time 5000 \- http://localhost:7777/lume/vms-```-```-[- {- "name": "my-vm",- "state": "stopped",- "os": "macOS",- "cpu": 2,- "memory": "4GB",- "diskSize": "64GB"- },- {- "name": "my-vm-2",- "state": "stopped",- "os": "linux",- "cpu": 2,- "memory": "4GB",- "diskSize": "64GB"- }-]-```-</details>--<details open>-<summary><strong>Get VM Details</strong> - GET /vms/:name</summary>--```bash-# Basic get-curl --connect-timeout 6000 \- --max-time 5000 \- http://localhost:7777/lume/vms/lume_vm--# Get with storage location specified-curl --connect-timeout 6000 \- --max-time 5000 \- http://localhost:7777/lume/vms/lume_vm?storage=ssd-```-```-{- "name": "lume_vm",- "state": "running",- "os": "macOS",- "cpu": 2,- "memory": "4GB",- "diskSize": "64GB"-}-```-</details>--<details open>-<summary><strong>Update VM Settings</strong> - PATCH /vms/:name</summary>--```bash-curl --connect-timeout 6000 \- --max-time 5000 \- -X PATCH \- -H "Content-Type: application/json" \- -d '{- "cpu": 4,- "memory": "8GB",- "diskSize": "128GB",- "storage": "ssd"- }' \- http://localhost:7777/lume/vms/my-vm-name-```-</details>--<details open>-<summary><strong>Stop VM</strong> - POST /vms/:name/stop</summary>--```bash-# Basic stop-curl --connect-timeout 6000 \- --max-time 5000 \- -X POST \- http://localhost:7777/lume/vms/my-vm-name/stop--# Stop with storage location specified-curl --connect-timeout 6000 \- --max-time 5000 \- -X POST \- http://localhost:7777/lume/vms/my-vm-name/stop?storage=ssd-```-</details>--<details open>-<summary><strong>Delete VM</strong> - DELETE /vms/:name</summary>--```bash-# Basic delete-curl --connect-timeout 6000 \- --max-time 5000 \- -X DELETE \- http://localhost:7777/lume/vms/my-vm-name--# Delete with storage location specified-curl --connect-timeout 6000 \- --max-time 5000 \- -X DELETE \- http://localhost:7777/lume/vms/my-vm-name?storage=ssd-```-</details>--<details open>-<summary><strong>Pull Image</strong> - POST /pull</summary>--```bash-curl --connect-timeout 6000 \- --max-time 5000 \- -X POST \- -H "Content-Type: application/json" \- -d '{- "image": "macos-sequoia-vanilla:latest",- "name": "my-vm-name",- "registry": "ghcr.io",- "organization": "trycua",- "storage": "ssd"- }' \- http://localhost:7777/lume/pull-```--```bash-curl --connect-timeout 6000 \- --max-time 5000 \- -X POST \- -H "Content-Type: application/json" \- -d '{- "image": "macos-sequoia-vanilla:15.2",- "name": "macos-sequoia-vanilla"- }' \- http://localhost:7777/lume/pull-```-</details>--<details open>-<summary><strong>Push Image (Async)</strong> - POST /vms/push</summary>--```bash-# Push VM 'my-local-vm' to 'my-org/my-image:latest' and 'my-org/my-image:v1'-curl --connect-timeout 6000 \- --max-time 5000 \- -X POST \- -H "Content-Type: application/json" \- -d '{- "name": "my-local-vm",- "imageName": "my-image",- "tags": ["latest", "v1"],- "organization": "my-org",- "registry": "ghcr.io",- "chunkSizeMb": 512,- "storage": null- }' \- http://localhost:7777/lume/vms/push-```--**Response (202 Accepted):**--```json-{- "message": "Push initiated in background",- "name": "my-local-vm",- "imageName": "my-image",- "tags": [- "latest",- "v1"- ]-}-```-</details>--<details open>-<summary><strong>Clone VM</strong> - POST /vms/:name/clone</summary>--```bash-curl --connect-timeout 6000 \- --max-time 5000 \- -X POST \- -H "Content-Type: application/json" \- -d '{- "name": "source-vm",- "newName": "cloned-vm",- "sourceLocation": "default",- "destLocation": "ssd"- }' \- http://localhost:7777/lume/vms/clone-```-</details>--<details open>-<summary><strong>Get Latest IPSW URL</strong> - GET /ipsw</summary>--```bash-curl --connect-timeout 6000 \- --max-time 5000 \- http://localhost:7777/lume/ipsw-```-</details>--<details open>-<summary><strong>List Images</strong> - GET /images</summary>--```bash-# List images with default organization (trycua)-curl --connect-timeout 6000 \- --max-time 5000 \- http://localhost:7777/lume/images-```--```json-{- "local": [- "macos-sequoia-xcode:latest",- "macos-sequoia-vanilla:latest"- ]-}-```-</details>--<details open>-<summary><strong>Prune Images</strong> - POST /lume/prune</summary>--```bash-curl --connect-timeout 6000 \- --max-time 5000 \- -X POST \- http://localhost:7777/lume/prune-```-</details>--<details open>-<summary><strong>Get Configuration</strong> - GET /lume/config</summary>--```bash-curl --connect-timeout 6000 \- --max-time 5000 \- http://localhost:7777/lume/config-```--```json-{- "homeDirectory": "~/.lume",- "cacheDirectory": "~/.lume/cache",- "cachingEnabled": true-}-```-</details>--<details open>-<summary><strong>Update Configuration</strong> - POST /lume/config</summary>--```bash-curl --connect-timeout 6000 \- --max-time 5000 \- -X POST \- -H "Content-Type: application/json" \- -d '{- "homeDirectory": "~/custom/lume",- "cacheDirectory": "~/custom/lume/cache",- "cachingEnabled": true- }' \- http://localhost:7777/lume/config-```-</details>--<details open>-<summary><strong>Get VM Storage Locations</strong> - GET /lume/config/locations</summary>--```bash-curl --connect-timeout 6000 \- --max-time 5000 \- http://localhost:7777/lume/config/locations-```--```json-[- {- "name": "default",- "path": "~/.lume/vms",- "isDefault": true- },- {- "name": "ssd",- "path": "/Volumes/SSD/lume/vms",- "isDefault": false- }-]-```-</details>--<details open>-<summary><strong>Add VM Storage Location</strong> - POST /lume/config/locations</summary>--```bash-curl --connect-timeout 6000 \- --max-time 5000 \- -X POST \- -H "Content-Type: application/json" \- -d '{- "name": "ssd",- "path": "/Volumes/SSD/lume/vms"- }' \- http://localhost:7777/lume/config/locations-```-</details>--<details open>-<summary><strong>Remove VM Storage Location</strong> - DELETE /lume/config/locations/:name</summary>--```bash-curl --connect-timeout 6000 \- --max-time 5000 \- -X DELETE \- http://localhost:7777/lume/config/locations/ssd-```-</details>--<details open>-<summary><strong>Set Default VM Storage Location</strong> - POST /lume/config/locations/default/:name</summary>--```bash-curl --connect-timeout 6000 \- --max-time 5000 \- -X POST \- http://localhost:7777/lume/config/locations/default/ssd-```-</details>diff --git a/libs/lume/docs/FAQ.md b/libs/lume/docs/FAQ.mddeleted file mode 100644index 21d0d287e9..0000000000--- a/libs/lume/docs/FAQ.md+++ /dev/null@@ -1,114 +0,0 @@-# FAQs--### Where are the VMs stored?--VMs are stored in `~/.lume` by default. You can configure additional storage locations using the `lume config` command.--### How are images cached?--Images are cached in `~/.lume/cache`. When doing `lume pull <image>`, it will check if the image is already cached. If not, it will download the image and cache it, removing any older versions.--### Where is the configuration file stored?--Lume follows the XDG Base Directory specification for the configuration file:--- Configuration is stored in `$XDG_CONFIG_HOME/lume/config.yaml` (defaults to `~/.config/lume/config.yaml`)--By default, other data is stored in:-- VM data: `~/.lume`-- Cache files: `~/.lume/cache`--The config file contains settings for:-- VM storage locations and the default location-- Cache directory location-- Whether caching is enabled--You can view and modify these settings using the `lume config` commands:--```bash-# View current configuration-lume config get--# Manage VM storage locations-lume config storage list # List all VM storage locations-lume config storage add <name> <path> # Add a new VM storage location-lume config storage remove <name> # Remove a VM storage location-lume config storage default <name> # Set the default VM storage location--# Manage cache settings-lume config cache get # Get current cache directory-lume config cache set <path> # Set cache directory--# Manage image caching settings-lume config caching get # Show current caching status-lume config caching set <boolean> # Enable or disable image caching-```--### How do I use multiple VM storage locations?--Lume supports storing VMs in different locations (e.g., internal drive, external SSD). After configuring storage locations, you can specify which location to use with the `--storage` parameter in various commands:--```bash-# Create a VM in a specific storage location-lume create my-vm --os macos --ipsw latest --storage ssd--# Run a VM from a specific storage location-lume run my-vm --storage ssd--# Delete a VM from a specific storage location-lume delete my-vm --storage ssd--# Pull an image to a specific storage location-lume pull macos-sequoia-vanilla:latest --name my-vm --storage ssd--# Clone a VM between storage locations-lume clone source-vm cloned-vm --source-storage default --dest-storage ssd-```--If you don't specify a storage location, Lume will use the default one or search across all configured locations.--### Are VM disks taking up all the disk space?--No, macOS uses sparse files, which only allocate space as needed. For example, VM disks totaling 50 GB may only use 20 GB on disk.--### How do I get the latest macOS restore image URL?--```bash-lume ipsw-```--### How do I delete a VM?--```bash-lume delete <name>-```--### How to Install macOS from an IPSW Image--#### Create a new macOS VM using the latest supported IPSW image:-Run the following command to create a new macOS virtual machine using the latest available IPSW image:--```bash-lume create <name> --os macos --ipsw latest-```--#### Create a new macOS VM using a specific IPSW image:-To create a macOS virtual machine from an older or specific IPSW file, first download the desired IPSW (UniversalMac) from a trusted source.--Then, use the downloaded IPSW path:--```bash-lume create <name> --os macos --ipsw <downloaded_ipsw_path>-```--### How do I install a custom Linux image?--The process for creating a custom Linux image differs than macOS, with IPSW restore files not being used. You need to create a linux VM first, then mount a setup image file to the VM for the first boot.--```bash-lume create <name> --os linux--lume run <name> --mount <path-to-setup-image>--lume run <name>-```