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