5.7 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 — ZERO EXCEPTIONS
DO NOT RUN ANY OF THESE COMMANDS AT ANY TIME, FOR ANY REASON:
nixos-rebuild switch / test / build / dry-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
docker/podman build
Why:
- These commands take 20–40+ minutes
- They consume significant CPU/RAM on the user's machine
- They can block the user from their own work
- They can break the live system if something is wrong
- The user MUST control when and what gets built
Your job: Make correct edits to source files. The user validates and runs builds themselves.
Even if the user says "go ahead": Do NOT run these. Your role is to write good Nix, not execute it.
❌ 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 rules and hold yourself accountable to them. These are not suggestions — they are non-negotiable.
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/
When In Doubt
If you are unsure whether a command is safe, assume it is not safe and don't run it.
Instead: describe what you would do and ask the user for permission.
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
If you want to verify syntax without triggering a build, these are safe:
# Check Nix expression syntax only (fast, safe, no eval)
nix-instantiate --parse <file>.nix
But even these are optional. The user will validate by running nh os switch themselves.
Golden rule: When in doubt, don't run anything. Just describe your changes.
Commit / Branch / Git Policy
- Do NOT commit changes or create branches unless the user explicitly asks
- Do NOT
git add,git commit, orgit pushautonomously - You may run
git addonly if required for a Nix evaluation (e.g., new files must be tracked for flakes) - Describe what you changed in your final message so the user can review before committing