NixOS Configuration

Personal NixOS configuration using flakes, home-manager, and agenix for secret management.

Quick Start

All common tasks are managed via just. Run just to see available commands.

System Operations

# Rebuild and switch to new configuration
just switch

# Rebuild and switch a specific host
just switch desktop

# Try out configuration without making it permanent (reverts on reboot)
just test

# Apply on next boot
just boot

# Build without switching
just build-system

# Update flake inputs
just update

# Compare current system with configuration
just diff

# Format configuration files
just fmt

# Validate configuration (flake check)
just check

# Maintenance: Collect garbage and delete old generations
just gc

Remote Deployment

# Deploy to a remote host (via nixos-rebuild --target-host)
just switch hostname user@remote

# Fresh install on a new machine (via nixos-anywhere)
just deploy-remote hostname user@remote

# Generate hardware configuration for a remote host
just factor hostname user@remote

Tools & Debugging

# Open nix repl with flake loaded
just repl

# List system generations/history
just history

# Visualize dependency tree
just tree

# Build an install ISO for a specific host
just iso hostname

Bootstrap ISO

# Build bootable USB installer
just bootstrap-iso

# Flash to USB drive
just bootstrap-flash /dev/sdX

Adding a New Host

1. Run the new-host command:

   just new-host <hostname> <username>
   

   This creates:

   • hosts/<hostname>/default.nix file which you should edit
   • secrets/hosts/<hostname>/ directory with SSH keys

2. Add host configuration in hosts/default.nix:

   <hostname> = mkSystem { host = .<hostname>; };
   

3. Create required files in hosts/<hostname>/:

   • configuration.nix - Main host config
   • disk-configuration.nix - Disk layout (for disko)
   • Other host-specific modules as needed

4. Generate hardware config:

   just factor <hostname>
   # Or for remote:
   just factor <hostname> user@remote
   

5. Deploy or Build:

   just test <hostname>
   

Tip

If you upload the public key (secrets/hosts/<hostname>/id_ed25519.pub) to GitHub, you can pull & push directly from the new host.

Deploying

Nixos ISO install

A simple way to install a new machine is to use the official NixOS ISO to prepare a machine

Copy the private SSH key for the new host to /etc/ssh/ssh_host_ed25519_key

Enable flakes support in /etc/nixos/configuration.nix

{
  nix = {
    package = pkgs.nixFlakes;
    extraOptions = ''
      experimental-features = nix-command flakes
    '';
  };
}

Then run:

$ nix develop
$ just switch <hostname>

Secret Management

Secrets are managed with agenix + agenix-rekey, using a YubiKey as the master identity.

Structure

secrets/
├── yubikey-identity.pub    # Master encryption key
├── *.age                   # Global secrets
└── hosts/<hostname>/
    ├── id_ed25519.pub      # Host public key
    ├── id_ed25519.age      # Host private key (encrypted)
    └── .rekey/             # Rekeyed secrets for this host

Commands

# Edit a secret
just secret-edit <secret-name>

# Rekey all secrets (after adding hosts/secrets)
just secret-rekey

# Decrypt a file to stdout
just decrypt <file.age>

# Run rage with yubikey
just age -e <file> -o <output.age>

Development

Development Shell

A Nix development shell is available with useful tools for working on this configuration:

# Enter the development shell
nix develop

Formatting

Code is formatted using treefmt-nix with:

• alejandra - Nix formatter
• deadnix - Remove unused Nix code
• statix - Nix linter
• prettier - JSON/YAML/Markdown
• just - Justfile formatter
• fish_indent - Fish scripts

nix fmt

Useful Tools

# Explore dependency tree
just tree

# Generate Nix fetcher from URL
just nurl https://github.com/owner/repo

Theme

Heavily inspired by / stolen from Flexoki

Name	Hex
bg	#1C1B1A
bg-alt	#282726
fg	#DAD8CE
fg-alt	#B7B5AC
muted	#878580
ui	#343331
ui-alt	#403E3C
black	#100F0F
accent	#CF6A4C
red	#D14D41
red-alt	#AF3029
orange	#DA702C
orange-alt	#BC5215
yellow	#D0A215
yellow-alt	#AD8301
green	#879A39
green-alt	#66800B
cyan	#3AA99F
cyan-alt	#24837B
blue	#4385BE
blue-alt	#205EA6
purple	#8B7EC8
purple-alt	#5E409D
magenta	#CE5D97
magenta-alt	#A02F6F
white	#DAD8CE
white-alt	#F2F0E5