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.10 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 -fsSLO https://github.com/Danathar/atomic-image-builder/releases/latest/download/aib &&
curl -fsSL  https://github.com/Danathar/atomic-image-builder/releases/latest/download/aib.sha256 | sha256sum -c - &&
install -D -m 755 aib ~/.local/bin/aib && rm aib
aib

The wrapper verifies the container image's signature before running it and then forwards your GitHub credential into it, so it is worth having checked the wrapper too. The sha256sum -c - line above is that check, the && between the lines is what makes it a gate rather than a report — a failed checksum stops before install — and it is why the recommended install comes from a release rather than from main. See Installing for the main version, which is the bleeding edge and unverified.

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 the image locally with Podman before pushing, whichever build method you chose.

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.
• Advanced BlueBuild modules beyond the guided wizard are out of scope, by design. The wizard only offers choices that produce the same image under either build method. You can add other modules by editing recipes/recipe.yml yourself, but the tool rewrites that file on every update, so once you do, stop updating that repo with the tool.

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 — and ARCHITECTURE.md for a map of the code.

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.

Maintained with Hive (ACMM L5)

This repository's Hive runs at ACMM L5 (Semi-Autonomous). Maintenance here is assisted by Hivecommons Hive.

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

What L5 means for this repository:

• All of Hive's agents may file issues and open pull requests here.
• Hive puts a hold label on every pull request an agent opens, and nothing merges on its own. A human maintainer reviews agent pull requests in batches and merges the ones that should land.
• L5 adds three agents. The reviewer works through the open pull requests and backs each finding with a file and line; it never merges, approves or closes one. The architect writes RFCs and opens pull requests for structural changes. The strategist coordinates work across the other agents.
• The telemetry and operations agents are part of L5 but start paused.

The ACMM levels table in the Hive README describes all six levels in general terms.

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

License

GPL-3.0-only. See LICENSE.