I manage four machines with one Git repo. A desktop, two laptops, a kid’s machine, and a headless server running Jellyfin, Frigate, and Mosquitto — all declaratively configured, all pulling from the same flake. When I set up a new machine, I clone the repo, run two commands, and it’s done. When I make a change, every host picks it up automatically.
This is what converted me to NixOS.
The Problem I Was Solving
Before NixOS I had the usual collection of dotfiles, shell scripts, and “trust me it works on my machine” configuration. Setting up a new machine meant hours of reinstalling packages, tweaking configs, and wondering why something that worked on the desktop didn’t work on the laptop. After a fresh install, it’d take weeks before the new machine felt right.
NixOS flips that. The entire system state — packages, services, user environment, secrets — is declared in code and reproduced exactly. Roll it back with a single command if something breaks. Add a machine in an afternoon.
The Machines
| Host | Hardware | Role |
|---|---|---|
gsparks-sitespect |
Intel desktop | Primary work/daily driver |
15z-eh000 |
HP Pavilion 15z (AMD) | Personal laptop |
jellyfin |
HP Elite 800 G1 | Headless server: Jellyfin, Frigate, Mosquitto, go2rtc |
lenovo-yoga-11e |
Lenovo Yoga 11e | Kids’ laptop |
Repo Layout
flake.nix / flake.lock entry point — inputs, nixosConfigurations
hosts/<name>/ per-machine config + hardware-configuration.nix
modules/
common/ applied to every host
desktop/ applied to KDE Plasma machines only
home/ home-manager (user environment), shared across hosts
overlays/ package overrides
packages/ custom packages exposed as flake outputs
secrets/ agenix-encrypted secrets
The key idea is the layering. Every host assembles its config from these layers:
hosts/<name>/— hardware config and anything genuinely specific to that machinemodules/common/— always applied (boot, locale, security baseline, core packages)modules/desktop/— only if it’s a KDE Plasma machinehome/gsparks.nix— my user environment via home-manager
A module belongs in modules/common/ only if every host should have it — including a headless Raspberry Pi or Kodi box. If it needs a GPU or a desktop environment, it goes in modules/desktop/ or stays host-local.
Machines Auto-Update from GitHub
This is in modules/common/nix.nix, applied to every host:
system.autoUpgrade = {
enable = true;
flake = "github:GSSparks/nixos-config#${config.networking.hostName}";
allowReboot = false;
};
Each machine knows its own hostname, looks itself up in the flake, and applies updates automatically. Push a change to GitHub; the machines pick it up. allowReboot = false means it won’t restart services that need a reboot — I handle those manually.
The store also self-maintains:
nix.gc = {
automatic = true;
dates = "weekly";
options = "--delete-older-than 7d";
};
nix.settings.auto-optimise-store = true;
home-manager: Your Shell as Code
home/gsparks.nix manages my entire user environment across every desktop machine — the same config shared across all three. Git identity, bash aliases, tmux, vim settings, direnv, Chromium flags — all declared, all reproducible.
A few things worth calling out:
Bash aliases declared as data, not shell script:
programs.bash.shellAliases = {
ports = "ss -tulanp";
pbcopy = "xsel --clipboard --input";
pbpaste = "xsel --clipboard --output";
gitop = "cd `git rev-parse --show-toplevel`";
mkdir = "mkdir -pv";
};
Git config that follows me everywhere:
programs.git = {
enable = true;
settings = {
user.name = "Gary Sparks";
init.defaultBranch = "main";
pull.rebase = true;
};
};
yt-dlp wrapped to fix YouTube’s PO Token requirement:
YouTube started requiring a proof-of-origin token to serve video. The fix is a plugin (bgutil-ytdlp-pot-provider) that talks to a local server on port 4416. Rather than exporting PYTHONPATH manually in every shell session, I wrap yt-dlp so it always finds the plugin:
yt-dlp-with-pot = pkgs.symlinkJoin {
name = "yt-dlp-with-pot";
paths = [ pkgs.yt-dlp ];
buildInputs = [ pkgs.makeWrapper ];
postBuild = ''
wrapProgram $out/bin/yt-dlp \
--set PYTHONPATH "${pkgs.python313Packages.bgutil-ytdlp-pot-provider}/lib/python3.13/site-packages"
'';
};
The bgutil provider container itself is declared in the system config (home-manager can’t own OCI containers):
virtualisation.oci-containers.containers.bgutil-provider = {
image = "docker.io/brainicism/bgutil-ytdlp-pot-provider:1.3.2";
ports = [ "127.0.0.1:4416:4416" ];
autoStart = true;
};
Secrets with agenix
Secrets — WireGuard keys, Frigate camera credentials, Mosquitto passwords — are encrypted with agenix and committed to the repo as .age files. This is safe because they’re encrypted to each machine’s SSH host key. Only the machine they’re meant for can decrypt them.
secrets/secrets.nix maps secrets to their recipients:
let
gsparks-sitespect = "ssh-ed25519 AAAA...";
jellyfin = "ssh-ed25519 AAAA...";
in {
"oddspedia-privatekey.age".publicKeys = [ gsparks-sitespect ];
"frigate-env.age".publicKeys = [ jellyfin ];
"mosquitto-iotdevice.age".publicKeys = [ jellyfin ];
}
To edit a secret:
cd secrets
nix run github:ryantm/agenix -- -e frigate-env.age
The private key that decrypts them (/etc/ssh/ssh_host_ed25519_key, root-only) is never committed and never needs to be — it’s regenerated per-install.
Private Config That’s Not Actually Secret
Some config isn’t secret — no key material — but still shouldn’t be in a public repo. Internal hostnames, VPN service names, subnet layout. I keep this at /home/gsparks/.nixos-private/<hostname>.nix on the machine itself, imported by absolute path:
imports = [
/home/gsparks/.nixos-private/gsparks-sitespect.nix
...
];
It’s not tracked by git at all — not even in .gitignore, since that creates a path for the content to end up committed by accident. It just lives outside the repo. Keep a copy in your password manager.
The Jellyfin Server
The jellyfin host is headless — no desktop modules at all — but it’s doing a lot:
- Jellyfin — media server
- Frigate — NVR for security cameras, using the GPU for detection
- go2rtc — RTSP stream management
- Mosquitto — MQTT broker for IoT/Home Assistant
Frigate’s state directory is hardcoded to /var/lib/frigate by its nixpkgs module. Rather than fighting that, I bind-mount it onto the big storage disk:
fileSystems."/var/lib/frigate" = {
device = "/home/jellyfin/frigate/media";
fsType = "none";
options = [ "bind" "nofail" ];
};
systemd.services.frigate.unitConfig.RequiresMountsFor = [ "/var/lib/frigate" ];
The RequiresMountsFor line ensures Frigate doesn’t start (and start writing to the root disk) before the bind mount is up.
Adding a New Machine
- Generate hardware config on the machine:
sudo nixos-generate-config --show-hardware-config > hosts/<name>/hardware-configuration.nix - Create
hosts/<name>/configuration.nix, importingmodules/common/*andmodules/desktop/*if applicable. - Add a
nixosConfigurations.<name>entry inflake.nix. - Build before switching:
nixos-rebuild build --flake .#<name> sudo nixos-rebuild switch --flake .#<name>
Everyday Commands
nixos-rebuild build --flake .#gsparks-sitespect # dry run, check it evaluates
sudo nixos-rebuild switch --flake .#gsparks-sitespect # apply
sudo nixos-rebuild switch --flake .#gsparks-sitespect --rollback # undo
The repo is on GitHub. It’s a living document — more hosts are planned, and there are always things to clean up — but the core pattern has been stable and it’s saved me a lot of pain on new machine setups.