---
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. `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" }

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

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

- `definition.type` is `kiwi` (the only type today); `path` points at the `.kiwi` file;
  `profile` selects a kiwi profile (optional).
- `capabilities` are tri-state flags describing the image — `machine-bootable`,
  `container`, `systemd`, `runtime-package-management`. Set only the ones that apply.
- `tests.test-suites` lists the test suites `azldev image test` runs.
- `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. Generated for azldev version `v0.1.0`.