Skip to content

File Structure

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

File Structure

Understanding the NullOS directory structure.

Overview

NullOS uses a well-organized structure separating system configuration, home manager settings, and documentation.

NullOS/
├── flake.nix              # Main flake configuration
├── flake.lock             # Locked dependencies
├── AGENTS.md              # AI agent documentation and system architecture
├── README.md              # Project documentation
├── WIKI.md                # Wiki index
├── .gitignore             # Git ignore rules
├── .sops.yaml             # SOPS secret configuration
├── _screenshots/          # Screenshots
├── wallpapers/            # Wallpaper images
├── home/                  # Home Manager configs
├── machines/              # Per-machine configs, profiles, and secrets
├── modules/               # NixOS system modules
├── packages/              # Custom packages (derivations)
└── wiki/                  # Local wiki (optional)

Root Directory Files

flake.nix

Main flake configuration that:

  • Defines inputs (nixpkgs, home-manager, sops-nix, etc.)
  • Configures system outputs
  • Sets up overlays
  • Implements the three-stage variable merging pipeline (base -> profile -> machine)
  • Defines machine configurations (nixosConfigurations)
  • Defines home configurations (homeConfigurations)

AGENTS.md

Documentation detailing the architecture, quirk explanations, and quick references. This file is vital for understanding the 3-stage config pipeline.

flake.lock

Locked versions of all inputs. Ensures reproducibility.

Update with:

nix flake update

Machines Directory (machines/)

This directory replaces the old variables.nix and handles per-machine settings and feature flags.

machines/
├── profiles/
│   ├── base.nix           # ~70 feature flags, system defaults
│   ├── pc.nix             # Feature sets for PCs
│   └── server.nix         # Feature sets for servers
├── nslapt/                # Laptop configuration
│   ├── default.nix        # Per-machine overrides and vars
│   └── secrets.yaml       # Encrypted secrets via sops-nix
├── nspc/                  # Desktop configuration
│   ├── default.nix
│   └── secrets.yaml
└── nsminipc/              # Headless server
    ├── default.nix
    └── secrets.yaml

The 3-Stage Pipeline

  1. Base (machines/profiles/base.nix) - Feature flags, most false.
  2. Profile (machines/profiles/{pc,server}.nix) - Feature sets based on machine class.
  3. Machine (machines/{hostname}/default.nix) - Per-machine overrides.

Result: vars object available to all modules via specialArgs. Non-reserved attributes in machine config become extraNixosConfig.

Home Directory (home/)

User-level configurations managed by Home Manager.

home/
├── default.nix          # Main entry point (conditional imports)
├── hyprland/            # Hyprland configs
├── zsh/                 # Shell configs and aliases
└── ...                  # Other application configs

home/default.nix

Main home-manager configuration that conditionally imports all other home configs based on the vars feature flags.

Modules Directory (modules/)

System-level NixOS modules organized by category.

modules/
├── default.nix         # Imports all system modules
├── services/           # System services (e.g. backup, ssh)
├── software/           # Applications (e.g. packages.nix)
└── system/             # System settings (boot, nvidia, network)

Secrets Management (.sops.yaml & secrets.yaml)

NullOS now uses sops-nix for managing secrets. Secrets like githubToken or resticRepository passwords are encrypted per-machine in machines/{hostname}/secrets.yaml.

Next Steps

Clone this wiki locally