HTTP Server

Lume's HTTP API lets you manage VMs programmatically—useful for automation scripts, CI/CD pipelines, and the Computer Use Agent SDK.

# Start the server
lume serve

# Or on a custom port
lume serve --port 8080

If you installed Lume with default settings, the server runs as a background service on port 7777. No need to start it manually.

Base URL

http://localhost:7777

Quick examples

List VMs

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

Run a VM

curl -X POST http://localhost:7777/lume/vms/my-vm/run \
  -H "Content-Type: application/json" \
  -d '{"noDisplay": true}'

Stop a VM

curl -X POST http://localhost:7777/lume/vms/my-vm/stop

Create a VM

VM creation is asynchronous—returns immediately with 202 Accepted while provisioning runs in the background:

curl -X POST http://localhost:7777/lume/vms \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-vm",
    "os": "macOS",
    "cpu": 4,
    "memory": "8GB",
    "diskSize": "50GB",
    "ipsw": "latest",
    "unattended": "tahoe"
  }'

Response:

{
  "message": "VM creation started",
  "name": "my-vm",
  "status": "provisioning"
}

Poll the list endpoint to check provisioning status:

# Check status (will show "provisioning (ipsw_install)" or "provisioning (unattended_setup)")
curl http://localhost:7777/lume/vms | jq '.[] | select(.name == "my-vm") | .status'

Get VM details

curl http://localhost:7777/lume/vms/my-vm

Common workflows

Automation script

#!/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:

from cua import Computer

async with Computer() as computer:
    await computer.run("my-vm")
    # Perform automation...
    await computer.stop()

Managing the background service

# Check if running
launchctl list | grep com.trycua.lume_daemon

# Stop
launchctl unload ~/Library/LaunchAgents/com.trycua.lume_daemon.plist

# Start
launchctl load ~/Library/LaunchAgents/com.trycua.lume_daemon.plist

# View logs
tail -f /tmp/lume_daemon.log

Configuration

The server uses settings from ~/.config/lume/config.yaml:

VM storage locations
Cache settings
Default resource allocations

See the FAQ for more on configuration.

Full API reference

For all endpoints, request/response formats, and language-specific examples, see the HTTP API Reference.

Was this page helpful?

HTTP Server

On this page