Advanced Lume Configuration and Features

This page covers Lume’s advanced capabilities: disk resizing, Metal GPU capability unlock, SIP management, the HTTP API server, the MCP server, the lumier Docker interface, and running agents like OpenClaw inside a VM.

Expanding VM disk size

Lume can increase the total disk capacity of a stopped VM. Shrinking is not supported. For macOS VMs, Lume relocates the paired RecoveryOS partition, grows the APFS container into the freed space, and creates a rollback copy before making any changes.

Stop the VM

lume stop macos-tahoe

Preview the change without modifying the disk

lume set macos-tahoe --disk-size 120GB --dry-run

Resolve any reported layout, encryption, host-space, or VM-state error before continuing.

Expand the disk

lume set macos-tahoe --disk-size 120GB

The operation may take several minutes. Lume preserves RecoveryOS and grows the APFS container. Use --keep-backup to retain the rollback files after success, or --no-backup only when you have a separate verified copy of the VM.

Verify guest capacity

Start the VM and check the root container from the host:

lume run macos-tahoe --display none
lume ssh macos-tahoe 'diskutil info / | grep "Container Total Space"'
lume stop macos-tahoe

For Linux VMs, Lume can increase the image size, but the guest is responsible for growing its partition and filesystem after the resize. The exact commands depend on the partition table and filesystem type.

How disk expansion works

A standard Lume macOS disk has this layout:

[ ISC ][ main APFS ][ RecoveryOS ]

Simply extending the disk image appends free space after RecoveryOS, which blocks APFS from using it. Lume instead copies RecoveryOS to the new end of the disk — preserving its identity, type, and contents — then rewrites both GUID Partition Table copies and asks diskutil to grow the main APFS container:

[ ISC ][ expanded main APFS ][ RecoveryOS ]

Before any modification, Lume validates the partition table, confirms the VM is stopped, and creates a copy-on-write backup. A persistent transaction marker prevents run, clone, and push operations while the resize is in progress. If a step fails, the disk and configuration are restored from the backup automatically.

GPU passthrough for Metal workloads

Lume VMs use Apple’s paravirtualized GPU bridge. A stock macOS guest can report conservative Metal capability values, causing applications to skip newer GPU code paths even when the paravirtualized device can execute them. The Metal capability shim changes selected capability answers for a single process without patching the host or guest kernel.

This feature is experimental and version-sensitive. The shim relies on private Metal implementation details that may change in any macOS release. Test each workload and host/guest version combination independently before relying on it.

Enable the host capability path

Stop the VM, set the host preference, then restart the VM so the graphics device is recreated with the requested feature level:

lume stop my-vm
defaults write com.apple.gpusw.ParavirtualizedGraphics \
  ForceUnrestrictedDeviceFeatureLevel -bool true
lume run my-vm

Build the capability shim

Clone the Cua repository on your Apple Silicon Mac and build the shim:

git clone https://github.com/trycua/cua.git
cd cua/libs/lume/metal-capability-shim
./Scripts/build.sh
./Scripts/verify.sh

The output is written to dist/:

dist/
├── LumeMetalCapabilities-arm64.dylib
├── LumeMetalCapabilities-arm64e.dylib
├── SHA256SUMS
└── metal-capabilities

Copy the shim into the guest

lume ssh my-vm "mkdir -p '/Users/lume/.local/share/lume/metal-capabilities'"

VM_IP=$(lume get my-vm --format json | jq -r '.[0].ipAddress')
scp ./dist/LumeMetalCapabilities-arm64.dylib ./dist/metal-capabilities \
  "lume@${VM_IP}:/Users/lume/.local/share/lume/metal-capabilities/"

Run a workload with the shim injected

Injection is per-process — only the target workload and its children see the changed capability answers:

lume ssh my-vm \
  "DYLD_INSERT_LIBRARIES='/Users/lume/.local/share/lume/metal-capabilities/LumeMetalCapabilities-arm64.dylib' \
   LUME_METAL_APPLE_FAMILY_MAX=1009 \
   /absolute/path/to/your-workload"

