thegeneralist's Nix Configuration

A comprehensive Nix flake configuration supporting both NixOS (Linux) and nix-darwin (macOS) systems with home-manager integration.

Overview

This configuration provides a unified way to manage multiple machines across different platforms:

• NixOS hosts: thegeneralist
• Darwin hosts: thegeneralist-mbp

Quick Start

Prerequisites

• Nix package manager with flakes enabled
• Git for cloning the repository

Installation

1. Clone the repository:

   git clone https://github.com/thegeneralist01/config.git ~/config
   cd ~/config

2. For NixOS systems:

   sudo nixos-rebuild switch --flake .#<hostname>

3. For Darwin systems:

   darwin-rebuild switch --flake .#<hostname>

Development Environment

Enter the development shell for configuration management:

nix develop

This provides:

• nil - Nix language server
• nixpkgs-fmt - Nix formatter
• agenix - Secret management

Architecture

Directory Structure

├── docs/           # Documentation
├── flake.nix       # Main flake configuration
├── flake.lock      # Locked dependency versions
├── hosts/          # Host-specific configurations
│   ├── default.nix # Host discovery and categorization
│   └── <hostname>/ # Individual host configurations
├── lib/            # Custom library functions
│   ├── default.nix # Library entry point
│   ├── option.nix  # Option utilities
│   └── system.nix  # System building functions
├── modules/        # Reusable system modules
│   ├── common/     # Cross-platform modules
│   ├── darwin/     # macOS-specific modules
│   └── linux/      # Linux-specific modules
├── keys.nix        # Age public keys for secrets
└── secrets.nix     # Encrypted secrets

Key Components

Flake Inputs

• nixpkgs: Main package repository (nixos-unstable)
• home-manager: Dotfiles and user environment management
• nix-darwin: macOS system configuration
• agenix: Age-based secret management
• ghostty: Modern terminal emulator
• fenix: Rust toolchain provider

Library Functions

• mkSystem: Core system builder for both Linux and Darwin
• mkOption: Custom option utilities
• Host auto-discovery and categorization

Host Configuration

Adding a New Host

1. Create a new directory under hosts/:

   mkdir hosts/new-hostname

2. Create the host's default.nix:

   lib: inputs: self: lib.mkSystem "linux" ./configuration.nix
   # or for macOS:
   lib: inputs: self: lib.mkSystem "darwin" ./configuration.nix

3. Create configuration.nix with your host-specific settings:

   { config, pkgs, ... }: {
     # Host-specific configuration here
   }

4. Rebuild your flake:

   nix flake lock  # Update lock file if needed
   nixos-rebuild switch --flake .#new-hostname

Host Categorization

Hosts are automatically categorized based on naming conventions:

• Names ending with mbp or containing central-mbp → Darwin
• All others → NixOS

Pinned AeroSpace fork

thegeneralist-mbp builds N1ark/AeroSpace at d720311 from source for left/right modifier support. All Option-based bindings use lalt, leaving right Option available for typing. Other modifiers and commands are unchanged. Config version 2 explicitly lists persistent workspaces, preserving the workspace set that version 1 inferred from the bindings.

The build is defined in nixpkgs-overlay/aerospace/:

• aerospace-src in flake.nix and flake.lock pins the complete source revision, including its prerequisite commits.
• swift-toolchain.nix pins the official Swift 6.4.0 installer and its hash, matching the source's .swift-version.
• The source's Package.resolved supplies Swift dependency versions/revisions; dependency-hashes.nix fixes their archive hashes.
• The existing nixpkgs lock pins Apple SDK 26.0, the linker, native libraries, documentation/completion tools, and signer.
• Both executables are release builds from the fork. Only compiled icon assets are reused from nixpkgs' pinned official AeroSpace release.
• The app bundle is ad-hoc signed without a developer certificate or host keychain. No manually built artifact or installed Xcode is needed.

Build the package without activating it:

nix --extra-experimental-features pipe-operators build .#aerospace --no-link

Apply it through the existing Darwin service:

sudo darwin-rebuild switch --flake .#thegeneralist-mbp \
  --option extra-experimental-features pipe-operators

