computer/libs/lume/docs/API-Reference.md

API Reference

Create VM - POST /vms

curl --connect-timeout 6000 \
    --max-time 5000 \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{
      "name": "lume_vm",
      "os": "macOS",
      "cpu": 2,
      "memory": "4GB",
      "diskSize": "64GB",
      "display": "1024x768",
      "ipsw": "latest",
      "storage": "ssd"
    }' \
    http://localhost:7777/lume/vms

Run VM - POST /vms/:name/run

# Basic run
curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  http://localhost:7777/lume/vms/my-vm-name/run

# Run with VNC client started and shared directory
curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "noDisplay": false,
    "sharedDirectories": [
      {
        "hostPath": "~/Projects",
        "readOnly": false
      }
    ],
    "recoveryMode": false,
    "storage": "ssd"
  }' \
  http://localhost:7777/lume/vms/lume_vm/run

List VMs - GET /vms

curl --connect-timeout 6000 \
  --max-time 5000 \
  http://localhost:7777/lume/vms

[
  {
    "name": "my-vm",
    "state": "stopped",
    "os": "macOS",
    "cpu": 2,
    "memory": "4GB",
    "diskSize": "64GB"
  },
  {
    "name": "my-vm-2",
    "state": "stopped",
    "os": "linux",
    "cpu": 2,
    "memory": "4GB",
    "diskSize": "64GB"
  }
]

Get VM Details - GET /vms/:name

# Basic get
curl --connect-timeout 6000 \
  --max-time 5000 \
  http://localhost:7777/lume/vms/lume_vm

# Get with storage location specified
curl --connect-timeout 6000 \
  --max-time 5000 \
  http://localhost:7777/lume/vms/lume_vm?storage=ssd

{
  "name": "lume_vm",
  "state": "running",
  "os": "macOS",
  "cpu": 2,
  "memory": "4GB",
  "diskSize": "64GB"
}

Update VM Settings - PATCH /vms/:name

curl --connect-timeout 6000 \
  --max-time 5000 \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{
    "cpu": 4,
    "memory": "8GB",
    "diskSize": "128GB",
    "storage": "ssd"
  }' \
  http://localhost:7777/lume/vms/my-vm-name

Stop VM - POST /vms/:name/stop

# Basic stop
curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  http://localhost:7777/lume/vms/my-vm-name/stop

# Stop with storage location specified
curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  http://localhost:7777/lume/vms/my-vm-name/stop?storage=ssd

Delete VM - DELETE /vms/:name

# Basic delete
curl --connect-timeout 6000 \
  --max-time 5000 \
  -X DELETE \
  http://localhost:7777/lume/vms/my-vm-name

# Delete with storage location specified
curl --connect-timeout 6000 \
  --max-time 5000 \
  -X DELETE \
  http://localhost:7777/lume/vms/my-vm-name?storage=ssd

Pull Image - POST /pull

curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "image": "macos-sequoia-vanilla:latest",
    "name": "my-vm-name",
    "registry": "ghcr.io",
    "organization": "trycua",
    "storage": "ssd"
  }' \
  http://localhost:7777/lume/pull

curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "image": "macos-sequoia-vanilla:15.2",
    "name": "macos-sequoia-vanilla"
  }' \
  http://localhost:7777/lume/pull

Push Image (Async) - POST /vms/push

# Push VM 'my-local-vm' to 'my-org/my-image:latest' and 'my-org/my-image:v1'
curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-local-vm", 
    "imageName": "my-image",
    "tags": ["latest", "v1"],
    "organization": "my-org", 
    "registry": "ghcr.io",
    "chunkSizeMb": 512,
    "storage": null 
  }' \
  http://localhost:7777/lume/vms/push 

Response (202 Accepted):

{
  "message": "Push initiated in background",
  "name": "my-local-vm",
  "imageName": "my-image",
  "tags": [
    "latest",
    "v1"
  ]
}

Clone VM - POST /vms/:name/clone

curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "source-vm",
    "newName": "cloned-vm",
    "sourceLocation": "default",
    "destLocation": "ssd"
  }' \
  http://localhost:7777/lume/vms/clone

Get Latest IPSW URL - GET /ipsw

curl --connect-timeout 6000 \
  --max-time 5000 \
  http://localhost:7777/lume/ipsw

List Images - GET /images

# List images with default organization (trycua)
curl --connect-timeout 6000 \
  --max-time 5000 \
  http://localhost:7777/lume/images

{
  "local": [
    "macos-sequoia-xcode:latest",
    "macos-sequoia-vanilla:latest"
  ]
}

Prune Images - POST /lume/prune

curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  http://localhost:7777/lume/prune

Get Configuration - GET /lume/config

curl --connect-timeout 6000 \
  --max-time 5000 \
  http://localhost:7777/lume/config

{
  "homeDirectory": "~/.lume",
  "cacheDirectory": "~/.lume/cache",
  "cachingEnabled": true
}

Update Configuration - POST /lume/config

curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "homeDirectory": "~/custom/lume",
    "cacheDirectory": "~/custom/lume/cache",
    "cachingEnabled": true
  }' \
  http://localhost:7777/lume/config

Get VM Storage Locations - GET /lume/config/locations

curl --connect-timeout 6000 \
  --max-time 5000 \
  http://localhost:7777/lume/config/locations

[
  {
    "name": "default",
    "path": "~/.lume/vms",
    "isDefault": true
  },
  {
    "name": "ssd",
    "path": "/Volumes/SSD/lume/vms",
    "isDefault": false
  }
]

Add VM Storage Location - POST /lume/config/locations

curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ssd",
    "path": "/Volumes/SSD/lume/vms"
  }' \
  http://localhost:7777/lume/config/locations

Remove VM Storage Location - DELETE /lume/config/locations/:name

curl --connect-timeout 6000 \
  --max-time 5000 \
  -X DELETE \
  http://localhost:7777/lume/config/locations/ssd

Set Default VM Storage Location - POST /lume/config/locations/default/:name

curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  http://localhost:7777/lume/config/locations/default/ssd