A highly modular NixOS configuration repository targeting desktop, server, and virtualized environments.
This flake is built on a dendritic aspect-oriented structure, focusing on small, fully self-contained, modular, and shareable aspects. It leverages den as the underlying configuration framework.
Note
System & Network Co-Orchestration (denful-networks)
This repository is not just a NixOS host configuration; it is the single source of truth for the physical and logical network infrastructure of the homelab. Using the denful-networks schema, network definitions (VLANs, static IPs, MAC bindings, and port profiles) are compiled into two outputs to keep the host and the physical switch/router in sync:
- NixOS Configurations: Automatic creation of host bridges, VLAN interfaces, firewall rules, and internal nameserver records.
- Terranix/Terraform Configs: Generated declarative UniFi profiles (client definitions, subnet rules, port overrides) and Cloudflare DNS zone records.
The configuration is structured as independent modules, each containing distinct aspects that package system options, home-manager environments, and dependencies together:
| Module Category | Description |
|---|---|
| 🖥️ apps | GUI applications (Chromium, Neovide, Wezterm, etc.) and their user configurations. |
| 🥾 boot | Bootloaders, systemd-initrd configurations, and Disko declarations. |
| 🐚 cli | Command-line utilities, shells (Zsh), terminal multiplexers (Tmux), and git configurations. |
| 📦 containers | Docker and OCI container services (media stacks, databases, self-hosted applications). |
| 🛠️ dev | Developer environments, language servers (LSPs), runtimes, and compiler setups. |
| 🔤 fonts | System-wide custom font packages and rendering settings. |
| 👥 groups | User groups and shared access roles declarations. |
| 🖼️ gui | Compositor configuration (Niri), bar modules (Quickshell), and notification daemons (Mako). |
| 💻 hosts | Machine-specific host profiles (desktop, server) and hardware configurations. |
| 🔌 hw | Hardware-specific drivers (Nvidia, AMD), controllers (liquidctl, coolercontrol), and peripherals. |
| 🌐 infra | Network infrastructure definitions, static IP allocations, VLAN networks, device specifications, and cloudflare/unifi integrations. |
| 💿 iso | Custom minimal installation ISO generation rules and automated setup scripts. |
| 🔌 networking | Core system-wide network services (NAT, NetworkManager daemon configurations). |
| 🔒 security | Secret management setup utilizing SOPS-NIX and age keys. |
| ⚙️ services | System daemons (SSH, resolving, sd-login, Btrfs scrubbing utilities). |
| 🎨 style | Theme and system styling setup using Stylix (base16 templates). |
| 👤 users | User account definitions and individual home-manager profiles. |
packages/sys-mcp/ is a Model Context Protocol server bundled with this repo that understands the homelab's topology. It is declared in modules/cli/mcp.nix and automatically registered with all MCP-aware clients (Claude Code, IDEs, agents) via home-manager's programs.mcp — no manual wiring required.
Capabilities:
- Nix topology — resolve containers, VLANs, infra clients, and physical devices; look up anything by IP, port, or fuzzy name; browse the full network topology
- Runtime — fetch container logs, systemd status, and exec commands inside containers (auto-SSHes to the correct host)
- UniFi live state — query active devices, connected clients, networks, WiFi SSIDs, firewall policies, and port forward/profile rules directly from the controller
Credentials and addresses are injected automatically: the UniFi URL is resolved from the infra device definition, and the API key is read from SOPS at runtime.
We use a Justfile to organize common administration, building, and maintenance operations.
just build: Builds both the server and desktop configurations (dry run).just build-desktop: Builds the desktop configuration locally without applying changes (dry run).just build-server: Builds the server configuration locally without applying changes (dry run).just test: Tests both the server and desktop configurations in-place temporarily.just test-desktop: Test desktop changes in place temporarily (reverts on reboot).just test-server: Test server changes in place temporarily (reverts on reboot).just switch: Apply the entire homelab configuration in sequence (runs network infrastructure apply, server deploy, and desktop apply).just switch-desktop: Apply changes immediately and switch the local desktop system.just switch-server: Deploy the NixOS configuration to the remote server host.just boot-desktop: Apply desktop changes and write them to the bootloader (active on next reboot).
just infra-plan-homelab: Preview declarative UniFi and Cloudflare configuration changes.just infra-apply-homelab: Deploy declarative UniFi and Cloudflare configuration changes.
just sops-user-secrets: Edit user-level secrets (secrets/user-secrets.yaml) using SOPS.just sops-host-secrets: Edit host-level secrets (secrets/host-secrets.yaml) as root using the host's AGE key.
just flake: Regenerates theflake.nixoutput mappings usingflake-fileto register new modules.just update: Performs anix flake updateto bump all input dependencies.just update-den: Updates specifically thedenframework dependency.just format: Formats all Nix source files recursively.
just vm-desktop: Launches thedesktopconfiguration in a virtual machine for local testing.just vm-server: Launches theserverconfiguration in a virtual machine.just make-iso [out]: Builds the custom installation ISO image (defaults output to/tmp/nixos-installer).just test-iso [out] [key]: Boots the generated installer ISO in QEMU to test partitioning and automated installs.
just clean: Garbage collects the Nix store using root privileges.just gc: Runsnh clean allto prune old generations and optimize storage.
- Enter the environment:
If you have
direnvenabled, entering the directory will automatically initialize the environment and install git hooks. Otherwise, run:nix develop - Apply changes:
Modify your settings, regenerate the flake configuration if you added new modules, and switch:
just flake just switch-desktop