Restart AeroSpace after updating if the CLI reports a client/server protocol mismatch: the fork's CLI must be used with its matching app. macOS Accessibility approval remains an OS-level action; a changed ad-hoc signature may require re-granting it. Sided shortcuts do not work while Secure Input is enabled, including in password fields. lalt matches left Option alone, not both Option keys held together.

To update the fork, change the full commit in inputs.aerospace-src.url, then run nix flake update aerospace-src. Review Package.resolved and .swift-version at the new revision and update the dependency/toolchain hashes when they change. The source stays pinned during ordinary nix flake update operations.

Module System

Common Modules

Located in modules/common/, these are loaded on all systems:

• nix.nix - Nix configuration and binary caches
• home-manager.nix - User environment management
• packages.nix - Common packages
• git.nix, neovim.nix, zsh.nix - Development tools
• agenix.nix - Secret management

OMP model routing

modules/dotfiles/omp/models.nix declares OMP's model roles, per-agent model overrides, and saved presets. modules/common/omp.nix applies them during Home Manager activation, alongside the custom agent definitions and prompts.

The activation replaces modelRoles, task.agentModelOverrides, and modelPresets in ~/.omp/agent/config.yml. Other settings, including other task options, are preserved. The file remains writable: changes saved through OMP work immediately, but the next rebuild restores these three repo-owned sections. Edit models.nix to make routing changes permanent across rebuilds.

The gemmysolopus, haikugemmyopus, and aura presets retain their different default/small models, while sharing Gemini Flash Medium for tasks and Opus 5.5 High for planning. Per-agent overrides keep both reviewers on Sol High and l-worker on Sol independently of the selected preset. Selecting a preset or changing the active session model remains an OMP action, not a rebuild action.

Platform-Specific Modules

• modules/darwin/ - macOS-specific (SSH, Karabiner, packages)
• modules/linux/ - Linux-specific (boot, networking, X11, NVIDIA)

Creating Custom Modules

1. Add your module to the appropriate directory:

   # modules/common/mymodule.nix
   { config, pkgs, ... }: {
     # Module configuration
   }

2. The module is automatically discovered and loaded

Secret Management

Uses agenix for encrypted secrets management:

1. Add recipient public keys to keys.nix
2. Define secrets in secrets.nix
3. Edit secrets: agenix -e secret-name.age
4. Reference in configuration: config.age.secrets.secret-name.path

Builds and Binary Cache

thegeneralist performs its own x86_64 builds and serves the personal binary cache.

Binary Caches

Configured caches for improved build performance:

• cache.thegeneralist01.com - Personal cache
• cache.garnix.io - Community cache
• cache.nixos.org - Official cache

Development Workflow

Updating Dependencies

nix flake update

Formatting Code

nixpkgs-fmt **/*.nix

Checking Configuration

nix flake check

Cleaning Up

# Via nh (configured in home-manager)
nh clean all --keep 3 --keep-since 4d

# Manual cleanup
nix-collect-garbage -d

Common Tasks

Installing Packages System-wide

Add to the appropriate modules/*/packages.nix file.

Installing User Packages

Modify the home-manager configuration in your host's configuration.nix.

Updating a Single Host

nixos-rebuild switch --flake .#hostname
# or
darwin-rebuild switch --flake .#hostname  

Rolling Back Changes

nixos-rebuild switch --rollback
# or
darwin-rebuild switch --rollback

Troubleshooting

Build Failures

1. Check flake lock compatibility: nix flake update
2. Clear build cache: nix-collect-garbage -d
3. Verify module syntax: nix flake check

Secret Access Issues

1. Verify keys are properly configured in keys.nix
2. Re-encrypt secrets: agenix -r
3. Check file permissions on age keys

Performance Issues

1. Verify binary cache access
2. Use nh for optimized rebuilds

Contributing

1. Follow existing code style and organization
2. Test changes on a single host before applying broadly
3. Update documentation for significant changes
4. Use meaningful commit messages

References

• NixOS Manual
• Nix-Darwin
• Home Manager
• Agenix