21 KiB
Agent Context: nixos-setup
A complete reference for an AI agent to understand, navigate, and modify this NixOS homelab configuration repository.
⚠️ MANDATORY: Before doing anything in this repository, read
GUIDELINES.mdin full and follow it. It contains non-negotiable hard rules (never run builds, never editflake.lock, etc.) and requires you to present a plan and get user approval before making any changes.
Repository Purpose
A NixOS flake managing multiple machines (laptops, desktops, servers) and one OpenWrt
router for a personal homelab. Everything is declarative Nix. No imperative scripts except
the skyg CLI wrapper and the OpenWrt deploy script.
The configured user, default system architecture, and NixOS state version are all defined
in flake.nix (the lib = binding at the top of outputs). Check that file for
source-of-truth values rather than relying on any hardcoded constants here.
Repository Layout
nixos-setup/
├── flake.nix # All outputs: nixosConfigurations, homeConfigurations, packages, devShells
├── flake.lock # Locked input revisions — do not edit by hand
├── secrets.nix # agenix: maps .age files → authorized SSH public keys
├── bin/
│ ├── skyg # Bash shim: exec nu --commands "use lib/cmds.nu *; skyg $*"
│ └── lib/
│ ├── cmds.nu # All skyg subcommands (NuShell — source of truth)
│ ├── profile.nu # Profile helpers and tab-completion data
│ └── types.nu # Type definitions
├── hosts/
│ ├── <hostname>.nix # One file per managed machine
│ ├── <hostname>.hardware-configuration.nix
│ ├── iso.nix # Bootable install image
│ └── scripts/ # Host-specific helper scripts
├── modules/
│ ├── lib.nix # makeNixOs / makeIso / makeHomeManagerUsers / makeDarwinModule / eachSystem
│ ├── main.nix # Base module every host gets: core/ + nixos/ + network-drives.nix
│ ├── skyg-utils.nix # makeHyperlinkScriptToConfigs (symlinks configs/ → ~/.config/)
│ ├── macos.nix # macOS/nix-darwin module
│ ├── network-drives.nix # skyg.networkDrives — NFS auto-mounts
│ ├── core/
│ │ ├── default.nix # Imports: user.nix, macos.nix, nix-substituters.nix
│ │ ├── user.nix # skyg.user.* and skyg.home-manager.* options; wires HM
│ │ ├── nix-substituters.nix # Binary caches + remote builder config
│ │ └── macos.nix # Pipx workaround overlay; distributed build config
│ ├── home/
│ │ ├── default.nix # makeCommonUser / makeRootUser factories
│ │ ├── programs.nix # bat, neovim, direnv, eza, starship, nushell, carapace, zsh, zellij, tmux
│ │ ├── services.nix # gpg-agent with SSH support
│ │ ├── fonts.nix # Font packages
│ │ └── git.nix # makeCommonGitConfigs
│ ├── nixos/
│ │ ├── default.nix # Imports: common/ + server/ + desktop/
│ │ ├── common/
│ │ │ ├── core.nix # nix-ld, nh, appimage-run, GC cron, timezone, locale
│ │ │ ├── networking.nix # skyg.core.hostName; NetworkManager; disables nm-wait-online
│ │ │ ├── user.nix # System user creation; zsh as default shell
│ │ │ ├── ssh-server.nix # skyg.nixos.common.ssh-server.enable; key-only SSH
│ │ │ ├── qemu.nix # skyg.core.qemu.enable; QEMU + SPICE stack
│ │ │ ├── fonts.nix
│ │ │ ├── hardware/ # amdgpu, nvidia, coral-tpu-udev, fan2go, fancontrol, laptop-power, pipewire, sound
│ │ │ ├── containers/ # Docker/Podman options; local registry config; metrics port
│ │ │ └── pritunl/ # Pritunl VPN client
│ │ ├── server/
│ │ │ ├── admin.nix # skyg.server.admin.enable → www-data group
│ │ │ ├── exporters.nix # skyg.server.exporters.enable → Prometheus node exporter
│ │ │ ├── timers.nix # skyg.server.timers attrset → systemd timer+service pairs
│ │ │ ├── k3s/ # skyg.nixos.server.k3s.{enable,role,envPath}
│ │ │ ├── k8s/ # Raw Kubernetes: master.nix + node.nix
│ │ │ ├── dns/ # certbot/, routing/ (dnsmasq), local-ca/
│ │ │ ├── arrs/ # Prowlarr + DB for *arr stack
│ │ │ └── services/ # ai-services, audiobookshelf, comfyui, dockge, jellyfin, scrypted
│ │ └── desktop/
│ │ ├── default.nix # skyg.nixos.desktop.enable; PipeWire, dbus, portals, avahi
│ │ ├── wayland.nix # NIXOS_OZONE_WL=1, xwayland
│ │ ├── tiler/ # DankMaterialShell + niri + hyprland + swww
│ │ ├── stylix/ # skyg.nixos.desktop.stylix.enable
│ │ ├── gnome.nix / kde.nix / cosmic.nix
│ │ ├── crypto.nix # skyg.nixos.desktop.crypto.enable
│ │ ├── packages.nix
│ │ └── printers.nix
│ └── openwrt/
│ ├── default.nix # Builds openwrt-gen Rust binary; exports deployScript
│ └── generator/ # Rust: stdin JSON → dnsmasq.conf or ethers
├── openwrt-routers/
│ └── <router>.nix # Per-router config (IP, SSH user, configSecret path)
├── secrets/
│ └── *.age # Encrypted secrets (see secrets.nix for authorization map)
├── configs/
│ ├── niri/ # niri compositor config (symlinked to ~/.config/niri)
│ ├── hypr/ # Hyprland config
│ ├── hyprpanel/ # HyprPanel config
│ └── extra.nu # Extra NuShell config
└── docs/ # Documentation (hosts, modules, secrets, DNS, OpenWrt)
For the full host list and per-machine details, see docs/hosts/README.md.
skyg CLI Reference
skyg is implemented in bin/lib/cmds.nu. All commands cd to $REPO_ROOT first.
The bin/skyg file is a thin bash shim — the NuShell file is the source of truth.
System Deployment
# Local system (whichever host the repo is checked out on)
skyg os switch
skyg os test
skyg os switch --build-host <builder> # offload compilation to a remote builder
# Remote system
skyg remote switch <hostname> # deploys to root@<hostname>.<domain>
skyg remote test <hostname> # test without activating
skyg remote switch <hostname> --build-host <builder>
# Rollback
skyg rollback # sudo nixos-rebuild switch --rollback
# Validate flake without building
skyg check # nix flake check --no-build
skyg remote maps <hostname> → NixOS profile hl-<hostname> → SSH target
root@<hostname>.<domain>. See bin/lib/profile.nu for the full list of valid targets.
Home Manager
skyg hm switch # apply for the default profile
skyg hm build # build only
skyg hm switch <profile> # explicit profile name
Flake Updates
skyg update # nix flake update (all inputs) + shows flake.lock diff
skyg update <input> # update a single input, e.g. skyg update nixpkgs
OpenWrt
skyg openwrt # decrypt router secret, pipe to deploy script
skyg openwrt <router> # explicit router name (matches openwrt-routers/<router>.nix)
Deploy flow: age-decrypts the router's JSON secret → generates dnsmasq.conf + ethers
via the Rust binary → shows colored diffs → prompts for confirmation × 2 → SSHes to the
router → validates with dnsmasq --test → restarts dnsmasq (auto-reverts on failure).
ISO
skyg build-iso # nix build .#nixosConfigurations.iso.config.system.build.isoImage
Secrets
skyg secrets # list known secret names
skyg decrypt <name> # decrypt → .tmp/unencrypted-<name>
skyg encrypt <name> [source] # re-encrypt ← .tmp/unencrypted-<name>
skyg compare-secret <name> # diff .tmp/unencrypted-<name> vs the .age file
Profiles
skyg profiles # list all configured profiles
skyg profiles true # list remote-only profiles (hl-* prefixed)
Flake Outputs
nixosConfigurations = {
# One entry per host — names match hosts/<name>.nix
# See flake.nix for the full list and hardware modules used
<hostname> = lib.makeNixOs { ... };
iso = lib.makeIso { ... };
}
homeConfigurations = {
# Standalone home-manager (non-NixOS use)
# Profile name defined in flake.nix
<profile> = lib.makeHomeManagerUsers { ... };
}
packages.<system> = {
# One deploy script per router, named openwrt-<router>
openwrt-<router> = (openwrt (import ./openwrt-routers/<router>.nix)).deployScript;
}
devShells.<system>.default # nix develop shell
formatter.<system> # nixpkgs-fmt
lib.nix API
lib.makeNixOs {
hostName; # required — sets networking.hostName
system ? "x86_64-linux";
systemStateVersion ? "26.05";
configuration ? []; # extra modules/files appended after main.nix
}
# Automatically includes: determinate, stylix, home-manager, nix-flatpak,
# agenix, dms (DankMaterialShell), nix-index-database, hermes-agent NixOS modules.
lib.makeIso { hostName; ... } # same as makeNixOs + installation-cd-minimal.nix
lib.makeHomeManagerUsers {
modules ? [];
userConfig ? user; # defaults to the user attrset defined in flake.nix
system ? "x86_64-linux";
}
lib.makeDarwinModule {
hostName; user;
system ? "x86_64-darwin";
configuration ? [];
}
lib.eachSystem (system: ...) # genAttrs over all systems from nix-systems/default
specialArgs injected into every host module: unstablePkgs, skygUtils, user,
system, hyprlauncher, dms, noctalia, nix-index-database, hermes-agent.
skyg.* Option Namespace
All custom NixOS options. Set these in host files (hosts/<name>.nix).
skyg.user
.name string username
.fullName string
.email string
.enable bool enable home-manager config for this user
.createSystemUser bool create the Linux user account (default: true)
.extraGitConfigs list [{path = "..."}] extra git config includes
skyg.home-manager
.version string HM stateVersion (default: "26.05")
.extraImports list extra HM modules to import
skyg.core
.hostName string REQUIRED — sets networking.hostName
.qemu.enable bool QEMU + quickemu + SPICE stack
.substituters.urls list extra Nix binary cache URLs
.substituters.keys list extra Nix binary cache trusted public keys
skyg.nixos.desktop
.enable bool PipeWire, dbus, libinput, avahi, XDG portals, user groups
.tiler.enable bool DankMaterialShell, gnome-keyring, polkit, wayland tools
.tiler.niri.enable bool niri compositor; symlinks configs/niri → ~/.config/niri
.tiler.hyprland.enable bool Hyprland compositor
.stylix.enable bool Stylix theming
.crypto.enable bool crypto/wallet tools
skyg.nixos.common
.ssh-server.enable bool OpenSSH, key-only auth, a master pubkey pre-authorized
.hardware
.sound.enable bool
.pipewire.enable bool
.amdgpu.enable bool
.nvidia.enable bool
.laptop-power-mgr.* attrset TLP/power management; lid switch config
.udevrules.coraltpu.enable bool
.containers
.runtime string "docker" (default) | "podman"
.openMetricsPort bool opens the container metrics port
skyg.nixos.server
.k3s
.enable bool
.role string "server" (default) | "agent"
.envPath string path to env file with K3s tokens/config
.services
.ai.enable bool Ollama+openwakeword containers + Wyoming whisper/piper
.audiobookshelf.* attrset {enable, host, port, openFirewall, configDir, metadataDir}
.comfyui.* attrset {enable, mode ("rocm"|"cuda"), port, rocm.dataDir}
.dockge.* attrset {enable, openFirewall, port, volumes.stacks/data.{nfsServer,share}}
.jellyfin.enable bool NFS-backed storage
.scrypted.enable bool
skyg.server
.admin.enable bool creates www-data group (gid=33) with user as member
.exporters.enable bool Prometheus node exporter
.timers attrset {<name> = {script, OnCalendar, wantedBy}} → systemd timer+service
.dns
.routing.enable bool
.routing.openFirewall bool
.routing.addressesSecretName string agenix secret name for dnsmasq address= lines
.certbot.enable bool
.certbot.email string
.certbot.publicDomains list
skyg.networkDrives
.enable bool
.tnas1.{enable, host} NAS host (default defined in network-drives.nix)
.terra1.{enable, host} storage server host
.bigBox2.{enable, host} storage server host
.options list NFS mount options (default: x-systemd.automount, auto, nofail, _netdev)
The NFS mount points provided by skyg.networkDrives are defined in modules/network-drives.nix.
Hosts
See docs/hosts/README.md for the full per-host reference (hardware, role, services, ports).
The flake.nix nixosConfigurations block is the canonical list of managed systems.
Each host's source file is hosts/<hostname>.nix paired with
hosts/<hostname>.hardware-configuration.nix.
Secrets Management
Uses agenix. All .age files in secrets/ are
committed to the repo. secrets.nix maps each file to the SSH public keys authorized to
decrypt it — check that file for the current authorization matrix and secret list.
Using a secret in a module
age.secrets.my-secret = {
file = ../../secrets/my-secret.age;
};
# Reference the runtime-decrypted path (e.g. /run/agenix/my-secret).
# Never hardcode a path to the .age file itself in service config.
someOption = config.age.secrets.my-secret.path;
Managing secrets
# Create or edit
agenix -e secrets/my-secret.age
# After adding a new host key to secrets.nix, re-encrypt everything:
agenix -r -i ~/.ssh/id_ed25519
# skyg wrappers
skyg secrets # list known secret names
skyg decrypt <name> # → .tmp/unencrypted-<name>
skyg encrypt <name> # ← .tmp/unencrypted-<name>
skyg compare-secret <name> # diff plaintext vs encrypted
.tmp/ is gitignored. Never commit unencrypted secrets.
Adding a secret for a new host
ssh root@<host> "cat /etc/ssh/ssh_host_ed25519_key.pub"
# Add the key to secrets.nix, then:
agenix -r -i ~/.ssh/id_ed25519
Binary Caches
Configured in modules/core/nix-substituters.nix and applied to all hosts. Includes a
local nix-serve instance on the lab network for fast rebuilds, plus several public caches.
See that file for the current URLs and trusted public keys.
Dev Shell
nix develop # or: direnv allow (if .envrc is present)
Provides: nixpkgs-fmt, nixd, nh, agenix, age, home-manager, rustc, cargo,
rust-analyzer, nushell
- Adds
bin/toPATH→skygis available immediately - Sets
SKYG_LIBenv var for NuShell - Enforces
nixpkgs-fmtas a pre-commit hook on all.nixfiles - Auto-launches NuShell with
cmds.nuimported when running interactively
Coding Conventions
- Formatter:
nixpkgs-fmt— enforced by pre-commit. Run before committing. - Options: Use
lib.mkEnableOptionfor booleans,lib.mkOptionwithtypeanddescriptionfor everything else. - Conditional config:
config = lib.mkIf cfg.enable { ... }pattern throughout. - Defaults: Use
lib.mkDefaultinmain.nixso host configs can override cleanly. - Unfree:
nixpkgs.config.allowUnfree = trueis set globally — no need to repeat per-host. - Secrets: Never hardcode sensitive values. Use agenix. Reference
config.age.secrets.<name>.pathat runtime. specialArgs:unstablePkgs,skygUtils,user,systemare always available in every module — no need to pass them explicitly.- Nix features:
nix-commandandflakesexperimental features are enabled everywhere. nh: Preferred over rawnixos-rebuild. Used by bothskyg osandskyg remote.
Common Patterns
Minimal server host
# hosts/<name>.nix
{ ... }: {
skyg.user.enable = true;
skyg.nixos.common.ssh-server.enable = true;
skyg.server.exporters.enable = true;
skyg.networkDrives.enable = true;
boot.loader.systemd-boot.enable = true;
boot.loader.efi.canTouchEfiVariables = true;
services.fwupd.enable = true;
}
Declarative systemd timer
skyg.server.timers.my-backup = {
OnCalendar = "daily";
wantedBy = [ "some-mount.mount" ];
script = ''
set -eu
${pkgs.rsync}/bin/rsync -av /src /dest
'';
};
Enable K3s
skyg.nixos.server.k3s = {
enable = true;
role = "agent";
envPath = "/opt/k3s/k3s.env"; # file contains K3S_URL and K3S_TOKEN
};
Use an agenix secret in a service
age.secrets.my-api-key.file = ../../secrets/my-api-key.age;
services.myapp.apiKeyFile = config.age.secrets.my-api-key.path;
NFS-backed Dockge
skyg.nixos.server.services.dockge = {
enable = true;
openFirewall = true;
volumes.stacks = { nfsServer = "<nfs-host>"; share = "/path/to/stacks"; };
volumes.data = { nfsServer = "<nfs-host>"; share = "/path/to/data"; };
};
Desktop with tiling WM
skyg.nixos.desktop = {
enable = true;
tiler.enable = true;
tiler.niri.enable = true; # or hyprland.enable = true
stylix.enable = true;
};
Adding a New Host — Checklist
-
Create host files:
hosts/<name>.nix hosts/<name>.hardware-configuration.nix # from nixos-generate-config -
Register in
flake.nixundernixosConfigurations:<name> = lib.makeNixOs { hostName = "<name>"; configuration = [ ./hosts/<name>.nix ./hosts/<name>.hardware-configuration.nix ]; }; -
Add SSH host key to
secrets.nixif the host needs any secrets:ssh root@<host> "cat /etc/ssh/ssh_host_ed25519_key.pub" # Add the key to secrets.nix, then re-encrypt: agenix -r -i ~/.ssh/id_ed25519 -
Deploy:
skyg remote switch <name>
Adding a New Service Module — Checklist
-
Create
modules/nixos/server/services/<name>.nix:{ config, lib, pkgs, ... }: let cfg = config.skyg.nixos.server.services.<name>; in { options.skyg.nixos.server.services.<name> = { enable = lib.mkEnableOption "Enable <Name>"; # add typed options here }; config = lib.mkIf cfg.enable { # NixOS configuration goes here }; } -
Import in
modules/nixos/server/services/default.nix:imports = [ ... ./<name>.nix ]; -
Enable on relevant hosts:
skyg.nixos.server.services.<name>.enable = true;
Key File Locations
| What | Path |
|---|---|
| Host registrations (canonical list) | flake.nix → nixosConfigurations |
| Secret authorization map | secrets.nix |
| User / global config (name, email, etc.) | flake.nix → lib = binding |
| Base module every host receives | modules/main.nix |
| Home Manager programs | modules/home/programs.nix |
| Binary cache configuration | modules/core/nix-substituters.nix |
| SSH master public key | modules/nixos/common/ssh-server.nix |
All skyg subcommand implementations |
bin/lib/cmds.nu |
| Valid remote deployment targets | bin/lib/profile.nu |
| Router configs | openwrt-routers/ |
| Desktop compositor configs | configs/ |
| Full host documentation | docs/hosts/README.md |
| Module architecture + option reference | docs/modules/README.md |
| Secrets workflow | docs/secrets/README.md |