Atomic Image Builder

A guided terminal tool that turns the customizations already on your atomic desktop into a GitHub-backed bootc image. It scans your running system, carries the packages you have layered with rpm-ostree into a new repository, and lets GitHub Actions build the image — 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. The scan only reads your rpm-ostree state; everything it creates happens on GitHub. 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

Create Image starts by scanning the system you are on. It reads your booted deployment's rpm-ostree state — the image you are running, the packages you have layered, and any base packages you have removed — and offers all of it, pre-selected, to carry into a new repo. The base image comes from your system rather than a menu, because Universal Blue images are not rebase-compatible with each other and one built on the wrong base is one you cannot switch back onto.

What it creates and maintains is a separate GitHub repository that builds your image through GitHub Actions. From the guided menu you can:

• Carry layered packages and base-package removals from the running system into a new repo, picking which ones come along.
• Add more on top: packages, COPR repos, systemd services, and further base-package removals.
• Choose the build method — Containerfile (from a bundled snapshot of ublue-os/image-template) or BlueBuild (from blue-build/template).
• Update repos it created, view build status, and rotate the cosign signing key.
• Test-build a Containerfile image locally with Podman before pushing.

Nothing has to be layered for this to be useful — with a clean system it simply starts from the base you are on and you add what you want. And if there is no system to read, as with a bare podman run, the tool says so and lets you pick a base image by hand.

Supported bases — the scan needs you to be running one of these: 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 — the scan reads and never writes: no in-place changes, no automatic rebase, and your layered packages stay exactly where they are.
• 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 — in particular anyone who has accumulated a pile of rpm-ostree layered packages and would rather have them baked into the image than re-applied on top of every update. 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.

Want to fix something yourself? See CONTRIBUTING.md for the development workflow — tests, coverage, linting, and how to submit a change.

Found a security vulnerability instead? Please don't open a public issue for it — see SECURITY.md for how to report it privately.

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 4.

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

At L4 (Security-Aware) all agents may file issues, and the quality, security and CI agents may additionally open pull requests that carry a hold label. The rest 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.