Skip to content

Customization Guide

Jump to bottom
NullString1 edited this page May 29, 2026 · 3 revisions

Customization Guide

NullOS is designed to be highly customizable while remaining declarative and reproducible. This guide covers the main ways to customize your system.

Configuration Overview

NullOS uses a layered configuration approach driven by a feature-flag pipeline:

  1. machines/profiles/base.nix - System-wide defaults and available feature flags.
  2. machines/profiles/{pc,server}.nix - Machine-class specific feature overrides.
  3. machines/{hostname}/default.nix - Per-machine overrides and variable definitions.
  4. home/ - User-level configurations (Home Manager, loaded conditionally).
  5. modules/ - System-level configurations (NixOS, loaded conditionally).

Quick Customization Checklist

✅ Essential Configuration (in machines/{hostname}/default.nix):

  • Username and hostname
  • Enabling/disabling features (e.g. enableSteam, enableOllama)
  • Monitor configuration (extraMonitorSettings)
  • Wallpaper path (stylixImage)

✅ Desktop Customization:

  • Waybar configuration (home/waybar/)
  • Hyprland keybindings (home/hyprland/binds.nix)
  • Animation settings (home/hyprland/animations-end4.nix)
  • Theme and colors (via Stylix)

✅ Application Management:

  • System packages (modules/software/packages.nix)
  • Home Manager packages (home/default.nix)

Customizing machines/{hostname}/default.nix

The default.nix file inside your machine's folder is your main configuration hub.

Example: Disabling NVIDIA PRIME

{
  useNvidiaPrime = false;
}

Example: Adding Custom NixOS Config

Any key that isn't a reserved feature flag becomes extraNixosConfig automatically.

{
  services.openssh.enable = true;
  boot.devSize = "8G";
}

Customizing the Desktop

Hyprland Keybindings

NullOS utilizes dynamic keybindings managed via home/hyprland/binds.nix.

Some of the most important bindings include:

  • SUPER + Return: Open terminal (Ghostty)
  • SUPER + SHIFT + Return (or just releasing SUPER): Toggle Rofi app launcher
  • SUPER + W: Open Browser
  • SUPER + S: Interactive Screenshot (using screenshotin script)
  • SUPER + SHIFT + S: Screenshot OCR to clipboard (using screenshot-ocr script)
  • SUPER + T: Toggle dropdown scratchpad terminal
  • SUPER + SPACE: Toggle special workspace (scratchpad)

Tip: Press SUPER + K (or run list-keybinds) to view a searchable Rofi menu of all current keybindings!

Window Rules

Modify home/hyprland/windowrules.nix to customize window behavior:

windowrulev2 = float, class:^(pavucontrol)$
windowrulev2 = size 800 600, class:^(pavucontrol)$
windowrulev2 = center, class:^(pavucontrol)$

Theming with Stylix

Stylix provides system-wide theming based on your wallpaper.

Changing Wallpaper

# In machines/{hostname}/default.nix
{
  stylixImage = ../../wallpapers/your-wallpaper.jpg;
}

Manual Theme Override

If you want specific colors instead of auto-generated:

# In home/stylix.nix
stylix.base16Scheme = "${pkgs.base16-schemes}/share/themes/gruvbox-dark-medium.yaml";

Disabling Stylix for Specific Applications

# In home/default.nix
stylix.targets = {
  vscode.enable = false;  # Keep VSCode theme
  firefox.enable = false; # Keep Firefox theme
};

Adding/Removing Applications

System-Level Applications

Edit modules/software/packages.nix:

{ config, pkgs, vars, ... }:
{
  environment.systemPackages = with pkgs; [
    # Add your packages here
    btop
    neofetch
    vlc
  ] ++ lib.optionals vars.enableDevMisc [
    binwalk
    hexedit
  ];
}

Home Manager Applications

Edit home/default.nix:

{ config, pkgs, vars, ... }:
{
  home.packages = with pkgs; [
    # Add user-level packages
    discord
    spotify
  ];
}

Testing Changes

Rebuild Your System

NullOS provides handy zsh aliases for rebuilding:

  • fr: Rebuild current machine (runs nh os switch --hostname ${hostname})
  • fu: Rebuild + update inputs (runs nh os switch --hostname ${hostname} --update)

Make sure you run nix develop first before running the rebuild command!

Check for Errors

nix flake check

Rollback Changes

If something breaks:

Boot into Previous Generation

  1. Reboot
  2. Select previous generation from the boot menu
  3. System boots with old configuration

Using nh to Rollback

nh os rollback

Next Steps

Clone this wiki locally