Skip to main content
A BlueBuild recipe is a YAML file that declares what goes into the image — which packages to install, which files to copy, which services to enable, and how to configure the system. When you build Agate, BlueBuild reads the recipes and assembles them into a container image layer by layer. Agate’s recipes live in the recipes/ directory of the repository. The main entry point is recipe.yml, which includes all the other recipes in a defined order.
Editing a recipe file has no effect on a running system. You must rebuild the image and rebase to it for changes to take effect.

​
Recipe files

The top-level recipe. It sets the base image (ghcr.io/ublue-os/bazzite-dx-nvidia:latest) and includes all the common-* recipes in order. This is the only file you pass to the BlueBuild build command. Every other recipe flows through this one.For the authoritative recipe format and available fields, see the BlueBuild recipe documentation.
Copies custom wallpapers, icons, and logo files into the image. This is where Agate’s visual identity is baked in — anything you want present on first boot goes here.
Installs development tools, runtimes, and configuration files used for software development. This includes compilers, language toolchains, container tooling, and IDE integrations.
Sets up the dotfiles manager (yadm) and any configuration needed to bootstrap it on a fresh install. This ensures your personal configuration is applied automatically after rebase.
Declares the list of Flatpak applications to install from Flathub and other remotes. Flatpaks are managed separately from RPMs to keep the two package sources distinct and easy to audit.
Lists all extra RPM packages to layer on top of the base image. Packages are organized by category (development, security, utilities, etc.) and pulled from Fedora’s repositories and any enabled COPR repos.
Installs desktop theme assets into the image: Catppuccin for KDE, the Kora icon theme, and the PlasMusic widget. These assets are baked into the image so they are available immediately after rebase.
Configures the Niri Wayland compositor as an alternative session alongside KDE Plasma. This recipe installs Niri and registers its session with the display manager so you can select it at login.

​
Modifying recipes when building from source

If you are building your own image from the Agate source, you can edit any recipe file to customize the result:
  1. Open the relevant recipes/*.yml file in your editor.
  2. Add, remove, or modify entries according to the BlueBuild module documentation.
  3. Rebuild the image — your changes will be included in the next build.
# Example: adding an RPM package in common-packages.yml
modules:
  - type: rpm-ostree
    install:
      - your-package-name
See the build image page for the full build command and workflow.

​
Further reading

  • BlueBuild documentation — full reference for recipe syntax, available modules, and image configuration options.
Last modified on April 7, 2026