## 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

# Creating a VM Imperatively

This tutorial walks through the full lifecycle of a VM using individual vmctl commands.

## Create a VM

    vmctl create \
      --name tutorial \
      --image-url https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img \
      --vcpus 2 \
      --memory 2048 \
      --ssh-key ~/.ssh/id_ed25519.pub

This downloads the image (cached for future use), creates a QCOW2 overlay, generates a cloud-init ISO with your SSH key, and registers the VM.

## Start It

    vmctl start tutorial

## Check Status

    vmctl list

    NAME             BACKEND  VCPUS   MEM NETWORK     PID      SSH
    tutorial         qemu     2       2048 user       12345    10042

For detailed info:

    vmctl status tutorial

## Connect via SSH

    vmctl ssh tutorial

vmctl waits for SSH to become available (cloud-init needs a moment to set up the user), then drops you into a shell.

## Suspend and Resume

Pause the VM without shutting it down:

    vmctl suspend tutorial

Resume it:

    vmctl resume tutorial

The VM continues from exactly where it was, no reboot needed.

## Stop the VM

    vmctl stop tutorial

This sends an ACPI power-down signal. If the guest doesn't shut down within 30 seconds, vmctl sends SIGTERM.

To change the timeout:

    vmctl stop tutorial --timeout 60

## Restart

A stopped VM can be started again:

    vmctl start tutorial

## Destroy

When you're done, clean up everything:

    vmctl destroy tutorial

This stops the VM (if running), removes the overlay, cloud-init ISO, and all work directory files, and unregisters the VM from the store.