Skip to content

Customization Guide

Jump to bottom
NullString1 edited this page Jan 13, 2026 · 1 revision

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:

  1. variables.nix - High-level per-machine settings
  2. home/ - User-level configurations (Home Manager)
  3. modules/ - System-level configurations (NixOS)
  4. flake.nix - System integration and inputs

Quick Customization Checklist

✅ Essential Configuration (in variables.nix):

  • Username and hostname
  • Git credentials
  • Keyboard layout and timezone
  • Default applications (terminal, browser)
  • Monitor configuration
  • Wallpaper path

✅ Desktop Customization:

  • Waybar configuration
  • Hyprland keybindings
  • Animation settings
  • Theme and colors (via Stylix)

✅ Application Management:

  • System packages
  • Home Manager packages
  • Service configuration

Customizing variables.nix

The variables.nix file is your main configuration hub. See Variables Reference for all options.

Example: Changing Your Browser

browser = pkgs.firefox;  # Instead of pkgs.brave

Example: Custom Monitor Setup

extraMonitorSettings = "
  monitor = DP-1, 2560x1440@144, 0x0, 1
  monitor = HDMI-A-1, 1920x1080@60, 2560x0, 1
  ";

Example: Disabling NVIDIA PRIME

useNvidiaPrime = false;

Customizing the Desktop

Waybar

Waybar can be customized by modifying the configuration file:

  1. Edit home/waybar/default.nix
  2. Rebuild with sudo nixos-rebuild switch --flake .#yourhostname

Common customizations:

  • Add/remove modules (clock, CPU, memory, etc.)
  • Change module positions (left, center, right)
  • Customize styling and colors
  • Add custom scripts

Hyprland Keybindings

Edit home/hyprland/binds.nix to customize keybindings:

bind = $mainMod, Return, exec, ghostty  # Terminal
bind = $mainMod, W, exec, brave        # Browser
bind = $mainMod, E, exec, dolphin      # File manager

Tip: Press SUPER + K to view all current keybindings!

Animations

NullOS includes custom animation sets. To change:

# In variables.nix
animationSet = home/hyprland/animations-end4.nix;

Create your own animation file in home/hyprland/ and reference it.

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 variables.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:

environment.systemPackages = with pkgs; [
  # Add your packages here
  btop
  neofetch
  vlc
];

Home Manager Applications

Edit home/default.nix:

home.packages = with pkgs; [
  # Add user-level packages
  discord
  spotify
  obs-studio
];

Tip: See Adding Applications for detailed guide.

Service Configuration

Enabling/Disabling Services

Edit modules/services/services.nix:

services.tailscale.enable = true;   # Enable Tailscale VPN
services.printing.enable = false;   # Disable printing

Ollama AI Server

services.ollama = {
  enable = true;
  acceleration = "cuda";  # Use NVIDIA GPU
};

Sunshine Game Streaming

services.sunshine = {
  enable = true;
  openFirewall = true;
  capSysAdmin = true;
};

Git Configuration

Edit home/git.nix for advanced Git settings:

programs.git = {
  enable = true;
  userName = "Your Name";
  userEmail = "you@email.com";
  
  aliases = {
    st = "status";
    co = "checkout";
    br = "branch";
  };
  
  extraConfig = {
    init.defaultBranch = "main";
    pull.rebase = true;
  };
};

Terminal Customization

Ghostty Terminal

Edit home/ghostty.nix:

programs.ghostty = {
  enable = true;
  settings = {
    font-family = "JetBrainsMono Nerd Font";
    font-size = 12;
    theme = "gruvbox";
    window-padding-x = 10;
    window-padding-y = 10;
  };
};

Starship Prompt

Edit home/starship.nix to customize your shell prompt.

Zsh Configuration

Add custom aliases and functions in home/zsh/zshrc-personal.nix:

programs.zsh.initExtra = ''
  alias ll='ls -lah'
  alias gs='git status'
  
  function mkcd() {
    mkdir -p "$1" && cd "$1"
  }
'';

Neovim Configuration

NullOS uses NVF for Neovim configuration. Edit home/nvf.nix:

programs.nvf = {
  enable = true;
  settings = {
    vim = {
      # Your Neovim config
      viAlias = true;
      vimAlias = true;
      theme.enable = true;
    };
  };
};

VSCode Configuration

Edit home/vscode.nix:

programs.vscode = {
  enable = true;
  extensions = with pkgs.vscode-extensions; [
    jnoortheen.nix-ide
    github.copilot
    # Add more extensions
  ];
  userSettings = {
    "editor.fontSize" = 14;
    "editor.fontFamily" = "JetBrains Mono";
  };
};

Per-Machine Configuration

For managing multiple machines, see Per Machine Config.

Using Specialisations

Create boot-time variants in your hardware configuration:

specialisation = {
  nvidia-on.configuration = {
    # NVIDIA enabled config
  };
  nvidia-off.configuration = {
    # Integrated graphics only
  };
};

Backup Configuration

Edit modules/services/backup.nix:

services.restic = {
  backups = {
    daily = {
      repository = "sftp:user@server:/backups";
      passwordFile = "/path/to/password";
      paths = [
        "/home/${username}"
      ];
      exclude = [
        "/home/${username}/.cache"
        "**/.git"
      ];
      timerConfig = {
        OnCalendar = "daily";
      };
    };
  };
};

Development Environments

Direnv Integration

NullOS includes direnv support. Create a .envrc in your project:

use flake

Or for specific packages:

use nix

Project-Specific Shells

Create a shell.nix in your project:

{ pkgs ? import <nixpkgs> {} }:

pkgs.mkShell {
  buildInputs = with pkgs; [
    nodejs
    python3
    rust-bin.stable.latest.default
  ];
}

Advanced Customization

Modifying Flake Inputs

Edit flake.nix to change or add inputs:

inputs = {
  nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
  home-manager.url = "github:nix-community/home-manager";
  # Add custom input
  my-package.url = "github:user/my-package";
};

Creating Custom Modules

Create a new file in modules/ and import it in the appropriate default.nix:

# modules/software/my-custom-app.nix
{ config, pkgs, ... }:

{
  environment.systemPackages = with pkgs; [
    my-custom-package
  ];
  
  # Additional configuration
}

Then import in modules/software/default.nix:

imports = [
  ./my-custom-app.nix
];

Testing Changes

Rebuild Without Switching

Test changes without making them permanent:

sudo nixos-rebuild test --flake .#yourhostname

Build Only (No Activation)

sudo nixos-rebuild build --flake .#yourhostname

Check for Errors

nix flake check

Rollback Changes

If something breaks:

Boot into Previous Generation

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

List Generations

sudo nix-env --list-generations --profile /nix/var/nix/profiles/system

Switch to Specific Generation

sudo nix-env --switch-generation 42 --profile /nix/var/nix/profiles/system
sudo /nix/var/nix/profiles/system/bin/switch-to-configuration switch

Tips for Effective Customization

  1. Start Small - Make one change at a time
  2. Test First - Use nixos-rebuild test before switching
  3. Document Changes - Add comments explaining why you changed something
  4. Use Git - Commit working configurations
  5. Check Nixpkgs - Search https://search.nixos.org for packages and options
  6. Read Source - Look at the actual Nix files to understand how things work

Next Steps

Clone this wiki locally