v0.1.7

Install Endpoint

Last updated


This page covers the request fields, defaults, and response of POST /api/vm/install.

Request


  1. curl -N -X POST http://192.168.0.11:8080/api/vm/install \
  2. -H "Content-Type: application/json" \
  3. -d '{
  4. "name": "web",
  5. "os": "ubuntu",
  6. "version": "24.04",
  7. "cpu": 2,
  8. "ram": 4096,
  9. "disk": "32G",
  10. "node": "pve2",
  11. "pubkey": "ssh-ed25519 AAAA... user@laptop"
  12. }'

Fields


FieldTypeRequiredDefaultRule
osstringYes—debian / ubuntu / rockylinux
versionstringYes—See supported versions
idintNoautoUsed as is without an availability check; also sets the last IP octet
namestringNoVMIDFinal name becomes <name>-<vmid>
nodestringNomain nodeMigrate to this node after creation, before first boot
cpuintNo1≤ 0 → 1; capped by VM_MAX_CPU
ramintNo512MB; < 512 → 512; capped by VM_MAX_RAM
diskstringNo16GParses the number after stripping G; < 16 → 16G; ≥ VM_MAX_DISK → the cap
userstringNoper OSCloud-init user; defaults to debian / ubuntu / rocky
passwdstringNopasswdCloud-init user password
pubkeystringNo—Extra SSH public key to inject

The server overwrites ip, gateway, and storage from the VMID, GATEWAY, and ASSIGN_STORAGE; values sent by clients have no effect.
The SSH readiness check always logs in as the OS default user (debian / ubuntu / rocky), while the init script logs in as user; with a custom user, both accounts must accept the main node's key.

Response


CaseResponse
JSON parsing or os / version validation fails400 JSON: {"success": false, "message": "please check your input:..."}
Client IP not in ALLOW_IPS200 with a single data: error line
OtherwiseAn SSE stream reporting each Provisioning Pipeline stage, ending with event: close

The last four events on success:
  1. data: {"step":"VM initialization > finalizing","status":"success","message":"[+] VM installation completed in 182.41s"}
  2. data: {"step":"VM initialization > finalizing","status":"success","message":"[*] VMID: 120"}
  3. data: {"step":"VM initialization > finalizing","status":"success","message":"[*] IP: 192.168.0.120"}
  4. data: {"step":"VM initialization > finalizing","status":"success","message":"[*] User: ubuntu"}

SSE streams always return HTTP 200; success means no event with status: "error" appeared.
中文