Skip to main content

RECIPE GEN

tacklebox recipe-gen reads one YAML or JSON file and writes a JSON recipe. It only reads and converts configuration; it does not pull images, build media, or need root. The input uses the same field names as a full recipe, with most fields optional. See the user guide for how recipes affect media builds.

tacklebox recipe-gen environments.yaml > recipe.json
# Equivalent, with a confirmation message on stderr:
tacklebox recipe-gen environments.yaml --output recipe.json

-o is the short form of --output. Output is always JSON, indented with two spaces and ending with a newline, regardless of the input or output filename. The command creates the output file or overwrites it. Input must be a file path; - does not read stdin. YAML and JSON both go through the YAML parser, so the filename extension does not select a parser.

Input fields​

Use a top-level mapping/object and the exact snake_case names below. Quote size values and image references as strings. YAML booleans should be true or false.

FieldTypeRequirement / behavior
media_namestringRequired, nonempty media label.
bootable_environmentsarray of objectsRequired, at least one environment. Order determines the default boot environment.
sizestringOptional; estimated when empty or omitted. Use sizes such as "20G" or "8192M".
default_bootstringOptional environment ID; defaults to the first environment's id.
shared_storeobjectOptional; fields listed below.
partitionsobjectOptional string fields esp, store, and persist, such as esp: "1G". Passed through without estimating partition sizes.
offline_payloadsarrayOptional image-reference strings or objects with nonempty string source and ref fields. See the offline example.
kargsarray of stringsOptional extra kernel arguments; passed through.

Each bootable_environments entry supports:

FieldTypeRequirement / behavior
idstringSupply a unique, nonempty ID for a usable recipe; used in paths and boot entries.
imagestringSupply a bootable container image reference for a usable recipe.
titlestringOptional; empty or omitted becomes id.
modesarray of stringsOptional; omitted, null, or [] becomes ["live"]. Use live, persistent, or both.
desktop, backendstringOptional full-recipe settings; passed through.
skip_initramfs_rebuildbooleanOptional; passed through. Enable only for images already shipping the required modules.
live_customizearray of stringsOptional script paths; passed through. Relative paths resolve from the generated recipe's directory when building, so keep it beside the input or adjust paths.
remorastring or objectOptional manifest path/URL or inline manifest; passed through as JSON.

shared_store supports these optional fields:

FieldTypeGeneration behavior
formatstringEmpty or omitted becomes "ext4".
dedupbooleanDefaults to false for one environment; forced to true for two or more.
compression, compressorstringPassed through; generation does not fill build-time compression defaults.
dedup_layout, delta_basestringPassed through; see multi-env ISOs.
prune_source_imagesbooleanPassed through; removes source payload images during a build when enabled. Intended for ephemeral builders.

Default rules and validation limits​

When size is empty or omitted, the estimate is 5G per environment + 3G: 8G for one, 13G for two, 18G for three. The extra 3G represents a 1G ESP and 2G persistence partition. This is a fixed estimate, not an inspection of image sizes. Partition overrides and offline payloads do not increase it; choose an explicit size when needed. If you omit a partition size, recipe-gen leaves it unset, and the build calculates it later.

For multiple environments, even an explicit shared_store.dedup: false becomes true. To disable it, edit the generated JSON afterward. Dedup has an effect only on ISO targets. The generator keeps explicit nonempty values for size, format, title, default_boot, and modes; an empty string gives the corresponding default.

recipe-gen stops with an error for malformed input, incompatible field types, an empty media_name, and a missing or empty environment list. It does not validate image availability, unique/nonempty IDs, image presence, mode names, size syntax, or whether default_boot names an existing environment. Successful generation is not proof that a recipe can build or boot.

Pass-through means that the output keeps the values of fields from the full recipe schema, subject to the defaults above. If a key is unknown or misspelled, the generator discards it. It writes the output from the recipe structure, so the output does not keep key order or YAML comments. Some unset fields appear as empty strings, {}, or null, and optional zero-valued fields can disappear. For example, an omitted offline_payloads becomes null. A payload object whose source and ref are equal becomes a single string.

Examples​

Save any example to a file and run the command above. Image references here illustrate the input format; generation does not contact their registries.

Single environment (YAML)​

media_name: TUNAOS
bootable_environments:
- id: gnome
image: ghcr.io/tuna-os/yellowfin:gnome

This produces size: "8G", default_boot: "gnome", store format ext4, title gnome, and modes ["live"]. Dedup stays false, and the JSON does not include it.

Multiple environments with dedup (YAML)​

media_name: TUNAOS-MULTI
shared_store:
dedup: true
compression: release
bootable_environments:
- id: gnome
image: ghcr.io/tuna-os/yellowfin:gnome
title: GNOME
- id: gnome-hwe
image: ghcr.io/tuna-os/yellowfin:gnome-hwe
title: GNOME (HWE)

The size becomes 13G, the default boot is gnome, and both environments get ["live"]. If you omit dedup, the result is the same enabled setting.

Offline payloads and explicit overrides (JSON)​

{
"media_name": "TUNAOS-OFFLINE",
"size": "30G",
"default_boot": "kde",
"partitions": {"esp": "1G", "persist": "4G"},
"kargs": ["console=ttyS0"],
"bootable_environments": [
{
"id": "kde",
"image": "ghcr.io/tuna-os/yellowfin:kde",
"title": "KDE offline installer",
"modes": ["live"]
}
],
"offline_payloads": [
"ghcr.io/tuna-os/yellowfin:kde",
{"source": "localhost/custom-os:stable", "ref": "ghcr.io/example/custom-os:stable"}
]
}

The generator keeps these values for size, partitions, kernel arguments, and payloads. It does not get payloads from the environment list: list every image that you want to embed. A string uses the same image name as source and destination; an object maps a builder-side image to its canonical name in the embedded store. See offline installs. For selected-image identity, storage ownership, and the remaining runtime verification for deduplicated media, see the evaluation of the installer handoff for multiple images.