Atomic Image Builder

A guided terminal tool for creating and updating GitHub-backed bootc image repositories — for people who want a custom image without learning the full template and workflow setup first. (The author RECOMMENDS YOU LEARN anyway!) Works with Universal Blue and Fedora Atomic desktops.

Tip

Safe to explore — it won't touch the system you're running on. Everything happens on GitHub: it creates a new repo and lets GitHub Actions build your image. It never modifies, rebases, or removes packages from your current install. Switching your machine to the built image is a separate, deliberate step you take later.

Warning

0.9 beta, not fully tested. Review the changes it makes before applying them.

Quick start

Have Homebrew? (Bazzite, Bluefin, and Aurora ship with it.)

brew tap danathar/aib https://github.com/Danathar/atomic-image-builder
brew install danathar/aib/atomic-image-builder
aib-tool

Have Podman?

curl -fsSL https://raw.githubusercontent.com/Danathar/atomic-image-builder/main/contrib/aib -o ~/.local/bin/aib
chmod +x ~/.local/bin/aib
aib

Either one launches the guided menu. YOU WILL NEED A GITHUB ACCOUNT — if you are not already logged in, the tool walks you through gh auth login on first run.

Other options — plain podman run, distrobox, running from source — are in Installing.

What it does

Creates and maintains a separate GitHub repository that builds a custom bootc image for you through GitHub Actions. From the guided menu you can:

• Create a repo using either build method — Containerfile (from a bundled snapshot of ublue-os/image-template) or BlueBuild (from blue-build/template).
• Add packages, COPR repos, systemd services, and base-package removals.
• Scan your running system and carry layered packages into a new repo.
• Update repos it created, view build status, and rotate the cosign signing key.
• Test-build a Containerfile image locally with Podman before pushing.

Supported bases: Universal Blue — Bazzite (also GNOME, DX, DX GNOME), Aurora (also DX), Bluefin (also DX) — and Fedora Atomic: Silverblue, Kinoite, Sway, Budgie, COSMIC.

What it does not do

• Leaves the system you run it on alone — no in-place changes, no automatic rebase, never removes layered packages from your current install.
• Does not adopt repos it did not create — a repo without .atomic-image-builder.json is not treated as managed.
• Local test builds are Containerfile-only.
• Advanced BlueBuild modules beyond the guided wizard are out of scope.

Documentation

• Installing — every install path, container limitations, command-line options
• Using the tool — the guided menu, migrating layered packages, Homebrew in your built image

Who it's for

Beginner and intermediate atomic-desktop users who want a guided path to a custom image repo. Bootc desktops are powerful, but the normal setup assumes you are comfortable with image templates, GitHub Actions, signing, and image maintenance. This tool trades that setup cost for a guided workflow with stricter defaults — it is intentionally not aimed at exposing every advanced workflow.

Feedback

Bugs, confusing behavior, and rough edges are all welcome: open an issue.

About this project

Note

This project was created with AI assistance and should be treated cautiously.

This is a third-party tool. It is not an official Universal Blue utility, is not sanctioned by the Universal Blue project, is not an official Fedora utility, and is not sanctioned by the Fedora Project.

It is provided as-is, without any promise that it will be safe for your repositories, data, systems, or build pipeline. Use it carefully, review its changes before applying them, and keep backups where appropriate. The maintainer is not responsible for repository damage, data loss, failed builds, system changes, or other consequences that may result from using this software.

Note

Maintenance on this repository is assisted by KubeStellar Hive at ACMM level 3.

Hive orchestrates a fleet of AI agents that continuously review this codebase and publish what they find to a living advisory report.

At L3 (Quality-Gated) the quality agent may open issues and pull requests that carry a hold label, while the remaining agents stay advisory: they report, they do not act. Every change is still reviewed and merged by a human maintainer.

Learn more: KubeStellar · Hive · Hive Hub · full ACMM policy matrix

License

GPL-3.0-only. See LICENSE.