From 4eac69285dd3445e4b266affb32e22d00627dd8c Mon Sep 17 00:00:00 2001 From: James Murdza Date: Wed, 27 Aug 2025 20:40:43 -0400 Subject: [PATCH] Restructure API reference for clarity --- docs/content/docs/libraries/lume/http-api.mdx | 2165 +++++++++-------- 1 file changed, 1098 insertions(+), 1067 deletions(-) diff --git a/docs/content/docs/libraries/lume/http-api.mdx b/docs/content/docs/libraries/lume/http-api.mdx index 079a134a..04792f26 100644 --- a/docs/content/docs/libraries/lume/http-api.mdx +++ b/docs/content/docs/libraries/lume/http-api.mdx @@ -1,9 +1,10 @@ --- title: HTTP Server API -description: Lume exposes a local HTTP API server that listens at localhost for programatic management of VMs. +description: Lume exposes a local HTTP API server that listens at localhost for programmatic management of VMs. --- import { Tabs, Tab } from 'fumadocs-ui/components/tabs'; +import { Callout } from 'fumadocs-ui/components/callout'; ## Default URL @@ -19,11 +20,13 @@ http://localhost:7777 ## Endpoints +--- + ### Create VM Create a new virtual machine. -`POST: /vms` +`POST: /lume/vms` #### Parameters @@ -40,6 +43,1099 @@ Create a new virtual machine. #### Example Request + + + +```bash +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 +``` + + + + +```python +import requests + +payload = { + "name": "lume_vm", + "os": "macOS", + "cpu": 2, + "memory": "4GB", + "diskSize": "64GB", + "display": "1024x768", + "ipsw": "latest", + "storage": "ssd" +} +r = requests.post("http://localhost:7777/lume/vms", json=payload, timeout=50) +print(r.json()) +``` + + + + +```typescript +const payload = { + name: 'lume_vm', + os: 'macOS', + cpu: 2, + memory: '4GB', + diskSize: '64GB', + display: '1024x768', + ipsw: 'latest', + storage: 'ssd', +}; + +const res = await fetch('http://localhost:7777/lume/vms', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify(payload), +}); +console.log(await res.json()); +``` + + + + +--- + +### Run VM + +Run a virtual machine instance. + +`POST: /lume/vms/:name/run` + +#### Parameters + +| Name | Type | Required | Description | +| ----------------- | --------------- | -------- | --------------------------------------------------- | +| noDisplay | boolean | No | If true, do not start VNC client | +| sharedDirectories | array of object | No | List of shared directories (`hostPath`, `readOnly`) | +| recoveryMode | boolean | No | Start in recovery mode | +| storage | string | No | Storage type (`ssd`, etc.) | + +#### Example Request + + + + +```bash +# 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 +``` + + + + +```python +import requests + +# Basic run +r = requests.post("http://localhost:7777/lume/vms/my-vm-name/run", timeout=50) +print(r.json()) + +# With VNC and shared directory +payload = { + "noDisplay": False, + "sharedDirectories": [ + {"hostPath": "~/Projects", "readOnly": False} + ], + "recoveryMode": False, + "storage": "ssd" +} +r = requests.post("http://localhost:7777/lume/vms/lume_vm/run", json=payload, timeout=50) +print(r.json()) +``` + + + + +```typescript +// Basic run +let res = await fetch('http://localhost:7777/lume/vms/my-vm-name/run', { + method: 'POST', +}); +console.log(await res.json()); + +// With VNC and shared directory +const payload = { + noDisplay: false, + sharedDirectories: [{ hostPath: '~/Projects', readOnly: false }], + recoveryMode: false, + storage: 'ssd', +}; +res = await fetch('http://localhost:7777/lume/vms/lume_vm/run', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify(payload), +}); +console.log(await res.json()); +``` + + + + +--- + +### List VMs + +List all virtual machines. + +`GET: /lume/vms` + +#### Example Request + + + + +```bash +curl --connect-timeout 6000 \ + --max-time 5000 \ + http://localhost:7777/lume/vms +``` + + + + +```python +import requests + +r = requests.get("http://localhost:7777/lume/vms", timeout=50) +print(r.json()) +``` + + + + +```typescript +const res = await fetch('http://localhost:7777/lume/vms'); +console.log(await res.json()); +``` + + + + +```json +[ + { + "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 details for a specific virtual machine. + +`GET: /lume/vms/:name` + +#### Parameters + +| Name | Type | Required | Description | +| ------- | ------ | -------- | -------------------------- | +| storage | string | No | Storage type (`ssd`, etc.) | + +#### Example Request + + + + +```bash +# Basic get +curl --connect-timeout 6000 \ + --max-time 5000 \ + http://localhost:7777/lume/vms/lume_vm + +# Get with specific storage +curl --connect-timeout 6000 \ + --max-time 5000 \ + http://localhost:7777/lume/vms/lume_vm?storage=ssd +``` + + + + +```python +import requests + +# Basic get +details = requests.get("http://localhost:7777/lume/vms/lume_vm", timeout=50) +print(details.json()) + +# Get with specific storage +details = requests.get("http://localhost:7777/lume/vms/lume_vm", params={"storage": "ssd"}, timeout=50) +print(details.json()) +``` + + + + +```typescript +// Basic get +let res = await fetch('http://localhost:7777/lume/vms/lume_vm'); +console.log(await res.json()); + +// Get with specific storage +res = await fetch('http://localhost:7777/lume/vms/lume_vm?storage=ssd'); +console.log(await res.json()); +``` + + + + +```json +{ + "name": "lume_vm", + "state": "stopped", + "os": "macOS", + "cpu": 2, + "memory": "4GB", + "diskSize": "64GB", + "display": "1024x768", + "ipAddress": "192.168.65.2", + "vncPort": 5900, + "sharedDirectories": [ + { + "hostPath": "~/Projects", + "readOnly": false, + "tag": "com.apple.virtio-fs.automount" + } + ] +} +``` + +--- + +### Update VM Configuration + +Update the configuration of a virtual machine. + +`PATCH: /lume/vms/:name` + +#### Parameters + +| Name | Type | Required | Description | +| -------- | ------- | -------- | ------------------------------------- | +| cpu | integer | No | Number of CPU cores | +| memory | string | No | Memory size (e.g. `8GB`) | +| diskSize | string | No | Disk size (e.g. `100GB`) | +| display | string | No | Display resolution (e.g. `1920x1080`) | +| storage | string | No | Storage type (`ssd`, etc.) | + +#### Example Request + + + + +```bash +curl --connect-timeout 6000 \ + --max-time 5000 \ + -X PATCH \ + -H "Content-Type: application/json" \ + -d '{ + "cpu": 4, + "memory": "8GB", + "diskSize": "100GB", + "display": "1920x1080", + "storage": "ssd" + }' \ + http://localhost:7777/lume/vms/lume_vm +``` + + + + +```python +import requests + +payload = { + "cpu": 4, + "memory": "8GB", + "diskSize": "100GB", + "display": "1920x1080", + "storage": "ssd" +} +r = requests.patch("http://localhost:7777/lume/vms/lume_vm", json=payload, timeout=50) +print(r.json()) +``` + + + + +```typescript +const payload = { + cpu: 4, + memory: '8GB', + diskSize: '100GB', + display: '1920x1080', + storage: 'ssd', +}; +const res = await fetch('http://localhost:7777/lume/vms/lume_vm', { + method: 'PATCH', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify(payload), +}); +console.log(await res.json()); +``` + + + + +--- + +### Stop VM + +Stop a running virtual machine. + +`POST: /lume/vms/:name/stop` + +#### Parameters + +| Name | Type | Required | Description | +| ------- | ------ | -------- | -------------------------- | +| storage | string | No | Storage type (`ssd`, etc.) | + +#### Example Request + + + + +```bash +# Basic stop +curl --connect-timeout 6000 \ + --max-time 5000 \ + -X POST \ + http://localhost:7777/lume/vms/lume_vm/stop + +# Stop with storage location specified +curl --connect-timeout 6000 \ + --max-time 5000 \ + -X POST \ + http://localhost:7777/lume/vms/lume_vm/stop?storage=ssd +``` + + + + +```python +import requests + +# Basic stop +r = requests.post("http://localhost:7777/lume/vms/lume_vm/stop", timeout=50) +print(r.json()) + +# Stop with storage location specified +r = requests.post("http://localhost:7777/lume/vms/lume_vm/stop", params={"storage": "ssd"}, timeout=50) +print(r.json()) +``` + + + + +```typescript +// Basic stop +let res = await fetch('http://localhost:7777/lume/vms/lume_vm/stop', { + method: 'POST', +}); +console.log(await res.json()); + +// Stop with storage location specified +res = await fetch('http://localhost:7777/lume/vms/lume_vm/stop?storage=ssd', { + method: 'POST', +}); +console.log(await res.json()); +``` + + + + +--- + +### Delete VM + +Delete a virtual machine instance. + +`DELETE: /lume/vms/:name` + +#### Parameters + +| Name | Type | Required | Description | +| ------- | ------ | -------- | -------------------------- | +| storage | string | No | Storage type (`ssd`, etc.) | + +#### Example Request + + + + +```bash +# Basic delete +curl --connect-timeout 6000 \ + --max-time 5000 \ + -X DELETE \ + http://localhost:7777/lume/vms/lume_vm + +# Delete with specific storage +curl --connect-timeout 6000 \ + --max-time 5000 \ + -X DELETE \ + http://localhost:7777/lume/vms/lume_vm?storage=ssd +``` + + + + +```python +import requests + +# Basic delete +r = requests.delete("http://localhost:7777/lume/vms/lume_vm", timeout=50) +print(r.status_code) + +# Delete with specific storage +r = requests.delete("http://localhost:7777/lume/vms/lume_vm", params={"storage": "ssd"}, timeout=50) +print(r.status_code) +``` + + + + +```typescript +// Basic delete +let res = await fetch('http://localhost:7777/lume/vms/lume_vm', { + method: 'DELETE', +}); +console.log(res.status); + +// Delete with specific storage +res = await fetch('http://localhost:7777/lume/vms/lume_vm?storage=ssd', { + method: 'DELETE', +}); +console.log(res.status); +``` + + + + +--- + +### Clone VM + +Clone an existing virtual machine. + +`POST: /lume/vms/clone` + +#### Parameters + +| Name | Type | Required | Description | +| -------------- | ------ | -------- | ----------------------------------- | +| name | string | Yes | Source VM name | +| newName | string | Yes | New VM name | +| sourceLocation | string | No | Source storage location (`default`) | +| destLocation | string | No | Destination storage location | + +#### Example Request + + + + +```bash +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 +``` + + + + +```python +import requests + +payload = { + "name": "source-vm", + "newName": "cloned-vm", + "sourceLocation": "default", + "destLocation": "ssd" +} +r = requests.post("http://localhost:7777/lume/vms/clone", json=payload, timeout=50) +print(r.json()) +``` + + + + +```typescript +const payload = { + name: 'source-vm', + newName: 'cloned-vm', + sourceLocation: 'default', + destLocation: 'ssd', +}; +const res = await fetch('http://localhost:7777/lume/vms/clone', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify(payload), +}); +console.log(await res.json()); +``` + + + + +--- + +### Pull VM Image + +Pull a VM image from a registry. + +`POST: /lume/pull` + +#### Parameters + +| Name | Type | Required | Description | +| ------------ | ------ | -------- | ------------------------------------- | +| image | string | Yes | Image name (e.g. `macos-sequoia-...`) | +| name | string | No | VM name for the pulled image | +| registry | string | No | Registry host (e.g. `ghcr.io`) | +| organization | string | No | Organization name | +| storage | string | No | Storage type (`ssd`, etc.) | + +#### Example Request + + + + +```bash +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 +``` + + + + +```python +import requests + +payload = { + "image": "macos-sequoia-vanilla:latest", + "name": "my-vm-name", + "registry": "ghcr.io", + "organization": "trycua", + "storage": "ssd" +} +r = requests.post("http://localhost:7777/lume/pull", json=payload, timeout=50) +print(r.json()) +``` + + + + +```typescript +const payload = { + image: 'macos-sequoia-vanilla:latest', + name: 'my-vm-name', + registry: 'ghcr.io', + organization: 'trycua', + storage: 'ssd', +}; +const res = await fetch('http://localhost:7777/lume/pull', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify(payload), +}); +console.log(await res.json()); +``` + + + + +--- + +### Push VM Image + +Push a VM to a registry as an image (asynchronous operation). + +`POST: /lume/vms/push` + +#### Parameters + +| Name | Type | Required | Description | +| ------------ | ------------ | -------- | ----------------------------------------------- | +| name | string | Yes | Local VM name to push | +| imageName | string | Yes | Image name in registry | +| tags | array | Yes | Image tags (e.g. `["latest", "v1"]`) | +| organization | string | Yes | Organization name | +| registry | string | No | Registry host (e.g. `ghcr.io`) | +| chunkSizeMb | integer | No | Chunk size in MB for upload | +| storage | string/null | No | Storage type (`ssd`, etc.) | + +#### Example Request + + + + +```bash +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 +``` + + + + +```python +import requests + +payload = { + "name": "my-local-vm", + "imageName": "my-image", + "tags": ["latest", "v1"], + "organization": "my-org", + "registry": "ghcr.io", + "chunkSizeMb": 512, + "storage": None +} +r = requests.post("http://localhost:7777/lume/vms/push", json=payload, timeout=50) +print(r.json()) +``` + + + + +```typescript +const payload = { + name: 'my-local-vm', + imageName: 'my-image', + tags: ['latest', 'v1'], + organization: 'my-org', + registry: 'ghcr.io', + chunkSizeMb: 512, + storage: null, +}; +const res = await fetch('http://localhost:7777/lume/vms/push', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify(payload), +}); +console.log(await res.json()); +``` + + + + +**Response (202 Accepted):** + +```json +{ + "message": "Push initiated in background", + "name": "my-local-vm", + "imageName": "my-image", + "tags": [ + "latest", + "v1" + ] +} +``` + +--- + +### List Images + +List available VM images. + +`GET: /lume/images` + +#### Example Request + + + + +```bash +curl --connect-timeout 6000 \ + --max-time 5000 \ + http://localhost:7777/lume/images +``` + + + + +```python +import requests + +r = requests.get("http://localhost:7777/lume/images", timeout=50) +print(r.json()) +``` + + + + +```typescript +const res = await fetch('http://localhost:7777/lume/images'); +console.log(await res.json()); +``` + + + + +```json +{ + "local": [ + "macos-sequoia-xcode:latest", + "macos-sequoia-vanilla:latest" + ] +} +``` + +--- + +### Prune Images + +Remove unused VM images to free up disk space. + +`POST: /lume/prune` + +#### Example Request + + + + +```bash +curl --connect-timeout 6000 \ + --max-time 5000 \ + -X POST \ + http://localhost:7777/lume/prune +``` + + + + +```python +import requests + +r = requests.post("http://localhost:7777/lume/prune", timeout=50) +print(r.json()) +``` + + + + +```typescript +const res = await fetch('http://localhost:7777/lume/prune', { + method: 'POST', +}); +console.log(await res.json()); +``` + + + + +--- + +### Get Latest IPSW URL + +Get the URL for the latest macOS IPSW file. + +`GET: /lume/ipsw` + +#### Example Request + + + + +```bash +curl --connect-timeout 6000 \ + --max-time 5000 \ + http://localhost:7777/lume/ipsw +``` + + + + +```python +import requests + +r = requests.get("http://localhost:7777/lume/ipsw", timeout=50) +print(r.json()) +``` + + + + +```typescript +const res = await fetch('http://localhost:7777/lume/ipsw'); +console.log(await res.json()); +``` + + + + +--- + +## Configuration Management + +### Get Configuration + +Get current Lume configuration settings. + +`GET: /lume/config` + +#### Example Request + + + + +```bash +curl --connect-timeout 6000 \ + --max-time 5000 \ + http://localhost:7777/lume/config +``` + + + + +```python +import requests + +r = requests.get("http://localhost:7777/lume/config", timeout=50) +print(r.json()) +``` + + + + +```typescript +const res = await fetch('http://localhost:7777/lume/config'); +console.log(await res.json()); +``` + + + + +```json +{ + "homeDirectory": "~/.lume", + "cacheDirectory": "~/.lume/cache", + "cachingEnabled": true +} +``` + +### Update Configuration + +Update Lume configuration settings. + +`POST: /lume/config` + +#### Parameters + +| Name | Type | Required | Description | +| --------------- | ------- | -------- | -------------------------------- | +| homeDirectory | string | No | Lume home directory path | +| cacheDirectory | string | No | Cache directory path | +| cachingEnabled | boolean | No | Enable or disable caching | + +#### Example Request + + + + +```bash +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 +``` + + + + +```python +import requests + +payload = { + "homeDirectory": "~/custom/lume", + "cacheDirectory": "~/custom/lume/cache", + "cachingEnabled": True +} +r = requests.post("http://localhost:7777/lume/config", json=payload, timeout=50) +print(r.json()) +``` + + + + +```typescript +const payload = { + homeDirectory: '~/custom/lume', + cacheDirectory: '~/custom/lume/cache', + cachingEnabled: true, +}; +const res = await fetch('http://localhost:7777/lume/config', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify(payload), +}); +console.log(await res.json()); +``` + + + + +--- + +## Storage Location Management + +### Get VM Storage Locations + +List all configured VM storage locations. + +`GET: /lume/config/locations` + +#### Example Request + + + + +```bash +curl --connect-timeout 6000 \ + --max-time 5000 \ + http://localhost:7777/lume/config/locations +``` + + + + +```python +import requests + +r = requests.get("http://localhost:7777/lume/config/locations", timeout=50) +print(r.json()) +``` + + + + +```typescript +const res = await fetch('http://localhost:7777/lume/config/locations'); +console.log(await res.json()); +``` + + + + +```json +[ + { + "name": "default", + "path": "~/.lume/vms", + "isDefault": true + }, + { + "name": "ssd", + "path": "/Volumes/SSD/lume/vms", + "isDefault": false + } +] +``` + +### Add VM Storage Location + +Add a new VM storage location. + +`POST: /lume/config/locations` + +#### Parameters + +| Name | Type | Required | Description | +| ---- | ------ | -------- | ---------------------------- | +| name | string | Yes | Storage location name | +| path | string | Yes | File system path for storage | + +#### Example Request + @@ -169,1068 +1265,3 @@ console.log(await res.json()); - "name": "lume_vm", - "os": "macOS", - "cpu": 2, - "memory": "4GB", - "diskSize": "64GB", - "display": "1024x768", - "ipsw": "latest", - "storage": "ssd" - }' \ - http://localhost:7777/lume/vms -``` - - - - -```python -import requests - -payload = { - "name": "lume_vm", - "os": "macOS", - "cpu": 2, - "memory": "4GB", - "diskSize": "64GB", - "display": "1024x768", - "ipsw": "latest", - "storage": "ssd" -} -r = requests.post("http://localhost:7777/lume/vms", json=payload, timeout=50) -print(r.json()) -``` - - - - -```typescript -const payload = { - name: "lume_vm", - os: "macOS", - cpu: 2, - memory: "4GB", - diskSize: "64GB", - display: "1024x768", - ipsw: "latest", - storage: "ssd" -} - -const res = await fetch('http://localhost:7777/lume/vms', { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify(payload), -}); -console.log(await res.json()) -``` - - - - -### Run VM - -Run a virtual machine instance. - -`POST: /vms/:name/run` - -#### Parameters - -| Name | Type | Required | Description | -| ----------------- | --------------- | -------- | --------------------------------------------------- | -| noDisplay | boolean | No | If true, do not start VNC client | -| sharedDirectories | array of object | No | List of shared directories (`hostPath`, `readOnly`) | -| recoveryMode | boolean | No | Start in recovery mode | -| storage | string | No | Storage type (`ssd`, etc.) | - -#### Example Request - - - - -```bash -# 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 -``` - - - - -```python -import requests - -# Basic run -r = requests.post("http://localhost:7777/lume/vms/my-vm-name/run", timeout=50) -print(r.json()) - -# With VNC and shared directory -payload = { - "noDisplay": False, - "sharedDirectories": [ - {"hostPath": "~/Projects", "readOnly": False} - ], - "recoveryMode": False, - "storage": "ssd" -} -r = requests.post("http://localhost:7777/lume/vms/lume_vm/run", json=payload, timeout=50) -print(r.json()) -``` - - - - -```typescript -// Basic run -const res = await fetch('http://localhost:7777/lume/vms/my-vm-name/run', { - method: 'POST', -}); -console.log(await res.json()); - -// With VNC and shared directory -const payload = { - noDisplay: false, - sharedDirectories: [{ hostPath: '~/Projects', readOnly: false }], - recoveryMode: false, - storage: 'ssd', -}; -const res2 = await fetch('http://localhost:7777/lume/vms/lume_vm/run', { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify(payload), -}); -console.log(await res2.json()); -``` - - - - -### List VMs - -List all virtual machines. - -`GET: /vms` - -#### Example Request - - - - -```bash -curl --connect-timeout 6000 \ - --max-time 5000 \ - http://localhost:7777/lume/vms -``` - - - - -```python -import requests - -r = requests.get("http://localhost:7777/lume/vms", timeout=50) -print(r.json()) -``` - - - - -```typescript -const res = await fetch('http://localhost:7777/lume/vms'); -console.log(await res.json()); -``` - - - - -```json -[ - { - "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 details for a specific virtual machine. - -`GET: /vms/:name` - -#### Parameters - -| Name | Type | Required | Description | -| ------- | ------ | -------- | -------------------------- | -| storage | string | No | Storage type (`ssd`, etc.) | - -#### Example Request - - - - -```bash -# Basic get -curl --connect-timeout 6000 \ - --max-time 5000 \ - http://localhost:7777/lume/vms/lume_vm - -# Get with specific storage -curl --connect-timeout 6000 \ - --max-time 5000 \ - http://localhost:7777/lume/vms/lume_vm?storage=ssd -``` - - - - -```python -import requests - -# Basic get -details = requests.get("http://localhost:7777/lume/vms/lume_vm", timeout=50) -print(details.json()) - -# Get with specific storage -details = requests.get("http://localhost:7777/lume/vms/lume_vm", params={"storage": "ssd"}, timeout=50) -print(details.json()) -``` - - - - -```typescript -// Basic get -const res = await fetch('http://localhost:7777/lume/vms/lume_vm'); -console.log(await res.json()); - -// Get with specific storage -const res2 = await fetch('http://localhost:7777/lume/vms/lume_vm?storage=ssd'); -console.log(await res2.json()); -``` - - - - -```json -{ - "name": "lume_vm", - "state": "stopped", - "os": "macOS", - "cpu": 2, - "memory": "4GB", - "diskSize": "64GB", - "display": "1024x768", - "ipAddress": "192.168.65.2", - "vncPort": 5900, - "sharedDirectories": [ - { - "hostPath": "~/Projects", - "readOnly": false, - "tag": "com.apple.virtio-fs.automount" - } - ] -} -``` - -### Update VM Configuration - -Update the configuration of a virtual machine. - -`PATCH: /vms/:name` - -#### Parameters - -| Name | Type | Required | Description | -| -------- | ------- | -------- | ------------------------------------- | -| cpu | integer | No | Number of CPU cores | -| memory | string | No | Memory size (e.g. `8GB`) | -| diskSize | string | No | Disk size (e.g. `100GB`) | -| display | string | No | Display resolution (e.g. `1920x1080`) | -| storage | string | No | Storage type (`ssd`, etc.) | - -#### Example Request - - - - -```bash -curl --connect-timeout 6000 \ - --max-time 5000 \ - -X PATCH \ - -H "Content-Type: application/json" \ - -d '{ - "cpu": 4, - "memory": "8GB", - "diskSize": "100GB", - "display": "1920x1080", - "storage": "ssd" - }' \ - http://localhost:7777/lume/vms/lume_vm -``` - - - - -```python -import requests - -payload = { - "cpu": 4, - "memory": "8GB", - "diskSize": "100GB", - "display": "1920x1080", - "storage": "ssd" -} -r = requests.patch("http://localhost:7777/lume/vms/lume_vm", json=payload, timeout=50) -print(r.json()) -``` - - - - -```typescript -const payload = { - cpu: 4, - memory: '8GB', - diskSize: '100GB', - display: '1920x1080', - storage: 'ssd', -}; -const res = await fetch('http://localhost:7777/lume/vms/lume_vm', { - method: 'PATCH', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify(payload), -}); -console.log(await res.json()); -``` - - - - -### Stop VM - -Stop a running virtual machine. - -`POST: /vms/:name/stop` - -#### Parameters - -| Name | Type | Required | Description | -| ------- | ------ | -------- | -------------------------- | -| storage | string | No | Storage type (`ssd`, etc.) | - -#### Example Request - - - - -```bash -# Basic stop -curl --connect-timeout 6000 \ - --max-time 5000 \ - -X POST \ - http://localhost:7777/lume/vms/lume_vm/stop - -# Stop with storage location specified -curl --connect-timeout 6000 \ - --max-time 5000 \ - -X POST \ - http://localhost:7777/lume/vms/lume_vm/stop?storage=ssd -``` - - - - -```python -import requests - -# Basic stop -r = requests.post("http://localhost:7777/lume/vms/lume_vm/stop", timeout=50) -print(r.json()) - -# Stop with storage location specified -r = requests.post("http://localhost:7777/lume/vms/lume_vm/stop", params={"storage": "ssd"}, timeout=50) -print(r.json()) -``` - - - - -```typescript -// Basic stop -const res = await fetch('http://localhost:7777/lume/vms/lume_vm/stop', { - method: 'POST', -}); -console.log(await res.json()); - -// Stop with storage location specified -const res2 = await fetch('http://localhost:7777/lume/vms/lume_vm/stop?storage=ssd', { - method: 'POST', -}); -console.log(await res2.json()); -``` - - - - -### Delete VM - -Delete a virtual machine instance. - -`DELETE: /vms/:name` - -#### Parameters - -| Name | Type | Required | Description | -| ------- | ------ | -------- | -------------------------- | -| storage | string | No | Storage type (`ssd`, etc.) | - -#### Example Request - - - - -```bash -# Basic delete -curl --connect-timeout 6000 \ - --max-time 5000 \ - -X DELETE \ - http://localhost:7777/lume/vms/lume_vm - -# Delete with specific storage -curl --connect-timeout 6000 \ - --max-time 5000 \ - -X DELETE \ - http://localhost:7777/lume/vms/lume_vm?storage=ssd -``` - - - - -```python -import requests - -# Basic delete -r = requests.delete("http://localhost:7777/lume/vms/lume_vm", timeout=50) -print(r.status_code) - -# Delete with specific storage -r = requests.delete("http://localhost:7777/lume/vms/lume_vm", params={"storage": "ssd"}, timeout=50) -print(r.status_code) -``` - - - - -```typescript -// Basic delete -const res = await fetch('http://localhost:7777/lume/vms/lume_vm', { - method: 'DELETE', -}); -console.log(res.status); - -// Delete with specific storage -const res2 = await fetch('http://localhost:7777/lume/vms/lume_vm?storage=ssd', { - method: 'DELETE', -}); -console.log(res2.status); -``` - - - - -### Clone VM - -Clone an existing virtual machine. - -`POST: /vms/:name/clone` - -#### Parameters - -| Name | Type | Required | Description | -| -------------- | ------ | -------- | ----------------------------------- | -| name | string | Yes | Source VM name | -| newName | string | Yes | New VM name | -| sourceLocation | string | No | Source storage location (`default`) | -| destLocation | string | No | Destination storage location | - -#### Example Request - - - - -```bash -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 -``` - - - - -```python -import requests - -payload = { - "name": "source-vm", - "newName": "cloned-vm", - "sourceLocation": "default", - "destLocation": "ssd" -} -r = requests.post("http://localhost:7777/lume/vms/clone", json=payload, timeout=50) -print(r.json()) -``` - - - - -```typescript -const payload = { - name: 'source-vm', - newName: 'cloned-vm', - sourceLocation: 'default', - destLocation: 'ssd', -}; -const res = await fetch('http://localhost:7777/lume/vms/clone', { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify(payload), -}); -console.log(await res.json()); -``` - - - - -### Pull VM Image - -Pull a VM image from a registry. - -`POST: /pull` - -#### Parameters - -| Name | Type | Required | Description | -| ------------ | ------ | -------- | ------------------------------------- | -| image | string | Yes | Image name (e.g. `macos-sequoia-...`) | -| name | string | No | VM name for the pulled image | -| registry | string | No | Registry host (e.g. `ghcr.io`) | -| organization | string | No | Organization name | -| storage | string | No | Storage type (`ssd`, etc.) | - -#### Example Request - - - - -```bash -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 -``` - - - - -```python -import requests - -payload = { - "image": "macos-sequoia-vanilla:latest", - "name": "my-vm-name", - "registry": "ghcr.io", - "organization": "trycua", - "storage": "ssd" -} -r = requests.post("http://localhost:7777/lume/pull", json=payload, timeout=50) -print(r.json()) -``` - - - - -```typescript -const payload = { - image: 'macos-sequoia-vanilla:latest', - name: 'my-vm-name', - registry: 'ghcr.io', - organization: 'trycua', - storage: 'ssd', -}; -const res = await fetch('http://localhost:7777/lume/pull', { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify(payload), -}); -console.log(await res.json()); -``` - - - - -### Push VM Image - -Push a VM to a registry as an image (asynchronous operation). - -`POST: /vms/push` - -#### Parameters - -| Name | Type | Required | Description | -| ------------ | ------------ | -------- | ----------------------------------------------- | -| name | string | Yes | Local VM name to push | -| imageName | string | Yes | Image name in registry | -| tags | array | Yes | Image tags (e.g. `["latest", "v1"]`) | -| organization | string | Yes | Organization name | -| registry | string | No | Registry host (e.g. `ghcr.io`) | -| chunkSizeMb | integer | No | Chunk size in MB for upload | -| storage | string/null | No | Storage type (`ssd`, etc.) | - -#### Example Request - - - - -```bash -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 -``` - - - - -```python -import requests - -payload = { - "name": "my-local-vm", - "imageName": "my-image", - "tags": ["latest", "v1"], - "organization": "my-org", - "registry": "ghcr.io", - "chunkSizeMb": 512, - "storage": None -} -r = requests.post("http://localhost:7777/lume/vms/push", json=payload, timeout=50) -print(r.json()) -``` - - - - -```typescript -const payload = { - name: 'my-local-vm', - imageName: 'my-image', - tags: ['latest', 'v1'], - organization: 'my-org', - registry: 'ghcr.io', - chunkSizeMb: 512, - storage: null, -}; -const res = await fetch('http://localhost:7777/lume/vms/push', { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify(payload), -}); -console.log(await res.json()); -``` - - - - -**Response (202 Accepted):** - -```json -{ - "message": "Push initiated in background", - "name": "my-local-vm", - "imageName": "my-image", - "tags": [ - "latest", - "v1" - ] -} -``` - -### List Images - -List available VM images. - -`GET: /images` - -#### Example Request - - - - -```bash -curl --connect-timeout 6000 \ - --max-time 5000 \ - http://localhost:7777/lume/images -``` - - - - -```python -import requests - -r = requests.get("http://localhost:7777/lume/images", timeout=50) -print(r.json()) -``` - - - - -```typescript -const res = await fetch('http://localhost:7777/lume/images'); -console.log(await res.json()); -``` - - - - -```json -{ - "local": [ - "macos-sequoia-xcode:latest", - "macos-sequoia-vanilla:latest" - ] -} -``` - -### Prune Images - -Remove unused VM images to free up disk space. - -`POST: /lume/prune` - -#### Example Request - - - - -```bash -curl --connect-timeout 6000 \ - --max-time 5000 \ - -X POST \ - http://localhost:7777/lume/prune -``` - - - - -```python -import requests - -r = requests.post("http://localhost:7777/lume/prune", timeout=50) -print(r.json()) -``` - - - - -```typescript -const res = await fetch('http://localhost:7777/lume/prune', { - method: 'POST', -}); -console.log(await res.json()); -``` - - - - -### Get Latest IPSW URL - -Get the URL for the latest macOS IPSW file. - -`GET: /ipsw` - -#### Example Request - - - - -```bash -curl --connect-timeout 6000 \ - --max-time 5000 \ - http://localhost:7777/lume/ipsw -``` - - - - -```python -import requests - -r = requests.get("http://localhost:7777/lume/ipsw", timeout=50) -print(r.json()) -``` - - - - -```typescript -const res = await fetch('http://localhost:7777/lume/ipsw'); -console.log(await res.json()); -``` - - - - -## Configuration Management - -### Get Configuration - -Get current Lume configuration settings. - -`GET: /lume/config` - -#### Example Request - - - - -```bash -curl --connect-timeout 6000 \ - --max-time 5000 \ - http://localhost:7777/lume/config -``` - - - - -```python -import requests - -r = requests.get("http://localhost:7777/lume/config", timeout=50) -print(r.json()) -``` - - - - -```typescript -const res = await fetch('http://localhost:7777/lume/config'); -console.log(await res.json()); -``` - - - - -```json -{ - "homeDirectory": "~/.lume", - "cacheDirectory": "~/.lume/cache", - "cachingEnabled": true -} -``` - -### Update Configuration - -Update Lume configuration settings. - -`POST: /lume/config` - -#### Parameters - -| Name | Type | Required | Description | -| --------------- | ------- | -------- | -------------------------------- | -| homeDirectory | string | No | Lume home directory path | -| cacheDirectory | string | No | Cache directory path | -| cachingEnabled | boolean | No | Enable or disable caching | - -#### Example Request - - - - -```bash -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 -``` - - - - -```python -import requests - -payload = { - "homeDirectory": "~/custom/lume", - "cacheDirectory": "~/custom/lume/cache", - "cachingEnabled": True -} -r = requests.post("http://localhost:7777/lume/config", json=payload, timeout=50) -print(r.json()) -``` - - - - -```typescript -const payload = { - homeDirectory: '~/custom/lume', - cacheDirectory: '~/custom/lume/cache', - cachingEnabled: true, -}; -const res = await fetch('http://localhost:7777/lume/config', { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify(payload), -}); -console.log(await res.json()); -``` - - - - -## Storage Location Management - -### Get VM Storage Locations - -List all configured VM storage locations. - -`GET: /lume/config/locations` - -#### Example Request - - - - -```bash -curl --connect-timeout 6000 \ - --max-time 5000 \ - http://localhost:7777/lume/config/locations -``` - - - - -```python -import requests - -r = requests.get("http://localhost:7777/lume/config/locations", timeout=50) -print(r.json()) -``` - - - - -```typescript -const res = await fetch('http://localhost:7777/lume/config/locations'); -console.log(await res.json()); -``` - - - - -```json -[ - { - "name": "default", - "path": "~/.lume/vms", - "isDefault": true - }, - { - "name": "ssd", - "path": "/Volumes/SSD/lume/vms", - "isDefault": false - } -] -``` - -### Add VM Storage Location - -Add a new VM storage location. - -`POST: /lume/config/locations` - -#### Parameters - -| Name | Type | Required | Description | -| ---- | ------ | -------- | ------------------------------ | -| name | string | Yes | Storage location name | -| path | string | Yes | File system path for storage | - -#### Example Request - - - - -```bash -curl --connect-timeout 6000 \ - --max-time 5000 \ - -X POST \ - -H "Content-Type: application/json" \ - -d '{ \ No newline at end of file