# Boot a VM image as a zone

Edera zones are normally composed from OCI images. A **VM-image zone** is a different zone type: it boots an unmodified, UEFI-bootable virtual machine disk image—raw or qcow2—directly, with no repackaging. This lets you run VM-based workloads, such as GPU fleet images or vendor appliances shipped as virtual machines, on Edera without converting them to containers.

⚠️  
VM-image zones are an **Early Access** feature built on the KVM backend. They are not intended for production use and have not completed Edera’s security review.

## Prerequisites

- A **KVM-backed Edera host**. VM-image zones require the KVM virtualization backend, which is selected when you install Edera. They do not run on the Xen backend.
- A **UEFI-bootable disk image** in raw or qcow2 format. The image boots through Edera’s UEFI firmware, so it must use UEFI boot rather than legacy BIOS.
- A **cloud-init-enabled image**. Edera provisions the zone with a cloud-init seed that installs its in-zone agent. Without cloud-init the VM still boots, but the zone does not reach the `ready` state or support `exec`, `logs`, and metrics. The official Ubuntu cloud images work out of the box.
- Familiarity with the `protect` CLI.

## Stage the disk image

Copy the image into the daemon’s VM-image directory on the host, `/var/lib/edera/protect/vm-images/`:

```bash
sudo cp jammy-server-cloudimg-amd64.qcow2 /var/lib/edera/protect/vm-images/
```

The `--vm-image` flag takes the **bare filename** of an image in this directory—not a path. Keep the file extension consistent with the format.

## Launch the zone

Launch a zone from the staged image with `protect zone launch`, passing both `--vm-image` and the required `--vm-image-format`:

```bash
# qcow2 image
protect zone launch \
  --name vm-demo \
  --vm-image jammy-server-cloudimg-amd64.qcow2 \
  --vm-image-format qcow2
```

For a raw disk image, set the format to `raw`:

```bash
# raw disk image
protect zone launch \
  --name vm-demo \
  --vm-image disk.raw \
  --vm-image-format raw
```

`--vm-image-format` is required. Edera does not detect the format automatically.

## Verify the zone

Check that the zone reached the `ready` state:

```bash
protect zone list
```

Once ready, the zone behaves like any other Edera zone. Run a command inside it and read its console logs:

```bash
protect zone exec vm-demo hostname
protect zone logs vm-demo
```

## Clean up

Destroy the zone when you’re done. This releases the lock on the image file so it can be reused:

```bash
protect zone destroy vm-demo
```

## Requirements and limitations

VM-image zones are validated at launch. Keep these constraints in mind:

- **KVM backend only.** VM-image zones require a host installed with the KVM backend. Launching one on a Xen host is rejected.
- **Explicit format is required.** You must pass `--vm-image-format raw` or `--vm-image-format qcow2`. There is no automatic detection.
- **Filename, not a path.**`--vm-image` takes a bare filename resolved against `/var/lib/edera/protect/vm-images/`. Values containing path separators are rejected.
- **Extension must match the format.** A `qcow2` image must have a `.qcow2` extension. A `raw` image must not use `.qcow2`; raw images are typically `.raw`, `.img`, `.disk`, or have no extension.
- **No container payload.**`--vm-image` is mutually exclusive with `--kernel`, `--initrd`, `--addon`, `--create-scratch-disk`, and `--attach-scratch-disk`. A VM image already carries its own kernel and root filesystem.
- **One live zone per image file.** A given raw or qcow2 file can back only one running zone at a time. Launching a second zone from a file that is already in use fails with a lock error. Copy the image to a second filename to run two zones.
- **cloud-init is required for the full lifecycle.** The zone reaches `ready` and supports `exec`, `logs`, and metrics only if the guest runs cloud-init to apply Edera’s provisioning seed.
- **Supported formats are raw and qcow2.** No other disk image formats are supported.

## Additional resources

- [VM-image zones](https://docs.edera.dev/technical-overview/concepts/vm-image-zones/)  
- [KVM architecture](https://docs.edera.dev/technical-overview/architecture/kvm/)  
- [Running Edera without Kubernetes](https://docs.edera.dev/guides/standalone/no-kubernetes/)  
- [Edera CLI reference](https://docs.edera.dev/reference/cli/)

Last updated on 2026-07-23