Variable	Default	Effect
`LUME_METAL_APPLE_FAMILY_MAX`	Required	Answer `supportsFamily:` through this Apple-family ceiling. Tested value: Apple 9 (`1009`).
`LUME_METAL_MAX_THREADGROUP_MEMORY`	`65536`	Raise maximum threadgroup memory to at least this many bytes.
`LUME_METAL_RECOMMENDED_WORKING_SET_SIZE`	Unchanged	Raise the reported working-set size only when explicitly set.

To restore the stock host setting, stop the VM, delete the preference, and start it again:

lume stop my-vm
defaults delete com.apple.gpusw.ParavirtualizedGraphics ForceUnrestrictedDeviceFeatureLevel
lume run my-vm

SIP management in VMs

System Integrity Protection (SIP) on an Apple silicon VM is stored in a signed LocalPolicy — it cannot be changed by editing the disk image. Lume uses lume sip to change SIP by running csrutil inside the VM’s paired Recovery environment and verifying the result after a normal boot.

The lume sip command requires vncdotool. Install it before running SIP commands:

pip3 install vncdotool

Disable SIP

The VM must be stopped and must have a working administrator account with Remote Login enabled. VMs created with the --unattended preset meet these requirements by default.

lume sip off macos-tahoe

For non-default administrator accounts:

lume sip off macos-tahoe \
  --admin-user admin \
  --admin-password-stdin

For non-interactive use:

printf '%s\n' "$LUME_ADMIN_PASSWORD" | \
  lume sip off macos-tahoe \
    --admin-user admin \
    --admin-password-stdin \
    --yes

A successful run ends with:

System Integrity Protection status: disabled.
SIP is disabled.

Enable SIP

lume sip on macos-tahoe \
  --admin-user admin \
  --admin-password-stdin

Create a reusable SIP-disabled VM

Change SIP on a seed VM, then clone it for workers:

lume sip off macos-tahoe-seed --yes
lume clone macos-tahoe-seed macos-tahoe-worker-001

How it works

lume sip coordinates three VM sessions:

A normal boot verifies the administrator account works over SSH.
A Recovery boot runs csrutil enable or csrutil disable over a temporary VNC session.
A final normal boot runs csrutil status over SSH to confirm the change.

Lume accepts only the canonical top-level status (enabled. or disabled.) and rejects customized multi-component policies.

Running the Lume HTTP API server

lume serve starts a local HTTP API that exposes all VM management operations over HTTP. The standard installer starts this service automatically at login.

lume serve

To use a different port:

lume serve --port 7778

The API listens on localhost by default (port 7777). Verify it is running:

curl http://localhost:7777/lume/vms

To install Lume without the background service and manage the server yourself:

/bin/bash -c "$(curl -fsSL https://cua.ai/lume/install.sh) --no-background-service"

View server logs:

lume logs info
lume logs error
lume logs all

Using Lume as an MCP server

Lume can expose VM management tools through the Model Context Protocol (MCP). The MCP server uses stdio — the client starts one Lume process and communicates with it directly.

Find the Lume binary path

which lume

Add the MCP server to your client configuration

Add this entry to your MCP client’s configuration file, replacing the command path with the output from the previous step:

{
  "mcpServers": {
    "lume": {
      "command": "/Users/your-name/.local/bin/lume",
      "args": ["serve", "--mcp"]
    }
  }
}

Restart the MCP client

After saving the configuration, restart your MCP client. It can then list VMs, create Tahoe guests, run and stop VMs, clone or resize disks, and execute SSH commands inside unattended guests.

To test the MCP server with the MCP Inspector:

npx @modelcontextprotocol/inspector lume serve --mcp

The MCP server can create, delete, start, stop, clone, and SSH into VMs. Configure it only for clients you trust. Use a dedicated vanilla VM for agent tasks where the guest may be modified.

lumier: Docker-compatible interface

lumier is a Docker image that runs a Lume VM from inside a container. It starts the VM, serves its display over noVNC on port 8006, and connects to the Lume HTTP API on the host via host.docker.internal. Run a macOS Sequoia VM with lumier:

