Lifecycle Endpoints
Last updated
This page covers the five endpoints that start, reboot, shut down, force-stop, and destroy a VM.
Overview
| Endpoint | qm command | Required VM state | Response |
|---|---|---|---|
POST /api/vm/:id/start | qm start | stopped | SSE, waits until SSH accepts logins |
POST /api/vm/:id/reboot | qm reboot | running | SSE, waits until SSH accepts logins |
POST /api/vm/:id/shutdown | qm shutdown | running | text ok |
POST /api/vm/:id/stop | qm stop | running | text ok |
POST /api/vm/:id/destroy | qm destroy | stopped | text ok |
All are subject to
ALLOW_IPS and the disabled list, and run on the VM's node via Multi-Node Dispatch.start / reboot
- curl -N -X POST http://192.168.0.11:8080/api/vm/120/start
- data: {"step":"starting VM","status":"success","message":"[+] VM starting (1.12s)"}
- data: {"step":"waiting for SSH","status":"success","message":"[+] VM is ready (24.37s)"}
- data: {"step":"finalizing","status":"info","message":"[+] VM started successfully"}
- event: close
- data: {}
| Step | Behavior |
|---|---|
Run qm start / qm reboot | On failure, sends an error message and stops |
waiting for SSH | Picks the login user from the VM's OS tag (debian / ubuntu / rocky), tries every 5 seconds, up to 60 times |
finalizing | Waits 5 seconds, then sends an info event |
A VM without an OS tag (not created by this service) fails
waiting for SSH with OS user not found; the start command itself has already completed.shutdown / stop
- curl -X POST http://192.168.0.11:8080/api/vm/120/shutdown
- # ok
shutdown sends an ACPI power-off and waits for qm shutdown to return; stop cuts power immediately.destroy
- curl -X POST http://192.168.0.11:8080/api/vm/120/destroy
- # ok
Accepts only stopped VMs and runs
qm destroy <vmid> (without --purge). The VMID and IP become available to automatic allocation again.Error Responses
| Case | Sync endpoints | SSE endpoints |
|---|---|---|
Client IP not in ALLOW_IPS | 403 | single data: error |
| Wrong VM state or on the disabled list | 400 | single data: error |
qm fails | 500 failed to ... VM: <output> | data: error, then stop |