4.8 KiB
Agent Guidelines — nixos-setup
Rules and best practices for any AI agent working in this repository. Read this file before making any changes.
Hard Rules — Never Break These
❌ NEVER run builds or system switches
Do NOT run any of the following, ever:
nixos-rebuild switch / test / build
nh os switch / test / build
skyg os switch / test / build
skyg remote switch / test / build
skyg hm switch / build
nix build
nix flake check
These commands take 20–40+ minutes, consume significant CPU/RAM, and can break a live system. The user runs these themselves after reviewing changes. Your job is to make correct edits to the source files — not to apply them.
❌ NEVER edit flake.lock by hand
This file is managed exclusively by nix flake update. Editing it manually will corrupt
the lock file and break all builds.
❌ NEVER edit *.hardware-configuration.nix files
These are generated by nixos-generate-config and reflect the physical hardware. Edits
will be overwritten on the next hardware scan and can render a system unbootable.
❌ NEVER touch secrets
Do not read, write, or delete files in secrets/. Encrypted .age files must only be
managed with agenix via the skyg secrets commands. Do not modify secrets.nix unless
the user explicitly asks and explains the full context.
❌ NEVER add imports = [...] to host files
Host files (hosts/<hostname>.nix) do not use imports. All modules are composed through
the makeNixOs call in flake.nix via modules/main.nix. Adding imports to a host file
breaks the composition model.
Safe Operations
These are always safe to perform without asking:
- Reading any
.nix,.md, or config file - Editing host files (
hosts/<hostname>.nix) to add/remove packages or options - Editing module files in
modules/ - Creating or updating documentation in
docs/orABOUTME.md/GUIDELINES.md - Adding new packages to
pkgs/ - Editing configs in
configs/
NixOS Conventions in This Repo
Option Namespace
All custom options live under skyg.*. Never introduce options under any other top-level
namespace. Check modules/lib.nix for the full skyg.* structure.
# Correct
skyg.nixos.desktop.enable = true;
skyg.nixos.server.services.comfyui.enable = true;
# Wrong — do not invent new top-level attrs
myOptions.desktop.enable = true;
Enable/Disable Pattern
All modules follow lib.mkIf cfg.enable { ... }. Always gate config behind an enable
option. Default should be false unless the feature is universally required.
Host Files vs Shared Modules
- Host-specific (one machine only): goes in
hosts/<hostname>.nix - Shared (multiple hosts): goes in the appropriate
modules/nixos/ormodules/core/submodule - When in doubt, keep it in the host file and extract later if reuse emerges
Package Placement
- Packages needed on all desktops →
modules/nixos/desktop/packages.nix - Packages for one host only →
environment.systemPackagesin the host file - Custom/third-party packages not in nixpkgs →
pkgs/<name>/default.nixwith an overlay inmodules/core/default.nix
Home Manager
Home Manager config lives inside home-manager.users.<name> blocks. Do not mix
system-level and HM-level options. The HM entry point is modules/home/default.nix.
Greeter
Both desktop hosts (fwbook, hl-fwdesk) use DankMaterialShell greeter via:
programs.dank-material-shell.greeter = {
enable = true;
compositor.name = "niri";
configHome = "/home/<username>";
};
Do not configure services.greetd manually on these hosts — the DMS module handles it.
Navigation Tips
| Question | Where to look |
|---|---|
| What hosts exist? | hosts/ + docs/hosts/README.md |
What does a skyg.* option do? |
modules/ — find the defining .nix file |
| What flake inputs are available? | Top of flake.nix |
| What binary caches are configured? | modules/core/nix-substituters.nix |
| What secrets exist? | secrets.nix (lists files + authorized keys) |
| What custom packages exist? | pkgs/ |
| Full API reference | docs/modules/README.md |
| Host details (ports, services, hardware) | docs/hosts/README.md |
Validation Without Building
After making changes you can verify syntax without running a build:
# Check Nix expression syntax only (fast, safe)
nix-instantiate --parse <file>.nix
# Check the flake structure without building
nix flake show --no-build 2>/dev/null
Even these are optional — the user will validate by running nh os switch themselves.
Commit / Branch Policy
- Do NOT commit changes or create branches unless the user explicitly asks
- Do NOT
git add,git commit, orgit pushautonomously - Describe what you changed in your final message so the user can review before committing