Documentation v0.1.7
Home GitHub

Lifecycle Endpoints

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
中文