OS Architecture¶

Bazzite AI OS is built on Fedora Atomic Desktop with OSTree, providing an immutable, container-based operating system.

Pods Architecture

For pod inheritance and build system, see Pod Architecture.

System Overview¶

graph TD
    subgraph bazzite["Bazzite AI OS"]
        ostree[OSTree<br/>Atomic Updates]
        rpm[rpm-ostree<br/>Package Layer]
        flatpak[Flatpak<br/>Desktop Apps]
        pods_runtime[Container Runtime<br/>Podman + Apptainer]
    end

    ostree --> rpm
    rpm --> flatpak
    rpm --> pods_runtime

    pods_runtime -->|runs| external[Bazzite Pods<br/>from ghcr.io]

Immutable Foundation¶

Read-Only `/usr`¶

System files cannot be modified at runtime:

# This will fail
sudo touch /usr/test-file
# Error: Read-only file system

# System changes require rpm-ostree
rpm-ostree install <package>
systemctl reboot  # Apply changes

Benefits¶

Security - System files cannot be tampered with
Reliability - Consistent state across reboots
Reproducibility - Same image on every machine
Rollback - Instant recovery from bad updates

Update System¶

OSTree Deployments¶

Each update creates a new deployment, keeping previous versions available:

# Check current status
rpm-ostree status

# Output shows multiple deployments:
# * bazzite-ai:stable (active)
#   bazzite-ai:stable (previous)

Update Workflow¶

# Check for updates
rpm-ostree upgrade --check

# Apply updates (requires reboot)
rpm-ostree upgrade
systemctl reboot

# If issues, rollback
rpm-ostree rollback
systemctl reboot

Automatic Updates¶

Bazzite AI OS can auto-update in background:

# Updates applied on next reboot
# Configure in System Settings → Software Updates

Package Layers¶

Layered Packages¶

Add packages on top of the base image:

# Install a package
rpm-ostree install htop

# Remove a layered package
rpm-ostree uninstall htop

# List layered packages
rpm-ostree status

Minimize Layered Packages

Layered packages increase update time and can cause conflicts. Prefer Flatpak for desktop apps and containers for development tools.

Base Image Contents¶

The base image includes 450+ packages:

Category	Packages
Build Tools	gcc, make, cmake, ninja, meson
Languages	Python, Node.js, Go, Rust, .NET, PHP, Java, Ruby
Containers	Podman, Docker CE, Apptainer
Kubernetes	kubectl, Helm
Development	VS Code, git, gh CLI
GPU Drivers	NVIDIA open modules, Mesa

Application Layers¶

Flatpak (Desktop Apps)¶

Sandboxed desktop applications:

# Install apps from Flathub
flatpak install flathub org.mozilla.firefox

# List installed
flatpak list

# Update all
flatpak update

Containers (Development)¶

Development environments via Bazzite Pods:

# Run ML development environment with Apptainer
apptainer pull docker://ghcr.io/atrawog/bazzite-ai-pod-nvidia-python:stable
apptainer shell --nv bazzite-ai-pod-nvidia-python_stable.sif

Distrobox (Optional)¶

Run other distributions in containers:

# Create Ubuntu container
distrobox create -i ubuntu:24.04 -n ubuntu

# Enter container
distrobox enter ubuntu

Filesystem Layout¶

Path	Type	Purpose
`/usr`	Read-only	System binaries, libraries
`/etc`	Writable	System configuration
`/var`	Writable	Variable data, containers
`/home`	Writable	User data
`/opt`	Symlink	Additional software

Home Directory Structure¶

/home/user/
├── .config/          # User configuration
├── .local/
│   └── share/
│       └── apptainer/  # Pod images
├── .aws/             # AWS credentials
├── .kube/            # Kubernetes config
└── projects/         # Your code

Container Runtime¶

Podman¶

Daemonless container engine (Docker-compatible):

# Run containers
podman run -it fedora bash

# Build images
podman build -t myimage .

# Docker CLI also available
docker run -it fedora bash  # Uses podman

Apptainer¶

HPC-focused container runtime:

# Pull and run
apptainer pull docker://ghcr.io/atrawog/bazzite-ai-pod-nvidia-python:stable
apptainer exec --nv image.sif bash

GPU Access¶

NVIDIA: Run ujust setup-gpu-pods (one-time)
AMD/Intel: Automatic via /dev/dri

Key Technologies¶

Technology	Purpose
OSTree	Atomic filesystem updates
rpm-ostree	Package layering on OSTree
Flatpak	Sandboxed desktop applications
Podman	OCI container runtime
Apptainer	HPC container runtime
systemd	System and service manager

Comparison: Traditional vs Immutable¶

Aspect	Traditional Linux	Bazzite AI OS
System updates	Package-by-package	Atomic image swap
Rollback	Complex/impossible	Instant (boot menu)
System files	Mutable	Read-only
Package install	Immediate	Requires reboot
Reproducibility	Varies by history	Image-based
Security	Runtime modifications	Tamper-resistant