Unattended Setup

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.

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:

# 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

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

Additional options for lume create --unattended:

Option 2: On an Existing VM

Use the lume setup command on a freshly created VM that hasn't completed the Setup Assistant:

# First, create a VM without unattended setup
lume create my-vm --os macOS --ipsw latest

# Later, run the unattended setup with a preset
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:

• Reuse a VM that failed during setup
• Apply different configurations to cloned VMs
• Debug setup issues interactively before automating

Built-in Presets

Lume includes built-in configuration presets that you can reference by name:

# Use the tahoe preset during creation
lume create my-vm --os macOS --ipsw latest --unattended tahoe

YAML Schema

The unattended configuration file uses YAML format with three main sections:

# Seconds to wait after VM boots before starting automation
boot_wait: 30

# Sequence of commands to execute
boot_commands:
  - '<command>'
  - '<command>'
  # ...

# Optional health check to verify setup success
health_check:
  type: ssh
  user: lume
  password: lume

Configuration Fields

Health Check Configuration

Boot Commands

Boot commands are strings enclosed in angle brackets that control mouse, keyboard, and timing.

Timing Commands

Mouse Commands

Index parameter: When text appears multiple times on screen (e.g., "Agree" in both license text and button), use index to select which occurrence:

• index=0 - First (topmost) occurrence
• index=1 - Second occurrence
• index=-1 - Last (bottommost) occurrence
• index=-2 - Second to last occurrence

Keyboard Commands

Special Keys

Text Input

Hotkey Combinations

Combine modifier keys with +:

Examples:

• <cmd+space> - Open Spotlight
• <cmd+q> - Quit application
• <cmd+c> - Copy
• <cmd+v> - Paste
• <ctrl+alt+delete> - Multi-key combo
• <shift+cmd+3> - Screenshot

Example: Full macOS Setup

This example walks through macOS Tahoe's Setup Assistant:

boot_wait: 30

boot_commands:
  # Dismiss greeting screen
  - '<delay 5>'
  - '<space>'
  - '<delay 2>'

  # Language selection
  - "<wait 'English', timeout=120>"
  - "<type 'English'>"
  - '<delay 1>'
  - '<enter>'
  - '<delay 2>'

  # Country/Region
  - "<wait 'Country or Region'>"
  - '<click_at 960,900>' # Click list to focus
  - "<type 'United States'>"
  - '<enter>'
  - "<click 'Continue'>"
  - '<delay 2>'

  # Transfer Your Data - select "Set up as new"
  - "<wait 'Transfer Your Data'>"
  - '<delay 20>'
  - '<tab>'
  - '<tab>'
  - '<tab>'
  - '<space>' # Select "Set up as new"
  - "<click 'Continue'>"

  # Skip remaining screens...
  - "<wait 'Accessibility'>"
  - "<click 'Not Now'>"

  # Create account
  - "<wait 'Create a Mac Account'>"
  - '<tab><tab><tab><tab><tab><tab>' # Tab to Full Name field
  - "<type 'lume'>"
  - '<tab><tab>' # Skip to Password
  - "<type 'lume'>"
  - '<tab>'
  - "<type 'lume'>" # Verify password
  - '<tab><tab><space>' # Uncheck Apple Account reset
  - "<click 'Continue'>"

  # Terms and Conditions
  - "<wait 'Terms and Conditions'>"
  - "<click 'Agree', index=-1>" # Click button, not text
  - "<wait 'I have read and agree'>"
  - "<click 'Agree', index=0>" # Click modal button

health_check:
  type: ssh
  user: lume
  password: lume
  timeout: 30
  retries: 5
  retry_delay: 10

Debugging

Enable debug mode to save screenshots with OCR annotations. Debug flags work with both lume setup and lume create --unattended:

# Using lume setup
lume setup my-vm --unattended tahoe --debug

# Using lume create with unattended setup
lume create my-vm --os macOS --ipsw latest --unattended tahoe --debug

# 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

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

Tips for Writing Configurations

Handling Timing

• 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

OCR Text Matching

• 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:

- "<type 'defaults write NSGlobalDomain AppleKeyboardUIMode -int 3'>"
- '<enter>'

System Settings Automation

Some settings can only be changed through GUI (protected by SIP):

• Full Disk Access requires navigating System Settings
• Use Spotlight (<cmd+space>) to search for specific settings

Screen Coordinates

• 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>

Troubleshooting

Limitations

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