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