nix-config/AGENTS.md

Agent Guide for nix-config

This document provides guidelines for AI coding agents working in this Nix configuration repository.

Repository Overview

This is a flake-based Nix configuration managing multiple hosts:

• dnsc-air (nix-darwin, macOS)
• dnsc-work (nix-darwin, macOS)
• dnsc-deck (home-manager only, Steam Deck)
• dnsc-server (NixOS)
• dnsc-vps-sm (NixOS)

Directory Structure

.
├── flake.nix              # Main flake configuration
├── Justfile               # Common build/deploy commands
├── hosts/                 # Host-specific configurations
│   ├── dnsc-air/
│   ├── dnsc-work/
│   ├── dnsc-server/
│   └── dnsc-vps-sm/
├── home/                  # Home-manager configurations
│   ├── darwin.nix
│   ├── darwin-work.nix
│   ├── linux.nix
│   ├── server.nix
│   └── deck.nix
├── modules/               # Reusable modules
│   ├── base/
│   ├── fish/
│   ├── git/
│   ├── nixvim/
│   └── [40+ other modules]
└── secrets/               # agenix encrypted secrets

Build Commands

Validation and Testing

# Check flake evaluates correctly
nix flake check

# Show flake metadata
nix flake show

# Update flake inputs
just up

# Update specific input
just upi i=home-manager

Deployment

macOS (darwin-rebuild):

# Deploy to current macOS host
just mre

# Deploy with lock file recreation
just mup

# Manual deployment
darwin-rebuild switch --flake .

NixOS (nixos-rebuild):

# Deploy NixOS configuration
just deploy

# Deploy with debug output
just debug

# Manual deployment
nixos-rebuild switch --flake .

Steam Deck (home-manager):

# Deploy to Steam Deck
just dre

# Manual deployment
nix run home-manager/master -- switch --flake .#dnsc-deck

Maintenance

# View system generation history
just history

# Clean old generations (>7 days)
just clean

# Run garbage collection
just gc

# Open Nix REPL
just repl

Code Style Guidelines

Nix Language Conventions

File Structure:

{
  config,
  inputs,
  outputs,
  lib,
  pkgs,
  ...
}:
{
  imports = [
    # List imports first
  ];

  # Configuration follows
}

Formatting:

• Use 2 spaces for indentation
• Opening braces on same line: { foo = "bar"; }
• Function parameters use named pattern matching
• Multi-line lists: one item per line with trailing semicolons
• String interpolation: "${variable}" or ''${expression}''

Naming Conventions:

• Module files: default.nix in subdirectories
• Descriptive attribute names: services.syncthing.enable
• Host configurations: dnsc-<hostname>
• Use kebab-case for file/directory names: nixos-modules
• Use camelCase for attribute names in Nix expressions

Imports:

# In flake.nix
inputs.home-manager.nixosModules.home-manager

# In configuration files
outputs.nixosModules.base
../../modules/docker
./hardware-configuration.nix

Package Management:

# System packages
environment.systemPackages = with pkgs; [
  git
  btop
  neovim
];

# Using lib.mkAfter for additions
environment.systemPackages = lib.mkAfter (
  with pkgs; [
    additional-package
  ]
);

Module Structure:

• Keep modules focused and reusable
• Place in modules/<service-name>/default.nix
• Use option declarations when creating configurable modules
• Include modules in host configs via imports = [ ]

Configuration Patterns

Home Manager Integration:

home-manager = {
  extraSpecialArgs = { inherit inputs outputs; };
  useGlobalPkgs = true;
  backupFileExtension = "backup";
  users = {
    dennis = import ../../home/darwin.nix;
  };
};

Service Configuration:

services.syncthing = {
  enable = true;
  user = "dennis";
  configDir = "/home/dennis/.config/syncthing";
  # ... additional settings
};

Secrets with agenix:

age = {
  identityPaths = [ "${config.users.users.dennis.home}/.ssh/id_ed25519" ];
  secrets."restic/password".file = ../../secrets/restic/password.age;
};

Fish Shell Functions

Function Style:

functions = {
  function_name = /* fish */ ''
    # Fish shell code here
    echo "example"
  '';
};

Inline Comments: Use /* fish */ or /* bash */ before multi-line strings to indicate language

Common Tasks

Adding a New Module

1. Create modules/<module-name>/default.nix
2. Define module structure:

   { pkgs, ... }:
   {
     # Configuration here
   }
   

3. Export in flake.nix if needed:

   nixosModules.moduleName = import ./modules/module-name;
   

4. Import in host configuration:

   imports = [ ../../modules/module-name ];
   

Adding a New Host

1. Create hosts/<hostname>/default.nix
2. Create hosts/<hostname>/hardware-configuration.nix (for NixOS)
3. Add configuration to flake.nix:

   nixosConfigurations.hostname = nixpkgs.lib.nixosSystem {
     system = "x86_64-linux";
     specialArgs = { inherit inputs outputs; };
     modules = [ ./hosts/hostname ];
   };
   

Modifying Home Manager Config

1. Edit appropriate file in home/:
   • darwin.nix for dnsc-air
   • darwin-work.nix for dnsc-work
   • server.nix for servers
2. Changes take effect on next deployment
3. Home configs import modules from modules/ directory

Important Notes

• Never commit secrets: Use agenix for sensitive data
• Test before deploying: Run nix flake check before major changes
• System state version: Don't change system.stateVersion without migration
• Flake inputs: Keep inputs up-to-date with just up
• Git ignore: .DS_Store files are ignored globally (see modules/git/default.nix)
• No traditional package.json: This is a Nix project, not a Node.js project
• Experimental features: This config uses nix-command and flakes features