NixOS Configuration

A modular, reproducible NixOS configuration optimized for development and professional audio work. Built with flakes, nix-wrappers, and modern tooling.

Features

Flake-based - Reproducible, atomic updates with flake inputs
Modular architecture - Shared modules under modules/common/ for easy reuse
Wrapper-based user programs - User applications configured via nix-wrappers (migrated from Home Manager)
Professional audio - Low-latency PipeWire configuration with realtime scheduling
System tuning - Optimized for AMD Ryzen 7 5800X and RX 6700 XT
Code quality - treefmt with 10+ formatters, git-hooks.nix pre-commit hooks, CI checks
Secret management - SOPS-nix with age encryption
Modern tooling - nh, treefmt, nixfmt, and more

Quick Start

Prerequisites

Install Nix with flakes support:

curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

Clone and Setup

git clone https://github.com/kzndotsh/nixos && cd nixos

# Enter development shell
nix develop

# Validate configuration
just check

# Build configuration
just build

Apply Configuration

# Switch to new configuration (recommended: use nh)
nh os switch
# Or manually:
sudo nixos-rebuild switch --flake .#ikigai

# Test without switching
nh os test

Project Structure

nixos/
├── flake.nix              # Flake inputs and outputs
├── treefmt.nix            # treefmt-nix configuration
├── treefmt.toml           # treefmt direct configuration
├── justfile               # Convenience commands
│
├── hosts/                 # Host configurations
│   ├── ikigai.nix         # Main host (ikigai)
│   └── test-vm.nix        # VM variant
│
├── modules/
│   ├── common/            # Shared system modules
│   │   ├── desktop/       # Sway, theming, audio, XDG, greetd
│   │   ├── hardware/      # GPU configuration
│   │   ├── i18n/          # Locale, keyboard, timezone
│   │   ├── network/       # DNS, firewall, IPv6
│   │   ├── nix/           # Nix settings, registry, substituters
│   │   ├── packages/      # System packages, SSH config
│   │   ├── security/      # 1Password, SOPS, PAM
│   │   ├── services/      # Docker, Cachix, systemd services
│   │   ├── system/        # System environment variables
│   │   └── tuning/        # Kernel, sysctl, I/O, power, audio
│   │
│   └── wrappers/          # User program wrappers (nix-wrappers)
│       ├── default.nix    # Main entry point
│       ├── git.nix        # Git wrapper with config
│       ├── ghostty.nix    # Ghostty terminal wrapper
│       ├── fuzzel.nix     # Fuzzel launcher wrapper
│       └── neovim.nix     # Neovim wrapper
│
├── users/                 # User definitions
├── lib/                   # Helper functions
├── scripts/               # Utility scripts
└── secrets/               # SOPS-encrypted secrets

Usage

Development Commands

Enter the development shell first:

nix develop

Formatting

just format          # Format Nix files (nixfmt)
just treefmt         # Format all files (treefmt)
just treefmt-ci      # Check formatting (CI mode)
just treefmt-clear   # Clear cache and re-format
just treefmt-files <paths>  # Format specific files

Code Quality

just check           # Validate flake (includes pre-commit checks)
just dead            # Check for dead code
just dead-fix        # Remove dead code
just modules-check   # Check kernel modules
nix flake check      # Run pre-commit hooks in sandbox
pre-commit run --all-files  # Run all hooks manually

Building & Testing

just build           # Build NixOS configuration
just eval-config     # Evaluate config (no build)
just syntax-check <file>  # Check Nix syntax

System Management

nh os switch         # Switch to new configuration
nh os test           # Test without switching
nh update            # Update flake inputs
nh clean             # Clean build artifacts

System Information

just cpu             # CPU frequency scaling status
just probe           # Gather system information
just verify          # Verify hardware configuration
just tree            # Show configuration dependency tree

Secret Management

just sops-edit       # Edit secrets (auto-encrypts)
just sops-show       # View decrypted secrets
just sops-init-age   # Generate age key
just sops-create     # Create secrets from example
just sops-updatekeys # Update keys in secrets

Formatting & Linting

This configuration uses treefmt with multiple formatters:

Nix: nixfmt, deadnix (statix run manually: statix check .)
Shell: shfmt, shellcheck
Python: ruff-format, ruff-check
YAML: yamlfmt
Multi-language: prettier (JS/TS/JSON/CSS/HTML/MD)
GitHub Actions: actionlint

Run all formatters:

just treefmt
# or
nix run .#treefmt

Configuration Modules

Wrappers (`modules/wrappers/`)

User programs are configured via nix-wrappers (migrated from Home Manager):

Git (git.nix): Git wrapper with global configuration, aliases, SSH signing
Ghostty (ghostty.nix): Terminal emulator with theme and font configuration
Fuzzel (fuzzel.nix): Application launcher with styling
Neovim (neovim.nix): Editor wrapper (minimal, config can be extended)

Wrappers automatically add programs to environment.systemPackages when systemWide = true is set.

System Tuning (`modules/common/tuning/`)

Hardware-optimized configuration for AMD Ryzen 7 5800X and RX 6700 XT:

Kernel (kernel.nix): Zen kernel, AMD P-State active mode, GPU optimizations
Power (power.nix): CPU frequency scaling (performance governor)
I/O (io.nix): I/O schedulers, SATA power management, HDD optimization, CPU DMA latency
Sysctl (sysctl.nix): Memory, network, filesystem tuning
Audio (audio.nix): Low-latency PipeWire configuration

