Guest access
Prepare unattended setup, open SSH sessions, copy files and change SIP in a guest.
Prepare unattended setup, open SSH sessions, copy files and change SIP in a guest.
| Command | Description |
|---|---|
lume setup | Prepare unattended macOS setup. |
lume ssh | Connect to a VM via SSH or execute commands remotely. |
lume cp | Copy files between the host and a VM. |
lume sip | Enable or disable System Integrity Protection on a macOS VM. |
Every command also accepts the global options.
lume setup#Prepare unattended macOS setup.
Lume prepares the macOS disk offline, skips Setup Assistant, enables autologin and SSH, disables screensaver lock, verifies SSH, then stops the VM.
lume setup [OPTIONS] <name>| Argument | Type | Default | Description |
|---|---|---|---|
<name> | string | required | Name of the virtual machine. |
| Flag | Type | Default | Description |
|---|---|---|---|
--unattended | string | Built-in preset (sequoia, tahoe) or a YAML path, kept for compatibility and optional post-SSH commands (default: tahoe). | |
--storage | string | VM storage location name, or a direct path to the VM location. | |
--vnc-port | integer | 0 | Port for the temporary verification VNC server (0 picks a free port). |
--debug-dir | string | Compatibility option; ignored by offline setup. | |
--no-display | boolean | false | Compatibility flag; offline setup verifies headlessly. |
--debug | boolean | false | Compatibility flag; ignored by offline setup. |
Examples
lume setup my-vm
lume setup my-vm --unattended sequoialume ssh#Connect to a VM via SSH or execute commands remotely.
Opens an interactive shell, or runs one command and exits with its status. Password authentication is handled for you (no sshpass needed). Requires Remote Login in the guest; VMs created with --unattended have it enabled with credentials lume/lume.
lume ssh [OPTIONS] <name> [<command>...]| Argument | Type | Default | Description |
|---|---|---|---|
<name> | string | required | Name of the virtual machine. |
<command>... | string | optional | Command to execute (omit for an interactive shell). Repeatable. |
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--user | -u | string | lume | SSH username. |
--password | -p | string | lume | SSH password. |
--storage | string | Storage location name or path. | ||
--timeout | -t | integer | 60 | Command timeout in seconds (0 for no timeout). |
Examples
# Interactive shell
lume ssh my-vm
# Run one command
lume ssh my-vm "ls -la"
# A long-running command with no timeout
lume ssh my-vm --timeout 0 "cd /app && npm test"lume cp#Copy files between the host and a VM.
Copies a file or directory between the host and a running VM over SSH, using the same credentials as lume ssh. Exactly one of the source or destination is a VM path, written as VM:PATH. Host directories are copied recursively automatically; pass --recursive for a recursive guest-to-host copy.
lume cp [OPTIONS] <source> <destination>| Argument | Type | Default | Description |
|---|---|---|---|
<source> | string | required | Source path. Use VM:PATH for a path inside a VM. |
<destination> | string | required | Destination path. Use VM:PATH for a path inside a VM. |
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--user | -u | string | lume | SSH username. |
--password | -p | string | lume | SSH password. |
--storage | string | Storage location name or path. | ||
--timeout | -t | integer | 600 | Transfer timeout in seconds (0 for no timeout). |
--recursive | -r | boolean | false | Copy directories recursively. |
Examples
# Copy a host file into the VM
lume cp ./build.zip my-vm:/tmp/build.zip
# Copy a file out of the VM
lume cp my-vm:/tmp/out.log ./out.log
# Copy a directory into the VM
lume cp -r ./assets my-vm:/tmp/assetslume sip#Enable or disable System Integrity Protection on a macOS VM.
Boots the stopped VM normally to validate the admin credentials, runs csrutil disable (or enable) in paired recoveryOS over VNC, then boots normally once more to verify the result. The VM needs an admin account and Remote Login; VMs from unattended setup use lume/lume. Prefer --admin-password-stdin: --admin-password is visible to other processes. Requires vncdotool (pip3 install vncdotool).
lume sip [OPTIONS] <state> <name>| Argument | Type | Default | Description |
|---|---|---|---|
<state> | on | off | required | Desired SIP state. |
<name> | string | required | Name of the virtual machine. |
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--admin-user | string | lume | Administrator username in the guest. | |
--admin-password | string | Administrator password in the guest (default: lume); prefer --admin-password-stdin. | ||
--screenshot-dir | string | Save step-by-step framebuffer PNGs here for debugging. | ||
--vnc-port | integer | 5999 | TCP port for the temporary recovery VNC server. | |
--storage | string | VM storage location. | ||
--timeout | integer | 900 | Overall timeout in seconds. | |
--yes | -y | boolean | false | Skip the interactive confirmation prompt. |
--admin-password-stdin | boolean | false | Read one administrator-password line from standard input without echo. |
Examples
lume sip off my-vm --yes
# With another admin account, password read from stdin
lume sip on my-vm --yes --admin-user alice --admin-password-stdin| Code | Meaning |
|---|---|
0 | Success. |
1 | The command failed (for example the VM does not exist or the operation errored). |
64 | Usage error: an unknown command or option, a missing argument, or an invalid value. |