NullOS Architecture

NullOS Architecture Deep Dive

This document provides a technical deep dive into how NullOS is structured behind the scenes, specifically covering the configuration pipeline, custom derivations, and injected shell scripts.

The 3-Stage Configuration Pipeline

NullOS heavily relies on a 3-stage feature flag pipeline evaluated in flake.nix (lines 58-100). This replaces the traditional monolithic variables.nix and provides a highly modular and reusable way to define machines.

1. Base Defaults (machines/profiles/base.nix): Defines over 70 baseline variables and feature flags (e.g., enableSteam, enableDocker, desktopEnvironment). To keep the system minimal, almost all non-essential features are set to false by default.
2. Profile Overrides (machines/profiles/<profile>.nix): When defining a machine in flake.nix, a profile (like pc or server) is passed. This applies a set of overrides suitable for that class of machine. For example, pc.nix will typically enable enableSteam, enableLutris, and set desktopEnvironment = "hyprland", while server.nix keeps the GUI disabled.
3. Machine Overrides (machines/<hostname>/default.nix): This file provides the final layer of configuration. Variables defined here take highest precedence (e.g., setting the hostname, username, and specific useNvidiaPrime toggles).

The Quirky Magic of extraNixosConfig: When the machine's default.nix is evaluated, any key that isn't explicitly reserved as a feature flag in the base definitions is automatically bundled into a property called extraNixosConfig. This enables you to write raw, arbitrary NixOS configuration directly inside the machine's variables file without creating a new module for one-off tweaks.

Flake Overrides and Custom Packages

NullOS handles custom packages directly within the flake.nix overlay rather than utilizing standalone derivations inside the packages/ directory.

Injected Flake Inputs

Several flake inputs are directly exposed to the system pkgs via the final: prev: overlay pattern:

• stable: Exposes the nixpkgs-stable branch (pkgs.stable), allowing stable applications to be pulled into an otherwise unstable environment.
• fusion360: Exposes the fusion360 derivation from a custom GitHub flake.
• hyprland & xdg-desktop-portal-hyprland: Completely replaces the default nixpkgs Hyprland builds with the bleeding-edge flake input versions.
• dolphin-overlay: Applies custom patches to the Dolphin file manager.

Overridden Packages

The overlay modifies several existing packages:

• ananicy-rules-cachyos: Bumped to version 1.1.38 directly from GitHub source.
• picosvg (Python): Overridden to disable tests during the build (doCheck = false).
• openldap: Overridden to skip tests during the build phase (doCheck = false).

Custom User Scripts

NullOS injects several custom shell scripts as packages via pkgs.writeShellScriptBin. These are managed by Home Manager and are crucial for the desktop experience:

Script Name	Purpose
wallsetter	A daemon that cycles desktop wallpapers every 12 minutes. Uses awww for transitions. Ensures no duplicate consecutive wallpapers are selected.
list-keybinds	Parses hyprland.conf, replaces raw modifier names with SUPER, and displays all available keybindings via a searchable rofi menu.
rofi-launcher	A smart toggle script for the app launcher. Checks if rofi is running; if it is, it kills it. Otherwise, it launches rofi -show drun.
screenshotin	Interactive screenshot utility. Utilizes slurp for region selection, grim to capture the region, and immediately pipes to swappy for annotation.
screenshot-ocr	OCR utility for screenshots. Uses grim/slurp, passes the image to tesseract for text extraction, and pipes the result to wl-copy (clipboard).