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.

feat(lume): add telemetry, ASCII banner, docs rewrite, and build improvements (#820)

Francesco Bonaccib2724a2dc148
diff --git a/docs/content/docs/cuabench/guide/examples/custom-agent.mdx b/docs/content/docs/cuabench/examples/custom-agent.mdx
similarity index 100%
rename from docs/content/docs/cuabench/guide/examples/custom-agent.mdx
rename to docs/content/docs/cuabench/examples/custom-agent.mdx
diff --git a/docs/content/docs/cuabench/guide/examples/genai-task-generation.mdx b/docs/content/docs/cuabench/examples/genai-task-generation.mdx
similarity index 100%
rename from docs/content/docs/cuabench/guide/examples/genai-task-generation.mdx
rename to docs/content/docs/cuabench/examples/genai-task-generation.mdx
diff --git a/docs/content/docs/cuabench/guide/examples/meta.json b/docs/content/docs/cuabench/examples/meta.json
similarity index 100%
rename from docs/content/docs/cuabench/guide/examples/meta.json
rename to docs/content/docs/cuabench/examples/meta.json
diff --git a/docs/content/docs/cuabench/guide/examples/native-task.mdx b/docs/content/docs/cuabench/examples/native-task.mdx
similarity index 100%
rename from docs/content/docs/cuabench/guide/examples/native-task.mdx
rename to docs/content/docs/cuabench/examples/native-task.mdx
diff --git a/docs/content/docs/cuabench/guide/examples/universal-task.mdx b/docs/content/docs/cuabench/examples/universal-task.mdx
similarity index 100%
rename from docs/content/docs/cuabench/guide/examples/universal-task.mdx
rename to docs/content/docs/cuabench/examples/universal-task.mdx
diff --git a/docs/content/docs/cuabench/guide/meta.json b/docs/content/docs/cuabench/guide/meta.json
index edb23eeec1..bc617a2497 100644
--- a/docs/content/docs/cuabench/guide/meta.json
+++ b/docs/content/docs/cuabench/guide/meta.json
@@ -2,5 +2,5 @@
"title": "Guide",
"description": "Learn how to use Cua-Bench",
"icon": "Book",
- "pages": ["getting-started", "fundamentals", "examples", "advanced"]
+ "pages": ["getting-started", "fundamentals", "advanced"]
}
diff --git a/docs/content/docs/cuabench/meta.json b/docs/content/docs/cuabench/meta.json
index ac166133b7..0be5332970 100644
--- a/docs/content/docs/cuabench/meta.json
+++ b/docs/content/docs/cuabench/meta.json
@@ -1,5 +1,5 @@
{
"title": "Cua-Bench",
"description": "Framework for benchmarking and training computer-use agents",
- "pages": ["guide", "reference"]
+ "pages": ["guide", "examples", "reference"]
}
diff --git a/docs/content/docs/lume/examples/claude-cowork-sandbox.mdx b/docs/content/docs/lume/examples/claude-cowork-sandbox.mdx
new file mode 100644
index 0000000000..6f4b0a5301
--- /dev/null
+++ b/docs/content/docs/lume/examples/claude-cowork-sandbox.mdx
@@ -0,0 +1,181 @@
+---
+title: Claude Code in a macOS Sandbox
+description: Run Claude Code safely in an isolated macOS VM
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+[Claude Cowork](https://www.anthropic.com/news/cowork) uses Apple's Virtualization Framework to run AI agents in an isolated sandbox. You can build the same setup with Lume—run [Claude Code](https://claude.ai/code) on your host while it executes commands inside a sandboxed macOS VM.
+
+## Why sandbox Claude Code?
+
+Claude Code is powerful—it can read files, run commands, install packages, and modify your system. Sometimes you want that power contained:
+
+- **Experiment safely** — Let Claude install dependencies, run builds, test scripts without touching your real system
+- **Isolate risky operations** — Test destructive commands, untrusted code, or experimental changes
+- **Reset instantly** — Clone a fresh VM to undo everything Claude did
+
+## What we're building
+
+```
+┌─────────────────────────────────────────────────────┐
+│ Your Mac (Host) │
+│ │
+│ ┌───────────────────┐ ┌───────────────────┐ │
+│ │ Claude Code │ │ ~/project │ │
+│ │ (runs here) │ │ (shared folder) │ │
+│ └─────────┬─────────┘ └─────────┬─────────┘ │
+│ │ SSH │ mounted │
+│ ┌─────────▼─────────────────────────▼─────────┐ │
+│ │ macOS VM (Sandbox) │ │
+│ │ │ │
+│ │ Commands execute here, isolated from host │ │
+│ │ Full macOS environment with network access │ │
+│ │ Can only access /Volumes/My Shared Files │ │
+│ └─────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────┘
+```
+
+## Step 1: Create the sandbox VM
+
+```bash
+# Create a VM with automated setup (15-20 min, no interaction needed)
+lume create sandbox --os macos --ipsw latest --unattended tahoe
+```
+
+The `tahoe` preset creates user `lume` with password `lume` and enables SSH.
+
+## Step 2: Start the sandbox with your project
+
+```bash
+# Run headlessly, sharing your project folder
+lume run sandbox --no-display --shared-dir ~/my-project
+```
+
+Inside the VM, your files appear at `/Volumes/My Shared Files`.
+
+## Step 3: Get the VM's IP address
+
+```bash
+lume get sandbox
+# Look for the IP address in the output
+```
+
+Save this IP—you'll give it to Claude Code.
+
+## Step 4: Install Claude Code on your host
+
+```bash
+# macOS/Linux
+curl -fsSL https://claude.ai/install.sh | bash
+
+# Or with Homebrew
+brew install --cask claude-code
+```
+
+See [Claude Code docs](https://code.claude.com/docs) for other installation methods.
+
+## Step 5: Use Claude Code with the sandbox
+
+Now ask Claude Code to SSH into the sandbox and work there:
+
+```bash
+claude
+```
+
+Then tell Claude:
+
+> "SSH into [email protected] (password: lume) and work on the project in /Volumes/My Shared Files.
+> Install any dependencies you need, run builds, execute tests—all inside that VM."
+
+Claude Code will:
+1. SSH into the sandbox VM
+2. Navigate to your shared project
+3. Run commands in the isolated environment
+4. Report results back to you
+
+<Callout type="info">
+Claude Code runs on your host but executes commands via SSH inside the VM. Your host system stays untouched—only the sandbox and shared files are affected.
+</Callout>
+
+## Example session
+
+```
+You: SSH into [email protected] and set up a Python project in /Volumes/My Shared Files
+
+Claude: I'll connect to the VM and set up the project.
+
+[Runs: ssh [email protected]]
+[Runs: cd /Volumes/My\ Shared\ Files]
+[Runs: python3 -m venv venv]
+[Runs: source venv/bin/activate]
+[Runs: pip install -r requirements.txt]
+
+Done! I've created a virtual environment and installed the dependencies.
+The project is ready at /Volumes/My Shared Files.
+```
+
+All those commands ran inside the sandbox. Your host's Python, packages, and filesystem weren't touched.
+
+## Resetting the sandbox
+
+Made a mess? Reset instantly:
+
+```bash
+# Create a golden image first (do this once, after initial setup)
+lume clone sandbox sandbox-golden
+
+# Reset to clean state anytime
+lume stop sandbox
+lume delete sandbox
+lume clone sandbox-golden sandbox
+lume run sandbox --no-display --shared-dir ~/my-project
+```
+
+## Automating the workflow
+
+Script the entire setup:
+
+```bash
+#!/bin/bash
+
+PROJECT_DIR="$1"
+VM_NAME="sandbox"
+
+# Start the sandbox
+lume run $VM_NAME --no-display --shared-dir "$PROJECT_DIR"
+sleep 10 # Wait for boot
+
+# Get IP
+VM_IP=$(lume get $VM_NAME --format json | jq -r '.ip')
+
+echo "Sandbox ready!"
+echo "Run: claude"
+echo "Then tell Claude to SSH into lume@$VM_IP"
+```
+
+## Security considerations
+
+<Callout type="warn">
+The shared folder is read/write. Claude can modify or delete files in that folder. For sensitive work:
+- Share a copy of your project, not the original
+- Use git to track changes and revert if needed
+- Clone the VM before risky operations
+</Callout>
+
+The VM itself is fully isolated—code running inside cannot:
+- Access files outside the shared folder
+- Modify your host system
+- Read your host's environment variables or credentials
+
+But it can:
+- Access the network
+- Install software inside the VM
+- Consume CPU/memory
+
+## Next steps
+
+- [Unattended Setup](/lume/guide/fundamentals/unattended-setup) — Customize the VM configuration
+- [HTTP API](/lume/guide/advanced/http-server) — Automate VM control programmatically
+- [Lumier](/lume/guide/advanced/lumier) — Docker-based ephemeral VMs that reset automatically
+- [Claude Code docs](https://code.claude.com/docs) — Learn more about Claude Code's capabilities
diff --git a/docs/content/docs/lume/examples/index.mdx b/docs/content/docs/lume/examples/index.mdx
new file mode 100644
index 0000000000..1abcf8e7ea
--- /dev/null
+++ b/docs/content/docs/lume/examples/index.mdx
@@ -0,0 +1,32 @@
+---
+title: Examples
+description: Step-by-step tutorials and use cases for Lume
+---
+
+import { Card, Cards } from 'fumadocs-ui/components/card';
+import { Box, Cloud, Terminal } from 'lucide-react';
+
+# Examples
+
+Explore real-world examples and tutorials for using Lume to create and manage macOS virtual machines.
+
+<Cards>
+ <Card
+ icon={<Cloud className="w-6 h-6" />}
+ href="/lume/examples/claude-cowork-sandbox"
+ title="Claude Cowork Sandbox"
+ description="Run Claude Code in an isolated macOS VM sandbox"
+ />
+</Cards>
+
+## Available Examples
+
+### Development Environments
+
+- **[Claude Cowork Sandbox](/lume/examples/claude-cowork-sandbox)** - Set up a sandboxed macOS environment for running Claude Code safely with full system access
+
+## Coming Soon
+
+- **CI/CD with GitHub Actions** - Run macOS builds and tests in ephemeral VMs
+- **Multi-VM Development** - Manage multiple VMs for different project environments
+- **Automated Testing** - Set up VMs for automated UI testing
diff --git a/docs/content/docs/lume/examples/meta.json b/docs/content/docs/lume/examples/meta.json
new file mode 100644
index 0000000000..2f51d9dd0a
--- /dev/null
+++ b/docs/content/docs/lume/examples/meta.json
@@ -0,0 +1,6 @@
+{
+ "title": "Examples",
+ "description": "Step-by-step tutorials and use cases",
+ "icon": "Blocks",
+ "pages": ["claude-cowork-sandbox"]
+}
diff --git a/docs/content/docs/lume/guide/advanced/http-server.mdx b/docs/content/docs/lume/guide/advanced/http-server.mdx
index dcd417c825..3d4dad6650 100644
--- a/docs/content/docs/lume/guide/advanced/http-server.mdx
+++ b/docs/content/docs/lume/guide/advanced/http-server.mdx
@@ -5,30 +5,27 @@ description: Using the Lume REST API server
import { Callout } from 'fumadocs-ui/components/callout';
-Lume includes a built-in HTTP server that exposes a REST API for managing VMs. This enables integration with automation tools, scripts, and the Computer Use Agent SDK.
-
-## Starting the Server
+Lume's HTTP API lets you manage VMs programmatically—useful for automation scripts, CI/CD pipelines, and the Computer Use Agent SDK.
```bash
-# Start on default port (7777)
+# Start the server
lume serve
-# Start on custom port
+# Or on a custom port
lume serve --port 8080
```
-<Callout>
- If you installed Lume with the default settings, the server runs as a background service and
- starts automatically on login. You don't need to manually run `lume serve`.
+<Callout type="info">
+If you installed Lume with default settings, the server runs as a background service on port 7777. No need to start it manually.
</Callout>
-## Default URL
+## Base URL
```
http://localhost:7777
```
-## Quick Examples
+## Quick examples
### List VMs
@@ -36,12 +33,6 @@ http://localhost:7777
curl http://localhost:7777/lume/vms
```
-### Get VM Details
-
-```bash
-curl http://localhost:7777/lume/vms/my-vm
-```
-
### Run a VM
```bash
@@ -70,46 +61,68 @@ curl -X POST http://localhost:7777/lume/vms \
}'
```
-## Integration with Computer Use Agent
+### Get VM details
+
+```bash
+curl http://localhost:7777/lume/vms/my-vm
+```
+
+## Common workflows
-The Cua Computer Use Agent SDK uses the Lume HTTP API to manage VMs. When using `cua-computer`, ensure the Lume server is running:
+### Automation script
+
+```bash
+#!/bin/bash
+# Start a VM, wait for it, run tests, stop it
+
+curl -X POST localhost:7777/lume/vms/test-vm/run -d '{"noDisplay": true}'
+sleep 30 # Wait for boot
+
+# Run your tests here
+ssh lume@$(curl -s localhost:7777/lume/vms/test-vm | jq -r '.ip') 'run-tests.sh'
+
+curl -X POST localhost:7777/lume/vms/test-vm/stop
+```
+
+### Python integration
+
+The Computer Use Agent SDK connects to Lume's HTTP API:
```python
from cua import Computer
-# The Computer class connects to lume serve at localhost:7777
async with Computer() as computer:
await computer.run("my-vm")
- # ... perform automation
+ # Perform automation...
await computer.stop()
```
-## Background Service Management
-
-If installed as a background service:
+## Managing the background service
```bash
-# Check service status (macOS)
-launchctl list | grep lume
+# Check if running
+launchctl list | grep com.trycua.lume_daemon
+
+# Stop
+launchctl unload ~/Library/LaunchAgents/com.trycua.lume_daemon.plist
-# Stop the service
-launchctl unload ~/Library/LaunchAgents/com.trycua.lume.plist
+# Start
+launchctl load ~/Library/LaunchAgents/com.trycua.lume_daemon.plist
-# Start the service
-launchctl load ~/Library/LaunchAgents/com.trycua.lume.plist
+# View logs
+tail -f /tmp/lume_daemon.log
```
-## Server Configuration
+## Configuration
-The server respects Lume's configuration file for:
+The server uses settings from `~/.config/lume/config.yaml`:
- VM storage locations
- Cache settings
- Default resource allocations
-See the [FAQ](/lume/guide/advanced/faq) for configuration file locations.
+See the [FAQ](/lume/guide/getting-started/faq) for more on configuration.
-## Next Steps
+## Full API reference
-- [HTTP API Reference](/lume/reference/http-api) - Full API documentation
-- [CLI Reference](/lume/reference/cli-reference) - CLI command reference
+For all endpoints, request/response formats, and language-specific examples, see the [HTTP API Reference](/lume/reference/http-api).
diff --git a/docs/content/docs/lume/guide/advanced/lumier/building-lumier.mdx b/docs/content/docs/lume/guide/advanced/lumier/building-lumier.mdx
index bd9b99514b..178b8a8b51 100644
--- a/docs/content/docs/lume/guide/advanced/lumier/building-lumier.mdx
+++ b/docs/content/docs/lume/guide/advanced/lumier/building-lumier.mdx
@@ -1,42 +1,79 @@
---
title: Building Lumier
+description: Build Lumier from source or customize the container
---
-If you want to customize the Lumier container or build it from source, you can follow these steps:
+Build Lumier from source to customize packages, hooks, or configuration.
+
+## Build from source
```bash
-# 1. Navigate to the Lumier directory
-cd libs/lumier
+# Clone the repo (if you haven't)
+git clone https://github.com/trycua/cua.git
+cd cua/libs/lumier
-# 2. Build the Docker image locally
+# Build
docker build -t lumier-custom:latest .
-# 3. Run your custom build
+# Run your build
docker run -it --rm \
- --name lumier-vm \
- -p 8006:8006 \
- -e VM_NAME=lumier-vm \
- -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \
- -e CPU_CORES=4 \
- -e RAM_SIZE=8192 \
- lumier-custom:latest
+ -p 8006:8006 \
+ -e VM_NAME=my-vm \
+ -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \
+ -e CPU_CORES=4 \
+ -e RAM_SIZE=8192 \
+ lumier-custom:latest
+```
+
+## Customization points
+
+| Location | What to customize |
+|----------|-------------------|
+| `Dockerfile` | Base image, installed packages |
+| `/run/hooks/` | Scripts that run during VM lifecycle |
+| `/run/config/constants.sh` | Default settings |
+
+### Change the base image
+
+The default is Debian Bullseye Slim. To use a different base, edit the first line of `Dockerfile`:
+
+```dockerfile
+FROM debian:bookworm-slim
+```
+
+### Add packages
+
+Add to the `apt-get install` list in the Dockerfile:
+
+```dockerfile
+RUN apt-get update && apt-get install -y \
+ your-package-here \
+ ...
```
-### Customization Options
+### Add lifecycle hooks
-The Dockerfile provides several customization points:
+Scripts in `/run/hooks/` run at specific points. Create your own to customize behavior.
-1. **Base image**: The container uses Debian Bullseye Slim as the base. You can modify this if needed.
-2. **Installed packages**: You can add or remove packages in the apt-get install list.
-3. **Hooks**: Check the `/run/hooks/` directory for scripts that run at specific points during VM lifecycle.
-4. **Configuration**: Review `/run/config/constants.sh` for default settings.
+## Publish your build
-After making your modifications, you can build and push your custom image to your own Docker Hub repository:
+Push to Docker Hub or another registry:
```bash
-# Build with a custom tag
+# Tag for your registry
docker build -t yourusername/lumier:custom .
-# Push to Docker Hub (after docker login)
+# Login and push
+docker login
docker push yourusername/lumier:custom
```
+
+Then use your image:
+
+```bash
+docker run -it --rm \
+ -p 8006:8006 \
+ -e VM_NAME=my-vm \
+ -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \
+ yourusername/lumier:custom
+```
diff --git a/docs/content/docs/lume/guide/advanced/lumier/docker-compose.mdx b/docs/content/docs/lume/guide/advanced/lumier/docker-compose.mdx
index 312598e74b..17f415ac6e 100644
--- a/docs/content/docs/lume/guide/advanced/lumier/docker-compose.mdx
+++ b/docs/content/docs/lume/guide/advanced/lumier/docker-compose.mdx
@@ -1,8 +1,13 @@
---
title: Docker Compose
+description: Running Lumier with Docker Compose
---
-You can also use Docker Compose to run Lumier with a simple configuration file. Create a `docker-compose.yml` file with the following content:
+For easier management, use Docker Compose instead of raw `docker run` commands.
+
+## Setup
+
+Create `docker-compose.yml`:
```yaml
version: '3'
@@ -13,10 +18,10 @@ services:
container_name: lumier-vm
restart: unless-stopped
ports:
- - '8006:8006' # Port for VNC access
+ - '8006:8006'
volumes:
- - ./storage:/storage # VM persistent storage
- - ./shared:/shared # Shared folder accessible in the VM
+ - ./storage:/storage
+ - ./shared:/shared
environment:
- VM_NAME=lumier-vm
- VERSION=ghcr.io/trycua/macos-sequoia-cua:latest
@@ -28,18 +33,59 @@ services:
stop_grace_period: 2m
```
-Then run Lumier using:
+## Run it
```bash
-# First create the required directories
+# Create directories
mkdir -p storage shared
-# Start the container
+# Start in background
docker-compose up -d
-# View the logs
+# View logs
docker-compose logs -f
-# Stop the container when done
+# Stop
docker-compose down
```
+
+Access at `http://localhost:8006`.
+
+## Configuration options
+
+| Field | Description |
+|-------|-------------|
+| `restart: unless-stopped` | Auto-restart unless manually stopped |
+| `stop_grace_period: 2m` | Wait 2 minutes for graceful shutdown |
+| `stop_signal: SIGINT` | Send interrupt signal to stop |
+
+## Multiple VMs
+
+Run multiple VMs by adding services:
+
+```yaml
+version: '3'
+
+services:
+ dev-vm:
+ image: trycua/lumier:latest
+ ports:
+ - '8006:8006'
+ environment:
+ - VM_NAME=dev-vm
+ - VERSION=ghcr.io/trycua/macos-sequoia-cua:latest
+ - CPU_CORES=4
+ - RAM_SIZE=8192
+
+ test-vm:
+ image: trycua/lumier:latest
+ ports:
+ - '8007:8006'
+ environment:
+ - VM_NAME=test-vm
+ - VERSION=ghcr.io/trycua/macos-sequoia-cua:latest
+ - CPU_CORES=2
+ - RAM_SIZE=4096
+```
+
+Access at `localhost:8006` and `localhost:8007`.
diff --git a/docs/content/docs/lume/guide/advanced/lumier/docker.mdx b/docs/content/docs/lume/guide/advanced/lumier/docker.mdx
index b7c7205061..e22cf74960 100644
--- a/docs/content/docs/lume/guide/advanced/lumier/docker.mdx
+++ b/docs/content/docs/lume/guide/advanced/lumier/docker.mdx
@@ -1,128 +1,118 @@
---
title: Docker
+description: Running Lumier with Docker
---
-You can use Lumier through Docker:
+import { Callout } from 'fumadocs-ui/components/callout';
-### Run a macOS VM (ephemeral)
+## Quick start (ephemeral)
+
+Run a macOS VM that resets when you stop it:
```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
+ -p 8006:8006 \
+ -e VM_NAME=my-vm \
+ -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \
+ -e CPU_CORES=4 \
+ -e RAM_SIZE=8192 \
+ trycua/lumier:latest
```
-Access the VM in your browser at **http://localhost:8006**.
-
-After running the command above, you can access your macOS VM through a web browser (e.g., http://localhost:8006).
+Open `http://localhost:8006` in your browser.
-<Callout title="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 section below for how to
- save your VM state.
+<Callout type="info">
+In ephemeral mode, changes are lost when you stop the container. See below for persistent storage.
</Callout>
-## Saving Your VM State
+## Persistent storage
-To save your VM state between sessions (so your changes persist when you stop and restart the container), you'll need to set up a storage location:
+Keep your VM state between sessions:
```bash
-# First, create a storage directory if it doesn't exist
mkdir -p storage
-# Then run the container with persistent storage
docker run -it --rm \
- --name lumier-vm \
- -p 8006:8006 \
- -v $(pwd)/storage:/storage \
- -e VM_NAME=lumier-vm \
- -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \
- -e CPU_CORES=4 \
- -e RAM_SIZE=8192 \
- -e HOST_STORAGE_PATH=$(pwd)/storage \
- trycua/lumier:latest
+ -p 8006:8006 \
+ -v $(pwd)/storage:/storage \
+ -e VM_NAME=my-vm \
+ -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \
+ -e CPU_CORES=4 \
+ -e RAM_SIZE=8192 \
+ -e HOST_STORAGE_PATH=$(pwd)/storage \
+ trycua/lumier:latest
```
-This command creates a connection between a folder on your Mac (`$(pwd)/storage`) and a folder inside the Docker container (`/storage`). The `-v` flag (volume mount) and the `HOST_STORAGE_PATH` variable work together to ensure your VM data is saved on your host Mac.
+The `-v` mount and `HOST_STORAGE_PATH` work together to save VM data on your Mac.
-## Sharing Files with Your VM
+## Share files with the VM
-To share files between your Mac and the virtual machine, you can set up a shared folder:
+Add a shared folder accessible at `/Volumes/My Shared Files` inside the VM:
```bash
-# Create both storage and shared folders
mkdir -p storage shared
-# Run with both persistent storage and a shared folder
docker run -it --rm \
- --name lumier-vm \
- -p 8006:8006 \
- -v $(pwd)/storage:/storage \
- -v $(pwd)/shared:/shared \
- -e VM_NAME=lumier-vm \
- -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \
- -e CPU_CORES=4 \
- -e RAM_SIZE=8192 \
- -e HOST_STORAGE_PATH=$(pwd)/storage \
- -e HOST_SHARED_PATH=$(pwd)/shared \
- trycua/lumier:latest
+ -p 8006:8006 \
+ -v $(pwd)/storage:/storage \
+ -v $(pwd)/shared:/shared \
+ -e VM_NAME=my-vm \
+ -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \
+ -e CPU_CORES=4 \
+ -e RAM_SIZE=8192 \
+ -e HOST_STORAGE_PATH=$(pwd)/storage \
+ -e HOST_SHARED_PATH=$(pwd)/shared \
+ trycua/lumier:latest
```
-With this setup, any files you place in the `shared` folder on your Mac will be accessible from within the macOS VM, and vice versa.
+Files you put in `./shared` appear in the VM, and vice versa.
-## Automating VM Startup with on-logon.sh
+## Run scripts on VM startup
-You can automatically run scripts when the VM starts up by placing an `on-logon.sh` script in the shared folder's lifecycle directory. This is useful for setting up your VM environment each time it starts.
+Create `shared/lifecycle/on-logon.sh` to run commands when the VM boots:
```bash
-# Create the lifecycle directory in your shared folder
mkdir -p shared/lifecycle
-# Create a sample on-logon.sh script
cat > shared/lifecycle/on-logon.sh << 'EOF'
#!/usr/bin/env bash
-# Create a file on the desktop
-echo "Hello from Lumier!" > /Users/lume/Desktop/hello_lume.txt
+# Example: create a file on the desktop
+echo "Hello from Lumier!" > /Users/lume/Desktop/hello.txt
-# You can add more commands to execute at VM startup
-# For example:
-# - Configure environment variables
-# - Start applications
-# - Mount network drives
-# - Set up development environments
+# Add your setup commands here:
+# - Install packages
+# - Configure environment
+# - Start services
EOF
-# Make the script executable
chmod +x shared/lifecycle/on-logon.sh
```
-The script will be automatically executed when the VM starts up. It runs in the VM context and has access to:
-
-- The `/Users/lume` user directory (home directory in the VM)
-- The shared folder at `/Volumes/My Shared Files` inside the VM
-- Any resources available to the VM
+The script runs as the `lume` user and can access:
+- `/Users/lume` — home directory
+- `/Volumes/My Shared Files` — shared folder
-This feature enables automation of VM setup without modifying the base VM image.
+## Environment variables
-## Configuration Options
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `VM_NAME` | Name for the VM | `my-vm` |
+| `VERSION` | macOS image to use | `ghcr.io/trycua/macos-sequoia-cua:latest` |
+| `CPU_CORES` | CPU cores | `4` |
+| `RAM_SIZE` | Memory in MB | `8192` |
+| `HOST_STORAGE_PATH` | Persistent storage path | `$(pwd)/storage` |
+| `HOST_SHARED_PATH` | Shared folder path | `$(pwd)/shared` |
-When running Lumier, you'll need to configure a few things:
+## Change the port
-- **Port forwarding** (`-p 8006:8006`): Makes the VM's VNC interface accessible in your browser. If port 8006 is already in use, you can use a different port like `-p 8007:8006`.
+If port 8006 is in use, map to a different port:
-- **Environment variables** (`-e`): Configure your VM settings:
- - `VM_NAME`: A name for your virtual machine
- - `VERSION`: The macOS image to use
- - `CPU_CORES`: Number of CPU cores to allocate
- - `RAM_SIZE`: Memory in MB to allocate
- - `HOST_STORAGE_PATH`: Path to save VM state (when using persistent storage)
- - `HOST_SHARED_PATH`: Path to the shared folder (optional)
+```bash
+docker run -it --rm \
+ -p 9000:8006 \
+ # ... rest of options
+ trycua/lumier:latest
+```
-- **Background service**: The `lume serve` service should be running on your host (starts automatically when you install Lume using the `install.sh` script above).
+Then access at `http://localhost:9000`.
diff --git a/docs/content/docs/lume/guide/advanced/lumier/index.mdx b/docs/content/docs/lume/guide/advanced/lumier/index.mdx
index b6abdf5dc6..eb9f230d81 100644
--- a/docs/content/docs/lume/guide/advanced/lumier/index.mdx
+++ b/docs/content/docs/lume/guide/advanced/lumier/index.mdx
@@ -5,24 +5,63 @@ github:
- https://github.com/trycua/cua/tree/main/libs/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:
+import { Callout } from 'fumadocs-ui/components/callout';
-- 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
+Lumier wraps Lume in a Docker container, giving you browser-based access to macOS VMs with zero configuration.
-## How It Works
+```bash
+docker run -it --rm \
+ -p 8006:8006 \
+ -e VM_NAME=my-vm \
+ -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \
+ trycua/lumier:latest
+```
-<Callout title="Note">
- We're using Docker primarily as a convenient delivery mechanism, not as an isolation layer. Unlike
- traditional Docker containers, Lumier leverages the Apple Virtualization Framework (Apple Vz)
- through the `lume` CLI to create true virtual machines.
+Open `http://localhost:8006` in your browser—you'll see a macOS desktop.
+
+## When to use Lumier vs Lume directly
+
+| Use Lumier when... | Use Lume directly when... |
+|--------------------|---------------------------|
+| You want browser-based VNC access | You prefer native VNC clients |
+| You're distributing VM environments | You're running locally for development |
+| You want Docker Compose orchestration | You need maximum performance |
+| You're building Docker-based workflows | You want full CLI control |
+
+## How it works
+
+<Callout type="info">
+Docker is the delivery mechanism, not an isolation layer. Lumier connects to the Lume service on your host Mac to create real VMs using Apple's Virtualization Framework.
</Callout>
-Here's what's happening behind the scenes:
+```
+┌─────────────────────────────────────┐
+│ Docker Container │
+│ ┌─────────────────────────────┐ │
+│ │ Lumier + noVNC server │ │
+│ └──────────────┬──────────────┘ │
+└─────────────────┼───────────────────┘
+ │ connects to
+┌─────────────────▼───────────────────┐
+│ Lume service (port 7777) │
+│ on host Mac │
+└─────────────────┬───────────────────┘
+ │ creates
+┌─────────────────▼───────────────────┐
+│ macOS VM (Virtualization.framework) │
+└─────────────────────────────────────┘
+```
+
+The Docker container provides:
+- noVNC server for browser access
+- Environment variable configuration
+- Lifecycle hooks for automation
+
+The actual VM runs natively on your Mac with hardware acceleration.
+
+## Get started
-1. The Docker container provides a consistent environment to run the Lumier interface
-2. Lumier connects to the Lume service running on your host Mac
-3. Lume uses Apple's Virtualization Framework to create a true macOS virtual machine
-4. The VM runs with hardware acceleration using your Mac's native virtualization capabilities
+1. [Install prerequisites](/lume/guide/advanced/lumier/installation) — Docker and Lume
+2. [Run with Docker](/lume/guide/advanced/lumier/docker) — Basic usage and persistent storage
+3. [Use Docker Compose](/lume/guide/advanced/lumier/docker-compose) — Multi-container setups
+4. [Build from source](/lume/guide/advanced/lumier/building-lumier) — Customize the container
diff --git a/docs/content/docs/lume/guide/advanced/lumier/installation.mdx b/docs/content/docs/lume/guide/advanced/lumier/installation.mdx
index d2e6239932..2def7c8393 100644
--- a/docs/content/docs/lume/guide/advanced/lumier/installation.mdx
+++ b/docs/content/docs/lume/guide/advanced/lumier/installation.mdx
@@ -1,15 +1,72 @@
---
title: Installation
+description: Prerequisites for running Lumier
---
-Before using Lumier, make sure you have:
+import { Callout } from 'fumadocs-ui/components/callout';
-1. **Docker for Apple Silicon** - download it [here](https://desktop.docker.com/mac/main/arm64/Docker.dmg) and follow the installation instructions.
+Lumier needs two things: Docker and Lume.
-2. **Lume** - This is the virtualization CLI that powers Lumier. Install it with this command:
+## 1. Install Docker
+
+Download [Docker Desktop for Apple Silicon](https://desktop.docker.com/mac/main/arm64/Docker.dmg) and install it.
+
+Verify it's running:
+
+```bash
+docker --version
+# Docker version 24.0.0, build ...
+```
+
+## 2. Install Lume
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
```
-After installation, Lume runs as a background service and listens on port 7777. This service allows Lumier to create and manage virtual machines. If port 7777 is already in use on your system, you can specify a different port with the `--port` option when running the `install.sh` script.
+Verify the Lume service is running:
+
+```bash
+curl http://localhost:7777/lume/vms
+# Should return [] or a list of VMs
+```
+
+<Callout type="info">
+Lume runs as a background service on port 7777. Lumier connects to this service to create and manage VMs.
+</Callout>
+
+## Verify everything works
+
+Pull and run Lumier:
+
+```bash
+docker run -it --rm \
+ -p 8006:8006 \
+ -e VM_NAME=test-vm \
+ -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \
+ trycua/lumier:latest
+```
+
+Open `http://localhost:8006` in your browser. You should see a macOS desktop loading.
+
+## Troubleshooting
+
+**"Cannot connect to Lume service"** — The Lume background service isn't running. Start it:
+
+```bash
+lume serve
+```
+
+Or check if the daemon is loaded:
+
+```bash
+launchctl list | grep com.trycua.lume_daemon
+```
+
+**Port 7777 in use** — Another service is using the port. Either stop that service or reinstall Lume with a different port:
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)" -- --port 7778
+```
+
+Then update your Lumier commands to use the new port via the `LUME_PORT` environment variable.
diff --git a/docs/content/docs/lume/guide/fundamentals/unattended-setup.mdx b/docs/content/docs/lume/guide/fundamentals/unattended-setup.mdx
index 26839ddb71..63742529a1 100644
--- a/docs/content/docs/lume/guide/fundamentals/unattended-setup.mdx
+++ b/docs/content/docs/lume/guide/fundamentals/unattended-setup.mdx
@@ -5,249 +5,194 @@ description: Automate macOS Setup Assistant with YAML configuration files
import { Callout } from 'fumadocs-ui/components/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">
- **Version Compatibility**: Unattended configurations are specific to macOS versions. The Setup
- Assistant screens, button labels, and navigation flow can change between macOS releases. A
- configuration built for macOS Tahoe may not work on Sequoia or future versions.
-</Callout>
-
-## Quick Start
-
-There are two ways to use unattended setup:
-
-### Option 1: During VM Creation
-
-Use the `--unattended` flag with `lume create` to install from IPSW and automatically run the Setup Assistant:
+The macOS Setup Assistant takes 10+ minutes of clicking through screens. Unattended setup does it for you—using VNC and OCR to navigate the UI automatically.
```bash
-# Using a built-in preset
-lume create my-vm --os macOS --ipsw latest --unattended tahoe
-
-# Using a custom config file
-lume create my-vm --os macOS --ipsw latest --unattended path/to/config.yml
-
-# With debug mode enabled
-lume create my-vm --os macOS --ipsw latest --unattended tahoe --debug
+lume create my-vm --os macos --ipsw latest --unattended tahoe
```
-This will:
-
-1. Create the VM and install macOS from the IPSW
-2. Boot the VM (without opening VNC client by default)
-3. Automatically run through the Setup Assistant using your configuration
+This creates a VM, installs macOS, and runs through the entire Setup Assistant. When it's done, you have a configured VM with user `lume` (password `lume`) and SSH enabled.
-**Additional options for `lume create --unattended`:**
+<Callout type="warn">
+Unattended configs are macOS version-specific. The `tahoe` preset works with macOS Tahoe (15.x). Setup Assistant changes between versions, so configs may need updating for new releases.
+</Callout>
-| Option | Description |
-| ------ | ----------- |
-| `--debug` | Save screenshots with OCR annotations for debugging |
-| `--debug-dir` | Custom directory for debug screenshots |
-| `--no-display` | Don't open VNC client (default: true for unattended) |
-| `--vnc-port` | VNC server port (default: 0 for auto-assign) |
+## Quick start
-### Option 2: On an Existing VM
+### Use the built-in preset
-Use the `lume setup` command on a freshly created VM that hasn't completed the Setup Assistant:
+The `tahoe` preset handles macOS Tahoe's Setup Assistant:
```bash
-# First, create a VM without unattended setup
-lume create my-vm --os macOS --ipsw latest
+# During VM creation
+lume create my-vm --os macos --ipsw latest --unattended tahoe
-# Later, run the unattended setup with a preset
+# Or on an existing VM that's at the Setup Assistant
lume setup my-vm --unattended tahoe
-
-# Or with a custom config file
-lume setup my-vm --unattended path/to/config.yml
```
-This is useful when you want to:
+### Use a custom config
-- Reuse a VM that failed during setup
-- Apply different configurations to cloned VMs
-- Debug setup issues interactively before automating
+Point to your YAML file:
-## Built-in Presets
+```bash
+lume create my-vm --os macos --ipsw latest --unattended ./my-config.yml
+```
-Lume includes built-in configuration presets that you can reference by name:
+### Debug mode
-| Preset | Description |
-| ------- | --------------------------------------------------------------------------------------------------- |
-| `tahoe` | Full macOS Tahoe Setup Assistant automation (creates user `lume` with password `lume`, enables SSH) |
+Save screenshots showing what the automation sees:
```bash
-# Use the tahoe preset during creation
-lume create my-vm --os macOS --ipsw latest --unattended tahoe
+lume create my-vm --os macos --ipsw latest --unattended tahoe --debug
```
-## YAML Schema
+Screenshots go to `/tmp/unattended-<uuid>` by default, or specify `--debug-dir /path/to/folder`.
-The unattended configuration file uses YAML format with three main sections:
+## How it works
+
+1. VM boots and reaches the Setup Assistant
+2. Lume waits `boot_wait` seconds for the UI to stabilize
+3. Commands execute sequentially: click text, type strings, press keys
+4. OCR finds text on screen; VNC sends input
+5. Optional health check verifies success (e.g., SSH connection)
+
+## Writing a config file
+
+A config has three parts:
```yaml
-# Seconds to wait after VM boots before starting automation
-boot_wait: 30
+boot_wait: 30 # Seconds to wait after boot
-# Sequence of commands to execute
-boot_commands:
- - '<command>'
- - '<command>'
- # ...
+boot_commands: # Sequence of automation commands
+ - "<wait 'Continue'>"
+ - "<click 'Continue'>"
+ - "<type 'lume'>"
+ - "<enter>"
-# Optional health check to verify setup success
-health_check:
+health_check: # Optional verification
type: ssh
user: lume
password: lume
```
-### Configuration Fields
-
-| Field | Type | Required | Default | Description |
-| --------------- | ------- | -------- | ------- | --------------------------------------------------------- |
-| `boot_wait` | integer | No | 60 | Seconds to wait for VM to boot before starting automation |
-| `boot_commands` | array | Yes | - | List of automation commands to execute |
-| `health_check` | object | No | - | Health check configuration to verify setup success |
-
-### Health Check Configuration
-
-| Field | Type | Required | Default | Description |
-| ------------- | ------- | -------- | ------- | ----------------------------------- |
-| `type` | string | Yes | - | Type of health check (`ssh`) |
-| `user` | string | No | - | Username for SSH authentication |
-| `password` | string | No | - | Password for SSH authentication |
-| `timeout` | integer | No | 30 | Timeout in seconds for each attempt |
-| `retries` | integer | No | 3 | Number of retry attempts |
-| `retry_delay` | integer | No | 5 | Seconds to wait between retries |
-
-## Boot Commands
-
-Boot commands are strings enclosed in angle brackets that control mouse, keyboard, and timing.
-
-### Timing Commands
-
-| Command | Description | Example |
-| -------------------------- | ---------------------------------------- | ---------------------------- |
-| `<delay N>` | Wait N seconds (supports decimals) | `<delay 2>`, `<delay 0.5>` |
-| `<wait 'text'>` | Wait for text to appear on screen (OCR) | `<wait 'Continue'>` |
-| `<wait 'text', timeout=N>` | Wait with custom timeout (default: 120s) | `<wait 'Siri', timeout=300>` |
+## Commands
-### Mouse Commands
+### Wait for text (OCR)
-| Command | Description | Example |
-| --------------------------- | --------------------------------------- | ------------------------------ |
-| `<click 'text'>` | Click on detected text | `<click 'Continue'>` |
-| `<click 'text', index=N>` | Click Nth occurrence (0=first, -1=last) | `<click 'Agree', index=-1>` |
-| `<click 'text', xoffset=N>` | Click with horizontal offset | `<click 'Option', xoffset=50>` |
-| `<click 'text', yoffset=N>` | Click with vertical offset | `<click 'Label', yoffset=30>` |
-| `<click_at X,Y>` | Click at exact coordinates | `<click_at 960,540>` |
+```yaml
+- "<wait 'Continue'>" # Wait up to 120s (default)
+- "<wait 'Loading...', timeout=300>" # Custom timeout
+```
-**Index parameter**: When text appears multiple times on screen (e.g., "Agree" in both license text and button), use `index` to select which occurrence:
+### Click text
-- `index=0` - First (topmost) occurrence
-- `index=1` - Second occurrence
-- `index=-1` - Last (bottommost) occurrence
-- `index=-2` - Second to last occurrence
+```yaml
+- "<click 'Continue'>" # Click first occurrence
+- "<click 'Agree', index=-1>" # Click last occurrence
+- "<click 'Label', xoffset=50>" # Click 50px right of text
+- "<click_at 960,540>" # Click exact coordinates
+```
-### Keyboard Commands
+When text appears multiple times (like "Agree" in license text and button), use `index`:
+- `index=0` — first (top)
+- `index=-1` — last (bottom)
-#### Special Keys
+### Type text
-| Command | Description |
-| ------------------------------------- | ---------------------- |
-| `<enter>` or `<return>` | Press Enter/Return key |
-| `<tab>` | Press Tab key |
-| `<space>` | Press Spacebar |
-| `<esc>` or `<escape>` | Press Escape key |
-| `<backspace>` | Press Backspace key |
-| `<delete>` | Press Delete key |
-| `<up>`, `<down>`, `<left>`, `<right>` | Arrow keys |
-| `<f1>` through `<f12>` | Function keys |
+```yaml
+- "<type 'username'>"
+- "<type 'my-password'>"
+```
-#### Text Input
+### Press keys
-| Command | Description | Example |
-| --------------- | --------------------- | ------------------- |
-| `<type 'text'>` | Type a string of text | `<type 'username'>` |
+```yaml
+- "<enter>" # or <return>
+- "<tab>"
+- "<space>"
+- "<esc>"
+- "<backspace>"
+- "<delete>"
+- "<up>" "<down>" "<left>" "<right>"
+- "<f1>" through "<f12>"
+```
-#### Hotkey Combinations
+### Hotkey combinations
-Combine modifier keys with `+`:
+```yaml
+- "<cmd+space>" # Spotlight
+- "<cmd+c>" # Copy
+- "<cmd+v>" # Paste
+- "<cmd+q>" # Quit
+- "<shift+cmd+3>" # Screenshot
+- "<ctrl+alt+delete>"
+```
-| Modifier | Aliases |
-| -------- | ------------------------- |
-| Command | `cmd`, `command`, `super` |
-| Shift | `shift` |
-| Option | `alt`, `option` |
-| Control | `ctrl`, `control` |
+Modifiers: `cmd`/`command`/`super`, `shift`, `alt`/`option`, `ctrl`/`control`
-**Examples:**
+### Delays
-- `<cmd+space>` - Open Spotlight
-- `<cmd+q>` - Quit application
-- `<cmd+c>` - Copy
-- `<cmd+v>` - Paste
-- `<ctrl+alt+delete>` - Multi-key combo
-- `<shift+cmd+3>` - Screenshot
+```yaml
+- "<delay 2>" # Wait 2 seconds
+- "<delay 0.5>" # Decimals work
+```
-## Example: Full macOS Setup
+## Example: Complete Setup Assistant
-This example walks through macOS Tahoe's Setup Assistant:
+This walks through macOS Tahoe's Setup Assistant:
```yaml
boot_wait: 30
boot_commands:
- # Dismiss greeting screen
- - '<delay 5>'
- - '<space>'
- - '<delay 2>'
+ # Dismiss greeting
+ - "<delay 5>"
+ - "<space>"
+ - "<delay 2>"
- # Language selection
+ # Language
- "<wait 'English', timeout=120>"
- "<type 'English'>"
- - '<delay 1>'
- - '<enter>'
- - '<delay 2>'
+ - "<delay 1>"
+ - "<enter>"
+ - "<delay 2>"
- # Country/Region
+ # Country
- "<wait 'Country or Region'>"
- - '<click_at 960,900>' # Click list to focus
+ - "<click_at 960,900>"
- "<type 'United States'>"
- - '<enter>'
+ - "<enter>"
- "<click 'Continue'>"
- - '<delay 2>'
+ - "<delay 2>"
- # Transfer Your Data - select "Set up as new"
+ # Transfer - select "Set up as new"
- "<wait 'Transfer Your Data'>"
- - '<delay 20>'
- - '<tab>'
- - '<tab>'
- - '<tab>'
- - '<space>' # Select "Set up as new"
+ - "<delay 20>"
+ - "<tab><tab><tab>"
+ - "<space>"
- "<click 'Continue'>"
- # Skip remaining screens...
+ # Accessibility
- "<wait 'Accessibility'>"
- "<click 'Not Now'>"
- # Create account
+ # Account creation
- "<wait 'Create a Mac Account'>"
- - '<tab><tab><tab><tab><tab><tab>' # Tab to Full Name field
+ - "<tab><tab><tab><tab><tab><tab>"
- "<type 'lume'>"
- - '<tab><tab>' # Skip to Password
+ - "<tab><tab>"
- "<type 'lume'>"
- - '<tab>'
- - "<type 'lume'>" # Verify password
- - '<tab><tab><space>' # Uncheck Apple Account reset
+ - "<tab>"
+ - "<type 'lume'>"
+ - "<tab><tab><space>"
- "<click 'Continue'>"
- # Terms and Conditions
+ # Terms
- "<wait 'Terms and Conditions'>"
- - "<click 'Agree', index=-1>" # Click button, not text
+ - "<click 'Agree', index=-1>"
- "<wait 'I have read and agree'>"
- - "<click 'Agree', index=0>" # Click modal button
+ - "<click 'Agree', index=0>"
health_check:
type: ssh
@@ -258,79 +203,76 @@ health_check:
retry_delay: 10
```
-## Debugging
-
-Enable debug mode to save screenshots with OCR annotations. Debug flags work with both `lume setup` and `lume create --unattended`:
-
-```bash
-# Using lume setup
-lume setup my-vm --unattended tahoe --debug
+## Health checks
-# Using lume create with unattended setup
-lume create my-vm --os macOS --ipsw latest --unattended tahoe --debug
+Verify setup succeeded by testing SSH connectivity:
-# Save screenshots to custom directory (both commands support this)
-lume setup my-vm --unattended tahoe --debug --debug-dir /path/to/debug
-lume create my-vm --os macOS --ipsw latest --unattended tahoe --debug --debug-dir /path/to/debug
+```yaml
+health_check:
+ type: ssh
+ user: lume
+ password: lume
+ timeout: 30 # Seconds per attempt
+ retries: 5 # Number of attempts
+ retry_delay: 10 # Seconds between retries
```
-By default, debug screenshots are saved to a unique folder in the system temp directory (e.g., `/tmp/unattended-<uuid>`).
-
-Debug screenshots show:
-
-- OCR-detected text with bounding boxes
-- Click target coordinates
-- Command being executed
+The automation waits for the VM to become reachable via SSH before declaring success.
-## Tips for Writing Configurations
+## Tips
-### Handling Timing
+**Timing issues** — If commands run before the screen is ready, increase `boot_wait` or add `<delay>` commands. Use `<wait 'text'>` to sync with specific screens.
-- Use generous `<delay>` values between commands
-- Increase `boot_wait` if automation starts before the VM is ready
-- Use `<wait 'text', timeout=N>` for screens that load slowly
+**Text not found** — OCR is case-sensitive. Check exact spelling. If text is unreliable, use `<click_at X,Y>` with coordinates.
-### OCR Text Matching
+**Multiple occurrences** — When "Agree" appears in both license text and the button, use `<click 'Agree', index=-1>` to click the button (usually last).
-- Text matching is case-sensitive
-- Wait for unique text that identifies the screen before clicking
-- If text appears multiple times, use `index` parameter
-
-### Keyboard Navigation
-
-macOS requires full keyboard access to Tab through all UI elements:
+**Keyboard navigation** — macOS doesn't Tab through all elements by default. Enable full keyboard access:
```yaml
-- "<type 'defaults write NSGlobalDomain AppleKeyboardUIMode -int 3'>"
-- '<enter>'
+- "<cmd+space>"
+- "<type 'Keyboard'>"
+- "<delay 2>"
+- "<enter>"
+# Then enable "Keyboard navigation" in settings
```
-### System Settings Automation
+**Screen coordinates** — Default resolution is 1920x1440. Center is roughly `<click_at 960,720>`.
-Some settings can only be changed through GUI (protected by SIP):
+## Troubleshooting
-- Full Disk Access requires navigating System Settings
-- Use Spotlight (`<cmd+space>`) to search for specific settings
+| Problem | Solution |
+|---------|----------|
+| Commands run too early | Increase `boot_wait`, add `<delay>` |
+| Text not found | Check spelling/case, increase timeout, use coordinates |
+| Wrong element clicked | Use `index` to select correct occurrence |
+| Hotkeys ignored | Click desktop first to focus |
+| Tab skips elements | Enable keyboard navigation in System Settings |
-### Screen Coordinates
+## Limitations
-- Default VM resolution is 1920x1440 (Retina-scaled)
-- Use `<click_at X,Y>` when text detection is unreliable
-- Center of screen is approximately `<click_at 960,720>`
+- **OCR depends on resolution** — Text detection accuracy varies with display settings
+- **Version-specific** — Setup Assistant changes between macOS releases
+- **No conditionals** — Commands run sequentially; can't branch based on screen state
+- **Single display** — Coordinates assume one display at native resolution
-## Troubleshooting
+## Reference
-| Issue | Solution |
-| ----------------------------- | -------------------------------------------------------------------- |
-| Commands execute too early | Increase `boot_wait` or add `<delay>` commands |
-| Text not found | Check exact spelling/case, increase timeout, use coordinates instead |
-| Wrong element clicked | Use `index` parameter to select correct occurrence |
-| Hotkeys don't work | Click on desktop first to give it focus |
-| Tab navigation skips elements | Enable full keyboard access with `AppleKeyboardUIMode` |
+### Config fields
-## Limitations
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `boot_wait` | integer | 60 | Seconds to wait before starting |
+| `boot_commands` | array | required | List of commands |
+| `health_check` | object | optional | Verification config |
+
+### Health check fields
-1. **OCR accuracy**: Text detection depends on screen resolution and font rendering
-2. **Version-specific**: Setup Assistant flow changes between macOS versions
-3. **No conditional logic**: Commands execute sequentially without branching
-4. **Single display**: Coordinates assume single display at native resolution
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `type` | string | required | `ssh` |
+| `user` | string | — | SSH username |
+| `password` | string | — | SSH password |
+| `timeout` | integer | 30 | Seconds per attempt |
+| `retries` | integer | 3 | Number of attempts |
+| `retry_delay` | integer | 5 | Seconds between retries |
diff --git a/docs/content/docs/lume/guide/fundamentals/vm-management.mdx b/docs/content/docs/lume/guide/fundamentals/vm-management.mdx
index 6e87690e55..a7828bb137 100644
--- a/docs/content/docs/lume/guide/fundamentals/vm-management.mdx
+++ b/docs/content/docs/lume/guide/fundamentals/vm-management.mdx
@@ -1,180 +1,184 @@
---
title: VM Management
-description: Managing virtual machines with Lume
+description: Run, configure, and organize your VMs
---
import { Callout } from 'fumadocs-ui/components/callout';
-This guide covers the core operations for managing VMs with Lume.
+Once you've [created a VM](/lume/guide/getting-started/quickstart), here's how to manage it.
-## Listing VMs
+## Quick reference
-```bash
-# List all VMs
-lume ls
+| Task | Command |
+|------|---------|
+| List VMs | `lume ls` |
+| Get details | `lume get my-vm` |
+| Run | `lume run my-vm` |
+| Run headless | `lume run my-vm --no-display` |
+| Stop | `lume stop my-vm` |
+| Clone | `lume clone my-vm backup` |
+| Delete | `lume delete my-vm` |
-# Output includes: name, state, CPU, memory, disk size
-```
-
-## Getting VM Details
+## Run a VM
```bash
-# Get detailed information about a VM
-lume get my-vm
-```
+# Opens VNC window
+lume run my-vm
-This shows:
+# Headless (for automation)
+lume run my-vm --no-display
+```
-- VM state (running, stopped)
-- Resource allocation (CPU, memory, disk)
-- Network configuration
-- Display settings
+### Share files with your VM
-## Running VMs
+Mount a host directory that appears in the VM at `/Volumes/My Shared Files`:
```bash
-# Run with display window
-lume run my-vm
+lume run my-vm --shared-dir ~/Projects
+```
-# Run headless (no display)
-lume run my-vm --no-display
+### Attach USB storage
-# Run with shared directory
-lume run my-vm --shared-dir /path/to/local/folder
+Mount a disk image as USB storage (macOS 15+ only):
-# Run with USB storage device
+```bash
lume run my-vm --usb-storage /path/to/disk.img
```
-## Stopping VMs
+## Stop a VM
```bash
-# Graceful stop (sends shutdown signal)
+# Graceful shutdown
lume stop my-vm
-# Force stop (immediate termination)
+# Force stop (immediate)
lume stop my-vm --force
```
-## Modifying VM Settings
+## Inspect VMs
+
+```bash
+# List all VMs with state, CPU, memory, disk
+lume ls
+
+# Detailed info for one VM
+lume get my-vm
+```
+
+`lume get` shows state, resource allocation, network config, and display settings.
+
+## Change VM settings
+
+<Callout type="warn">
+Stop the VM before changing settings. Disk size can only increase, not decrease.
+</Callout>
```bash
-# Change CPU allocation
+# CPU cores
lume set my-vm --cpu 8
-# Change memory
+# Memory
lume set my-vm --memory 16GB
-# Resize disk (can only increase)
+# Disk (increase only)
lume set my-vm --disk-size 100GB
-# Change display resolution
+# Display resolution
lume set my-vm --display 1920x1080
```
-<Callout type="warn">
- The VM must be stopped before changing settings. Disk size can only be increased, not decreased.
-</Callout>
-
-## Cloning VMs
+## Clone a VM
-Create a copy of an existing VM:
+Cloning creates a full copy—useful for backups or creating variants:
```bash
-# Clone within same storage
-lume clone source-vm cloned-vm
+lume clone my-vm my-vm-backup
+```
-# Clone to different storage location
-lume clone source-vm cloned-vm --source-storage default --dest-storage external-ssd
+Clone between storage locations:
+
+```bash
+lume clone my-vm external-copy \
+ --source-storage default \
+ --dest-storage external-ssd
```
-## Deleting VMs
+## Delete a VM
```bash
-# Delete a VM
lume delete my-vm
-# Delete from specific storage
+# From specific storage
lume delete my-vm --storage external-ssd
```
-## Multiple Storage Locations
+## Storage locations
-Lume supports storing VMs in different locations (e.g., internal drive, external SSD).
+By default, VMs live in `~/.lume`. You can add more locations—useful for external drives or separating projects.
-### Configure Storage
+### Configure storage
```bash
-# List storage locations
+# List locations
lume config storage list
-# Add a new storage location
+# Add a location
lume config storage add external-ssd /Volumes/ExternalSSD/lume
-# Set default storage
+# Set default
lume config storage default external-ssd
-# Remove a storage location
-lume config storage remove old-storage
+# Remove a location
+lume config storage remove old-location
```
-### Using Storage Locations
+### Use storage in commands
+
+Most commands accept `--storage` to target a specific location:
```bash
-# Create VM in specific storage
+# Create in specific storage
lume create my-vm --os macos --ipsw latest --storage external-ssd
-# Run VM from specific storage
+# Run from specific storage
lume run my-vm --storage external-ssd
-
-# Move VM between storage locations
-lume clone source-vm dest-vm --source-storage default --dest-storage external-ssd
-lume delete source-vm --storage default
```
-## Image Caching
-
-When pulling VM images from the registry, Lume can cache the downloaded layers locally to speed up future pulls of the same or similar images. **Caching is disabled by default** to save disk space.
+Without `--storage`, Lume uses the default location or searches all locations.
-### Enable Caching
+### Move a VM between locations
-If you frequently pull images and want faster downloads:
+Clone to the new location, then delete the original:
```bash
-# Enable image caching
-lume config set cachingEnabled true
-
-# Set custom cache directory (optional)
-lume config set cacheDirectory /path/to/cache
+lume clone my-vm my-vm --source-storage default --dest-storage external-ssd
+lume delete my-vm --storage default
```
-### View Cache Settings
+## Image caching
-```bash
-# View current configuration
-lume config get
-```
+When pulling images from a registry, Lume can cache layers locally for faster future pulls. Caching is **disabled by default** to save disk space.
-This displays:
-- Default VM storage location
-- Cache directory path
-- Whether caching is enabled
+```bash
+# Enable caching
+lume config caching set true
-### Clear Cache
+# Set cache directory
+lume config cache set /path/to/cache
-To free up disk space used by cached image layers:
+# View current config
+lume config get
-```bash
-# Remove cached images
+# Clear cache
lume prune
```
<Callout type="info">
- With caching disabled (default), each `lume pull` downloads all image layers fresh. Enable caching if you frequently pull the same images or images that share common base layers.
+Enable caching if you frequently pull the same images or images sharing base layers. With caching disabled, each `lume pull` downloads everything fresh.
</Callout>
-## Next Steps
+## What's next
-- [Unattended Setup](/lume/guide/fundamentals/unattended-setup) - Automate macOS setup
-- [HTTP Server](/lume/guide/advanced/http-server) - Use the REST API
-- [CLI Reference](/lume/reference/cli-reference) - Full command reference
+- [Automate setup](/lume/guide/fundamentals/unattended-setup) with YAML configurations
+- [Use the HTTP API](/lume/guide/advanced/http-server) for programmatic access
+- See all options in the [CLI Reference](/lume/reference/cli-reference)
diff --git a/docs/content/docs/lume/guide/getting-started/faq.mdx b/docs/content/docs/lume/guide/getting-started/faq.mdx
index e4fa5a30df..e04afd1607 100644
--- a/docs/content/docs/lume/guide/getting-started/faq.mdx
+++ b/docs/content/docs/lume/guide/getting-started/faq.mdx
@@ -3,128 +3,143 @@ title: FAQ
description: Frequently asked questions about Lume
---
-### What is the default VM password?
+Common questions about using Lume. For detailed guides, see [VM Management](/lume/guide/fundamentals/vm-management) and [Unattended Setup](/lume/guide/fundamentals/unattended-setup).
+
+## Credentials
+
+### What's the default password?
+
+For VMs created with `--unattended tahoe`:
- **Username**: `lume`
- **Password**: `lume`
-### Where are the VMs stored?
+For manually configured VMs, you set credentials during the Setup Assistant.
-VMs are stored in `~/.lume` by default. You can configure additional storage locations using the `lume config` command.
+## Storage
-### How are images cached?
+### Where are VMs stored?
-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.
+Default location: `~/.lume`
-### Where is the configuration file stored?
+Add more locations with:
-Lume follows the XDG Base Directory specification for the configuration file:
+```bash
+lume config storage add external /Volumes/External/lume
+lume config storage list
+```
-- Configuration is stored in `$XDG_CONFIG_HOME/lume/config.yaml` (defaults to `~/.config/lume/config.yaml`)
+### Do VM disks use their full allocated size?
-By default, other data is stored in:
+No. macOS uses sparse files—a 50GB disk might only use 20GB on your actual drive, growing as needed.
-- VM data: `~/.lume`
-- Cache files: `~/.lume/cache`
+### How do I move a VM to another drive?
-The config file contains settings for:
+Clone it to the new location, then delete the original:
-- VM storage locations and the default location
-- Cache directory location
-- Whether caching is enabled
+```bash
+lume clone my-vm my-vm --source-storage default --dest-storage external
+lume delete my-vm --storage default
+```
-You can view and modify these settings using the `lume config` commands:
+## Configuration
-```bash
-# View current configuration
-lume config get
+### Where's the config file?
-# 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
+`~/.config/lume/config.yaml` (follows XDG Base Directory spec)
-# Manage cache settings
-lume config cache get # Get current cache directory
-lume config cache set <path> # Set cache directory
+View settings with:
-# Manage image caching settings
-lume config caching get # Show current caching status
-lume config caching set <boolean> # Enable or disable image caching
+```bash
+lume config get
```
-### 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:
+### How do I manage cache settings?
```bash
-# Create a VM in a specific storage location
-lume create my-vm --os macos --ipsw latest --storage ssd
+# Check caching status
+lume config caching get
-# Run a VM from a specific storage location
-lume run my-vm --storage ssd
+# Enable/disable caching
+lume config caching set true
-# Delete a VM from a specific storage location
-lume delete my-vm --storage ssd
+# Set cache directory
+lume config cache set /path/to/cache
-# 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
+# Clear cache
+lume prune
```
-If you don't specify a storage location, Lume will use the default one or search across all configured locations.
+## Limits
+
+### How many macOS VMs can I run at once?
+
+Apple's macOS Software License Agreement (section 2.B.iii) limits you to **2 concurrent macOS VMs** per physical Mac. This is a licensing restriction, not a technical one—the Virtualization Framework enforces it automatically.
-### Are VM disks taking up all the disk space?
+Linux VMs have no such limitation. You can run as many as your hardware supports.
-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.
+## Images
-### How do I get the latest macOS restore image URL?
+### How do I get the latest macOS IPSW URL?
```bash
lume ipsw
```
-### Where can I download older macOS IPSW versions?
+### Where can I get older macOS 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).
+Apple only provides the latest IPSW officially. Community archives exist—search "macOS IPSW download" and ensure you get UniversalMac files (for Apple Silicon).
-### How do I delete a VM?
+### How do I install from a specific IPSW?
+
+Download the IPSW first, then:
```bash
-lume delete <name>
+lume create my-vm --os macos --ipsw /path/to/downloaded.ipsw
```
-### How to Install macOS from an IPSW Image
+## Linux VMs
-#### Create a new macOS VM using the latest supported IPSW image:
+### How do I create a Linux VM?
-Run the following command to create a new macOS virtual machine using the latest available IPSW image:
+Linux uses ISO images instead of IPSW. Create the VM, boot with the installer mounted, then run normally:
```bash
-lume create <name> --os macos --ipsw latest
+# Create empty Linux VM
+lume create linux-vm --os linux
+
+# First boot: mount installer ISO
+lume run linux-vm --mount /path/to/ubuntu.iso
+
+# After installation: run normally
+lume run linux-vm
```
-#### Create a new macOS VM using a specific IPSW image:
+## Troubleshooting
-To create a macOS virtual machine from an older or specific IPSW file, first download the desired IPSW (UniversalMac) from a trusted source.
+### VM won't start
-Then, use the downloaded IPSW path:
+1. Check if another VM is running: `lume ls`
+2. Stop any running VMs: `lume stop <name>`
+3. Check available disk space
+4. Try running with `--no-display` to see if it's a VNC issue
-```bash
-lume create <name> --os macos --ipsw <downloaded_ipsw_path>
-```
+### Can't connect to VM via SSH
-### How do I install a custom Linux image?
+1. Ensure SSH is enabled in the VM (System Settings → Sharing → Remote Login)
+2. Get the VM's IP: `lume get my-vm`
+3. Try: `ssh lume@<ip-address>`
-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.
+For VMs created with `--unattended tahoe`, SSH is enabled automatically.
-```bash
-lume create <name> --os linux
+### `lume serve` port already in use
-lume run <name> --mount <path-to-setup-image>
+Another Lume instance is running. Either use it or kill it:
+
+```bash
+# Check what's using port 7777
+lsof -i :7777
-lume run <name>
+# Kill the process
+kill <pid>
```
diff --git a/docs/content/docs/lume/guide/getting-started/installation.mdx b/docs/content/docs/lume/guide/getting-started/installation.mdx
index d1f5656127..0f0714ea1c 100644
--- a/docs/content/docs/lume/guide/getting-started/installation.mdx
+++ b/docs/content/docs/lume/guide/getting-started/installation.mdx
@@ -1,158 +1,138 @@
---
title: Installation
-description: Installation instructions for Lume
+description: Install Lume on your Mac
---
import { Callout } from 'fumadocs-ui/components/callout';
-## System Requirements
-
-- Apple Silicon Mac (M1, M2, M3, M4, etc.)
-- macOS 13.0 or later
-- At least 8GB of RAM (16GB recommended)
-- At least 30GB of free disk space
-
-## Install with Script
-
Install Lume with a single command:
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
```
-By default, Lume is installed with:
-- A **background service** that starts automatically on login
-- An **auto-updater** that checks for updates at login and every 24 hours
-
-### Manual Start (No Background Service)
+This installs Lume with a background service (starts on login) and auto-updater (checks every 24 hours).
-If you prefer to start the Lume API service manually when needed, use the `--no-background-service` option:
+### Verify it worked
```bash
-/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)" -- --no-background-service
-```
+lume --version
+# Lume 0.2.27
-<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 to use tools or libraries that rely on the Lume API (such as the
- Computer Use Agent).
-</Callout>
+lume --help
+# OVERVIEW: Lume - CLI and framework for macOS VMs...
+```
-### Disable Auto-Updates
+If you see version output, you're ready to [create your first VM](/lume/guide/getting-started/quickstart).
-If you prefer to manage updates manually, use the `--no-auto-updater` option:
+## Requirements
-```bash
-/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)" -- --no-auto-updater
-```
+- Apple Silicon Mac (M1/M2/M3/M4)
+- macOS 13.0 or later
+- 8GB RAM minimum (16GB recommended)
+- 30GB free disk space
-You can combine options to disable both the background service and auto-updates:
+## Installation options
-```bash
-/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)" -- --no-background-service --no-auto-updater
-```
+The default install includes a background service and auto-updater. You can disable either:
-## Manual Download and Installation
+| Option | Command |
+|--------|---------|
+| No background service | `install.sh -- --no-background-service` |
+| No auto-updates | `install.sh -- --no-auto-updater` |
+| Neither | `install.sh -- --no-background-service --no-auto-updater` |
-You 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.
+Full command with options:
-## Verify Installation
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)" -- --no-background-service
+```
-After installation, verify Lume is working:
+<Callout type="info">
+Without the background service, you'll need to run `lume serve` manually when using tools that rely on the Lume API (like the Computer Use Agent).
+</Callout>
-```bash
-# Check version
-lume --version
+## Manual installation
-# List available commands
-lume --help
-```
+Download `lume.pkg.tar.gz` from the [latest release](https://github.com/trycua/cua/releases?q=lume&expanded=true), extract it, and install the package.
-## Managing the Background Service
+## Managing services
-If you installed with the background service (default), you can manage it with these commands:
+### Background service
```bash
-# Check if the daemon is running
+# Check if running
launchctl list | grep com.trycua.lume_daemon
-# View daemon logs
+# View logs
tail -f /tmp/lume_daemon.log
-# Manually start the Lume API service
+# Start manually (if service disabled)
lume serve
```
-## Managing Auto-Updates
-
-If you installed with auto-updates enabled (default), Lume will automatically check for and install updates at login and every 24 hours.
+### Auto-updater
```bash
-# Check if the auto-updater is running
+# Check if running
launchctl list | grep com.trycua.lume_updater
-# View auto-updater logs
+# View logs
tail -f /tmp/lume_updater.log
-# Manually run an update check
+# Manual update check
~/.local/bin/lume-update
```
-### Disable Auto-Updates After Installation
-
To disable auto-updates after installation:
```bash
launchctl unload ~/Library/LaunchAgents/com.trycua.lume_updater.plist
rm ~/Library/LaunchAgents/com.trycua.lume_updater.plist
-rm ~/.local/bin/lume-update
```
-## Uninstall Lume
-
-### Remove the Background Service
+## Uninstall
-If you installed Lume with the background service, first remove the daemon:
+Remove Lume completely:
```bash
-launchctl unload ~/Library/LaunchAgents/com.trycua.lume_daemon.plist
-rm ~/Library/LaunchAgents/com.trycua.lume_daemon.plist
-```
+# Stop and remove background service
+launchctl unload ~/Library/LaunchAgents/com.trycua.lume_daemon.plist 2>/dev/null
+rm -f ~/Library/LaunchAgents/com.trycua.lume_daemon.plist
-### Remove the Auto-Updater
+# Stop and remove auto-updater
+launchctl unload ~/Library/LaunchAgents/com.trycua.lume_updater.plist 2>/dev/null
+rm -f ~/Library/LaunchAgents/com.trycua.lume_updater.plist
+rm -f ~/.local/bin/lume-update
-If you installed with auto-updates enabled, remove the updater:
+# Optional: Remove cached images (run before removing binary)
+lume prune
-```bash
-launchctl unload ~/Library/LaunchAgents/com.trycua.lume_updater.plist
-rm ~/Library/LaunchAgents/com.trycua.lume_updater.plist
-rm ~/.local/bin/lume-update
+# Remove Lume binary
+rm -f $(which lume)
+
+# Optional: Remove VMs and config
+rm -rf ~/.lume
+rm -rf ~/.config/lume
```
-### Remove Lume Binary
+## Troubleshooting
-First, locate the Lume binary:
+**`lume: command not found`** — The install location (`~/.local/bin`) isn't in your PATH. Add it:
```bash
-which lume
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
```
-Then remove it:
+**Background service not starting** — Check the daemon logs:
```bash
-rm $(which lume)
+tail -50 /tmp/lume_daemon.log
```
-### Clean Up VM Images
-
-Optionally, remove downloaded VM images:
-
-```bash
-# Remove all Lume VM images
-rm -rf ~/.cache/lume-images
-```
+**Permission errors** — The installer needs to create files in `~/.local/bin` and `~/Library/LaunchAgents`. Ensure you have write access to these directories.
-## Next Steps
+**Intel Mac or Linux** — Lume requires Apple Silicon. It won't work on Intel Macs or other platforms.
-- [Quickstart](/lume/guide/getting-started/quickstart) - Create your first VM
-- [Prebuilt Images](/lume/guide/fundamentals/prebuilt-images) - Available images in the registry
+Ready to create a VM? Head to the [Quickstart](/lume/guide/getting-started/quickstart).
diff --git a/docs/content/docs/lume/guide/getting-started/introduction.mdx b/docs/content/docs/lume/guide/getting-started/introduction.mdx
index 69ccc1df3f..8a98f167bc 100644
--- a/docs/content/docs/lume/guide/getting-started/introduction.mdx
+++ b/docs/content/docs/lume/guide/getting-started/introduction.mdx
@@ -5,73 +5,54 @@ description: Introduction to Lume - the macOS VM CLI and framework
import { Callout } from 'fumadocs-ui/components/callout';
-Lume is a lightweight Command Line Interface and local API server for creating, running, and managing **macOS and Linux virtual machines** with near-native performance on Apple Silicon, using Apple's [Virtualization.Framework](https://developer.apple.com/documentation/virtualization).
+Lume is a VM runtime for building AI agents, running CI/CD pipelines, and automating macOS. It uses Apple's native Virtualization Framework to run macOS and Linux VMs at near-native speed on Apple Silicon.
-## Why Lume?
+```bash
+lume create test-vm --os macos --ipsw latest
+lume run test-vm
+```
-Before Lume, running macOS VMs on Apple Silicon required complex setup or expensive commercial tools. Lume provides:
+A single binary with an HTTP API. Create a VM, run it headlessly, control it programmatically.
-- **Simple CLI** - Intuitive commands for VM lifecycle management
-- **Near-native performance** - Built on Apple's Virtualization Framework
-- **Prebuilt images** - Ready-to-use macOS and Linux images
-- **HTTP API** - RESTful API for tool integration
-- **Open source** - MIT licensed, community-driven
+## Architecture
-## How It Works
+![Lume Architecture](/img/lume-architecture.png)
-Lume leverages Apple's Virtualization Framework to create hardware-accelerated VMs that run at near-native speed. The framework provides:
+You can use Lume directly via CLI, or run `lume serve` to expose an HTTP API for programmatic access. The [Computer SDK](/cua/reference/computer-sdk) uses this API to automate macOS interactions.
-- **Para-virtualized devices** - High-performance network and storage
-- **GPU acceleration** - Hardware graphics support
-- **Rosetta 2 support** - Run x86 Linux binaries on ARM VMs
+## How it works
-## Architecture
+Lume is a thin layer over Apple's [Virtualization Framework](https://developer.apple.com/documentation/virtualization), which provides hardware-accelerated virtualization on Apple Silicon. This gives you:
-```
-┌─────────────────────────────────────────────────┐
-│ Your Tools │
-│ (Cua Agent, Scripts, CI/CD, etc.) │
-└───────────────────┬─────────────────────────────┘
- │
- ┌─────────▼─────────┐
- │ Lume HTTP API │ ← lume serve (port 7777)
- │ (REST Server) │
- └─────────┬─────────┘
- │
- ┌─────────▼─────────┐
- │ Lume CLI │ ← lume create, run, stop...
- └─────────┬─────────┘
- │
- ┌───────────────▼───────────────┐
- │ Apple Virtualization.Framework │
- └───────────────┬───────────────┘
- │
- ┌───────────────▼───────────────┐
- │ macOS / Linux VMs │
- └───────────────────────────────┘
-```
+- **Native speed** — CPU instructions execute directly via hardware virtualization
+- **Paravirtualized graphics** — Basic GPU support via Apple's virtualization layer (limited to GPU Family 5)
+- **Efficient storage** — Sparse disk files only consume actual usage, not allocated size
+- **Rosetta 2 support** — Run x86 Linux binaries in ARM Linux VMs
+- **Automated golden images** — Go from IPSW to fully configured macOS VM without manual intervention
+- **Registry support** — Pull and push VM images from GHCR or GCS registries
+
+## When to use Lume
+
+**Testing across macOS versions** — Spin up a VM with a specific macOS version, test your software, tear it down. No need to maintain multiple physical machines.
+
+**Automating macOS tasks** — Combine Lume with [Unattended Setup](/lume/guide/fundamentals/unattended-setup) to create pre-configured VMs. The setup automation uses VNC and OCR to click through the Setup Assistant without manual intervention.
-## Use Cases
+**Running CI/CD locally** — Test your macOS builds in isolated VMs before pushing to remote CI. The `--no-display` flag runs VMs headlessly.
-### Development and Testing
+**Sandboxing risky operations** — Need to test untrusted software or destructive scripts? Run them in a VM, then delete it. Clone a known-good VM to reset to a clean state instantly.
-- Test software on different macOS versions
-- Isolate development environments
-- Run CI/CD pipelines locally
+**Building AI agents** — Lume powers the [Cua Computer SDK](/cua/reference/computer-sdk), providing VMs that AI models can interact with through screenshots and input simulation.
-### Automation
+<Callout type="info" title="Used by Anthropic">
+Apple's Virtualization Framework—the same technology Lume is built on—powers [Claude Cowork](https://www.anthropic.com/news/cowork), Anthropic's sandboxed environment for Claude Code. It downloads a Linux root filesystem and boots it in an isolated VM where Claude can safely execute commands without access to your broader system.
+</Callout>
-- Automate macOS setup with unattended configurations
-- Script VM operations via CLI or API
-- Integrate with Computer Use Agent for UI automation
+## What Lume doesn't do
-### Sandboxing
+Lume runs VMs locally on your Mac. It's not a cloud service, container runtime, or cluster orchestrator. If you need to run VMs in the cloud or across multiple machines, look elsewhere.
-- Create disposable environments
-- Test potentially risky operations safely
-- Reset to clean state instantly
+Lume also requires Apple Silicon—it won't work on Intel Macs or other platforms.
-## Next Steps
+## Get started
-- [Installation](/lume/guide/getting-started/installation) - Install Lume on your Mac
-- [Quickstart](/lume/guide/getting-started/quickstart) - Create your first VM
+Ready to try it? [Install Lume](/lume/guide/getting-started/installation) and create your first VM in the [Quickstart](/lume/guide/getting-started/quickstart).
diff --git a/docs/content/docs/lume/guide/getting-started/quickstart.mdx b/docs/content/docs/lume/guide/getting-started/quickstart.mdx
index 41da4b331a..e83f04efd1 100644
--- a/docs/content/docs/lume/guide/getting-started/quickstart.mdx
+++ b/docs/content/docs/lume/guide/getting-started/quickstart.mdx
@@ -5,88 +5,124 @@ description: Create and run your first VM with Lume
import { Callout } from 'fumadocs-ui/components/callout';
-This guide walks you through creating and running your first macOS VM with Lume.
+In under 5 minutes, you'll have a macOS VM running on your Mac.
-<Callout type="warn">
- **Registry Maintenance Notice**: The prebuilt images in the [trycua registry](https://github.com/orgs/trycua/packages) are no longer actively
- maintained. For new setups, we recommend building custom images using the [Unattended Setup](/lume/guide/fundamentals/unattended-setup) feature
- to configure macOS VMs according to your specific needs.
-</Callout>
+## Get the macOS restore image
+
+Before creating a VM, you need a macOS restore image (IPSW). You have two options:
-## Create a Custom VM
+### Option 1: Download manually (recommended)
-For more control, create a VM from scratch:
+Get the download URL and download the IPSW file yourself:
```bash
-# Create a new macOS VM using the latest IPSW
-lume create my-vm --os macos --ipsw latest
+# Get the latest IPSW download URL
+lume ipsw
+# Output: https://updates.cdn-apple.com/...
-# Run the VM
-lume run my-vm
+# Download it (using curl, wget, or your browser)
+curl -L -o ~/Downloads/macos.ipsw "$(lume ipsw)"
+
+# Create the VM with the downloaded file
+lume create my-vm --os macos --ipsw ~/Downloads/macos.ipsw
```
-### Customize Resources
+This approach is better for slower connections since you can resume downloads and reuse the IPSW for multiple VMs.
+
+### Option 2: Let Lume download it
+
+Use `--ipsw latest` and Lume will download the restore image automatically:
```bash
-# Create with custom resources
-lume create my-vm --os macos --ipsw latest \
- --cpu 4 \
- --memory 8GB \
- --disk-size 100GB
+lume create my-vm --os macos --ipsw latest
+```
+
+<Callout type="info">
+The IPSW file is ~15GB. If you plan to create multiple VMs, downloading manually and reusing the file saves time and bandwidth.
+</Callout>
+
+## Run your VM
+
+```bash
+lume run my-vm
```
-Default values:
+A VNC window opens with the macOS Setup Assistant. Complete the setup manually, or use [Unattended Setup](/lume/guide/fundamentals/unattended-setup) to automate it.
-- **CPU**: 4 cores
-- **Memory**: 8GB
-- **Disk**: 50GB
+## Create a VM with custom resources
-## Basic VM Operations
+By default, Lume creates VMs with 4 CPU cores, 8GB memory, and a 50GB disk. Override any of these:
```bash
-# List all VMs
-lume ls
+lume create dev-vm --os macos --ipsw latest \
+ --cpu 8 \
+ --memory 16GB \
+ --disk-size 100GB
+```
-# Get VM details
-lume get my-vm
+| Resource | Default | Notes |
+|----------|---------|-------|
+| CPU | 4 cores | Max is your Mac's core count |
+| Memory | 8GB | Leave headroom for your host |
+| Disk | 50GB | Uses sparse files—only consumes actual usage |
-# Stop a running VM
-lume stop my-vm
+## Automate the Setup Assistant
-# Delete a VM
-lume delete my-vm
+Skip manual setup entirely with the `--unattended` flag:
+
+```bash
+lume create my-vm --os macos --ipsw latest --unattended tahoe
```
-## Run Without Display
+The `tahoe` preset runs through the Setup Assistant automatically, creating a user `lume` with password `lume` and enabling SSH. This takes 10-15 minutes but requires no interaction.
-For headless operation (automation, CI/CD):
+For custom configurations, see [Unattended Setup](/lume/guide/fundamentals/unattended-setup).
+
+## Run a VM
```bash
-# Run without opening a display window
+# With display (VNC window opens)
+lume run my-vm
+
+# Headless (for automation, CI/CD)
lume run my-vm --no-display
```
-## Clone a VM
+When running headless, connect via SSH (if enabled) or VNC client.
-Create a copy of an existing VM:
+## Common operations
```bash
-lume clone my-vm my-vm-copy
+# List all VMs
+lume ls
+
+# Get details about a VM
+lume get my-vm
+
+# Stop a running VM
+lume stop my-vm
+
+# Clone a VM
+lume clone my-vm my-vm-backup
+
+# Delete a VM
+lume delete my-vm
```
-## Automate VM Configuration
+## Share files with your VM
-Use unattended setup to automatically run through the macOS Setup Assistant:
+Mount a host directory inside the VM:
```bash
-# Create VM and auto-configure with the tahoe preset
-lume create my-vm --os macos --ipsw latest --unattended tahoe
+lume run my-vm --shared-dir ~/Projects
```
-This creates a VM with user `lume` (password: `lume`) and configures common settings automatically. See [Unattended Setup](/lume/guide/fundamentals/unattended-setup) for custom configurations.
+Inside the VM, find your files at `/Volumes/My Shared Files`.
+
+## What's next
-## Next Steps
+Now that you have a VM running, you can:
-- [VM Management](/lume/guide/fundamentals/vm-management) - Learn more VM operations
-- [Unattended Setup](/lume/guide/fundamentals/unattended-setup) - Automate VM configuration
-- [CLI Reference](/lume/reference/cli-reference) - Full command reference
+- Learn more [VM operations](/lume/guide/fundamentals/vm-management) like modifying resources and managing storage locations
+- Set up [automated configuration](/lume/guide/fundamentals/unattended-setup) with custom YAML files
+- Integrate with your tools via the [HTTP API](/lume/guide/advanced/http-server)
diff --git a/docs/content/docs/lume/index.mdx b/docs/content/docs/lume/index.mdx
index 9c2ed10690..ab34766bb8 100644
--- a/docs/content/docs/lume/index.mdx
+++ b/docs/content/docs/lume/index.mdx
@@ -7,39 +7,50 @@ github:
import { Callout } from 'fumadocs-ui/components/callout';
-Lume is a lightweight CLI and local API server for creating, running, and managing **macOS and Linux virtual machines** with near-native performance on Apple Silicon.
-
-Built on Apple's [Virtualization.Framework](https://developer.apple.com/documentation/virtualization), Lume was the first open-source product released by trycua - providing the foundation for the Computer Use Agent SDK.
-
-## Key Features
-
-- **Near-native performance** - Run macOS VMs at native speed using Apple's Virtualization Framework
-- **Simple CLI** - Create, run, and manage VMs with intuitive commands
-- **Unattended setup** - Automate macOS installation and configuration with YAML files
-- **HTTP API** - Integrate with your tools via the built-in REST API server
-
-## Quick Start
+Lume lets you create and run macOS and Linux VMs on Apple Silicon—no Docker, no Kubernetes, no cloud account required. Just a CLI that works.
```bash
# Install Lume
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
-# Create a custom macOS VM
+# Create and run a macOS VM
lume create my-vm --os macos --ipsw latest
-
-# Run the VM
lume run my-vm
```
-<Callout title="System Requirements">
- - Apple Silicon Mac (M1, M2, M3, M4, etc.) - macOS 13.0 or later - At least 8GB of RAM (16GB
- recommended) - At least 30GB of free disk space
+That's it. Your VM boots in seconds, running at native speed through Apple's [Virtualization Framework](https://developer.apple.com/documentation/virtualization)—the same technology that powers [Claude Cowork](https://www.anthropic.com/news/cowork)'s sandboxed execution environment.
+
+## What you can do
+
+- **Run macOS VMs** at native speed on your M1/M2/M3/M4 Mac
+- **Automate setup** with YAML configs that handle the Setup Assistant for you
+- **Integrate with your tools** via CLI or the built-in HTTP API
+- **Script everything**—no manual clicking required
+
+## Get started
+
+The fastest path: install Lume, create a VM with the `--unattended tahoe` flag, and you'll have a fully-configured macOS VM with SSH enabled in minutes.
+
+```bash
+lume create dev-vm --os macos --ipsw latest --unattended tahoe
+lume run dev-vm --no-display
+```
+
+This creates a VM with user `lume` (password: `lume`) ready for automation.
+
+For step-by-step instructions, see the [Installation Guide](/lume/guide/getting-started/installation). To understand how Lume fits into the bigger picture, read [What is Lume?](/lume/guide/getting-started/introduction).
+
+<Callout type="info" title="Requirements">
+Apple Silicon Mac (M1 or later), macOS 13.0+, 8GB RAM minimum (16GB recommended), 30GB free disk space.
</Callout>
-## Next Steps
+## Learn more
-- [Installation Guide](/lume/guide/getting-started/installation) - Detailed installation options
-- [Quickstart](/lume/guide/getting-started/quickstart) - Create your first VM
-- [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
+| Guide | Description |
+|-------|-------------|
+| [Quickstart](/lume/guide/getting-started/quickstart) | Create your first VM |
+| [VM Management](/lume/guide/fundamentals/vm-management) | Run, stop, clone, and configure VMs |
+| [Unattended Setup](/lume/guide/fundamentals/unattended-setup) | Automate macOS configuration |
+| [HTTP API](/lume/guide/advanced/http-server) | Integrate via REST |
+| [CLI Reference](/lume/reference/cli-reference) | All commands |
+| [API Reference](/lume/reference/http-api) | All endpoints |
diff --git a/docs/content/docs/lume/meta.json b/docs/content/docs/lume/meta.json
index cc9ab1a135..af3275ad8e 100644
--- a/docs/content/docs/lume/meta.json
+++ b/docs/content/docs/lume/meta.json
@@ -1,5 +1,5 @@
{
"title": "Lume",
"description": "CLI and framework for macOS VMs using Apple Virtualization",
- "pages": ["guide", "reference"]
+ "pages": ["guide", "examples", "reference"]
}
diff --git a/docs/content/docs/lume/reference/cli-reference.mdx b/docs/content/docs/lume/reference/cli-reference.mdx
index 966d58d7b2..1a04ae127f 100644
--- a/docs/content/docs/lume/reference/cli-reference.mdx
+++ b/docs/content/docs/lume/reference/cli-reference.mdx
@@ -42,7 +42,7 @@ Create a new virtual machine
- `--display` - Display resolution (e.g., 1024x768) (default: 1024x768)
- `--ipsw` - Path to IPSW file or 'latest' for macOS VMs
- `--storage` - VM storage location to use
-- `--unattended` - [Preview] Preset name or path to YAML config file for unattended macOS Setup Assistant automation. Built-in presets: tahoe. Only supported for macOS VMs.
+- `--unattended` - [Preview] Preset name or path to YAML config file for unattended macOS Setup Assistant automation. Built-in presets: sequoia, tahoe. Only supported for macOS VMs.
- `--debug-dir` - Custom directory for debug screenshots during unattended setup (defaults to unique folder in system temp)
- `--vnc-port` - Port to use for the VNC server during unattended setup. Defaults to 0 (auto-assign) (default: 0)
@@ -264,7 +264,7 @@ View lume serve logs
**Options:**
-- `--unattended` - Preset name or path to YAML config file for unattended macOS Setup Assistant automation. Built-in presets: tahoe.
+- `--unattended` - Preset name or path to YAML config file for unattended macOS Setup Assistant automation. Built-in presets: sequoia, tahoe.
- `--storage` - VM storage location to use or direct path to VM location
- `--vnc-port` - Port to use for the VNC server. Defaults to 0 (auto-assign) (default: 0)
- `--debug-dir` - Custom directory for debug screenshots (defaults to unique folder in system temp)
diff --git a/docs/public/img/lume-architecture.png b/docs/public/img/lume-architecture.png
new file mode 100644
index 0000000000..79f1d90078
Binary files /dev/null and b/docs/public/img/lume-architecture.png differ
diff --git a/docs/src/app/api/copilotkit/route.ts b/docs/src/app/api/copilotkit/route.ts
index 3b95f5e491..4124dd5401 100644
--- a/docs/src/app/api/copilotkit/route.ts
+++ b/docs/src/app/api/copilotkit/route.ts
@@ -396,7 +396,7 @@ const docsAgent = new AnthropicSafeBuiltInAgent({
prompt: `You are a helpful assistant for Cua (Computer Use Agent) and Cua-Bench documentation.
Be concise and helpful. Answer questions about the documentation accurately.
-Use Cua as the name of the product and CUA for Computer Use Agent.
+Use "Cua" as the product name. "CUA" stands for Computer Use Agent.
You have access to tools for searching the Cua documentation and code:
- query_docs_db: SQL queries on the documentation database (full-text search via FTS5)
diff --git a/docs/src/providers/copilotkit-provider.tsx b/docs/src/providers/copilotkit-provider.tsx
index f574252bbd..02451bcd94 100644
--- a/docs/src/providers/copilotkit-provider.tsx
+++ b/docs/src/providers/copilotkit-provider.tsx
@@ -7,10 +7,10 @@ if (typeof window !== 'undefined') {
}
import {
+ CatchAllActionRenderProps,
CopilotKit,
- useRenderToolCall,
useCopilotChat,
- CatchAllActionRenderProps,
+ useRenderToolCall,
} from '@copilotkit/react-core';
import {
CopilotPopup,
@@ -18,10 +18,10 @@ import {
useChatContext,
} from '@copilotkit/react-ui';
import '@copilotkit/react-ui/styles.css';
-import { ReactNode, useMemo, useState, useCallback, useEffect, useRef, memo } from 'react';
import posthog from 'posthog-js';
+import { memo, ReactNode, useCallback, useEffect, useMemo, useRef, useState } from 'react';
-const DOCS_INSTRUCTIONS = `You are a helpful assistant for Cua, Cua-Bench and Lume documentation. Be concise and helpful. Use clear paragraph breaks between sections.`;
+const DOCS_INSTRUCTIONS = `You are a helpful assistant for Cua, Cua-Bench, and Lume documentation. Be concise and helpful. Use clear paragraph breaks between sections.`;
interface CopilotKitProviderProps {
children: ReactNode;
@@ -341,16 +341,14 @@ function CopilotPopupWithFeedback() {
<CopilotPopup
instructions={DOCS_INSTRUCTIONS}
labels={{
- title: 'CUA Docs Assistant',
+ title: 'Cua Docs Assistant',
initial: `Hello!
-I'm an agent that can search cua's docs and code to help answer questions
-
-Ask me anything about CUA!
+I can search Cua's documentation and code to answer your questions.
-This is currently an **experimental** feature.
+Ask me anything about Cua!
-Please refer to the source documentation for the most accurate information.`,
+This is an **experimental** feature. Refer to the source documentation for the most accurate information.`,
}}
AssistantMessage={CustomAssistantMessage}
Header={CustomHeader}
diff --git a/libs/lume/Package.resolved b/libs/lume/Package.resolved
index 9de98e1e25..bc561a9be5 100644
--- a/libs/lume/Package.resolved
+++ b/libs/lume/Package.resolved
@@ -1,5 +1,5 @@
{
- "originHash" : "ea1328493969a58996465b91a14c2bc352d9c779bb1eb5aaaa8b740fafa5eec1",
+ "originHash" : "ed46cd7e7ee1e4dbe96119cd4c31378f844f34f7da24d4a76eb473505049f454",
"pins" : [
{
"identity" : "dynamic",
diff --git a/libs/lume/resources/unattended-sequoia.yml b/libs/lume/resources/unattended-sequoia.yml
new file mode 100644
index 0000000000..ddfa80cab3
--- /dev/null
+++ b/libs/lume/resources/unattended-sequoia.yml
@@ -0,0 +1,288 @@
+# Unattended macOS Sequoia Setup Assistant Configuration
+# Use with: lume create my-vm --os macOS --ipsw latest --unattended resources/unattended-sequoia.yml
+
+# Seconds to wait after VM boots before starting automation
+boot_wait: 30
+
+boot_commands:
+ # Wait for greeting screen to appear (shows "Hello" animation cycling through languages)
+ # The boot_wait should be enough for the VM to reach this screen
+ # Note: VM framebuffer is 1920x1440 (Retina-scaled)
+ - "<delay 5>"
+
+ # Press spacebar to dismiss the greeting screen ("Hello" animation)
+ - "<space>"
+ - "<delay 2>"
+
+ # Language selection screen
+ # Wait for "English" to be visible in the list (may take a moment as languages cycle)
+ - "<wait 'English', timeout=120>"
+ - "<delay 1>"
+
+ # Type "English" to filter the list and select it, then press Enter
+ - "<type 'English'>"
+ - "<delay 1>"
+ - "<enter>"
+ - "<delay 2>"
+
+ # Country/Region selection
+ - "<wait 'Country or Region'>"
+ - "<delay 1>"
+ # Click in the center of the list area to give it focus before typing
+ - "<click_at 960,900>"
+ - "<delay 1>"
+ # Type to filter the country list
+ - "<type 'United States'>"
+ - "<delay 1>"
+ # Press Enter to select the filtered item in the list
+ - "<enter>"
+ - "<delay 1>"
+ # Click Continue button to proceed
+ - "<click 'Continue'>"
+ - "<delay 2>"
+
+ # Transfer Your Data to This Mac (Migration Assistant)
+ - "<wait 'Transfer Your Data'>"
+ - "<delay 30>" # wait for refresh
+ # Use tab navigation to select "Set up as new" (4th option)
+ - "<click 'Set up as new'>"
+ - "<delay 2>"
+ - "<click 'Continue'>"
+ - "<delay 2>"
+
+ # Written and Spoken Languages screen (appears AFTER "Set up as new")
+ - "<wait 'Written and Spoken Languages'>"
+ - "<delay 1>"
+ - "<click 'Continue'>"
+ - "<delay 2>"
+
+ # Accessibility screen - skip it
+ - "<wait 'Accessibility'>"
+ - "<delay 1>"
+ - "<click 'Not Now'>"
+ - "<delay 2>"
+
+ # Data & Privacy screen
+ - "<wait 'Data & Privacy'>"
+ - "<delay 1>"
+ - "<click 'Continue'>"
+ - "<delay 2>"
+
+ # Create a Mac Account
+ # Initial focus is on avatar picker (6 icons: +, panda, cow, fox, owl, etc.)
+ # Need to tab 6 times to reach Full Name field
+ # Field order after avatar: Full Name -> Account Name (auto-filled) -> Password -> Verify Password -> Hint -> Checkbox -> Continue
+ - "<wait 'Create a Mac Account'>"
+ - "<delay 1>"
+ # Type Full Name
+ - "<type 'lume'>"
+ - "<tab>"
+ # Skip Account Name (auto-filled from Full Name)
+ - "<tab>"
+ # Type Password
+ - "<type 'lume'>"
+ - "<tab>"
+ # Type Verify Password
+ - "<type 'lume'>"
+ - "<tab>"
+ # Skip Hint field
+ - "<tab>"
+ # Untoggle "Allow computer account password to be reset with Apple Account" checkbox
+ - "<space>"
+ - "<delay 1>"
+ # Click Continue button
+ - "<click 'Continue'>"
+ - "<delay 2>"
+
+ # Sign In to Your Apple Account - skip it
+ # Wait for "Email or Phone Number" to appear (indicates page is fully loaded and buttons are clickable)
+ - "<wait 'Email or Phone Number'>"
+ - "<delay 1>"
+ - "<click 'Set Up Later'>"
+ - "<delay 1>"
+ # Confirmation popup: "Are you sure you want to skip signing in with an Apple Account?"
+ # Tab to move focus to "Skip" button, then press Enter
+ - '<wait "Don''t Skip">'
+ - "<delay 1>"
+ - "<tab>"
+ - "<delay 1>"
+ - "<enter>"
+ - "<delay 2>"
+
+ # Terms and Conditions
+ # "Agree" appears in license text, so use index=-1 to click the last occurrence (the button)
+ - "<wait 'Terms and Conditions'>"
+ - "<delay 1>"
+ - "<click 'Agree', index=-1>"
+ - "<delay 1>"
+ # Confirmation popup: "I have read and agree to the macOS Software License Agreement"
+ # Modal "Agree" button is above the grayed-out background button, so use index=0 (first/topmost)
+ - "<wait 'I have read and agree'>"
+ - "<delay 1>"
+ - "<click 'Agree', index=0>"
+ - "<delay 2>"
+
+ # Enable Location Services (skip it)
+ - "<wait 'Enable Location Services'>"
+ - "<delay 1>"
+ - "<click 'Continue'>"
+ - "<delay 1>"
+ # Confirmation popup: "Are you sure you don't want to use Location Services?"
+ - '<wait "Don''t Use">'
+ - "<delay 1>"
+ - "<enter>"
+ - "<delay 2>"
+
+ # Select Your Time Zone
+ - "<wait 'Select Your Time Zone'>"
+ - "<delay 1>"
+ - "<click 'Continue'>"
+ - "<delay 2>"
+
+ # Analytics
+ - "<wait 'Analytics'>"
+ - "<delay 1>"
+ - "<click 'Continue'>"
+ - "<delay 2>"
+
+ # Screen Time
+ - "<wait 'Screen Time'>"
+ - "<delay 1>"
+ - "<click 'Set Up Later'>"
+ - "<delay 2>"
+
+ # Siri (longer timeout as Screen Time page can be slow)
+ - "<wait 'Siri', timeout=300>"
+ - "<delay 1>"
+ - "<click 'Continue'>"
+ - "<delay 2>"
+
+ # Select a Siri Voice
+ - "<wait 'Select a Siri Voice'>"
+ - "<delay 1>"
+ - "<click 'Choose For Me'>"
+ - "<delay 2>"
+
+ # Improve Siri & Dictation - select "Not Now" option
+ - "<wait 'Improve Siri'>"
+ - "<delay 1>"
+ - "<click 'Not Now'>"
+ - "<delay 1>"
+ - "<click 'Continue'>"
+ - "<delay 2>"
+
+ # Choose Your Look (Light/Dark mode)
+ - "<wait 'Choose Your Look'>"
+ - "<delay 1>"
+ - "<click 'Continue'>"
+ - "<delay 2>"
+
+ # Update Mac Automatically
+ - "<wait 'Update Mac Automatically'>"
+ - "<delay 1>"
+ - "<click 'Continue'>"
+ - "<delay 2>"
+
+ # Welcome screen - final step
+ - "<wait 'Welcome to Mac'>"
+ - "<delay 2>"
+ - "<space>"
+ - "<delay 5>"
+
+ # Setup complete - wait for desktop to fully load
+ - "<delay 30>"
+
+ # Click on desktop to give it keyboard focus
+ # Without this, hotkeys won't work (you'll hear the "trrr" error sound)
+ - "<click_at 960,540>"
+ - "<delay 1>"
+
+ # Open Spotlight with Cmd+Space
+ - "<cmd+space>"
+ - "<delay 2>"
+
+ # Type "Terminal" to search for Terminal app
+ - "<type 'Terminal'>"
+ - "<delay 1>"
+
+ # Press Enter to launch Terminal
+ - "<enter>"
+ - "<delay 3>"
+
+ # ============================================
+ # 1. Enable SSH (Remote Login)
+ # ============================================
+ # Enable Remote Login (SSH) using launchctl (works without Full Disk Access)
+ - "<type 'sudo launchctl load -w /System/Library/LaunchDaemons/ssh.plist'>"
+ - "<enter>"
+ - "<delay 1>"
+
+ # Enter the password when prompted
+ - "<type 'lume'>"
+ - "<enter>"
+ - "<delay 2>"
+
+ # ============================================
+ # 2. Enable Auto-Login (macOS Ventura+)
+ # ============================================
+ # Use sysadminctl to enable auto-login for the lume user
+ - "<type 'sudo sysadminctl -autologin set -userName lume -password lume'>"
+ - "<enter>"
+ - "<delay 2>"
+
+ # ============================================
+ # 3. Enable Full Disk Access for Remote Users
+ # ============================================
+ # This requires navigating System Settings GUI since TCC.db is SIP-protected
+
+ # Enable full keyboard navigation so Tab works on all UI elements
+ - "<type 'defaults write NSGlobalDomain AppleKeyboardUIMode -int 3'>"
+ - "<enter>"
+ - "<delay 1>"
+
+ # Close Terminal
+ - "<cmd+q>"
+ - "<delay 1>"
+
+ # Open Spotlight and search for System Settings
+ - "<cmd+space>"
+ - "<delay 2>"
+ - "<type 'System Settings'>"
+ - "<delay 1>"
+ - "<enter>"
+ - "<delay 3>"
+
+ # Click on the search bar, then search for Remote Login
+ - "<click 'Search'>"
+ - "<delay 1>"
+ - "<type 'Remote'>"
+ - "<delay 2>"
+ - "<click 'Remote login'>"
+ - "<delay 2>"
+
+ # Tab twice to reach the "Allow full disk access" toggle, then Space to toggle
+ - "<tab>"
+ - "<delay 0.3>"
+ - "<space>"
+ - "<delay 2>"
+
+ # Close System Settings
+ - "<cmd+q>"
+ - "<delay 1>"
+
+ # ============================================
+ # Setup Complete!
+ # ============================================
+ # SSH is now enabled - Connect with: ssh lume@<ip-address> (password: lume)
+ # Auto-login is enabled - VM will boot directly to desktop
+ # Full disk access for remote users is enabled via TCC database
+
+# Health check to verify setup was successful
+# This will SSH into the VM to confirm SSH is working
+health_check:
+ type: ssh
+ user: lume
+ password: lume
+ timeout: 30
+ retries: 5
+ retry_delay: 10
diff --git a/libs/lume/scripts/build/build-debug.sh b/libs/lume/scripts/build/build-debug.sh
index 452e20c326..b0259fb345 100755
--- a/libs/lume/scripts/build/build-debug.sh
+++ b/libs/lume/scripts/build/build-debug.sh
@@ -1,4 +1,12 @@
#!/bin/sh
+# Get the directory where this script is located
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Navigate to the lume root directory (two levels up from scripts/build/)
+LUME_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+cd "$LUME_DIR"
+
swift build --product lume
codesign --force --entitlement resources/lume.entitlements --sign - .build/debug/lume
diff --git a/libs/lume/scripts/build/build-release-notarized.sh b/libs/lume/scripts/build/build-release-notarized.sh
index 603446b790..79d1d44f17 100755
--- a/libs/lume/scripts/build/build-release-notarized.sh
+++ b/libs/lume/scripts/build/build-release-notarized.sh
@@ -1,5 +1,11 @@
#!/bin/bash
+# Get the directory where this script is located
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Navigate to the lume root directory (two levels up from scripts/build/)
+LUME_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
# Set default log level if not provided
LOG_LEVEL=${LOG_LEVEL:-"normal"}
@@ -7,7 +13,7 @@ LOG_LEVEL=${LOG_LEVEL:-"normal"}
log() {
local level=$1
local message=$2
-
+
case "$LOG_LEVEL" in
"minimal")
# Only show essential or error messages
@@ -48,7 +54,7 @@ done
VERSION=${VERSION:-"0.1.0"}
# Move to the project root directory
-pushd ../../ > /dev/null
+cd "$LUME_DIR"
# Ensure .release directory exists and is clean
mkdir -p .release
@@ -99,7 +105,7 @@ if [ "$LOG_LEVEL" = "minimal" ] || [ "$LOG_LEVEL" = "none" ]; then
--team-id "${TEAM_ID}" \
--password "${APP_SPECIFIC_PASSWORD}" \
--wait 2>&1)
-
+
# Check if notarization was successful
if echo "$NOTARY_OUTPUT" | grep -q "status: Accepted"; then
log "essential" "Notarization successful!"
@@ -202,10 +208,8 @@ ls -la "$RELEASE_DIR"
# Ensure correct permissions
chmod 644 "$RELEASE_DIR"/*.tar.gz "$RELEASE_DIR"/*.pkg.tar.gz "$RELEASE_DIR"/checksums.txt
-popd > /dev/null
-
# Clean up
rm -rf "$TEMP_ROOT"
rm -rf "$EXTRACT_ROOT"
-log "essential" "Build and packaging completed successfully."
\ No newline at end of file
+log "essential" "Build and packaging completed successfully."
diff --git a/libs/lume/scripts/build/build-release.sh b/libs/lume/scripts/build/build-release.sh
index 20b63124a3..e25ecbe5ff 100755
--- a/libs/lume/scripts/build/build-release.sh
+++ b/libs/lume/scripts/build/build-release.sh
@@ -1,6 +1,12 @@
#!/bin/sh
-pushd ../../
+# Get the directory where this script is located
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Navigate to the lume root directory (two levels up from scripts/build/)
+LUME_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+cd "$LUME_DIR"
swift build -c release --product lume
codesign --force --entitlement ./resources/lume.entitlements --sign - .build/release/lume
@@ -17,5 +23,3 @@ cp -f ./.release/lume "$USER_BIN/lume"
if ! echo "$PATH" | grep -q "$USER_BIN"; then
echo "[lume build] Note: $USER_BIN is not in your PATH. Add 'export PATH=\"$USER_BIN:\$PATH\"' to your shell profile."
fi
-
-popd
\ No newline at end of file
diff --git a/libs/lume/scripts/install.sh b/libs/lume/scripts/install.sh
index 439f35d05b..3d85ec0394 100755
--- a/libs/lume/scripts/install.sh
+++ b/libs/lume/scripts/install.sh
@@ -91,7 +91,14 @@ while [ "$#" -gt 0 ]; do
shift
done
-echo "${BOLD}${BLUE}Lume Installer${NORMAL}"
+echo "${BOLD}${BLUE}"
+echo " ⠀⣀⣀⡀⠀⠀⠀⠀⢀⣀⣀⣀⡀⠘⠋⢉⠙⣷⠀⠀ ⠀"
+echo " ⠀⠀⢀⣴⣿⡿⠋⣉⠁⣠⣾⣿⣿⣿⣿⡿⠿⣦⡈⠀⣿⡇⠃⠀"
+echo " ⠀⠀⠀⣽⣿⣧⠀⠃⢰⣿⣿⡏⠙⣿⠿⢧⣀⣼⣷⠀⡿⠃⠀⠀"
+echo " ⠀⠀⠀⠉⣿⣿⣦⠀⢿⣿⣿⣷⣾⡏⠀⠀⢹⣿⣿⠀⠀⠀⠀⠀⠀"
+echo " ⠀⠀⠀⠀⠀⠉⠛⠁⠈⠿⣿⣿⣿⣷⣄⣠⡼⠟⠁${NORMAL}${BOLD} Lume Installer${NORMAL}"
+echo "${BLUE} macOS VM CLI and server${NORMAL}"
+echo ""
echo "This script will install Lume to your system."
# Check if we're running with appropriate permissions
diff --git a/libs/lume/scripts/uninstall.sh b/libs/lume/scripts/uninstall.sh
new file mode 100755
index 0000000000..9f280bbc92
--- /dev/null
+++ b/libs/lume/scripts/uninstall.sh
@@ -0,0 +1,197 @@
+#!/bin/bash
+set -e
+
+# Lume Uninstaller
+# This script removes Lume from your system
+# Usage: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/uninstall.sh)"
+
+# Define colors for output
+BOLD=$(tput bold 2>/dev/null || echo "")
+NORMAL=$(tput sgr0 2>/dev/null || echo "")
+RED=$(tput setaf 1 2>/dev/null || echo "")
+GREEN=$(tput setaf 2 2>/dev/null || echo "")
+YELLOW=$(tput setaf 3 2>/dev/null || echo "")
+BLUE=$(tput setaf 4 2>/dev/null || echo "")
+
+# Default options
+PURGE_DATA=false
+FORCE=false
+
+# Parse command line arguments
+while [ "$#" -gt 0 ]; do
+ case "$1" in
+ --purge)
+ PURGE_DATA=true
+ ;;
+ --force|-f)
+ FORCE=true
+ ;;
+ --help|-h)
+ echo "${BOLD}${BLUE}Lume Uninstaller${NORMAL}"
+ echo "Usage: $0 [OPTIONS]"
+ echo ""
+ echo "Options:"
+ echo " --purge Also remove all Lume data (VMs, cache, config)"
+ echo " --force Skip confirmation prompts"
+ echo " --help Display this help message"
+ echo ""
+ echo "Examples:"
+ echo " $0 # Uninstall Lume, keep data"
+ echo " $0 --purge # Uninstall Lume and remove all data"
+ echo " $0 --purge --force # Uninstall without prompts"
+ exit 0
+ ;;
+ *)
+ echo "${RED}Unknown option: $1${NORMAL}"
+ echo "Use --help for usage information"
+ exit 1
+ ;;
+ esac
+ shift
+done
+
+echo "${BOLD}${BLUE}"
+echo " ⠀⣀⣀⡀⠀⠀⠀⠀⢀⣀⣀⣀⡀⠘⠋⢉⠙⣷⠀⠀ ⠀"
+echo " ⠀⠀⢀⣴⣿⡿⠋⣉⠁⣠⣾⣿⣿⣿⣿⡿⠿⣦⡈⠀⣿⡇⠃⠀"
+echo " ⠀⠀⠀⣽⣿⣧⠀⠃⢰⣿⣿⡏⠙⣿⠿⢧⣀⣼⣷⠀⡿⠃⠀⠀"
+echo " ⠀⠀⠀⠉⣿⣿⣦⠀⢿⣿⣿⣷⣾⡏⠀⠀⢹⣿⣿⠀⠀⠀⠀⠀⠀"
+echo " ⠀⠀⠀⠀⠀⠉⠛⠁⠈⠿⣿⣿⣿⣷⣄⣠⡼⠟⠁${NORMAL}${BOLD} Lume Uninstaller${NORMAL}"
+echo "${BLUE} macOS VM CLI and server${NORMAL}"
+echo ""
+
+# Confirmation prompt
+if [ "$FORCE" = false ]; then
+ echo "This will uninstall Lume from your system."
+ if [ "$PURGE_DATA" = true ]; then
+ echo "${YELLOW}WARNING: --purge flag detected. This will also delete:${NORMAL}"
+ echo " - All VMs in ~/.lume/"
+ echo " - Configuration in ~/.config/lume/"
+ echo " - Cached images"
+ fi
+ echo ""
+ read -p "Are you sure you want to continue? [y/N] " -n 1 -r
+ echo ""
+ if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+ echo "Uninstall cancelled."
+ exit 0
+ fi
+fi
+
+echo ""
+echo "${BOLD}Stopping Lume services...${NORMAL}"
+
+# Stop and remove LaunchAgent for daemon
+DAEMON_PLIST="$HOME/Library/LaunchAgents/com.trycua.lume_daemon.plist"
+if [ -f "$DAEMON_PLIST" ]; then
+ echo " Unloading lume daemon..."
+ launchctl unload "$DAEMON_PLIST" 2>/dev/null || true
+ rm -f "$DAEMON_PLIST"
+ echo " ${GREEN}Removed daemon LaunchAgent${NORMAL}"
+else
+ echo " Daemon LaunchAgent not found (skipped)"
+fi
+
+# Stop and remove LaunchAgent for updater
+UPDATER_PLIST="$HOME/Library/LaunchAgents/com.trycua.lume_updater.plist"
+if [ -f "$UPDATER_PLIST" ]; then
+ echo " Unloading lume updater..."
+ launchctl unload "$UPDATER_PLIST" 2>/dev/null || true
+ rm -f "$UPDATER_PLIST"
+ echo " ${GREEN}Removed updater LaunchAgent${NORMAL}"
+else
+ echo " Updater LaunchAgent not found (skipped)"
+fi
+
+# Remove cron job for auto-updater
+if crontab -l 2>/dev/null | grep -q "lume-update"; then
+ echo " Removing cron job..."
+ crontab -l 2>/dev/null | grep -v "lume-update" | crontab - 2>/dev/null || true
+ echo " ${GREEN}Removed auto-updater cron job${NORMAL}"
+else
+ echo " Auto-updater cron job not found (skipped)"
+fi
+
+echo ""
+echo "${BOLD}Removing Lume binaries...${NORMAL}"
+
+# Find and remove lume binary
+LUME_BIN=$(command -v lume 2>/dev/null || echo "")
+if [ -z "$LUME_BIN" ]; then
+ # Check common locations
+ for loc in "$HOME/.local/bin/lume" "/usr/local/bin/lume" "/opt/lume/lume"; do
+ if [ -f "$loc" ]; then
+ LUME_BIN="$loc"
+ break
+ fi
+ done
+fi
+
+if [ -n "$LUME_BIN" ] && [ -f "$LUME_BIN" ]; then
+ INSTALL_DIR=$(dirname "$LUME_BIN")
+ rm -f "$LUME_BIN"
+ echo " ${GREEN}Removed $LUME_BIN${NORMAL}"
+
+ # Remove updater script if in same directory
+ if [ -f "$INSTALL_DIR/lume-update" ]; then
+ rm -f "$INSTALL_DIR/lume-update"
+ echo " ${GREEN}Removed $INSTALL_DIR/lume-update${NORMAL}"
+ fi
+
+ # Remove legacy wrapper script if exists
+ if [ -f "$INSTALL_DIR/lume-daemon" ]; then
+ rm -f "$INSTALL_DIR/lume-daemon"
+ echo " ${GREEN}Removed $INSTALL_DIR/lume-daemon${NORMAL}"
+ fi
+else
+ echo " ${YELLOW}Lume binary not found (skipped)${NORMAL}"
+fi
+
+# Remove log files
+echo ""
+echo "${BOLD}Removing log files...${NORMAL}"
+for logfile in /tmp/lume_daemon.log /tmp/lume_daemon.error.log /tmp/lume_updater.log /tmp/lume_updater.error.log; do
+ if [ -f "$logfile" ]; then
+ rm -f "$logfile"
+ echo " ${GREEN}Removed $logfile${NORMAL}"
+ fi
+done
+
+# Purge data if requested
+if [ "$PURGE_DATA" = true ]; then
+ echo ""
+ echo "${BOLD}${YELLOW}Purging Lume data...${NORMAL}"
+
+ # Remove VMs and cache
+ if [ -d "$HOME/.lume" ]; then
+ # Stop any running VMs first
+ if [ -n "$LUME_BIN" ] && [ -x "$LUME_BIN" ]; then
+ echo " Attempting to stop running VMs..."
+ "$LUME_BIN" ls 2>/dev/null | grep -E "running|starting" | awk '{print $1}' | while read vm; do
+ "$LUME_BIN" stop "$vm" 2>/dev/null || true
+ done
+ fi
+
+ rm -rf "$HOME/.lume"
+ echo " ${GREEN}Removed ~/.lume/ (VMs and cache)${NORMAL}"
+ else
+ echo " ~/.lume/ not found (skipped)"
+ fi
+
+ # Remove config
+ if [ -d "$HOME/.config/lume" ]; then
+ rm -rf "$HOME/.config/lume"
+ echo " ${GREEN}Removed ~/.config/lume/ (configuration)${NORMAL}"
+ else
+ echo " ~/.config/lume/ not found (skipped)"
+ fi
+fi
+
+echo ""
+echo "${GREEN}${BOLD}Lume has been successfully uninstalled!${NORMAL}"
+if [ "$PURGE_DATA" = false ]; then
+ echo ""
+ echo "Note: Your VMs and configuration were preserved."
+ echo "To also remove all data, run with ${BOLD}--purge${NORMAL}:"
+ echo " /bin/bash -c \"\$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/uninstall.sh)\" -- --purge"
+fi
+echo ""
diff --git a/libs/lume/src/Commands/Clone.swift b/libs/lume/src/Commands/Clone.swift
index 59649638b1..5b2778a89b 100644
--- a/libs/lume/src/Commands/Clone.swift
+++ b/libs/lume/src/Commands/Clone.swift
@@ -22,6 +22,9 @@ struct Clone: AsyncParsableCommand {
@MainActor
func run() async throws {
+ // Record telemetry
+ TelemetryClient.shared.record(event: TelemetryEvent.clone)
+
let vmController = LumeController()
try vmController.clone(
name: name,
diff --git a/libs/lume/src/Commands/Config.swift b/libs/lume/src/Commands/Config.swift
index af7f02c315..3d21e9de9d 100644
--- a/libs/lume/src/Commands/Config.swift
+++ b/libs/lume/src/Commands/Config.swift
@@ -5,7 +5,7 @@ struct Config: ParsableCommand {
static let configuration = CommandConfiguration(
commandName: "config",
abstract: "Get or set lume configuration",
- subcommands: [Get.self, Storage.self, Cache.self, Caching.self],
+ subcommands: [Get.self, Storage.self, Cache.self, Caching.self, Telemetry.self],
defaultSubcommand: Get.self
)
@@ -32,6 +32,9 @@ struct Config: ParsableCommand {
// Display caching enabled status
print("Caching enabled: \(settings.cachingEnabled)")
+ // Display telemetry status
+ print("Telemetry enabled: \(settings.telemetryEnabled)")
+
// Display all locations
if !settings.vmLocations.isEmpty {
print("\nConfigured VM storage locations:")
@@ -221,4 +224,69 @@ struct Config: ParsableCommand {
}
}
}
+
+ // MARK: - Telemetry Management Subcommands
+
+ struct Telemetry: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "telemetry",
+ abstract: "Manage anonymous telemetry settings",
+ subcommands: [Status.self, Enable.self, Disable.self],
+ defaultSubcommand: Status.self
+ )
+
+ struct Status: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "status",
+ abstract: "Show current telemetry status"
+ )
+
+ func run() throws {
+ let controller = LumeController()
+ let settings = controller.getSettings()
+ let envOverride = ProcessInfo.processInfo.environment["LUME_TELEMETRY_ENABLED"]
+
+ print("Telemetry enabled: \(settings.telemetryEnabled)")
+
+ if let envValue = envOverride {
+ let lowercased = envValue.lowercased()
+ let envEnabled = ["1", "true", "yes", "on"].contains(lowercased)
+ let envDisabled = ["0", "false", "no", "off"].contains(lowercased)
+ if envEnabled || envDisabled {
+ print(" (overridden by LUME_TELEMETRY_ENABLED=\(envValue))")
+ }
+ }
+
+ print("\nTelemetry collects anonymous usage data to help improve Lume.")
+ print("No personal information or VM contents are ever collected.")
+ }
+ }
+
+ struct Enable: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "enable",
+ abstract: "Enable anonymous telemetry"
+ )
+
+ func run() throws {
+ let controller = LumeController()
+ try controller.setTelemetryEnabled(true)
+ print("Telemetry enabled")
+ print("Thank you for helping improve Lume!")
+ }
+ }
+
+ struct Disable: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "disable",
+ abstract: "Disable anonymous telemetry"
+ )
+
+ func run() throws {
+ let controller = LumeController()
+ try controller.setTelemetryEnabled(false)
+ print("Telemetry disabled")
+ }
+ }
+ }
}
diff --git a/libs/lume/src/Commands/Create.swift b/libs/lume/src/Commands/Create.swift
index 509f159837..ea4145953b 100644
--- a/libs/lume/src/Commands/Create.swift
+++ b/libs/lume/src/Commands/Create.swift
@@ -45,7 +45,7 @@ struct Create: AsyncParsableCommand {
@Option(
name: .customLong("unattended"),
- help: "[Preview] Preset name or path to YAML config file for unattended macOS Setup Assistant automation. Built-in presets: tahoe. Only supported for macOS VMs.",
+ help: "[Preview] Preset name or path to YAML config file for unattended macOS Setup Assistant automation. Built-in presets: sequoia, tahoe. Only supported for macOS VMs.",
completion: .file(extensions: ["yml", "yaml"])
)
var unattended: String?
@@ -93,6 +93,15 @@ struct Create: AsyncParsableCommand {
])
}
+ // Record telemetry
+ TelemetryClient.shared.record(event: TelemetryEvent.create, properties: [
+ "os_type": os.lowercased(),
+ "cpu": cpu,
+ "memory_gb": memory / (1024 * 1024 * 1024),
+ "disk_size_gb": diskSize / (1024 * 1024 * 1024),
+ "has_unattended": unattendedConfig != nil
+ ])
+
let controller = LumeController()
try await controller.create(
name: name,
diff --git a/libs/lume/src/Commands/Delete.swift b/libs/lume/src/Commands/Delete.swift
index 7d78ca6d8a..8679d1ddc6 100644
--- a/libs/lume/src/Commands/Delete.swift
+++ b/libs/lume/src/Commands/Delete.swift
@@ -31,6 +31,9 @@ struct Delete: AsyncParsableCommand {
}
}
+ // Record telemetry
+ TelemetryClient.shared.record(event: TelemetryEvent.delete)
+
let vmController = LumeController()
try await vmController.delete(name: name, storage: storage)
}
diff --git a/libs/lume/src/Commands/Pull.swift b/libs/lume/src/Commands/Pull.swift
index cd84338161..9c214d69dc 100644
--- a/libs/lume/src/Commands/Pull.swift
+++ b/libs/lume/src/Commands/Pull.swift
@@ -26,6 +26,12 @@ struct Pull: AsyncParsableCommand {
@MainActor
func run() async throws {
+ // Record telemetry - only capture image name without tag for privacy
+ let imageName = image.split(separator: ":").first.map(String.init) ?? image
+ TelemetryClient.shared.record(event: TelemetryEvent.pull, properties: [
+ "image_name": imageName
+ ])
+
let controller = LumeController()
try await controller.pullImage(
image: image,
diff --git a/libs/lume/src/Commands/Push.swift b/libs/lume/src/Commands/Push.swift
index df784b39c1..5d4be281bc 100644
--- a/libs/lume/src/Commands/Push.swift
+++ b/libs/lume/src/Commands/Push.swift
@@ -40,6 +40,9 @@ struct Push: AsyncParsableCommand {
@MainActor
func run() async throws {
+ // Record telemetry
+ TelemetryClient.shared.record(event: TelemetryEvent.push)
+
let controller = LumeController()
// Parse primary image name and tag
diff --git a/libs/lume/src/Commands/Run.swift b/libs/lume/src/Commands/Run.swift
index 273e8ba7eb..15ea38d5d8 100644
--- a/libs/lume/src/Commands/Run.swift
+++ b/libs/lume/src/Commands/Run.swift
@@ -98,6 +98,11 @@ struct Run: AsyncParsableCommand {
@MainActor
func run() async throws {
+ // Record telemetry
+ TelemetryClient.shared.record(event: TelemetryEvent.run, properties: [
+ "headless": noDisplay
+ ])
+
try await LumeController().runVM(
name: name,
noDisplay: noDisplay,
diff --git a/libs/lume/src/Commands/Serve.swift b/libs/lume/src/Commands/Serve.swift
index f22e8107d6..1722413176 100644
--- a/libs/lume/src/Commands/Serve.swift
+++ b/libs/lume/src/Commands/Serve.swift
@@ -10,8 +10,13 @@ struct Serve: AsyncParsableCommand {
var port: UInt16 = 7777
func run() async throws {
+ // Record telemetry
+ TelemetryClient.shared.record(event: TelemetryEvent.serve, properties: [
+ "port": port
+ ])
+
let server = await Server(port: port)
-
+
Logger.info("Starting server", metadata: ["port": "\(port)"])
// Using custom error handling to prevent ArgumentParser from printing additional error messages
diff --git a/libs/lume/src/Commands/Setup.swift b/libs/lume/src/Commands/Setup.swift
index 170e55ceec..da9c285d2c 100644
--- a/libs/lume/src/Commands/Setup.swift
+++ b/libs/lume/src/Commands/Setup.swift
@@ -19,7 +19,7 @@ struct Setup: AsyncParsableCommand {
@Option(
name: .customLong("unattended"),
- help: "Preset name or path to YAML config file for unattended macOS Setup Assistant automation. Built-in presets: tahoe.",
+ help: "Preset name or path to YAML config file for unattended macOS Setup Assistant automation. Built-in presets: sequoia, tahoe.",
completion: .file(extensions: ["yml", "yaml"]))
var unattended: String
@@ -69,6 +69,11 @@ struct Setup: AsyncParsableCommand {
throw UnattendedError.configLoadFailed("Failed to load config from \(unattended): \(error.localizedDescription)")
}
+ // Record telemetry
+ TelemetryClient.shared.record(event: TelemetryEvent.setup, properties: [
+ "preset_name": isPreset ? unattended : "custom"
+ ])
+
try await LumeController().setup(
name: name,
config: config,
diff --git a/libs/lume/src/Commands/Stop.swift b/libs/lume/src/Commands/Stop.swift
index 3b92111494..a7776ae67e 100644
--- a/libs/lume/src/Commands/Stop.swift
+++ b/libs/lume/src/Commands/Stop.swift
@@ -17,6 +17,9 @@ struct Stop: AsyncParsableCommand {
@MainActor
func run() async throws {
+ // Record telemetry
+ TelemetryClient.shared.record(event: TelemetryEvent.stop)
+
let vmController = LumeController()
try await vmController.stopVM(name: name, storage: storage)
}
diff --git a/libs/lume/src/FileSystem/Settings.swift b/libs/lume/src/FileSystem/Settings.swift
index 4337acc8ec..5b8924669c 100644
--- a/libs/lume/src/FileSystem/Settings.swift
+++ b/libs/lume/src/FileSystem/Settings.swift
@@ -7,6 +7,7 @@ struct LumeSettings: Codable, Sendable {
var cacheDirectory: String
var cachingEnabled: Bool
var registry: RegistryConfig?
+ var telemetryEnabled: Bool
var defaultLocation: VMLocation? {
vmLocations.first { $0.name == defaultLocationName }
@@ -24,7 +25,8 @@ struct LumeSettings: Codable, Sendable {
defaultLocationName: "default",
cacheDirectory: "~/.lume/cache",
cachingEnabled: false,
- registry: .defaultConfig
+ registry: .defaultConfig,
+ telemetryEnabled: true
)
/// Gets all locations sorted by name
@@ -84,7 +86,8 @@ final class SettingsManager: @unchecked Sendable {
defaultLocationName: "default",
cacheDirectory: "~/.lume/cache",
cachingEnabled: false,
- registry: .defaultConfig
+ registry: .defaultConfig,
+ telemetryEnabled: true
)
// Try to save default settings
@@ -108,6 +111,9 @@ final class SettingsManager: @unchecked Sendable {
// Caching enabled flag
yamlContent += "cachingEnabled: \(settings.cachingEnabled)\n"
+ // Telemetry enabled flag
+ yamlContent += "telemetryEnabled: \(settings.telemetryEnabled)\n"
+
// VM locations
yamlContent += "\n# VM Locations\nvmLocations:\n"
for location in settings.vmLocations {
@@ -268,6 +274,18 @@ final class SettingsManager: @unchecked Sendable {
return getSettings().cachingEnabled
}
+ // MARK: - Telemetry Management
+
+ func setTelemetryEnabled(_ enabled: Bool) throws {
+ var settings = getSettings()
+ settings.telemetryEnabled = enabled
+ try saveSettings(settings)
+ }
+
+ func isTelemetryEnabled() -> Bool {
+ return getSettings().telemetryEnabled
+ }
+
// MARK: - Private Helpers
private func ensureConfigDirectoryExists() {
@@ -298,6 +316,7 @@ final class SettingsManager: @unchecked Sendable {
var defaultLocationName = "default"
var cacheDirectory = "~/.lume/cache"
var cachingEnabled = false // default to false to save disk space
+ var telemetryEnabled = true // default to true for anonymous usage tracking
var vmLocations: [VMLocation] = []
// Registry config parsing state
@@ -449,6 +468,8 @@ final class SettingsManager: @unchecked Sendable {
cacheDirectory = value
} else if key == "cachingEnabled" {
cachingEnabled = value.lowercased() == "true"
+ } else if key == "telemetryEnabled" {
+ telemetryEnabled = value.lowercased() == "true"
}
}
}
@@ -477,7 +498,8 @@ final class SettingsManager: @unchecked Sendable {
defaultLocationName: defaultLocationName,
cacheDirectory: cacheDirectory,
cachingEnabled: cachingEnabled,
- registry: registryConfig
+ registry: registryConfig,
+ telemetryEnabled: telemetryEnabled
)
}
diff --git a/libs/lume/src/LumeController.swift b/libs/lume/src/LumeController.swift
index 017ce42655..70efec26f8 100644
--- a/libs/lume/src/LumeController.swift
+++ b/libs/lume/src/LumeController.swift
@@ -304,15 +304,31 @@ final class LumeController {
display: display
)
- try await vm.setup(
- ipswPath: ipsw ?? "none",
- cpuCount: cpuCount,
- memorySize: memorySize,
- diskSize: diskSize,
- display: display
- )
+ // Track the temp directory for cleanup on failure
+ let tempVMDir = vm.vmDirContext.dir
+
+ do {
+ try await vm.setup(
+ ipswPath: ipsw ?? "none",
+ cpuCount: cpuCount,
+ memorySize: memorySize,
+ diskSize: diskSize,
+ display: display
+ )
- try vm.finalize(to: name, home: home, storage: storage)
+ try vm.finalize(to: name, home: home, storage: storage)
+ } catch {
+ // Clean up the temporary VM directory on setup/finalize failure
+ Logger.info("Cleaning up temporary VM directory after failed creation",
+ metadata: ["path": tempVMDir.dir.path])
+ do {
+ try tempVMDir.delete()
+ } catch let cleanupError {
+ Logger.error("Failed to clean up temporary VM directory",
+ metadata: ["error": cleanupError.localizedDescription])
+ }
+ throw error
+ }
Logger.info("VM created successfully", metadata: ["name": name])
@@ -330,14 +346,28 @@ final class LumeController {
// Run the unattended installer
let installer = UnattendedInstaller()
- try await installer.install(
- vm: finalVM,
- config: config,
- vncPort: vncPort,
- noDisplay: noDisplay,
- debug: debug,
- debugDir: debugDir
- )
+ do {
+ try await installer.install(
+ vm: finalVM,
+ config: config,
+ vncPort: vncPort,
+ noDisplay: noDisplay,
+ debug: debug,
+ debugDir: debugDir
+ )
+ } catch {
+ // Clean up the finalized VM directory on unattended setup failure
+ Logger.info("Cleaning up VM after failed unattended setup",
+ metadata: ["name": name])
+ do {
+ let vmDir = try home.getVMDirectory(name, storage: storage)
+ try vmDir.delete()
+ } catch let cleanupError {
+ Logger.error("Failed to clean up VM after unattended setup failure",
+ metadata: ["error": cleanupError.localizedDescription])
+ }
+ throw error
+ }
Logger.info("Unattended setup completed", metadata: ["name": name])
}
@@ -946,6 +976,20 @@ final class LumeController {
Logger.info("Caching setting updated", metadata: ["enabled": "\(enabled)"])
}
+ // MARK: - Telemetry Management
+
+ public func isTelemetryEnabled() -> Bool {
+ return SettingsManager.shared.isTelemetryEnabled()
+ }
+
+ public func setTelemetryEnabled(_ enabled: Bool) throws {
+ Logger.info("Setting telemetry enabled", metadata: ["enabled": "\(enabled)"])
+
+ try SettingsManager.shared.setTelemetryEnabled(enabled)
+
+ Logger.info("Telemetry setting updated", metadata: ["enabled": "\(enabled)"])
+ }
+
// MARK: - Private Helper Methods
/// Normalizes a VM name by replacing colons with underscores
diff --git a/libs/lume/src/Main.swift b/libs/lume/src/Main.swift
index e4fbe8fe63..a63e7885d8 100644
--- a/libs/lume/src/Main.swift
+++ b/libs/lume/src/Main.swift
@@ -21,19 +21,60 @@ extension Lume {
}
}
+// MARK: - ASCII Art Banner
+extension Lume {
+ static let banner = """
+ \u{001B}[34m ⠀⣀⣀⡀⠀⠀⠀⠀⢀⣀⣀⣀⡀⠘⠋⢉⠙⣷⠀⠀ ⠀
+ ⠀⠀⢀⣴⣿⡿⠋⣉⠁⣠⣾⣿⣿⣿⣿⡿⠿⣦⡈⠀⣿⡇⠃⠀
+ ⠀⠀⠀⣽⣿⣧⠀⠃⢰⣿⣿⡏⠙⣿⠿⢧⣀⣼⣷⠀⡿⠃⠀⠀
+ ⠀⠀⠀⠉⣿⣿⣦⠀⢿⣿⣿⣷⣾⡏⠀⠀⢹⣿⣿⠀⠀⠀⠀⠀⠀
+ ⠀⠀⠀⠀⠀⠉⠛⠁⠈⠿⣿⣿⣿⣷⣄⣠⡼⠟⠁\u{001B}[0m\u{001B}[1m lume v\(Version.current)\u{001B}[0m
+ \u{001B}[34m macOS VM CLI and server\u{001B}[0m
+ """
+
+ static func printBanner() {
+ print(banner)
+ print()
+ }
+
+ static func shouldShowBanner() -> Bool {
+ let args = CommandLine.arguments.dropFirst()
+ // Show banner when: no args, --help, -h, help, or just the root command
+ if args.isEmpty {
+ return true
+ }
+ if args.contains("--help") || args.contains("-h") {
+ return true
+ }
+ // Check if first arg is "help" (e.g., "lume help")
+ if args.first == "help" && args.count == 1 {
+ return true
+ }
+ return false
+ }
+}
+
// MARK: - Command Execution
extension Lume {
public static func main() async {
+ // Record installation event on first run (sent regardless of telemetry opt-out)
+ TelemetryClient.shared.recordInstallation()
+
+ // Print banner when showing help
+ if shouldShowBanner() {
+ printBanner()
+ }
+
do {
try await executeCommand()
} catch {
exit(withError: error)
}
}
-
+
private static func executeCommand() async throws {
var command = try parseAsRoot()
-
+
if var asyncCommand = command as? AsyncParsableCommand {
try await asyncCommand.run()
} else {
diff --git a/libs/lume/src/Resources/unattended-presets/sequoia.yml b/libs/lume/src/Resources/unattended-presets/sequoia.yml
new file mode 100644
index 0000000000..ddfa80cab3
--- /dev/null
+++ b/libs/lume/src/Resources/unattended-presets/sequoia.yml
@@ -0,0 +1,288 @@
+# Unattended macOS Sequoia Setup Assistant Configuration
+# Use with: lume create my-vm --os macOS --ipsw latest --unattended resources/unattended-sequoia.yml
+
+# Seconds to wait after VM boots before starting automation
+boot_wait: 30
+
+boot_commands:
+ # Wait for greeting screen to appear (shows "Hello" animation cycling through languages)
+ # The boot_wait should be enough for the VM to reach this screen
+ # Note: VM framebuffer is 1920x1440 (Retina-scaled)
+ - "<delay 5>"
+
+ # Press spacebar to dismiss the greeting screen ("Hello" animation)
+ - "<space>"
+ - "<delay 2>"
+
+ # Language selection screen
+ # Wait for "English" to be visible in the list (may take a moment as languages cycle)
+ - "<wait 'English', timeout=120>"
+ - "<delay 1>"
+
+ # Type "English" to filter the list and select it, then press Enter
+ - "<type 'English'>"
+ - "<delay 1>"
+ - "<enter>"
+ - "<delay 2>"
+
+ # Country/Region selection
+ - "<wait 'Country or Region'>"
+ - "<delay 1>"
+ # Click in the center of the list area to give it focus before typing
+ - "<click_at 960,900>"
+ - "<delay 1>"
+ # Type to filter the country list
+ - "<type 'United States'>"
+ - "<delay 1>"
+ # Press Enter to select the filtered item in the list
+ - "<enter>"
+ - "<delay 1>"
+ # Click Continue button to proceed
+ - "<click 'Continue'>"
+ - "<delay 2>"
+
+ # Transfer Your Data to This Mac (Migration Assistant)
+ - "<wait 'Transfer Your Data'>"
+ - "<delay 30>" # wait for refresh
+ # Use tab navigation to select "Set up as new" (4th option)
+ - "<click 'Set up as new'>"
+ - "<delay 2>"
+ - "<click 'Continue'>"
+ - "<delay 2>"
+
+ # Written and Spoken Languages screen (appears AFTER "Set up as new")
+ - "<wait 'Written and Spoken Languages'>"
+ - "<delay 1>"
+ - "<click 'Continue'>"
+ - "<delay 2>"
+
+ # Accessibility screen - skip it
+ - "<wait 'Accessibility'>"
+ - "<delay 1>"
+ - "<click 'Not Now'>"
+ - "<delay 2>"
+
+ # Data & Privacy screen
+ - "<wait 'Data & Privacy'>"
+ - "<delay 1>"
+ - "<click 'Continue'>"
+ - "<delay 2>"
+
+ # Create a Mac Account
+ # Initial focus is on avatar picker (6 icons: +, panda, cow, fox, owl, etc.)
+ # Need to tab 6 times to reach Full Name field
+ # Field order after avatar: Full Name -> Account Name (auto-filled) -> Password -> Verify Password -> Hint -> Checkbox -> Continue
+ - "<wait 'Create a Mac Account'>"
+ - "<delay 1>"
+ # Type Full Name
+ - "<type 'lume'>"
+ - "<tab>"
+ # Skip Account Name (auto-filled from Full Name)
+ - "<tab>"
+ # Type Password
+ - "<type 'lume'>"
+ - "<tab>"
+ # Type Verify Password
+ - "<type 'lume'>"
+ - "<tab>"
+ # Skip Hint field
+ - "<tab>"
+ # Untoggle "Allow computer account password to be reset with Apple Account" checkbox
+ - "<space>"
+ - "<delay 1>"
+ # Click Continue button
+ - "<click 'Continue'>"
+ - "<delay 2>"
+
+ # Sign In to Your Apple Account - skip it
+ # Wait for "Email or Phone Number" to appear (indicates page is fully loaded and buttons are clickable)
+ - "<wait 'Email or Phone Number'>"
+ - "<delay 1>"
+ - "<click 'Set Up Later'>"
+ - "<delay 1>"
+ # Confirmation popup: "Are you sure you want to skip signing in with an Apple Account?"
+ # Tab to move focus to "Skip" button, then press Enter
+ - '<wait "Don''t Skip">'
+ - "<delay 1>"
+ - "<tab>"
+ - "<delay 1>"
+ - "<enter>"
+ - "<delay 2>"
+
+ # Terms and Conditions
+ # "Agree" appears in license text, so use index=-1 to click the last occurrence (the button)
+ - "<wait 'Terms and Conditions'>"
+ - "<delay 1>"
+ - "<click 'Agree', index=-1>"
+ - "<delay 1>"
+ # Confirmation popup: "I have read and agree to the macOS Software License Agreement"
+ # Modal "Agree" button is above the grayed-out background button, so use index=0 (first/topmost)
+ - "<wait 'I have read and agree'>"
+ - "<delay 1>"
+ - "<click 'Agree', index=0>"
+ - "<delay 2>"
+
+ # Enable Location Services (skip it)
+ - "<wait 'Enable Location Services'>"
+ - "<delay 1>"
+ - "<click 'Continue'>"
+ - "<delay 1>"
+ # Confirmation popup: "Are you sure you don't want to use Location Services?"
+ - '<wait "Don''t Use">'
+ - "<delay 1>"
+ - "<enter>"
+ - "<delay 2>"
+
+ # Select Your Time Zone
+ - "<wait 'Select Your Time Zone'>"
+ - "<delay 1>"
+ - "<click 'Continue'>"
+ - "<delay 2>"
+
+ # Analytics
+ - "<wait 'Analytics'>"
+ - "<delay 1>"
+ - "<click 'Continue'>"
+ - "<delay 2>"
+
+ # Screen Time
+ - "<wait 'Screen Time'>"
+ - "<delay 1>"
+ - "<click 'Set Up Later'>"
+ - "<delay 2>"
+
+ # Siri (longer timeout as Screen Time page can be slow)
+ - "<wait 'Siri', timeout=300>"
+ - "<delay 1>"
+ - "<click 'Continue'>"
+ - "<delay 2>"
+
+ # Select a Siri Voice
+ - "<wait 'Select a Siri Voice'>"
+ - "<delay 1>"
+ - "<click 'Choose For Me'>"
+ - "<delay 2>"
+
+ # Improve Siri & Dictation - select "Not Now" option
+ - "<wait 'Improve Siri'>"
+ - "<delay 1>"
+ - "<click 'Not Now'>"
+ - "<delay 1>"
+ - "<click 'Continue'>"
+ - "<delay 2>"
+
+ # Choose Your Look (Light/Dark mode)
+ - "<wait 'Choose Your Look'>"
+ - "<delay 1>"
+ - "<click 'Continue'>"
+ - "<delay 2>"
+
+ # Update Mac Automatically
+ - "<wait 'Update Mac Automatically'>"
+ - "<delay 1>"
+ - "<click 'Continue'>"
+ - "<delay 2>"
+
+ # Welcome screen - final step
+ - "<wait 'Welcome to Mac'>"
+ - "<delay 2>"
+ - "<space>"
+ - "<delay 5>"
+
+ # Setup complete - wait for desktop to fully load
+ - "<delay 30>"
+
+ # Click on desktop to give it keyboard focus
+ # Without this, hotkeys won't work (you'll hear the "trrr" error sound)
+ - "<click_at 960,540>"
+ - "<delay 1>"
+
+ # Open Spotlight with Cmd+Space
+ - "<cmd+space>"
+ - "<delay 2>"
+
+ # Type "Terminal" to search for Terminal app
+ - "<type 'Terminal'>"
+ - "<delay 1>"
+
+ # Press Enter to launch Terminal
+ - "<enter>"
+ - "<delay 3>"
+
+ # ============================================
+ # 1. Enable SSH (Remote Login)
+ # ============================================
+ # Enable Remote Login (SSH) using launchctl (works without Full Disk Access)
+ - "<type 'sudo launchctl load -w /System/Library/LaunchDaemons/ssh.plist'>"
+ - "<enter>"
+ - "<delay 1>"
+
+ # Enter the password when prompted
+ - "<type 'lume'>"
+ - "<enter>"
+ - "<delay 2>"
+
+ # ============================================
+ # 2. Enable Auto-Login (macOS Ventura+)
+ # ============================================
+ # Use sysadminctl to enable auto-login for the lume user
+ - "<type 'sudo sysadminctl -autologin set -userName lume -password lume'>"
+ - "<enter>"
+ - "<delay 2>"
+
+ # ============================================
+ # 3. Enable Full Disk Access for Remote Users
+ # ============================================
+ # This requires navigating System Settings GUI since TCC.db is SIP-protected
+
+ # Enable full keyboard navigation so Tab works on all UI elements
+ - "<type 'defaults write NSGlobalDomain AppleKeyboardUIMode -int 3'>"
+ - "<enter>"
+ - "<delay 1>"
+
+ # Close Terminal
+ - "<cmd+q>"
+ - "<delay 1>"
+
+ # Open Spotlight and search for System Settings
+ - "<cmd+space>"
+ - "<delay 2>"
+ - "<type 'System Settings'>"
+ - "<delay 1>"
+ - "<enter>"
+ - "<delay 3>"
+
+ # Click on the search bar, then search for Remote Login
+ - "<click 'Search'>"
+ - "<delay 1>"
+ - "<type 'Remote'>"
+ - "<delay 2>"
+ - "<click 'Remote login'>"
+ - "<delay 2>"
+
+ # Tab twice to reach the "Allow full disk access" toggle, then Space to toggle
+ - "<tab>"
+ - "<delay 0.3>"
+ - "<space>"
+ - "<delay 2>"
+
+ # Close System Settings
+ - "<cmd+q>"
+ - "<delay 1>"
+
+ # ============================================
+ # Setup Complete!
+ # ============================================
+ # SSH is now enabled - Connect with: ssh lume@<ip-address> (password: lume)
+ # Auto-login is enabled - VM will boot directly to desktop
+ # Full disk access for remote users is enabled via TCC database
+
+# Health check to verify setup was successful
+# This will SSH into the VM to confirm SSH is working
+health_check:
+ type: ssh
+ user: lume
+ password: lume
+ timeout: 30
+ retries: 5
+ retry_delay: 10
diff --git a/libs/lume/src/Server/Handlers.swift b/libs/lume/src/Server/Handlers.swift
index 94ee0ac2ab..8854afd1c2 100644
--- a/libs/lume/src/Server/Handlers.swift
+++ b/libs/lume/src/Server/Handlers.swift
@@ -7,6 +7,9 @@ extension Server {
// MARK: - VM Management Handlers
func handleListVMs(storage: String? = nil) async throws -> HTTPResponse {
+ // Record telemetry
+ TelemetryClient.shared.record(event: TelemetryEvent.apiVMList)
+
do {
let vmController = LumeController()
let vms = try vmController.list(storage: storage)
@@ -20,6 +23,9 @@ extension Server {
}
func handleGetVM(name: String, storage: String? = nil) async throws -> HTTPResponse {
+ // Record telemetry
+ TelemetryClient.shared.record(event: TelemetryEvent.apiVMGet)
+
print("Getting VM details: name=\(name), storage=\(String(describing: storage))")
do {
@@ -76,6 +82,14 @@ extension Server {
)
}
+ // Record telemetry
+ TelemetryClient.shared.record(event: TelemetryEvent.apiVMCreate, properties: [
+ "os_type": request.os.lowercased(),
+ "cpu": request.cpu,
+ "memory": request.memory,
+ "disk_size": request.diskSize
+ ])
+
do {
let sizes = try request.parse()
let vmController = LumeController()
@@ -107,6 +121,9 @@ extension Server {
}
func handleDeleteVM(name: String, storage: String? = nil) async throws -> HTTPResponse {
+ // Record telemetry
+ TelemetryClient.shared.record(event: TelemetryEvent.apiVMDelete)
+
do {
let vmController = LumeController()
try await vmController.delete(name: name, storage: storage)
@@ -130,6 +147,9 @@ extension Server {
)
}
+ // Record telemetry
+ TelemetryClient.shared.record(event: TelemetryEvent.apiVMClone)
+
do {
let vmController = LumeController()
try vmController.clone(
@@ -170,6 +190,9 @@ extension Server {
)
}
+ // Record telemetry
+ TelemetryClient.shared.record(event: TelemetryEvent.apiVMUpdate)
+
do {
let vmController = LumeController()
let sizes = try request.parse()
@@ -197,6 +220,9 @@ extension Server {
}
func handleStopVM(name: String, storage: String? = nil) async throws -> HTTPResponse {
+ // Record telemetry
+ TelemetryClient.shared.record(event: TelemetryEvent.apiVMStop)
+
Logger.info(
"Stopping VM", metadata: ["name": name, "storage": String(describing: storage)])
@@ -335,6 +361,11 @@ extension Server {
?? RunVMRequest(
noDisplay: nil, sharedDirectories: nil, recoveryMode: nil, storage: nil)
+ // Record telemetry
+ TelemetryClient.shared.record(event: TelemetryEvent.apiVMRun, properties: [
+ "headless": request.noDisplay ?? false
+ ])
+
Logger.info(
"Parsed request",
metadata: [
@@ -417,6 +448,12 @@ extension Server {
)
}
+ // Record telemetry - strip version tag from image name for privacy
+ let imageName = request.image.split(separator: ":").first.map(String.init) ?? request.image
+ TelemetryClient.shared.record(event: TelemetryEvent.apiPull, properties: [
+ "image_name": imageName
+ ])
+
do {
let vmController = LumeController()
try await vmController.pullImage(
@@ -474,6 +511,9 @@ extension Server {
)
}
+ // Record telemetry
+ TelemetryClient.shared.record(event: TelemetryEvent.apiPush)
+
// Trigger push asynchronously, return Accepted immediately
Task.detached { @MainActor @Sendable in
do {
@@ -513,6 +553,9 @@ extension Server {
}
func handleGetImages(_ request: HTTPRequest) async throws -> HTTPResponse {
+ // Record telemetry
+ TelemetryClient.shared.record(event: TelemetryEvent.apiImages)
+
let pathAndQuery = request.path.split(separator: "?", maxSplits: 1)
let queryParams =
pathAndQuery.count > 1
diff --git a/libs/lume/src/Telemetry/TelemetryClient.swift b/libs/lume/src/Telemetry/TelemetryClient.swift
new file mode 100644
index 0000000000..8bd457ad67
--- /dev/null
+++ b/libs/lume/src/Telemetry/TelemetryClient.swift
@@ -0,0 +1,257 @@
+import Foundation
+
+/// Singleton telemetry client for anonymous usage tracking
+/// Uses PostHog HTTP API directly for CLI compatibility
+final class TelemetryClient: @unchecked Sendable {
+ // MARK: - Constants
+
+ private enum Constants {
+ static let apiKey = "phc_eSkLnbLxsnYFaXksif1ksbrNzYlJShr35miFLDppF14"
+ static let captureURL = "https://eu.i.posthog.com/capture/"
+ static let telemetryIdFileName = ".telemetry_id"
+ static let installationRecordedFileName = ".installation_recorded"
+ static let envTelemetryEnabled = "LUME_TELEMETRY_ENABLED"
+ static let envTelemetryDebug = "LUME_TELEMETRY_DEBUG"
+ }
+
+ // MARK: - Singleton
+
+ static let shared = TelemetryClient()
+
+ // MARK: - Properties
+
+ private var installationId: String?
+ private let settingsManager: SettingsManager
+ private let urlSession: URLSession
+
+ // MARK: - Initialization
+
+ private init(settingsManager: SettingsManager = .shared) {
+ self.settingsManager = settingsManager
+
+ // Configure URL session with short timeout (don't block CLI)
+ let config = URLSessionConfiguration.default
+ config.timeoutIntervalForRequest = 10
+ config.timeoutIntervalForResource = 10
+ self.urlSession = URLSession(configuration: config)
+ }
+
+ // MARK: - Public Methods
+
+ /// Record a telemetry event
+ /// - Parameters:
+ /// - event: Event name (e.g., "lume_create", "lume_api_vm_run")
+ /// - properties: Additional event properties
+ func record(event: String, properties: [String: Any] = [:]) {
+ guard isEnabled() else { return }
+
+ // Lazy load installation ID
+ if installationId == nil {
+ installationId = getOrCreateInstallationId()
+ }
+
+ sendEvent(event: event, properties: properties, bypassOptOut: false)
+ }
+
+ /// Record installation event - sent ONCE on first run, regardless of telemetry opt-out
+ /// This tracks adoption while respecting user's choice to opt out of ongoing telemetry
+ func recordInstallation() {
+ let homeDir = (("~/.lume") as NSString).expandingTildeInPath
+ let markerPath = "\(homeDir)/\(Constants.installationRecordedFileName)"
+
+ // Check if we've already recorded installation
+ if FileManager.default.fileExists(atPath: markerPath) {
+ return
+ }
+
+ // Get or create installation ID
+ let installId = getOrCreateInstallationId()
+ self.installationId = installId
+
+ // Send installation event (bypasses isEnabled check)
+ sendEvent(event: TelemetryEvent.install, properties: [:], bypassOptOut: true)
+
+ // Mark as recorded
+ do {
+ try FileManager.default.createDirectory(atPath: homeDir, withIntermediateDirectories: true)
+ try "1".write(toFile: markerPath, atomically: true, encoding: .utf8)
+ } catch {
+ if isDebugEnabled() {
+ Logger.info("[Telemetry] Failed to write installation marker: \(error.localizedDescription)")
+ }
+ }
+
+ if isDebugEnabled() {
+ Logger.info("[Telemetry] Installation event recorded for: \(installId)")
+ }
+ }
+
+ /// Check if telemetry is enabled
+ /// - Returns: true if telemetry should be collected
+ func isEnabled() -> Bool {
+ // Check environment variable first (highest priority for CI/CD)
+ if let envValue = ProcessInfo.processInfo.environment[Constants.envTelemetryEnabled] {
+ let lowercased = envValue.lowercased()
+ if ["0", "false", "no", "off"].contains(lowercased) {
+ return false
+ }
+ if ["1", "true", "yes", "on"].contains(lowercased) {
+ return true
+ }
+ }
+
+ // Check settings
+ return settingsManager.getSettings().telemetryEnabled
+ }
+
+ // MARK: - Private Methods
+
+ private func sendEvent(event: String, properties: [String: Any], bypassOptOut: Bool) {
+ guard bypassOptOut || isEnabled() else { return }
+
+ let distinctId = installationId ?? getOrCreateInstallationId()
+
+ // Build event properties
+ var eventProperties = properties
+ eventProperties["lume_version"] = Lume.Version.current
+ eventProperties["os"] = "macos"
+ eventProperties["os_version"] = ProcessInfo.processInfo.operatingSystemVersionString
+ eventProperties["arch"] = getArchitecture()
+ eventProperties["is_ci"] = isCI()
+ eventProperties["$lib"] = "lume-swift"
+ eventProperties["$lib_version"] = Lume.Version.current
+
+ // Build PostHog capture payload
+ let payload: [String: Any] = [
+ "api_key": Constants.apiKey,
+ "event": event,
+ "distinct_id": distinctId,
+ "properties": eventProperties,
+ "timestamp": ISO8601DateFormatter().string(from: Date())
+ ]
+
+ guard let url = URL(string: Constants.captureURL),
+ let jsonData = try? JSONSerialization.data(withJSONObject: payload) else {
+ if isDebugEnabled() {
+ Logger.info("[Telemetry] Failed to serialize event payload")
+ }
+ return
+ }
+
+ var request = URLRequest(url: url)
+ request.httpMethod = "POST"
+ request.setValue("application/json", forHTTPHeaderField: "Content-Type")
+ request.httpBody = jsonData
+
+ if isDebugEnabled() {
+ Logger.info("[Telemetry] Sending event: \(event)", metadata: ["properties": "\(eventProperties)"])
+ }
+
+ // Fire and forget - don't block CLI execution
+ let debugEnabled = isDebugEnabled()
+ Task.detached {
+ do {
+ let (_, response) = try await self.urlSession.data(for: request)
+ if debugEnabled {
+ let statusCode = (response as? HTTPURLResponse)?.statusCode ?? 0
+ Logger.info("[Telemetry] Event sent: \(event), status: \(statusCode)")
+ }
+ } catch {
+ if debugEnabled {
+ Logger.info("[Telemetry] Failed to send event \(event): \(error.localizedDescription)")
+ }
+ }
+ }
+ }
+
+ private func isDebugEnabled() -> Bool {
+ if let envValue = ProcessInfo.processInfo.environment[Constants.envTelemetryDebug] {
+ return ["on", "true", "1", "yes"].contains(envValue.lowercased())
+ }
+ return false
+ }
+
+ private func getOrCreateInstallationId() -> String {
+ let homeDir = (("~/.lume") as NSString).expandingTildeInPath
+ let idFilePath = "\(homeDir)/\(Constants.telemetryIdFileName)"
+
+ // Try to read existing ID
+ if let existingId = try? String(contentsOfFile: idFilePath, encoding: .utf8) {
+ let trimmedId = existingId.trimmingCharacters(in: .whitespacesAndNewlines)
+ if !trimmedId.isEmpty {
+ return trimmedId
+ }
+ }
+
+ // Generate new ID
+ let newId = UUID().uuidString
+
+ // Try to persist it
+ do {
+ try FileManager.default.createDirectory(
+ atPath: homeDir,
+ withIntermediateDirectories: true
+ )
+ try newId.write(toFile: idFilePath, atomically: true, encoding: .utf8)
+ } catch {
+ if isDebugEnabled() {
+ Logger.info("[Telemetry] Failed to persist installation ID: \(error.localizedDescription)")
+ }
+ }
+
+ return newId
+ }
+
+ private func getArchitecture() -> String {
+ #if arch(arm64)
+ return "arm64"
+ #elseif arch(x86_64)
+ return "x86_64"
+ #else
+ return "unknown"
+ #endif
+ }
+
+ private func isCI() -> Bool {
+ let ciEnvVars = ["CI", "CONTINUOUS_INTEGRATION", "GITHUB_ACTIONS", "GITLAB_CI", "JENKINS_URL", "CIRCLECI"]
+ for envVar in ciEnvVars {
+ if ProcessInfo.processInfo.environment[envVar] != nil {
+ return true
+ }
+ }
+ return false
+ }
+}
+
+// MARK: - Telemetry Events
+
+/// Standard telemetry event names
+enum TelemetryEvent {
+ // Installation (sent once, regardless of opt-out)
+ static let install = "lume_install"
+
+ // CLI Commands
+ static let create = "lume_create"
+ static let run = "lume_run"
+ static let stop = "lume_stop"
+ static let delete = "lume_delete"
+ static let clone = "lume_clone"
+ static let pull = "lume_pull"
+ static let push = "lume_push"
+ static let serve = "lume_serve"
+ static let setup = "lume_setup"
+ static let config = "lume_config"
+
+ // API Endpoints
+ static let apiVMList = "lume_api_vm_list"
+ static let apiVMGet = "lume_api_vm_get"
+ static let apiVMCreate = "lume_api_vm_create"
+ static let apiVMRun = "lume_api_vm_run"
+ static let apiVMStop = "lume_api_vm_stop"
+ static let apiVMDelete = "lume_api_vm_delete"
+ static let apiVMClone = "lume_api_vm_clone"
+ static let apiVMUpdate = "lume_api_vm_update"
+ static let apiPull = "lume_api_pull"
+ static let apiPush = "lume_api_push"
+ static let apiImages = "lume_api_images"
+}
diff --git a/libs/lume/src/Utils/CommandDocExtractor.swift b/libs/lume/src/Utils/CommandDocExtractor.swift
index d2780750f8..5479e2fb2a 100644
--- a/libs/lume/src/Utils/CommandDocExtractor.swift
+++ b/libs/lume/src/Utils/CommandDocExtractor.swift
@@ -108,7 +108,7 @@ enum CommandDocExtractor {
OptionDoc(name: "display", shortName: nil, help: "Display resolution (e.g., 1024x768)", type: "String", defaultValue: "1024x768", isOptional: false),
OptionDoc(name: "ipsw", shortName: nil, help: "Path to IPSW file or 'latest' for macOS VMs", type: "String", defaultValue: nil, isOptional: true),
OptionDoc(name: "storage", shortName: nil, help: "VM storage location to use", type: "String", defaultValue: nil, isOptional: true),
- OptionDoc(name: "unattended", shortName: nil, help: "[Preview] Preset name or path to YAML config file for unattended macOS Setup Assistant automation. Built-in presets: tahoe. Only supported for macOS VMs.", type: "String", defaultValue: nil, isOptional: true),
+ OptionDoc(name: "unattended", shortName: nil, help: "[Preview] Preset name or path to YAML config file for unattended macOS Setup Assistant automation. Built-in presets: sequoia, tahoe. Only supported for macOS VMs.", type: "String", defaultValue: nil, isOptional: true),
OptionDoc(name: "debug-dir", shortName: nil, help: "Custom directory for debug screenshots during unattended setup (defaults to unique folder in system temp)", type: "String", defaultValue: nil, isOptional: true),
OptionDoc(name: "vnc-port", shortName: nil, help: "Port to use for the VNC server during unattended setup. Defaults to 0 (auto-assign)", type: "Int", defaultValue: "0", isOptional: true),
],
@@ -509,7 +509,7 @@ enum CommandDocExtractor {
ArgumentDoc(name: "name", help: "Name of the virtual machine", type: "String", isOptional: false),
],
options: [
- OptionDoc(name: "unattended", shortName: nil, help: "Preset name or path to YAML config file for unattended macOS Setup Assistant automation. Built-in presets: tahoe.", type: "String", defaultValue: nil, isOptional: false),
+ OptionDoc(name: "unattended", shortName: nil, help: "Preset name or path to YAML config file for unattended macOS Setup Assistant automation. Built-in presets: sequoia, tahoe.", type: "String", defaultValue: nil, isOptional: false),
OptionDoc(name: "storage", shortName: nil, help: "VM storage location to use or direct path to VM location", type: "String", defaultValue: nil, isOptional: true),
OptionDoc(name: "vnc-port", shortName: nil, help: "Port to use for the VNC server. Defaults to 0 (auto-assign)", type: "Int", defaultValue: "0", isOptional: true),
OptionDoc(name: "debug-dir", shortName: nil, help: "Custom directory for debug screenshots (defaults to unique folder in system temp)", type: "String", defaultValue: nil, isOptional: true),
diff --git a/libs/lume/src/VM/VMDetailsPrinter.swift b/libs/lume/src/VM/VMDetailsPrinter.swift
index db9ebfbfa4..f96543b47a 100644
--- a/libs/lume/src/VM/VMDetailsPrinter.swift
+++ b/libs/lume/src/VM/VMDetailsPrinter.swift
@@ -11,7 +11,7 @@ enum VMDetailsPrinter {
/// Configuration for all columns in the status table
private static let columns: [Column] = [
- Column(header: "name", width: 34, getValue: { $0.name }),
+ Column(header: "name", width: 40, getValue: { $0.name }),
Column(header: "os", width: 8, getValue: { $0.os }),
Column(header: "cpu", width: 8, getValue: { String($0.cpuCount) }),
Column(