Sanatana Linux

सनातन SANATANA: Perpetual, constant, eternal, permanent; Firm, fixed, settled;Primeval, ancient. - DSAL Online Sanskrit Dictionary

---

Warning

While I hope you can gain from my configuration and have attempted, for my own sake at least, to document what is going on in the configuration as thoroughly as possible, this is my configuration that I use personally and as such it is reasonable to assume it is highly unstable, subject to sudden radical changes in form and function coming after long periods of stagnation and is thus a perpetual a work in progress much as its author.

Hosts

Host	Machine	Description
bagalamukhi	Lenovo Legion 16IRX9H	Primary workstation (NVIDIA + Intel, AwesomeWM)
matangi	Lenovo Legion	Secondary system
chhinamasta	Live USB / ISO	Portable installer and rescue environment

# Build and switch
sudo nixos-rebuild switch --flake .#bagalamukhi

# Test without switching
sudo nixos-rebuild test --flake .#bagalamukhi

# Build ISO
nix build .#nixosConfigurations.chhinamasta.config.system.build.isoImage

Module Architecture

The configuration has been refactored from an activate-by-import pattern to an activate-by-enable-option pattern. Every module now exposes a config.modules.<category>.<name>.enable option, making the entire system composable and self-documenting.

modules/
  nixos/                        # System-level modules
    ai/                         # AI/ML tooling (CUDA, etc.)
    base/                       # Core system defaults
    desktop/                    # Desktop environments (AwesomeWM, XFCE, Newm)
    environment/                # Environment variables, session
    hardware/                   # NVIDIA, audio (Pipewire), peripherals
    packages/                   # Package collections
    performance/                # ZRAM, systemd-oomd, tuning
    power/                      # Power management
    printer/                    # Printing services
    programs/                   # Thunar, nix-ld, general programs
    security/                   # Security hardening
    services/                   # Networking, systemd units, Android
    shell/                      # Shell configuration
    system/                     # Users, boot, locale
users/ # User account declarations
virtualization/ # Waydroid, containers
home-manager/ # User-level modules (Home Manager)
    desktop/                    # Per-user desktop config
    packages/                   # Per-user package sets
    programs/                   # Firefox, Neovim, etc.
    services/                   # User services
    shell/                      # Zsh, Starship
    theme.nix                   # Theming
    xresources.nix              # X resources

Each module follows a consistent structure:

{ config, lib, ... }:
let
  cfg = config.modules.category.name;
in {
  options.modules.category.name = {
    enable = lib.mkEnableOption "description";
  };
  config = lib.mkIf cfg.enable {
    # ...
  };
}

Documentation

Quickstart

⚡ Installation Quickstart - Single-command installation script + post-install secrets bootstrap

Installation and Setup

1. Encrypted Root Setup - LUKS root partition details.
2. Live USB / ISO - Building and using the Chhinamasta live environment.

Nix Reference

1. Useful Nix Commands - Command reference informing the nix wrapper script.
2. Nix Modules Explained Coherently - A walkthrough of how NixOS modules actually work.
3. Flakes - Flake concepts and usage.
4. flake.nix Walkthrough - Annotated breakdown of this repository's flake.
5. Using Repository Templates - Dev shell templates and how to use them.
6. Searching and Installing Packages - Package discovery workflows.

Hardware and Desktop

1. NVIDIA Settings - NVIDIA driver and CUDA configuration notes.
2. Advanced BIOS for Lenovo Legion - Access the unlocked "Advanced BIOS" firmware settings from the Grub boot menu.

Secrets

1. Secrets Research - Evaluating secret management approaches.
2. Secrets - Current secrets management strategy.
3. SOPS - sops-nix integration details.

Debugging

1. Debugging Journal - Logs of problems and mitigations; useful for insight into the process of adjusting to NixOS.
2. NVIDIA Reinstallation
3. CUDA Compatibility
4. Nix Store Issues
5. CPU/Memory Overload
6. Display Manager Troubleshooting
7. Zsh Slowdown
8. Systemd VConsole
9. GCC Compilation
10. Not Enough Memory
11. Annoying Permissions
12. Neovim

Credits

1. Inspiration and Credits - Those who have inadvertently helped along in this process either as inspiration or through careful examination of their implementations.

Swarm Engineering

The module refactoring -- migrating dozens of NixOS and Home Manager modules from the legacy activate-by-import pattern to the enable-option pattern -- was carried out using swarm engineering, an agentic AI workflow where multiple specialized coding agents operate in parallel on isolated worktrees, each tackling a discrete subtask with built-in review gates.

This approach considerably reduced the tedium and error-prone nature of porting a large number of files and configurations from one module paradigm to another. The kind of work involved -- mechanical yet context-sensitive, repetitive yet requiring consistency across many files -- is exactly the sort of refactoring that is hard to test incrementally and easy to get subtly wrong by hand. Swarm orchestration made it tractable: each module conversion was an atomic unit of work, independently verifiable, with an agent-reviewer loop catching regressions before they merged.

It helped that the agents used in this project were defined with Nix-language-specific expertise (see AGENTS.md), and that recent Claude and Gemini models appear to have been trained on enough modern Nix code to handle it competently. This is noteworthy because Nix -- especially in the context of system configuration via flakes -- has historically been a pain point for LLMs: a niche use of a niche language with sparse training data and idiosyncratic patterns. The current generation of models has closed that gap enough to be genuinely useful for this kind of structured refactoring work.

Image Sourced from the Writer IT Blog