CachyOS BoppOS 🚀

A high-performance, desktop-focused atomic (bootc) Linux image based on CachyOS.

CachyOS BoppOS is a custom-built OS designed for high-end desktop gaming and development. It's a fork of cachyos-deckify-bootc, transformed from a handheld-oriented system into a powerful, desktop-first experience.

This is all very experimental. So use at your own risk.

---

Key Features

• High-Performance Base: Built on CachyOS, an Arch-based distribution with performance-tuned kernels and repositories.
• Atomic & Immutable: Uses bootc for an atomic, image-based system that offers incredible stability and easy rollbacks.
• Desktop Choice: Choose your preferred flavor: KDE Plasma, GNOME, or the Niri Wayland compositor.
• Modern Hardware Support: Includes build-time support for znver4 CPU optimizations for AMD Ryzen 7000 series processors.
• Gaming Ready: Comes with a suite of pre-installed gaming software and utilities:
  • cachyos-gaming-applications, proton-cachyos, wine-cachyos
  • sunshine, mangohud, goverlay, lact
  • faugus-launcher, umu-launcher, winboat
• Developer Focused: Includes essential development environments and tools out of the box:
  • Homebrew (brew) support integrated into the base image
  • distrobox container-native environment (run any distro's toolchain natively)
  • docker, docker-compose, and podman
  • python-pip and python-pipx for user-space app installations
• Laptop Hardware Compatibility: Pre-installed compatibility and management tools for ASUS (asusctl, supergfxctl), Framework and generic laptops (power-profiles-daemon, iio-sensor-proxy, bolt, fprintd). Systemd services are kept disabled by default to eliminate background overhead on non-target hardware.
• Seamless Setup & Migration: Features custom scripts to transition safely from other atomic distributions (bopp-migrate).
• Hardware Encryption Utility: Includes bopp-tpm-refresh to automatically re-enroll LUKS TPM2 encryption keys after system updates or migrations.
• Enhanced Shell: A pre-configured shell environment with starship, zoxide, and eza for a modern terminal experience.

Custom Enhancements

• Desktop First: Stripped away Steam Deck/handheld-specific UI elements and scaling tweaks in favor of standard desktop environments (with support for KDE Plasma, GNOME, and Niri).
• Developer Ready: Pre-installed essentials like Distrobox, Homebrew (brew), Docker, and Python (with full support for container-native development workloads).
• BoppOS Tools: We have created a suite of custom administration utilities, available in the boppos-tools repository.

⚠️ WARNING: HIGHLY EXPERIMENTAL AND POTENTIALLY DESTRUCTIVE ⚠️ Some of these tools (specifically bopp-migrate) manipulate core system and user configurations. Do NOT run them unless you fully understand what they do. They are largely untested and could result in a broken system or data loss. Always ensure you have a separate, verified backup of your data before running migration commands.

Important commands included in boppos-tools:

• boppos-update: A comprehensive update script that seamlessly updates your OS (bootc), firmware, Flatpaks, Homebrew, and Distroboxes.
• bopp-tray: A background tray application that checks for new image updates periodically.
• bopp-diff: Analyzes the current running system against staged or upstream bootc images to provide a clear package diff.
• bopp-kargs: A utility to manage Boot Loader Specification (BLS) kernel arguments for atomic deployments.
• bopp-tpm-refresh: Re-enroll LUKS/TPM2 decryption keys after system updates.
• bopp-dev-setup: Provisions a container-native development environment in a CachyOS-based Distrobox container, optimized for your CPU's microarchitecture.
• bopp-migrate: Transition your $HOME and /etc configurations from Fedora-based atomic distributions to this Arch-based BoppOS image.
• install-optional-flatpaks: An interactive script to easily fetch, customize, and install a curated list of essential Flatpak applications.

Installation & Switching

This image is designed to be managed by bootc. The recommended and easiest way to install BoppOS is to switch an existing bootc-based OS directly to it without losing your data. Alternatively, you can perform a fresh installation on a new system.

1. Switching from an Existing bootc OS (Recommended)

If you are already running a bootc-based system (e.g., Bazzite, Bluefin, or Fedora Atomic desktops with bootc), you can switch to BoppOS directly without needing to reformat or reinstall. This is one of the major advantages of bootc.

To switch, run the following command, pointing to the BoppOS image in your registry:

sudo bootc switch ghcr.io/bopp-os/cachyos-plasma:latest

Your system will download the new image and stage it for the next boot.

Note on Signature Verification: For a secure transition, you may need to configure your system to trust the signature of the new image. The Containerfile includes a cosign.pub key and policy.json, which you may need to adapt for your registry and signing setup.

2. Fresh Installation

After building the container image, you can:

1. Push it to a container registry (like ghcr.io, quay.io, or a local registry).
2. Use bootc install from a live environment to install CachyOS BoppOS to a target disk.

For detailed installation instructions, refer to the official bootc documentation.

A typical installation command would look like this:

# Example:
bootc install to-disk --image ghcr.io/bopp-os/cachyos-plasma:latest /dev/sdX

Build Instructions

CachyOS BoppOS uses just as a command runner to simplify the build process. Ensure you have just and podman installed.

The OS is built using a multi-image architecture. You must first build the base image, and then build your preferred desktop environment flavor (plasma, gnome, or niri) on top of it.

You cannot create an image for an architecture your build system doesn't support!<br>

x86-64-v3 Build (v3 Default)

This build is compatible with most modern x86-64 hardware and is suitable for sharing or for use in CI/CD environments.

# 1. Construct the fastest-mirror list
just build-mirrorlist v3

# 2. Build the base image
just build v3 base

# 3. Build your preferred flavor (e.g., plasma, gnome, niri)
just build v3 plasma

x86-64-v4 Build (v4)

This enables optimizations for a wide range of modern CPUs (e.g., Intel Haswell and newer, AMD Excavator and newer) that support the x86-64-v4 microarchitecture level.

# 1. Construct the fastest-mirror list
just build-mirrorlist v4

# 2. Build the base image
just build v4 base

# 3. Build your preferred flavor (e.g., plasma, gnome, niri)
just build v4 plasma

Zen4/Zen5 Build (znver4)

If you are building on and for a system with an AMD Ryzen 7000 series CPU (or newer), you can enable native znver4 optimizations for maximum performance.

# 1. Construct the fastest-mirror list
just build-mirrorlist znver4

# 2. Build the base image
just build znver4 base

# 3. Build your preferred flavor (e.g., plasma, gnome, niri)
just build znver4 plasma

Switching to a Local Build

If you are building the image locally and want to apply it to your current system without pushing to a registry first, you can use the just switch command. This transfers the locally built container from your user environment to the root environment and tells bootc to switch to it via local storage.

# 1. Construct the fastest-mirror list
just build-mirrorlist

# 2. Build the image
just build

# 3. Switch to the local v3 build
just switch

# (Optional) Switch to a specific architecture tag instead (requires having built them separately already):
just switch v4
just switch znver4

Acknowledgements

This project was made possible by the excellent work of the CachyOS team and the creators of the original cachyos-deckify-bootc repository from which this was forked. It also stands on the shoulders of the Bootcrew and bootc projects.