Desktop (`modules/common/desktop/`)

Sway (sway.nix): Window manager configuration (config written to /etc/sway/config)
Theming (theming.nix): Tokyo Night theme via base16.nix, GTK/Qt theming
Audio (audio.nix): PipeWire, WirePlumber, realtime scheduling
XDG (xdg.nix): XDG portal configuration, desktop/session environment variables
Greetd (greetd.nix): Display manager configuration

Security (`modules/common/security/`)

1Password (1password.nix): SSH agent integration
SOPS (sops.nix): Secret management with age encryption
PAM (pam.nix): Realtime audio privileges

Services (`modules/common/services/`)

Docker (docker.nix): Docker daemon configuration
Cachix: Binary caching setup (substituters in modules/common/nix/substituters.nix, CLI tool in modules/common/services/services.nix)

Nix Configuration (`modules/common/nix/`)

Registry (registry.nix): Flake registry configuration
Substituters (substituters.nix): Binary cache configuration
Settings (default.nix): Nix experimental features, performance settings

Flake Inputs

nixpkgs - Stable (nixos-25.11)
nixpkgs-unstable - For newer packages
wrappers - nix-wrappers library for user program configuration
sops-nix - Secret management
base16 - Theming support
treefmt-nix - Code formatting
git-hooks - Pre-commit hooks
nix-topology - Infrastructure visualization

Note: Home Manager has been deprecated and migrated to nix-wrappers for user program configuration.

Hardware

Optimized for:

CPU: AMD Ryzen 7 5800X (Zen 3)
GPU: AMD Radeon RX 6700 XT (RDNA 2)
Memory: 128GB DDR4
Storage: NVMe SSDs, SATA SSD, HDD

Development Workflow

Make changes to configuration files
Format code: just treefmt
Check quality: just check && just dead
Test: nh os test
Switch: nh os switch

CI/CD

GitHub Actions workflow runs:

treefmt --ci - All formatters and linters
nix flake check - Flake validation (includes pre-commit hooks)
deadnix-action - Auto-PR for dead code fixes

Pre-commit Hooks

Pre-commit hooks are automatically installed when entering the development shell (nix develop). The hooks run automatically on git commit and can be run manually:

# Run all hooks
pre-commit run --all-files

# Run hooks in sandbox (read-only, no network)
nix flake check

Configured hooks:

nixfmt - Format Nix files
deadnix - Find unused Nix code

Note: statix is disabled in treefmt (doesn't work with file-by-file processing). Run manually: statix check . or statix fix .

Customization

Host Configuration

Edit hosts/ikigai.nix for host-specific settings:

# Networking
networking.hostName = "ikigai";
networking.firewall.enable = false;

# System packages
environment.systemPackages = with pkgs; [
  # Add packages here
];

# Zsh configuration
programs.zsh = {
  enable = true;
  # ... configuration
};

Add Packages

System packages: Edit modules/common/packages/default.nix
User programs via wrappers: Add to modules/wrappers/ (e.g., modules/wrappers/myapp.nix)

Add a Wrapper

Create a new wrapper file in modules/wrappers/:

# modules/wrappers/myapp.nix
{
  pkgs,
  ...
}:
{
  wrappers.myapp = {
    basePackage = pkgs.myapp;
    systemWide = true;  # Automatically add to systemPackages
    executables.myapp = {
      environment = {
        MYAPP_CONFIG = {
          value = pkgs.writeText "myapp.conf" ''
            # Configuration here
          '';
        };
      };
    };
  };
}

Then import it in modules/wrappers/default.nix.

Modify Tuning

Edit modules in modules/common/tuning/:

kernel.nix - Kernel parameters, modules
sysctl.nix - System parameters
io.nix - I/O schedulers, udev rules
power.nix - CPU frequency scaling

Troubleshooting

Build Fails

just check              # Validate flake
just eval-config        # Check evaluation
nix build .#nixosConfigurations.ikigai --show-trace

Formatting Issues

just treefmt-clear      # Clear cache
just treefmt            # Re-format

Kernel Modules Not Blacklisted

After adding to boot.blacklistedKernelModules:

sudo nixos-rebuild switch
sudo modprobe -r <module>  # Manually unload

Migration Notes

This configuration migrated from Home Manager to nix-wrappers. The old Home Manager configuration is preserved in home.old/ for reference.

Key differences:

User programs are now configured via wrappers in modules/wrappers/
System-wide configuration remains in modules/common/
Zsh configuration is now in host files (hosts/ikigai.nix) via programs.zsh
Git configuration is in modules/wrappers/git.nix as a wrapper

Name		Name	Last commit message	Last commit date
Latest commit History 91 Commits
.cursor/rules		.cursor/rules
.github/workflows		.github/workflows
.vscode		.vscode
hosts		hosts
lib		lib
modules		modules
scripts		scripts
secrets		secrets
users		users
.editorconfig		.editorconfig
.gitignore		.gitignore
.sops.yaml		.sops.yaml
NOTES.md		NOTES.md
README.md		README.md
TODO.md		TODO.md
flake.lock		flake.lock
flake.nix		flake.nix
justfile		justfile
topology.nix		topology.nix
treefmt.nix		treefmt.nix
treefmt.toml		treefmt.toml

Folders and files

Latest commit

History

Repository files navigation