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
docs(lume): add Tahoe tutorial and how-to guides
Francesco Bonaccic05ef5f26315
diff --git a/README.md b/README.mdindex 09c2158a37..2cc2bbd911 100644--- a/README.md+++ b/README.md@@ -144,9 +144,9 @@ Create and manage macOS/Linux VMs with near-native performance on Apple Silicon/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"# Create and start a vanilla macOS VM from an Apple restore image-curl -L "$(lume ipsw | tail -n 1)" -o ~/Downloads/macos.ipsw-lume create macos-sequoia --ipsw ~/Downloads/macos.ipsw --unattended sequoia-lume run macos-sequoia+curl -L "$(lume ipsw | tail -n 1)" -o ~/Downloads/macos-tahoe.ipsw+lume create macos-tahoe --ipsw ~/Downloads/macos-tahoe.ipsw --unattended tahoe+lume run macos-tahoe```The `--unattended` option prepares the installed guest offline. The built-indiff --git a/docs/content/docs/concepts/how-lume-unattended-setup-works.mdx b/docs/content/docs/concepts/how-lume-unattended-setup-works.mdxnew file mode 100644index 0000000000..51ad10ac6b--- /dev/null+++ b/docs/content/docs/concepts/how-lume-unattended-setup-works.mdx@@ -0,0 +1,47 @@+---+title: How Lume prepares vanilla macOS VMs+description: Understand the offline setup flow behind Lume's unattended macOS VMs.+---++Lume creates vanilla macOS VMs from Apple restore images. The unattended setup+prepares the installed guest on disk, so the workflow does not depend on GUI+clicks or a particular Setup Assistant layout.++## The setup sequence++When you run `lume create` with `--unattended tahoe` or `--unattended sequoia`,+Lume:++1. Installs macOS from the IPSW into a new VM disk.+2. Boots the VM once so macOS materializes its first-boot state.+3. Stops the VM and mounts its Data volume on the host.+4. Patches the guest account and login configuration offline.+5. Enables SSH, autologin, and the no-sleep settings.+6. Boots the VM again and verifies SSH before finalizing creation.++The default account is `lume` with the initial password `lume`. Change that+password before using the VM for sensitive work.++## Why the setup is offline++GUI automation depends on display timing, window state, and the controls that a+particular macOS release exposes. Disk setup writes the desired guest state+directly and keeps the verification step small: Lume checks that the guest+boots and accepts SSH.++## Presets and images++The `tahoe` and `sequoia` presets use the same offline patcher. Tahoe is the+verified preset for the current vanilla workflow. Sequoia can still show the+Accessibility step of Setup Assistant on its first display boot; see [issue+#2155](https://github.com/trycua/cua/issues/2155).++The IPSW flow creates a fresh vanilla guest each time. Registry snapshots remain+available for workflows that need a previously prepared disk, but they are not+required for unattended setup.++## Related pages++- [Create your first local macOS VM](/tutorials/create-your-first-lume-vm)+- [Create a vanilla Tahoe VM](/how-to-guides/lume/create-vanilla-vm)+- [Lume CLI reference](/reference/lume/cli-reference)diff --git a/docs/content/docs/concepts/index.mdx b/docs/content/docs/concepts/index.mdxindex f298e56070..44cf494eff 100644--- a/docs/content/docs/concepts/index.mdx+++ b/docs/content/docs/concepts/index.mdx@@ -5,4 +5,4 @@ description: "Understand the design ideas behind Cua and how its main pieces fitUse these pages when you want the model behind Cua rather than a step-by-step guide or API table. They explain what computer use means in Cua, how Cua Driver keeps the desktop usable while it acts, and how Cua Sandbox gives an agent a disposable computer.-Start with [What is computer use?](/concepts/what-is-computer-use) for the basic model. Read [Best-effort background](/concepts/the-no-foreground-contract) to understand Cua Driver's default behavior on a shared machine, then [Capture and delivery modalities](/concepts/capture-and-delivery-modalities) for the action axes. Read [How sandboxes work](/concepts/how-sandboxes-work) when you need the model for disposable computers.+Start with [What is computer use?](/concepts/what-is-computer-use) for the basic model. Read [Best-effort background](/concepts/the-no-foreground-contract) to understand Cua Driver's default behavior on a shared machine, then [Capture and delivery modalities](/concepts/capture-and-delivery-modalities) for the action axes. Read [How sandboxes work](/concepts/how-sandboxes-work) when you need the model for disposable computers. Read [How Lume prepares vanilla macOS VMs](/concepts/how-lume-unattended-setup-works) when you need the local VM setup model.diff --git a/docs/content/docs/concepts/meta.json b/docs/content/docs/concepts/meta.jsonindex ba09bd3452..f4113c0ce2 100644--- a/docs/content/docs/concepts/meta.json+++ b/docs/content/docs/concepts/meta.json@@ -1 +1 @@-{ "title": "Concepts", "icon": "Lightbulb", "pages": ["index", "what-is-computer-use", "the-no-foreground-contract", "capture-and-delivery-modalities", "how-sandboxes-work"] }+{ "title": "Concepts", "icon": "Lightbulb", "pages": ["index", "what-is-computer-use", "the-no-foreground-contract", "capture-and-delivery-modalities", "how-sandboxes-work", "how-lume-unattended-setup-works"] }diff --git a/docs/content/docs/how-to-guides/lume/create-vanilla-vm.mdx b/docs/content/docs/how-to-guides/lume/create-vanilla-vm.mdxnew file mode 100644index 0000000000..9093d200af--- /dev/null+++ b/docs/content/docs/how-to-guides/lume/create-vanilla-vm.mdx@@ -0,0 +1,68 @@+---+title: Create a vanilla Tahoe VM+description: Create and manage a vanilla macOS Tahoe VM from a local Apple restore image.+---++Use this guide when you already have Lume installed and need a repeatable local+Tahoe VM. The offline unattended setup does not drive Setup Assistant through+the display.++## Download an IPSW++Use the latest supported Apple restore image, or provide an IPSW you already+downloaded:++```bash+IPSW_URL="$(lume ipsw | tail -n 1)"+curl -L "$IPSW_URL" -o ~/Downloads/macos-tahoe.ipsw+```++## Create the VM++```bash+lume create macos-tahoe \+ --ipsw ~/Downloads/macos-tahoe.ipsw \+ --unattended tahoe+```++The `tahoe` preset creates the `lume` user, enables SSH, configures autologin,+and disables sleep and screen locking. The default credentials are+`lume` / `lume`.++## Run and inspect it++```bash+lume run macos-tahoe+lume ls+lume ssh macos-tahoe 'sw_vers; id -un'+```++Use `lume run` with no `--no-display` flag when you want the VNC display. Use+`lume run --no-display macos-tahoe` for a headless boot.++## Stop or remove it++```bash+lume stop macos-tahoe+lume delete macos-tahoe+```++Deletion removes the VM disk and its configuration. Clone the VM first if you+need a reusable copy:++```bash+lume clone macos-tahoe macos-tahoe-backup+```++## Troubleshoot common failures++Run Lume as the same user that owns its VM directory. `sudo lume` uses a+different home directory and cannot see VMs created under your account.++If Lume reports that auxiliary storage is locked, another `lume run` process is+still using the VM. Stop that process or run `lume stop macos-tahoe` before+starting it again.++Tahoe is the verified unattended preset. Sequoia may still show the+Accessibility step of Setup Assistant on its first display boot; track that+behavior in [issue #2155](https://github.com/trycua/cua/issues/2155).diff --git a/docs/content/docs/how-to-guides/lume/install-lume.mdx b/docs/content/docs/how-to-guides/lume/install-lume.mdxindex 02f37f93ab..585a259e23 100644--- a/docs/content/docs/how-to-guides/lume/install-lume.mdx+++ b/docs/content/docs/how-to-guides/lume/install-lume.mdx@@ -3,8 +3,6 @@ title: Install and run Lumedescription: Install Lume, Cua's local Apple Silicon VM manager for macOS and Linux guests.----import { Callout } from 'fumadocs-ui/components/callout';-Lume is Cua's local VM manager for Apple Silicon Macs. Use it when you want to create, run, or serve macOS and Linux VMs on your own machine. It can provide local VM substrate for Cua workflows, but the primary product choice is still [Cua Driver](/tutorials/drive-your-first-app) for an existing machine or [Cua Sandbox](/tutorials/your-first-cloud-sandbox) for a fresh isolated desktop.## Requirements@@ -45,61 +43,14 @@ lume update --applyThe installer no longer creates scheduled auto-updaters. Older `lume-update` cron jobs andLaunchAgents are removed the next time the installer runs.-## Create a vanilla macOS VM--Download the latest supported Apple restore image, then let Lume prepare the VM-offline. This skips Setup Assistant, creates the `lume` user, enables SSH and-autologin, and disables screen-lock sleep settings:--```bash-IPSW_URL="$(lume ipsw | tail -n 1)"-curl -L "$IPSW_URL" -o ~/Downloads/macos.ipsw-lume create macos-sequoia --ipsw ~/Downloads/macos.ipsw --unattended sequoia-lume run macos-sequoia-```--The built-in `sequoia` and `tahoe` presets create the `lume` user, enable SSH,-configure autologin, and disable sleep and screen locking without GUI-automation. The default SSH credentials are `lume` / `lume`.--The Tahoe flow is E2E verified from a local IPSW. Sequoia can still present-the Accessibility step of Setup Assistant on its first display boot; see-[issue #2155](https://github.com/trycua/cua/issues/2155).--<Callout title="Security Note">- The unattended VM uses `lume`/`lume` for initial SSH and login access. Change- the password immediately with the `passwd` command.-</Callout>--## Use a registry image--Lume can also pull and run prebuilt or custom VM snapshots from an OCI-compatible-registry. Registry images are optional; they are useful when you need a prepared-snapshot or want to share a customized VM.--```bash-lume pull <image>:<tag>-lume run <image>:<tag>-```--## Start the API service manually--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"-```--<Callout title="Note">- With this option, you'll need to manually start the Lume API service by running `lume serve` in- your terminal whenever you need tools or libraries that rely on the local Lume HTTP API.-</Callout>--## Manual download+## Manual installationYou can also download the `lume.pkg.tar.gz` archive from the [latest release](https://github.com/trycua/cua/releases?q=lume&expanded=true), extract it, and install the package manually.## Next steps+- [Create your first local VM](/tutorials/create-your-first-lume-vm): follow the Tahoe happy path from IPSW to SSH.+- [Create a vanilla Tahoe VM](/how-to-guides/lume/create-vanilla-vm): create, run, inspect, and remove a local VM.+- [Serve the Lume API](/how-to-guides/lume/serve-api): run the local HTTP API for tools and scripts.- [Lume CLI reference](/reference/lume/cli-reference): inspect every command and option.- [Lume HTTP API reference](/reference/lume/http-api): use the local API from tools and scripts.diff --git a/docs/content/docs/how-to-guides/lume/meta.json b/docs/content/docs/how-to-guides/lume/meta.jsonindex b060387bc5..8e35138cd6 100644--- a/docs/content/docs/how-to-guides/lume/meta.json+++ b/docs/content/docs/how-to-guides/lume/meta.json@@ -1 +1 @@-{ "title": "Lume", "pages": ["install-lume"] }+{ "title": "Lume", "pages": ["install-lume", "create-vanilla-vm", "serve-api"] }diff --git a/docs/content/docs/how-to-guides/lume/serve-api.mdx b/docs/content/docs/how-to-guides/lume/serve-api.mdxnew file mode 100644index 0000000000..b5951c9cc3--- /dev/null+++ b/docs/content/docs/how-to-guides/lume/serve-api.mdx@@ -0,0 +1,46 @@+---+title: Serve the Lume API+description: Run Lume's local HTTP API for tools and scripts.+---++Use the Lume API when another local process needs to list, create, run, or stop+VMs through HTTP.++## Start the server++Start the API on its default port:++```bash+lume serve+```++To use another port:++```bash+lume serve --port 7778+```++The API listens on `localhost`. Keep the server bound to the local host unless+you have a specific network boundary and authentication plan for exposing it.++## Check the server++List the local VMs:++```bash+curl http://localhost:7777/lume/vms+```++Use the [HTTP API reference](/reference/lume/http-api) for request bodies,+responses, and the complete endpoint list.++## Run it at login++The standard installer starts Lume's background service at login. Install with+`--no-background-service` when you want to manage the API process yourself:++```bash+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh) --no-background-service"+```++After that installation, start the server explicitly with `lume serve`.diff --git a/docs/content/docs/reference/lume/cli-reference.mdx b/docs/content/docs/reference/lume/cli-reference.mdxindex 3e29f958bf..7dc759e7ec 100644--- a/docs/content/docs/reference/lume/cli-reference.mdx+++ b/docs/content/docs/reference/lume/cli-reference.mdx@@ -7,12 +7,12 @@ description: Command Line Interface reference for LumeAUTO-GENERATED FILE - DO NOT EDIT DIRECTLYGenerated by: npx tsx scripts/docs-generators/lume.tsSource: lume dump-docs --type cli- Version: 0.3.11+ Version: 0.3.12*/}A lightweight CLI and local API server to build, run and manage macOS VMs.-Documented against Lume **0.3.11**. Run `lume --version` for your installed version.+Documented against Lume **0.3.12**. Run `lume --version` for your installed version.For installation steps, see [Install Lume](/how-to-guides/lume/install-lume).diff --git a/docs/content/docs/reference/lume/http-api.mdx b/docs/content/docs/reference/lume/http-api.mdxindex a886e00267..dd0cf76151 100644--- a/docs/content/docs/reference/lume/http-api.mdx+++ b/docs/content/docs/reference/lume/http-api.mdx@@ -7,14 +7,14 @@ description: HTTP API reference for Lume serverAUTO-GENERATED FILE - DO NOT EDIT DIRECTLYGenerated by: npx tsx scripts/docs-generators/lume.tsSource: lume dump-docs --type api- Version: 0.3.11+ Version: 0.3.12*/}import { Tabs, Tab } from 'fumadocs-ui/components/tabs';HTTP API for managing macOS and Linux virtual machines-Documented against Lume **0.3.11**. Run `lume --version` for your installed version.+Documented against Lume **0.3.12**. Run `lume --version` for your installed version.## Default URLdiff --git a/docs/content/docs/tutorials/create-your-first-lume-vm.mdx b/docs/content/docs/tutorials/create-your-first-lume-vm.mdxnew file mode 100644index 0000000000..c02b501bea--- /dev/null+++ b/docs/content/docs/tutorials/create-your-first-lume-vm.mdx@@ -0,0 +1,75 @@+---+title: Create your first local macOS VM with Lume+description: Install Lume and create a vanilla macOS Tahoe VM from an Apple restore image.+---++This tutorial walks through one complete local VM setup on an Apple Silicon Mac.+You will install Lume, download a Tahoe restore image, create a vanilla VM, and+connect to it over SSH.++## Before you start++You need an Apple Silicon Mac with macOS 13 or later, 8GB of available memory,+and at least 50GB of free disk space. The restore image requires additional+download and VM disk space.++## Install Lume++Run the installer:++```bash+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"+```++Check the installed version:++```bash+lume --version+```++## Download the Tahoe restore image++Ask Lume for the latest supported restore image URL and download it locally:++```bash+IPSW_URL="$(lume ipsw | tail -n 1)"+curl -L "$IPSW_URL" -o ~/Downloads/macos-tahoe.ipsw+```++## Create the VM++The Tahoe preset prepares the installed guest offline. It creates the `lume`+user, enables SSH, configures autologin, and disables sleep and screen locking.++```bash+lume create macos-tahoe \+ --ipsw ~/Downloads/macos-tahoe.ipsw \+ --unattended tahoe+```++Creation includes a temporary boot, offline disk setup, and an SSH health check.+The VM is stopped when creation finishes.++## Run the VM++Start the VM with its display:++```bash+lume run macos-tahoe+```++The default guest credentials are `lume` / `lume`. In another terminal, verify+the guest account over SSH:++```bash+lume ssh macos-tahoe 'id -un'+```++The command prints `lume`. Change the password before using the VM for anything+sensitive.++## Next steps++- [Create a vanilla Tahoe VM](/how-to-guides/lume/create-vanilla-vm) for lifecycle commands and troubleshooting.+- [Serve the Lume API](/how-to-guides/lume/serve-api) for local tools and scripts.+- [Read the CLI reference](/reference/lume/cli-reference) for every command and option.diff --git a/docs/content/docs/tutorials/index.mdx b/docs/content/docs/tutorials/index.mdxindex fb25b0ca2f..22495d9e51 100644--- a/docs/content/docs/tutorials/index.mdx+++ b/docs/content/docs/tutorials/index.mdx@@ -7,5 +7,6 @@ Tutorials teach Cua by building something end to end. Start here if you are new- [Drive your first app](/tutorials/drive-your-first-app) - operate a native app in the background with Cua Driver.- [Your first cloud sandbox](/tutorials/your-first-cloud-sandbox) - spin up a disposable cloud computer.+- [Create your first local macOS VM](/tutorials/create-your-first-lume-vm) - install Lume and boot a vanilla Tahoe guest.Once you are comfortable, [How-to guides](/how-to-guides) cover specific goals and [Reference](/reference) has the exact APIs.diff --git a/docs/content/docs/tutorials/meta.json b/docs/content/docs/tutorials/meta.jsonindex 9175cf80f5..d9757ea796 100644--- a/docs/content/docs/tutorials/meta.json+++ b/docs/content/docs/tutorials/meta.json@@ -1 +1 @@-{ "title": "Tutorials", "icon": "GraduationCap", "pages": ["index", "drive-your-first-app", "your-first-cloud-sandbox"] }+{ "title": "Tutorials", "icon": "GraduationCap", "pages": ["index", "drive-your-first-app", "your-first-cloud-sandbox", "create-your-first-lume-vm"] }