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.

Replace text in READMEs with links to Cua documentations

James Murdzad2500a2c47be
diff --git a/libs/lume/docs/Development.md b/libs/lume/Development.md
similarity index 76%
rename from libs/lume/docs/Development.md
rename to libs/lume/Development.md
index 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 Locally
1. **Fork the Repository**: Create your own fork of lume
diff --git a/libs/lume/README.md b/libs/lume/README.md
index 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>
-
```bash
lume 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)
## Contributing
diff --git a/libs/lume/docs/API-Reference.md b/libs/lume/docs/API-Reference.md
deleted file mode 100644
index 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.md
deleted file mode 100644
index 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>
-```