BinaryOS

BinaryOS is a custom bootc image built on top of Bluefin-DX with Hyprland and an opinionated set of development tools. This image is designed primarily for my personal software development workflow, but you're welcome to use it, fork it, or submit issues and pull requests.

What's Inside

BinaryOS builds on Bluefin-DX's excellent developer experience foundation and adds:

• Hyprland: A dynamic tiling Wayland compositor for an efficient, keyboard-driven workflow
• Opinionated Development Tools: A curated set of tools and configurations optimized for my development workflow
• Personal Preferences: Custom configurations and tweaks that I've found useful over time

Available Variants

BinaryOS is available in two variants:

• Regular: Built on bluefin-dx:stable-daily for systems with Intel/AMD graphics
• NVIDIA: Built on bluefin-dx-nvidia:stable-daily with NVIDIA driver support

This is not meant to be a general-purpose distribution, but rather a personal daily driver that happens to be publicly available for others who might share similar preferences.

Community & Support

While this is a personal image, community contributions are welcome! If you encounter issues or have suggestions:

• Open an issue on this repository
• Submit a pull request with improvements
• For general bootc and Universal Blue questions:
  • Universal Blue Forums
  • Universal Blue Discord
  • bootc discussion forums

Installation

Prerequisites

• A machine running a bootc-compatible image (e.g., Bazzite, Bluefin, Aurora, or Fedora Atomic)
• Basic familiarity with bootc and container-based operating systems

Switching to BinaryOS

From your existing bootc system, run:

For systems with Intel/AMD graphics:

sudo bootc switch ghcr.io/binarypie/binaryos:latest

For systems with NVIDIA graphics:

sudo bootc switch ghcr.io/binarypie/binaryos:latest-nvidia

Then reboot your system:

systemctl reboot

After rebooting, you'll be running BinaryOS.

Switching Back

If BinaryOS isn't for you, you can switch back to your previous image:

sudo bootc status  # Find your previous image
sudo bootc switch <your-previous-image>
systemctl reboot

Customization & Forking

Want to create your own variant of BinaryOS? You're welcome to fork this repository! Here's how the build system works:

Repository Structure

• Containerfile: The main build definition. This is where the base image is selected and the build process is orchestrated.
• build.sh: The primary customization script. This is where packages are installed and system configurations are applied.
• build.yml: GitHub Actions workflow that builds and publishes the image to GitHub Container Registry (GHCR).

Building Your Own Variant

If you fork this repository:

1. Modify build.sh to add/remove packages and configurations
2. Update the Containerfile if you want to change the base image
3. Push your changes - GitHub Actions will automatically build your image
4. Your image will be available at ghcr.io/<your-username>/<your-repo-name>

For detailed information about customizing the image, see the files mentioned above. They contain examples and documentation.

Building Disk Images

The repository includes workflows for creating bootable disk images (ISO, QCOW2, raw) using bootc-image-builder. These can be used for:

• Installing BinaryOS on bare metal (ISO)
• Testing in virtual machines (QCOW2)
• Deploying to cloud environments (raw)

Available via GitHub Actions

The build-disk.yml workflow can generate these images automatically. After the workflow completes, disk images are available as artifacts in the GitHub Actions run.

Building Locally

You can also build disk images locally using the included just commands (see Justfile Documentation below).

Artifacthub

BinaryOS is indexed on artifacthub.io to make it easier to discover and track. If you fork this image, you can list your own variant there as well using the artifacthub-repo.yml file.

Learn more in the Universal Blue Artifacthub discussion.

Development with Just

The repository includes a Justfile with commands for building and testing BinaryOS locally. just is a command runner that simplifies common development tasks.

Just is pre-installed on all Universal Blue images (including BinaryOS and Bluefin-DX). If you're using another system, install it from your package manager or see the just installation guide.

Available Commands

Run just without arguments to see all available commands. Here are the most useful ones:

Building

• just build - Build the BinaryOS container image locally (regular variant)
• just build-regular - Build the regular variant (Intel/AMD graphics)
• just build-nvidia - Build the NVIDIA variant
• just build-all - Build both regular and NVIDIA variants
• just build-iso - Build a bootable ISO image
• just build-qcow2 - Build a QCOW2 VM image
• just build-raw - Build a raw disk image

Testing

• just run-vm-qcow2 - Run BinaryOS in a VM using QCOW2 image
• just spawn-vm - Run BinaryOS using systemd-vmspawn

Maintenance

• just clean - Clean build artifacts
• just lint - Check shell scripts for issues
• just format - Format shell scripts

For detailed usage and additional commands, see the Justfile itself.

Related Projects

BinaryOS is part of the larger Universal Blue ecosystem. Check out these other custom images for inspiration:

• Bluefin-DX - The base image for BinaryOS
• m2Giles' OS - Another custom bootc image
• bOS - Custom image by bsherman
• Homer - Custom image by bketelsen
• Amy OS - Custom image by astrovm
• VeneOS - Custom image by Venefilyn

License

This project follows the same licensing as the Universal Blue project. See the LICENSE file for details.

Acknowledgments

BinaryOS is built on the shoulders of giants:

• Universal Blue for the excellent image-based desktop platform
• Project Bluefin for the outstanding developer experience foundation
• bootc for the bootable container technology
• Hyprland for the amazing Wayland compositor
• The Fedora and broader open source community