Quick Start

This guide walks you through creating your first VM in under a minute.

Imperative (One-Off)

Create and start a VM from an Ubuntu cloud image:

vmctl create \
  --name demo \
  --image-url https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img \
  --vcpus 2 \
  --memory 2048 \
  --start

Wait a moment for the image to download and the VM to boot, then connect:

vmctl ssh demo

When you're done:

vmctl destroy demo

Declarative (Reproducible)

Create a VMFile.kdl in your project directory:

vm "demo" {
    image-url "https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img"
    vcpus 2
    memory 2048

    cloud-init {
        hostname "demo"
    }

    ssh {
        user "ubuntu"
    }
}

Bring it up:

vmctl up

vmctl will download the image (cached for future use), create a QCOW2 overlay, generate an Ed25519 SSH keypair, build a cloud-init ISO, and boot the VM.

Connect:

vmctl ssh

Tear it down:

vmctl down

Or destroy it completely (removes all VM files):

vmctl down --destroy

Next Steps

• Concepts: How vmctl Works for an understanding of what happens under the hood.
• Tutorials: Declarative Workflow for a complete walkthrough with provisioning.
• VMFile.kdl Reference for the full configuration format.