---
name: azldev-image
description: "Read this before building, booting, or configuring an azldev image. Explains the azldev image commands (list, build, boot, test, customize) and the [images.<name>] config (kiwi definition, capabilities, tests, publish); the kiwi XML format itself is upstream KIWI NG. Triggers include image build, image boot, kiwi, container image, VM image, images.toml."
---

# Build and boot images

An image assembles built RPMs into a deliverable — a container or a bootable VM.
azldev drives the build from a kiwi-ng definition; the `.kiwi` file itself is
**upstream KIWI NG** ([docs](https://osinside.github.io/kiwi/)) and azldev does not
own its schema.

## Commands

Images are selected by their **name as a positional argument** (not `-p`).

| Task | Command |
| --- | --- |
| List images | `azldev image list` |
| Build an image (kiwi-ng) | `azldev image build <name>` |
| Boot an image in a QEMU VM | `azldev image boot <name>` |
| Run an image's tests | `azldev image test <name>` |
| Customize a pre-built image | `azldev image customize` |

`azldev image build` takes `--local-repo` / `--remote-repo` to add package sources and
`--arch` to target an architecture. When the selected distro version defines
`kiwi-config-override`, azldev passes it to KIWI with `--config`. These top-level
overrides have highest precedence. `azldev image boot` takes a built image name, or an
explicit `--image-path` / `--iso`. Confirm current flags with
`azldev image <command> --help` (there are more subcommands, e.g. `inject-files`).

## Registering an image

Images are declared under `[images.<name>]` (conventionally in an `images.toml`):

```toml
[images.container-base]
description = "Container base image"
definition = { type = "kiwi", path = "container-base/container-base.kiwi", profile = "core" }
architectures = ["x86_64", "aarch64"]

  [images.container-base.capabilities]
  container = true
  systemd = false

  [images.container-base.properties]
  openssl-fips-provider = "upstream"

  [images.container-base.tests]
  tests = [{ name = "smoke" }]
```

- `definition.type` is `kiwi` (the only type today); `path` points at the `.kiwi` file;
  `profile` selects a kiwi profile (optional).
- Boolean `capabilities` are tri-state flags describing the image — `machine-bootable`,
  `container`, `systemd`, `runtime-package-management`, `wsl`, `installer-media`,
  `fips-enabled`, and `cvm`. Set only the ones that apply.
- `properties` is an extensible string-to-string metadata bag. For example,
  `openssl-fips-provider = "upstream"` records the image's provider policy without
  requiring azldev to define that property in its schema.
- `architectures = ["x86_64", "aarch64"]` is optional; when unset or empty, the
   image is treated as unrestricted (all recognized architectures). Set it to
   restrict which architectures `image build --arch` allows for the image.
- `tests.tests` lists the tests or test groups `azldev image test` runs locally.
  An image ref may also set `sku-groups = ["<name>", ...]` to fan a test or group
  out across the VM sizes of one or more `[sku-groups.<name>]` entries; that
  fan-out is done by external test orchestration, not by local `azldev image test`.
  Do not map `sku-groups` onto arbitrary LISA tests: LISA tests carry their own
  requirements and are skipped when the SKU does not meet them, so this is
  meaningful only for the special case of multi-SKU performance tests.
- `publish.channels` lists the channels the image publishes to.

## The kiwi definition

The `.kiwi` file is upstream KIWI NG XML — azldev does not own its schema. It selects the
image type (container vs. VM), package lists, repositories, and boot configuration. See
the [KIWI NG documentation](https://osinside.github.io/kiwi/) for the format and elements.

Generated by `azldev docs agent`; do not hand-edit.