docker run \
  -e VERSION="ghcr.io/trycua/macos-sequoia-vanilla:latest" \
  -e RAM_SIZE="8192" \
  -e CPU_CORES="4" \
  -e DISK_SIZE="100" \
  -p 8006:8006 \
  ghcr.io/trycua/lumier:latest

Open http://localhost:8006 in a browser to access the VM display via noVNC. lumier is useful for container-based CI/CD workflows or any environment that manages infrastructure through Docker Compose or Kubernetes. Default VM configuration (overridable via environment variables):

Variable	Default	Description
`VERSION`	`ghcr.io/trycua/macos-sequoia-vanilla:latest`	OCI image to pull and run
`RAM_SIZE`	`8192`	VM memory in MB
`CPU_CORES`	`4`	Number of vCPU cores
`DISK_SIZE`	`100`	Disk size in GB
`DISPLAY`	`1024x768`	VM display resolution
`VM_NAME`	`lumier`	Name for the created VM
`HOST_SHARED_PATH`	(empty)	Host path to share with the guest

Running agents inside a Lume VM

Lume VMs make excellent sandboxes for AI agents that need access to a macOS desktop. The isolation means an agent can have full control of the guest without risk to the host.

OpenClaw

OpenClaw is a macOS agent gateway. Run it inside a dedicated Lume VM to keep it separate from your daily environment:

Create a dedicated VM

lume create openclaw --ipsw latest --unattended tahoe
lume run openclaw --display none

Install OpenClaw in the guest

lume ssh openclaw

Inside the guest shell:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh \
  | bash -s -- --no-onboard
openclaw onboard --install-daemon

Follow the prompts to choose a model provider and channels, then exit the shell.

Forward the gateway port to the host

Get the VM’s IP address and forward the gateway port over SSH:

lume get openclaw
ssh -N -L 18789:127.0.0.1:18789 lume@<VM_IP>

Open http://127.0.0.1:18789 in a browser to access the gateway.

General agent pattern

Any agent that can SSH into a macOS host can run inside a Lume VM:

# Create an isolated VM for your agent
lume create agent-sandbox --ipsw latest --unattended tahoe
lume run agent-sandbox --display none

# Use lume ssh to execute commands from the host
lume ssh agent-sandbox 'your-agent-command'

# Clone the VM to reset to a clean state
lume clone agent-sandbox agent-sandbox-clean

Use lume clone to snapshot a configured VM before an agent run. If the agent corrupts the guest, delete the working copy and clone from the snapshot again.

Get Started

Concepts

Cua Driver

Cua Sandbox

Lume

Cua Bench

Use Cua With

Advanced Lume Configuration and Features

Expanding VM disk size

How disk expansion works

GPU passthrough for Metal workloads

SIP management in VMs

Disable SIP

Enable SIP

Create a reusable SIP-disabled VM

How it works

Running the Lume HTTP API server

Using Lume as an MCP server

lumier: Docker-compatible interface

Running agents inside a Lume VM

OpenClaw

General agent pattern

Build docs developers (and LLMs) love

Get Started

Concepts

Cua Driver

Cua Sandbox

Lume

Cua Bench

Use Cua With

Documentation Index

​Expanding VM disk size

​How disk expansion works

​GPU passthrough for Metal workloads

​SIP management in VMs

​Disable SIP

​Enable SIP

​Create a reusable SIP-disabled VM

​How it works

​Running the Lume HTTP API server

​Using Lume as an MCP server

​lumier: Docker-compatible interface

​Running agents inside a Lume VM

​OpenClaw

​General agent pattern

Build docs developers (and LLMs) love

Expanding VM disk size

How disk expansion works

GPU passthrough for Metal workloads

SIP management in VMs

Disable SIP

Enable SIP

Create a reusable SIP-disabled VM

How it works

Running the Lume HTTP API server

Using Lume as an MCP server

lumier: Docker-compatible interface

Running agents inside a Lume VM

OpenClaw

General agent pattern