nixos-config

Configuration Reference

This document provides a comprehensive reference for the NixOS configuration framework.

Directory Structure

nixos-config/
├── docs/               # Documentation
│   ├── installation.md    # Installation guide
│   ├── reference.md       # This reference guide
│   ├── programs.md        # Program configurations
│   └── secrets_management.md  # Secrets management guide
├── home/               # Home Manager configurations
│   ├── default.nix        # Work mode (full dev setup)
│   ├── gaming.nix         # Gaming mode (minimal + Steam)
│   ├── env.nix           # Environment variables
│   └── programs/         # Individual program configurations
│       ├── claude.nix     # Claude AI assistant config
│       ├── claude/        # Claude commands & skills
│       │   ├── commands/  # Custom slash commands
│       │   └── skills/    # Custom skills
│       ├── browser.nix
│       ├── editor.nix
│       ├── terminal.nix
│       └── ...
├── hosts/              # Host-specific configurations
│   └── jokyv/          # Host-specific files
│       ├── default.nix           # Main host configuration
│       ├── hardware-configuration.nix  # Hardware settings
│       └── zsa-udev-rules.nix    # Custom udev rules
├── disks/              # Disk configurations (shared across hosts)
│   ├── universal-config.nix    # Auto-detecting installer
│   ├── disk-config-btrfs-luks.nix  # Legacy Btrfs+LUKS config
│   └── disk-config-btrfs.nix       # Legacy Btrfs config
├── install-config.nix  # Universal installer settings
├── flake.nix          # Main flake configuration
├── flake.lock         # Locked dependency versions
├── justfile          # Task automation commands
└── secrets.enc.yaml  # Encrypted secrets

Core Configuration Files

flake.nix

The main flake configuration defines:

• Nixpkgs inputs and dependencies
• System configurations
• Home Manager configurations
• Development shells
• Custom packages

Key sections:

• inputs: Define external dependencies (nixpkgs, home-manager, etc.)
• outputs: Define system configurations, packages, and development tools

Host Configuration (hosts/*/default.nix)

Each host configuration includes:

• System-level settings
• Hardware configurations
• Service definitions
• User configurations
• Import statements for modular components

Gaming Optimizations

System-level gaming performance is configured in hosts/jokyv/default.nix:

• GameMode daemon (programs.gamemode): Automatic CPU/IO prioritization when games run
• PipeWire low‑latency (services.pipewire.extraConfig): 48kHz clock, 256‑sample quantum, RTKit with high priority
• Steam hardware (hardware.steam-hardware.enable): udev rules for controllers, VR, Steam Deck support
• Kernel tuning (boot.kernelParams, boot.kernel.sysctl): nowatchdog, split_lock_detect=off, vm.max_map_count, vm.swappiness, etc.
• AMD CPU (nixos-hardware.nixosModules.common-cpu-amd-pstate): Optimal power management and performance

User‑level gaming packages (Steam, Wine, MangoHUD) and environment variables are managed by Home Manager home/gaming.nix and activated via just game.

Home Manager (home/)

Home configurations manage:

• User-level packages
• Dotfiles and configurations
• Program settings
• Environment variables
• Development tools

Common Configuration Patterns

Module System

Use imports to organize configurations:

{
  imports = [
    ./hardware-configuration.nix
    ../../modules/common.nix
    ../../modules/desktop.nix
  ];
}

Package Management

Add system packages:

environment.systemPackages = with pkgs; [
  git
  vim
  firefox
];

Add user packages via Home Manager:

home.packages = with pkgs; [
  helix
  kitty
  cargo
];

Service Configuration

Enable and configure system services:

services = {
  xserver.enable = true;
  printing.enable = true;
  pipewire = {
    enable = true;
    alsa.enable = true;
  };
};

Theming with Stylix

Configure system-wide theming:

stylix = {
  enable = true;
  base16Scheme = "${pkgs.base16-schemes}/share/themes/gruvbox-dark-hard.yaml";
  image = ../../wallpapers/nix.png;
  fonts = {
    monospace = {
      package = pkgs.nerdfonts;
      name = "FiraCode Nerd Font";
    };
  };
};

Justfile Commands

The project includes a justfile for common tasks:

• just switch: Rebuild system configuration
• just home: Apply Home Manager configuration (work mode)
• just game: Apply Home Manager configuration (gaming mode)
• just up: Update system packages
• just cleanup: Smart cleanup (keep 3 generations)
• just encode: Encrypt secrets
• just decode: Decrypt secrets

Secrets Management

The configuration uses sops-nix for encrypted secrets:

1. Edit secrets: sops secrets.enc.yaml
2. Generate keys: age-keygen -o ~/.config/sops/age/secrets.key
3. Access in configuration: config.sops.secrets.<secret-name>.path

Development Workflow

1. Make configuration changes
2. Test locally: nix flake check
3. Apply changes: just switch or just home
4. Commit changes with semantic commit messages
5. Update changelog for significant changes

Troubleshooting

Common Issues

1. Build failures
   • Check nix options: nix options
   • Verify flake inputs: nix flake update
   • Clean build: just clean
2. Secrets not decrypting
   • Verify key file permissions
   • Check sops configuration
   • Ensure age key is available
3. Hardware detection
   • Review hardware-configuration.nix
   • Check kernel modules
   • Verify firmware availability

Useful Commands

# Check flake outputs
nix flake show

# Test configuration
nixos-rebuild test --flake .#hostname

# Search packages
nix search nixpkgs package-name

# Garbage collect
nix-collect-garbage -d

Contributing

When contributing to the configuration:

1. Follow semantic commit messages
2. Update relevant documentation
3. Test changes thoroughly
4. Maintain backward compatibility where possible
5. Keep configurations modular and reusable

This site is open source. Improve this page.