5.0 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.
❌ NEVER modify GUIDELINES.md unless explicitly requested by the user, you must live and die by these and hold yourself accountable to them!
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/ ABOUTME.mdshould be seen as the 'living memory' of a folder, it should contain general information about what's in the folder and capture decisions made at the time of development the features.- 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