How it works

This page explains the architecture and operating principles of ALT Atomic for those who want to understand what is happening "under the hood".

Traditional distributions vs Atomic

In traditional distributions (regular ALT, Fedora, Ubuntu), the system works like this:

• The root file system / is writable
• The batch manager changes the system files directly
• Updates are applied live — each package is updated independently
• If the update fails, the system may end up in an inconsistent state
• Rolling back to the previous state is difficult or impossible

In atomic distributions (ALT Atomic, Fedora Silverblue):

• The root file system is, with some exceptions, read-only
• The system is distributed as a single image
• Updates occur atomically — either entirely or in no way
• Rolling back is possible to any previous version by date or tag

What is "The system rollback"

A system image is a snapshot of the entire operating system packaged in an OCI container. OCI (Open Container Initiative) is a container standard that is used in Docker and Podman.

ALT Atomic image contains:

• Linux kernel
• All system libraries and utils
• Preconfigured services
• Base application set

The image is stored in the container registry and delivered to the machine using bootc, a tool that allows you to boot the OS directly from the container.

How it looks in practice

  ┌──────────────────────────────────────────────────┐
  │               Container registery                │
  │  ┌──────────────────┐  ┌─────────────────┐       │
  │  │ alt-atomic:gnome │  │ alt-atomic:kde  │  ...  │
  │  └────────┬─────────┘  └────────┬────────┘       │
  └───────────┼─────────────────────┼────────────────┘
              │                     │
              │    bootc switch     │
              ▼                     ▼
┌───────────────────────────────────────────────────────┐
│                    Your computer                      │
│  ┌──────────────────────────────────────────────────┐ │
│  │            OSTree (container storage)            │ │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐  │ │
│  │  │  Image #1  │  │  Image #2  │  │  Image #3  │  │ │
│  │  │ (rollback) │  │ (rollback) │  │ (current)  │  │ │
│  │  └────────────┘  └────────────┘  └────────────┘  │ │
│  └──────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────┘

OSTree and atomic updates

OSTree is a version control system for operating systems. If Git stores source code versions, then OSTree stores versions of the entire file system.

When you update the system:

1. New image downloads from the registery

apm system image update / bootc upgrade

2. OSTree saves it next to the current one
3. Upon reboot, the system offers the new image as a choice. The image sequence number is always incremented and shifted, so the most recent image is under number 0
4. The old image remains available for rollback if there are no more than two images, or if it has been "pinned" via:

sudo ostree admin pin 0

What is APM and what does it do

APM (Atomic Package Manager) is a utility for managing ALT Atomic. It provides a single interface for:

Command	Explanation
apm system image update	Download and apply image updates, taking into account the local state
apm system image status	Display current image
apm system image history	Display history of images
apm system install	Add package to the local state
apm system image apply	Rebuild image with local changes
apm distrobox ...	Manage Distrobox containers

How to install applications

In ALT Atomic, there are four ways of program installation, each for its own tasks:

1. Flatpak — for graphical applications

Flatpak is a system for distributing applications in isolated containers. Flatpak applications:

• Do not depend on the versions of libraries in the system
• Are isolated from each other
• Are updated independently of the system

# Install application
flatpak install flathub org.mozilla.firefox

# Run
flatpak run org.mozilla.firefox

Flatpak application installation is also available through the "application center" in KDE/GNOME

Use cases: browsers, office suites, media players, games — any graphical applications.

2. Distrobox — for CLI tools and development

Distrobox creates full-fledged containers with any Linux distribution. Inside the container, you can use a regular package manager, or manage packages via apm

apm distrobox c create --image alt --name dev
apm distrobox install -c dev hello

Use cases: development tools, compilers, CLI-specific utilities.

Distrobox mounts your home directory inside the container and sets up transparent file access. Programs from the container can be exported to the application menu of the host machine.

3. Image layer — for system components

If you need a package that should be part of the system (drivers, system services):

# Add package to configuration
apm system install package-name

# Apply changes
apm system image apply

# Reboot to switch
sudo reboot

It is also worth noting that some changes, such as application installation, systemd service control and system configuration changes can be applied manually via editing of /etc/apm/image.yml and executing apm system image apply. This is the same declarative format that is used in CI/CD — the only difference is that the local image remains only on your machine.

The syntax is described in the section Image configuration.

Use cases: rarely. Only if there is a small number of packages and these packages are missing in the base system

4. CI/CD image building

The most powerful way of customizing images is to create your own image based on the official one. Your image will be:

• Automatically compiled into CI/CD at each commit
• Available for installation on any device via the bootc switch or via the universal installer (LIVE ISO)
• The image is available for installation on any device via the bootc switch or via the universal installer (LIVE ISO)

Here is a template that can be bent to modify the system

Use cases: rarely. If you need more than a few packages, a specific system configuration, want to create your own distribution or to have a reproducible environment on multiple machines

Why is it so difficult?

At first glance, the atomic system seems to be more complicated than the traditional one. But this complexity offers important advantages:

Traditional way	Atomic way
If you break the system with an update, you'll have to reinstall it	You can roll back to the previous image
Garbage accumulation from old packages	A clean image with every update
Difficult environment reproducibility	Image guarantees reproducible environment
Imperative: the command history determines the state	Declarative: the config describes the desired state

What are the advantages of ALT Atomic when there are btrfs with snapshots?

btrfs snapshots solve the rollback problem. But atomic systems provide more:

• Reproducibility: The image is not "my system after 12 apt-get commands", but a declarative description. You can deploy an identical environment on 10 machines or after a while on a new laptop. A snapshot is a cast of a specific car, an image is a recipe.
• Separation of responsibilities: system components (image), user applications (Flatpak/Distrobox) and configs (/etc, /var) are all separate
• CI/CD for OS generation: the image is assembled in a pipeline, tested by linters, published and stored in history
• Verification: The image is signed and verified upon download. A snapshot is just the state of a disk
• Switching between images: bootc switch allows you to switch from GNOME to KDE (or to your custom image) with a single command while maintaining the local application state

Further reading

• Working with an image — updates, rollbacks, switching images
• APM — learn more about management commands
• Image Configuration — create custom images
• bootc — bootc documentation
• OSTree — OSTree documentation
• Distrobox — Distrobox documentation