## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# VM Lifecycle

Every VM in vmctl moves through a set of well-defined states.

## States

State | Description
--- | ---
`Preparing` | Backend is allocating resources (overlay, ISO, sockets)
`Prepared` | Resources allocated, ready to boot
`Running` | VM is booted and executing
`Stopped` | VM has been shut down (gracefully or forcibly)
`Failed` | An error occurred during a lifecycle operation
`Destroyed` | VM and all its resources have been cleaned up

## Transitions

              prepare()         start()
    [new] ──────────> Prepared ──────────> Running
                                            │  │
                                suspend()   │  │  stop(timeout)
                               ┌────────────┘  └──────────────┐
                               v                               v
                            Suspended ─── resume() ──>     Stopped
                                                            │
                                               start()      │
                                         Running <──────────┘

    Any state ── destroy() ──> Destroyed

## Commands and Transitions

Command | From State | To State
--- | --- | ---
`vmctl create` | (none) | Prepared
`vmctl start` | Prepared, Stopped | Running
`vmctl stop` | Running | Stopped
`vmctl suspend` | Running | Suspended (paused vCPUs)
`vmctl resume` | Suspended | Running
`vmctl destroy` | Any | Destroyed
`vmctl up` | (none), Stopped | Running (auto-creates if needed)
`vmctl down` | Running | Stopped
`vmctl reload` | Any | Running (destroys + recreates)

## Graceful Shutdown

`vmctl stop` sends an ACPI power-down signal via QMP. If the guest doesn't shut down within the timeout (default 30 seconds), vmctl sends SIGTERM, and finally SIGKILL as a last resort.