"NixOS makes me feel like the world is my oyster" - A comprehensive, modular NixOS configuration supporting multiple platforms with declarative system management, dotfile synchronization, and secret management.
A sophisticated multi-platform Nix configuration repository utilizing flakes and flake-parts for reproducible system configurations across NixOS, macOS (nix-darwin), and WSL environments. This setup provides a unified development experience with consistent tooling, theming, and environment management.
- ✨ Features & Highlights
- 🚀 Quick Start
- 🏗️ Architecture
- 🖥️ Hosts
- 📚 Usage
- 🔧 Key Technologies
- 🎨 Desktop Environment
- 🛠️ Development Environment
- 🔐 Secret Management
- 🐛 Troubleshooting
- 🤝 Contributing
- 📖 References
- 📄 License
- NixOS: Full system configuration with desktop environment
- macOS: System preferences and package management via nix-darwin
- WSL2: Seamless Linux development environment on Windows
- Home Manager: Unified user environment across all platforms
- Flake-parts: Clean, modular flake organization
- Layered modules: Common, platform-specific, and user configurations
- Reusable components: Shared configurations across multiple hosts
- Type-safe configuration: Leveraging Nix's type system for robust configs
- SOPS integration: Encrypted secrets with age and GPG support
- Impermanence: Stateless system configuration for enhanced security
- Secure Boot: Support for secure boot configurations
- YubiKey integration: Hardware security key support
- Hyprland: Modern Wayland compositor with advanced features
- AGS: Custom widgets and desktop components
- Tokyo Night theme: Consistent theming across all applications
- Multiple display support: Seamless multi-monitor configurations
- Nix package manager (with flakes enabled)
- Git for cloning the repository
- Just command runner (optional, but recommended)
-
Enable Nix Flakes (if not already enabled):
mkdir -p ~/.config/nix echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf
-
Clone the repository:
git clone https://github.com/yourusername/dotfiles ~/.dotfiles cd ~/.dotfiles
-
Build for your system:
# For NixOS sudo nixos-rebuild switch --flake .#hostname # For macOS darwin-rebuild switch --flake .#hostname # Using just (recommended) just build hostname
- Generate SSH keys and add to your Git provider
- Configure SOPS with your age key for secret management
- Customize host-specific settings in
hosts/hostname/ - Apply changes with
just switch hostname
📁 ~/.dotfiles/
├── 📁 flakes/ # Flake-parts modules
│ ├── hosts.nix # Host definitions
│ ├── packages.nix # Custom packages
│ └── devshells.nix # Development shells
├── 📁 hosts/ # Host-specific configurations
│ ├── common/ # Shared host configs
│ └── <hostname>/ # Individual host settings
├── 📁 modules/ # Modular system components
│ ├── common/ # Cross-platform modules
│ ├── nixos/ # NixOS-specific modules
│ ├── darwin/ # macOS-specific modules
│ └── home/ # Home Manager modules
├── 📁 lib/ # Custom library functions
├── 📁 pkgs/ # Custom package definitions
├── 📁 config/ # Application dotfiles
├── 📁 secrets/ # SOPS-encrypted secrets
└── flake.nix # Main flake configuration
modules/common/: Cross-platform configurations (environment, nix settings, themes)modules/nixos/: Linux-specific modules (boot, desktop, hardware, networking)modules/darwin/: macOS-specific modules (brew, system preferences)modules/home/: User environment modules organized by category:cli/: Command-line tools, editors, shellsdesktop/: GUI applications, window managerslangs/: Programming language environments
| Host | Platform | Purpose | Description |
|---|---|---|---|
| tyr | macOS | Mac Mini | Primary macOS workstation for development and media |
| sigurd | NixOS | Desktop | High-performance Linux workstation with Hyprland |
| eir | macOS | MacBook Air | Portable development machine for travel and learning |
| Host | Platform | Purpose | Description |
|---|---|---|---|
| ymir | NixOS | Laptop | Testing ground for new NixOS configurations |
| nidhogg | WSL2 | Windows | Linux development environment on Windows |
| loki | NixOS | Flexible | Additional host for experimentation |
# Build system configuration (test without switching)
just build [hostname]
# Apply configuration changes
just switch [hostname] # Classic nixos-rebuild/darwin-rebuild
just switch2 [hostname] # Using nh (recommended)
# Deploy to remote host
just deploy <hostname>
# Fresh installation
just install <hostname> # Install on existing OS
just disko <hostname> # Full disk setup + install# Code quality & formatting
just fmt # Format all Nix files
just check # Validate flake & run linting
# Updates & maintenance
just up # Update all flake inputs
just upp <input> # Update specific input
just clean # Remove old system generations
just gc # Garbage collect unused store entries
# Development workflows
just dev [shell] # Enter development shell
just cfg <program> # Move config to ~/.config for development
just add <program> # Backup config from ~/.config to repo- Nix Flakes: Modern package management with lock files for reproducible builds
- flake-parts: Modular flake architecture for better organization
- Home Manager: Declarative dotfile and user environment management
- SOPS: Secure secret management with age encryption
- disko: Declarative disk partitioning and formatting
- impermanence: Stateless system configuration
- nix-darwin: macOS system configuration
- nixos-wsl: NixOS for Windows Subsystem for Linux
- Hyprland: Dynamic tiling Wayland compositor
- AGS: Customizable widgets and bars
- Hyprpaper: Wallpaper management
- Hyprlock: Screen locker
- Anyrun: Application launcher
- Aerospace: Tiling window manager for macOS
- System Preferences: Declarative macOS settings management
- Homebrew: GUI application management via nix-darwin
- Tokyo Night: Consistent dark theme across all applications
- JetBrains Mono: Primary monospace font with Nerd Font patches
- Cursor themes: Custom cursor styling across platforms
- Neovim: Heavily customized with LazyVim configuration
- LSP support for multiple languages
- AI integration (Copilot, Supermaven)
- Custom plugins and workflows
- VS Code: Platform-specific IDE setup
- Helix: Modern modal editor alternative
- Rust: Complete toolchain with cargo, clippy, rustfmt
- Python: Multiple versions, pip, poetry, conda integration
- Node.js: npm, yarn, pnpm package managers
- Java: JDK management and build tools
- C/C++: GCC, clang, cmake, debugging tools
- Shell: bash, zsh, fish with enhanced tooling
- Git: Advanced configuration with lazygit TUI
- tmux: Terminal multiplexer with custom config
- zsh: Enhanced shell with oh-my-zsh and plugins
- fzf: Fuzzy finder integration everywhere
- ripgrep, fd, bat: Modern alternatives to grep, find, cat
Secrets are encrypted using SOPS with age encryption:
# Edit secrets
sops secrets/services/example.yaml
# Re-key secrets for new hosts
sops updatekeys secrets/services/example.yamlsecrets/johnson/: User-specific secrets (SSH keys, GPG keys)secrets/services/: Service credentials and API keys- Age keys stored securely with hardware security key backup
- Hardware security key (YubiKey) integration
- GPG configuration with smart card support
- SSH key management with agent forwarding
- Secure boot support on compatible hardware
Build failures after flake updates:
# Clean build cache and retry
nix-collect-garbage -d
just build hostnameSecret decryption issues:
# Verify age key availability
age-keygen -y ~/.config/sops/age/keys.txt
# Re-import SOPS keys
sops updatekeys secrets/path/to/secret.yamlHome Manager activation failures:
# Reset conflicting files
mv ~/.config/conflicting-app ~/.config/conflicting-app.bak
just switch hostname# Verify flake structure
nix flake check
# Build with verbose output
nix build .#nixosConfigurations.hostname.config.system.build.toplevel -v
# Check system journal
sudo journalctl -u home-manager-username.service- Boot from NixOS installer for system recovery
- Use previous generation if current build fails
- Rollback Home Manager with
home-manager generations
- Test locally: Always test changes on your development host first
- Format code: Run
just fmtbefore committing - Validate configuration: Use
just checkto ensure flake validity - Update documentation: Keep README.md and CLAUDE.md in sync
- Use 2-space indentation for Nix files
- Follow existing naming conventions
- Add comments for complex configurations
- Organize imports alphabetically
- Create
hosts/hostname/directory - Add
default.nixandconfig.nix - Update
flakes/hosts.nixwith new host definition - Test build before committing
- nixos-and-flakes-book - Comprehensive tutorial for NixOS and flakes
- NixOS Wiki - Official documentation and guides
- Home Manager Manual - User environment management
- ryan4yin's nix-config - Original architectural inspiration
- Misterio77's nix-config - Excellent module organization
- isabelroses's dotfiles - Amazing NixOS desktop configuration
- fufexan's dotfiles - Hyprland and Wayland expertise
- hilissner's dotfiles - Clean code layout and structure
- khaneliman's khanelinix - Extensive AI configuration
- flake-parts - Modular flake architecture
- gytis-ivaskevicius's nixfiles - Framework concepts
- oddlama's nix-config - flake-parts implementation
- EmergentMind's nixos-config - System organization
- runarsf's dotfiles - Great configuration patterns
- oluceps's nixos-config - Advanced networking configuration
- Nobbz's nixos-config - Innovative configuration techniques
- azuwis's nix-config - Framework implementation ideas
This project is licensed under the MIT License - see the LICENSE file for details.
Special thanks to the incredible NixOS community and the maintainers of the projects that make this configuration possible. The declarative approach to system configuration has transformed my development workflow and system reliability.
"The best time to plant a tree was 20 years ago. The second best time is now." - The same applies to adopting NixOS! 🌱
Note: This configuration is tailored for my specific use cases and preferences. Feel free to fork and adapt it to your needs, but remember to update host-specific configurations and regenerate secrets appropriately.