The build spec

peiso.toml is the declarative TOML spec that drives peiso. A single file describes the whole bootable image: the peipkg-compose manifest to build the package root from, how the initramfs is packed, and the optional squashfs, UKI, ISO, registry-seed and feature stages that the build pipeline layers on top. This page documents schema version 1 — the only schema peiso accepts — field by field.

The spec is passed to peiso positionally and defaults to peiso.toml in the current directory:

sudo peiso build [spec.toml]

Three properties hold across the whole file:

• TOML, parsed strictly. An unknown key anywhere in the spec is a hard error, not a warning — peiso rejects the first undecoded key by name. A typo'd field fails the build rather than being silently ignored.
• schema is checked first. The spec must declare schema = 1; any other value (or a missing schema, which reads as 0) fails with unsupported schema.
• Relative paths resolve against the spec file's own directory — never the current working directory. So a build behaves the same wherever you invoke it from. There are two flavours of path handling, and it matters which a field uses:
  • Spec-relative paths (root.manifest, root.out, initramfs.manifest, squashfs.out, uki.cmdline_file, iso.source, iso.out, inject.src) are made absolute against the spec's directory. An already-absolute value is kept as given.
  • Root-relative paths (initramfs.dir, initramfs.cpio, uki.out, iso.efi_boot, inject.dest) are cleaned and kept relative (any leading / is stripped). These double as chroot-absolute paths inside the composed root, so they are validated to not escape with .. (see Validation).

A complete example #

A full spec that composes a root, packs the initramfs, squashes the rootfs, builds a UKI, emits a bootable ISO, and enables a feature on first boot:

schema      = 1
source_date = "2026-06-22T00:00:00Z"   # pins reproducible build timestamps

# The whole image. manifest.toml is multi-root — it composes the main system
# root into `out` and the nested initramfs root (at out/boot/initramfs) in one
# pass, so [initramfs] below needs no manifest of its own.
[root]
manifest = "manifest.toml"
out      = "root"

# How mkirf packs the already-composed initramfs root into a cpio. `dir` and
# `cpio` are root-relative: inside the chroot they are mkirf's /<dir> source and
# /<cpio> output. The peipkg database isn't needed at early boot, so it's excluded.
[initramfs]
dir     = "boot/initramfs"
cpio    = "system/boot/initramfs.cpio.gz"
exclude = ["var/lib/peipkg", "conf/peipkg"]

# Read-only rootfs image, squashed from the WHOLE composed root. `out` is written
# OUTSIDE root/ so the image can never contain itself.
[squashfs]
out         = "sysroot.squashfs"
compression = "zstd"

# Unified Kernel Image: kernel + initramfs cpio + cmdline in one EFI binary.
# cmdline_file is read from the composed root, so build-time and runtime agree.
[uki]
cmdline_file = "root/usr/share/live-boot/cmdline"
out          = "boot/efi/EFI/BOOT/BOOTX64.EFI"

# Bootable UEFI ISO built from the ESP tree at `source`, with the UKI marked as
# the EFI boot image at `efi_boot` (relative to source).
[iso]
source   = "root/boot/efi"
efi_boot = "EFI/BOOT/BOOTX64.EFI"
out      = "peios.iso"
label    = "PEIOS"

# Features this image enables on first boot (feat add <name>).
[features]
enable = ["dynamic-boot"]

[squashfs], [uki], [iso], [registry] and [features] are all optional — a minimal spec is just schema, [root] and [initramfs], which composes the root and packs the initramfs.

Top-level fields #

[root] — the package root (required) #

The main system root, composed by shelling out to peipkg-compose build. Both keys are required.

[initramfs] — packing the initramfs (required) #

Describes how peiso packs the initramfs root into a cpio archive using the composed root's own mkirf applet, run inside the chroot. dir and cpio are required; the rest are optional.

[[initramfs.inject]] (temporary) #

Each entry copies one file into the initramfs root before it is packed. This is a transitional mechanism — the intended path is to ship such files in a package so a cross-root dependency pulls them into the initramfs root during compose. src and dest are both required.

[squashfs] — the read-only rootfs image (optional) #

When present, peiso squashes the whole composed root into a read-only image (the live-boot lower layer). Presence of the table is what turns the stage on; out is then required.

[uki] — the Unified Kernel Image (optional) #

When present, peiso bundles a UKI — kernel + initramfs cpio + kernel cmdline in one EFI binary — using the composed root's own mkuki applet in the chroot. You must supply the cmdline exactly one way: cmdline or cmdline_file, never both and never neither.

[iso] — the bootable ISO (optional) #

When present, peiso emits a UEFI-bootable ISO9660 image (via xorriso) from an ESP tree. source, efi_boot and out are required; label defaults.

[registry] — registry seeds auto-applied on first boot (optional) #

Selects which vendor registry-seed masters (shipped by packages into /usr/share/peios/registry.d/) this image auto-applies on first boot. peiso stages each into the composed root's autoapply queue; peinit drains it at first boot. Selection lives here, in the image, not in the packages.

[features] — features enabled on first boot (optional) #

Selects which curated features (shipped by packages into /usr/libexec/peios/features.d/) this image enables on first boot. peiso writes a self-removing autorun script of feat add <name> lines; peinit runs it before Phase 2, so the services a feature creates start the same boot.

Validation #

peiso loads, decodes and validates the spec before running anything. The rules, exactly as enforced:

• Unknown keys are rejected. Any key the schema does not define — at any level — fails the build, naming the first offending key.
• Schema gate. schema must equal 1, or the build fails with unsupported schema.
• Required fields. root.manifest, root.out, initramfs.dir and initramfs.cpio must all be present and non-empty. Within an optional table that is present, its own required keys apply: squashfs.out; uki.out; iso.source, iso.efi_boot and iso.out; and both src and dest on every inject entry.
• No-escape path checks. The root-relative paths initramfs.dir, initramfs.cpio, uki.out, iso.efi_boot and inject.dest may not be .. or begin with ../ — they become chroot-absolute paths and must stay inside their tree. (Spec-relative paths are not subject to this check; they resolve to absolute paths.)
• UKI cmdline mutual-exclusion. When [uki] is present, exactly one of cmdline or cmdline_file must be set. Supplying both, or neither, is an error.
• Registry seeds must be bare filenames. Each registry.autoapply entry must be non-empty and contain no path separator (it must equal its own basename); a path component is a spec error.
• Feature-name grammar. Each features.enable entry must be non-empty, must not be . or .., and must consist only of ASCII alphanumerics plus -, _ and .. This mirrors feat's own name grammar and doubles as a guard against shell metacharacters, since the name is embedded in a generated feat add line.
• Inject mode. inject.mode, when set, must parse as an octal integer; a malformed value fails the build.

A spec that passes all of these is what peiso hands to the build pipeline.