dotfiles/AGENTS.md

Agent Guidelines for NixOS/nix-darwin Dotfiles

This repository contains NixOS, nix-darwin, and Home Manager configurations in Nix. You are a sysadmin managing server configurations and deployments.

Build, Test, and Deployment Commands

Build and Apply Configurations & Deploy to Remote Machines

Can use deploy for both local and remote hosts

deploy -s .#ryu      # Desktop (x86_64-linux)
deploy -s .#tako     # Server (x86_64-linux)
deploy -s .#tsuba    # Raspberry Pi (aarch64-linux)
deploy -s .#kuro     # MacBook M4 Pro (aarch64-darwin)
deploy -s .#shiro    # Mac Mini M4 (aarch64-darwin)

Linux (NixOS):

deploy -s .#ryu 
deploy -s .#tako
deploy -s .#tako --builders '' --cores 32 # with no other builders and 32 cores
deploy -s .#ryu --max-jobs 4 --cores 32 # use 32 cores and 4 parallel derivations
sudo nixos-rebuild test --fast --flake .  # Test without activation
sudo nixos-rebuild switch --rollback --flake .  # Rollback

macOS (nix-darwin):

deploy -s .#kuro
deploy -s .#shiro
sudo nix-darwin test --fast --flake .

Validation and Formatting

nix flake check --show-trace        # Check flake for errors
alejandra fmt .                     # Format all files
alejandra fmt <file>.nix            # Format single file

Directory Structure

• flake.nix - Main entry point, device definitions
• nixos/ - NixOS machine configs (ryu, tako, tsuba)
• darwin/ - macOS machine configs (kuro, shiro)
• home/ - Home Manager modules (programs/, services/, apps/)
• modules/ - Custom modules (nixos/, darwin/, home/)
• secrets/ - SOPS encrypted secrets
• overlays.nix, deploy.nix, sops.nix, stylix.nix - Config files

Code Style Guidelines

Nix Language Conventions

File Structure:

{inputs, config, pkgs, lib, device, ...}: {
  # Configuration here
}

Imports:

• Order: inputs, config, pkgs, lib, device, custom params, ...
• Use set destructuring for clarity

Formatting:

• Use alejandra formatter (run before committing)
• 2-space indentation
• Trailing commas in lists and attribute sets

Naming Conventions:

• Files: lowercase-with-hyphens (e.g., my-module.nix)
• Attributes: camelCase (e.g., enableMyFeature)
• Functions: camelCase (e.g., mkDevice)
• Constants: UPPER_SNAKE_CASE (e.g., API_KEY)
• Device names: lowercase (e.g., ryu, tako)

Let Expressions:

with lib; let
  cfg = config.programs.myProgram;
in {
  options = { ... };
  config = mkIf cfg.enable { ... };
}

Conditionals:

• Use mkIf for config options
• Use lib.optionalAttrs for attribute sets
• Use lib.optionals for lists

Module Patterns

Simple Package Module:

{pkgs, ...}: {
  home.packages = [pkgs.myPackage];
}

Program Configuration Module:

{config, pkgs, lib, ...}:
with lib; let
  cfg = config.programs.myProgram;
in {
  options.programs.myProgram = {
    enable = mkEnableOption "myProgram";
  };
  config = mkIf cfg.enable {
    home.packages = [pkgs.myProgram];
  };
}

Device-Specific Logic:

home.packages = lib.optionals device.isLinux [pkgs.linuxPackage]
  ++ lib.optionals device.isDarwin [pkgs.macPackage];

sessionVariables.BROWSER = if device.isDarwin then "open" else "xdg-open";

Important Rules

1. NEVER create markdown files unless explicitly requested
2. DO NOT add shell scripts - use Nix expressions
3. All configurations must use Nix expressions when possible
4. Follow existing naming conventions and directory structure
5. Create custom application entries in ~/.local/share/applications/{appname}.desktop

Secrets Management

• Secrets are managed with SOPS in secrets/ directory
• Encrypted secrets in secrets/ directory
• Configuration in .sops.yaml
• Access via config.sops.secrets."secret/value".path

  foo:
      bar: somesecret
  

  The path is the file that contains somesecret
• Add new secrets using sops set Example

    openssl rand -hex 32 | tr -d '\n' | jq -sR | sops set --value-stdin secrets/secrets.yaml '["foo"]["bar"]'
  

  This will add a randomly generated secret to the sops file

Common Patterns

Adding a New Program

just add program myprogram  # Creates home/programs/myprogram.nix and adds import

Adding a new dns entry

cfcli add --type A foobar.bazbar.biz 100.102.64.19

Creating a Module

1. Determine location: modules/nixos/, modules/darwin/, or modules/home/
2. Create file with proper structure
3. Add to modules/default.nix imports

Device Configuration

Devices are defined in flake.nix using mkDevice. Properties available:

• device.isLinux, device.isDarwin, device.isArm
• device.isServer, device.hasGui, device.isDesktopLinux
• device.name, device.user, device.home

Error Handling

• Use mkIf to conditionally enable configurations
• Handle both Linux and macOS cases when adding cross-platform features

Testing Changes

1. Build first: just build or nixos-rebuild build --flake .
2. Check for errors with --show-trace flag

Version Information

• Nix Version: 2.32+
• Flakes: Enabled (required)
• Formatter: alejandra
• State Version: (varies by machine & never change this)