# 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](/multi-node-dispatch).

## start / reboot

```bash
curl -N -X POST http://192.168.0.11:8080/api/vm/120/start
```

```text
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

```bash
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

```bash
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](/vmid-ip-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 |