My literate configurations with Org and Nix

3.1.1.1.1. nixpkgs#

nixpkgs.url = "git+https://github.com/nixos/nixpkgs?shallow=1&ref=nixos-unstable-small";

3.1.1.1.2. nixpkgs-stable#

nixpkgs-stable.url = "git+https://github.com/nixos/nixpkgs?shallow=1&ref=nixos-26.05";

3.1.1.1.3. nixpkgs-cuda#

nixpkgs-cuda.url = "git+https://github.com/nixos-cuda/nixpkgs?shallow=1&ref=nixos-unstable-cuda";

3.1.1.2.1. flake-parts#

flake-parts = {
  url = "github:hercules-ci/flake-parts";
  inputs.nixpkgs-lib.follows = "nixpkgs";
};

3.1.1.3.1. flake-utils#

flake-utils.url = "github:numtide/flake-utils";

3.1.1.4.1. darwin#

darwin = {
  url = "github:nix-darwin/nix-darwin";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.4.2. home-manager#

home-manager = {
  url = "github:nix-community/home-manager";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.4.3. nixos-wsl#

nixos-wsl = {
  url = "github:nix-community/nixos-wsl";
  inputs.flake-compat.follows = "";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.4.4. nix-on-droid#

nix-on-droid = {
  url = "github:nix-community/nix-on-droid";
  inputs.home-manager.follows = "home-manager";
  inputs.nix-formatter-pack.follows = "";
  inputs.nixpkgs-docs.follows = "nixpkgs";
  inputs.nixpkgs-for-bootstrap.follows = "nixpkgs";
  inputs.nixpkgs.follows = "nixpkgs";
  inputs.nmd.follows = "";
};

3.1.1.4.5. disko#

disko = {
  url = "github:nix-community/disko";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.4.6. impermanence#

impermanence.url = "github:nix-community/impermanence";

3.1.1.4.7. lanzaboote#

lanzaboote = {
  url = "github:nix-community/lanzaboote";
  inputs.nixpkgs.follows = "nixpkgs";
  inputs.pre-commit.follows = "git-hooks";
};

3.1.1.4.8. nixos-facter-modules#

nixos-facter-modules.url = "github:numtide/nixos-facter-modules";

3.1.1.5.1. comin#

comin = {
  url = "github:nlewo/comin";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.5.2. microvm#

microvm = {
  url = "github:astro/microvm.nix";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.5.3. sops-nix#

sops-nix = {
  url = "github:Mic92/sops-nix";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.5.4. tsnsrv#

tsnsrv = {
  url = "github:boinkor-net/tsnsrv";
  inputs.flake-parts.follows = "flake-parts";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.5.5. niks3#

niks3 = {
  url = "github:Mic92/niks3";
  inputs.nixpkgs.follows = "nixpkgs";
  inputs.treefmt-nix.follows = "treefmt-nix";
};

3.1.1.6.1. git-hooks#

git-hooks = {
  url = "github:cachix/git-hooks.nix";
  inputs.flake-compat.follows = "";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.6.2. treefmt-nix#

treefmt-nix = {
  url = "github:numtide/treefmt-nix";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.7.1. nix-colors#

nix-colors = {
  url = "github:misterio77/nix-colors";
  inputs.nixpkgs-lib.follows = "nixpkgs";
};

3.1.1.7.2. nix-wallpaper#

nix-wallpaper = {
  url = "github:natsukium/nix-wallpaper/custom-logo";
  inputs.flake-utils.follows = "flake-utils";
  inputs.nixpkgs.follows = "nixpkgs";
  inputs.pre-commit-hooks.follows = "git-hooks";
};

3.1.1.8.1. brew-nix#

brew-api = {
  url = "github:BatteredBunny/brew-api";
  flake = false;
};
brew-nix = {
  url = "github:BatteredBunny/brew-nix";
  inputs.brew-api.follows = "brew-api";
  inputs.nix-darwin.follows = "darwin";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.8.2. edgepkgs#

edgepkgs = {
  url = "github:natsukium/edgepkgs";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.8.3. emacs-overlay#

emacs-overlay = {
  url = "github:nix-community/emacs-overlay";
  inputs.nixpkgs-stable.follows = "nixpkgs-stable";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.8.4. felis#

felis = {
  url = "git+https://git.natsukium.com/natsukium/felis";
  inputs.nixpkgs.follows = "nixpkgs";
  inputs.flake-parts.follows = "flake-parts";
  inputs.treefmt-nix.follows = "treefmt-nix";
  inputs.git-hooks.follows = "git-hooks";
};

3.1.1.8.5. firefox-addons#

firefox-addons = {
  url = "gitlab:rycee/nur-expressions?dir=pkgs/firefox-addons";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.8.6. hermes-agent#

hermes-agent = {
  url = "github:natsukium/hermes-agent/fix/nix-read-only-eval";
  inputs.flake-parts.follows = "flake-parts";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.8.7. mcp-servers#

mcp-servers = {
  url = "github:natsukium/mcp-servers-nix";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.8.8. org-clickup#

org-clickup = {
  url = "git+https://git.natsukium.com/natsukium/org-clickup";
  flake = false;
};

3.1.1.8.9. nur-packages#

nur-packages = {
  url = "github:natsukium/nur-packages";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.8.10. paneru#

paneru = {
  url = "github:karinushka/paneru";
  inputs.flake-parts.follows = "flake-parts";
  inputs.nixpkgs.follows = "nixpkgs";
  inputs.nix-darwin.follows = "darwin";
};

3.1.1.8.11. simple-wol-manager#

simple-wol-manager = {
  url = "git+https://git.natsukium.com/natsukium/simple-wol-manager";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.8.12. spoor#

spoor = {
  url = "git+https://git.natsukium.com/natsukium/spoor";
  inputs.nixpkgs.follows = "nixpkgs";
  inputs.flake-parts.follows = "flake-parts";
};

3.1.1.8.13. vicinae#

vicinae = {
  url = "github:vicinaehq/vicinae";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.8.14. zen-browser#

zen-browser = {
  url = "github:0xc000022070/zen-browser-flake";
  inputs.nixpkgs.follows = "nixpkgs";
  inputs.home-manager.follows = "home-manager";
};

3.1.2.1.1. cache.nixos-cuda.org#

3.1.2.1.2. natsukium.cachix.org#

3.1.3.5.1. Setup#

1. Installing WSL
   

   --no-distribution avoids installing the default Ubuntu distribution, which would just be removed after importing NixOS.

   powershell

   wsl --install --no-distribution
   

2. Importing NixOS-WSL
   

   Download the latest NixOS-WSL release image and import it.

   powershell

   Invoke-RestMethod -Uri https://api.github.com/repos/nix-community/nixos-wsl/releases/latest `
     | Select-Object -ExpandProperty assets `
     | Where-Object { $_.name -eq "nixos.wsl" } `
     | ForEach-Object { Invoke-WebRequest -Uri $_.browser_download_url -OutFile $_.name }
   

   powershell

   ./nixos.wsl
   

3. Applying the configuration
   

   After the initial NixOS-WSL boot, apply this flake's configuration directly from GitHub. No local clone is needed for the first run.

   powershell

   wsl -d NixOS
   

   bash

   sudo nixos-rebuild switch --flake github:natsukium/dotfiles#arusha
   

4. Windows-side CLI tools
   

   Windows 24H2 includes a built-in sudo command, so winget can be elevated inline without a separate UAC prompt.

3.2.1.3.1. Python313 package set#

python313 = prev.python313.override {
  packageOverrides = pyfinal: pyprev: {
    <<rapidocr-onnxruntime>>
    <<lxml-html-clean>>
  };
};

1. rapidocr-onnxruntime
   

   The test suite causes a segmentation fault during execution. The root cause is still under investigation.

   This package is pulled in as a transitive dependency. Runtime functionality has been verified to work correctly in actual use, so disabling the test suite is a safe workaround.

   <<rapidocr-onnxruntime>>

   rapidocr-onnxruntime = pyprev.rapidocr-onnxruntime.overridePythonAttrs (_: {
     doCheck = false;
   });
   

2. lxml-html-clean
   

   Tests fail due to breaking changes in libxml2 2.14, which modified how certain DOM operations handle whitespace and entity encoding. These changes cause test assertions to fail even though the actual HTML cleaning functionality works correctly.

   Tracked upstream in fedora-python/lxml_html_clean#24. Remove this override once the test suite is updated for libxml2 2.14 compatibility.

   <<lxml-html-clean>>

   lxml-html-clean = pyprev.lxml-html-clean.overridePythonAttrs (_: {
     doCheck = false;
   });
   

3.2.1.3.2. Handy#

handy = prev.handy.overrideAttrs (oldAttrs: {
  patches = (oldAttrs.patches or [ ]) ++ [ ./handy-retry-without-reasoning.patch ];
});

3.2.1.5.1. gh-dash#

gh-dash =
  (final.writeShellApplication {
    name = "gh-dash";
    text = ''
      LANG=C.UTF-8 ${final.lib.getExe prev.gh-dash} "$@"
    '';
  }).overrideAttrs
    { pname = "gh-dash"; };

3.2.1.5.2. mkShim#

inherit (final.callPackage ../pkgs/mkShim { }) mkShim commandLineToolsShim;

3.3.2.1.1. Options#

options.my.nix = {
  enable = lib.mkEnableOption "Nix configuration";

  enableFlakes = lib.mkOption {
    default = true;
    example = false;
    description = "Whether to enable flakes.";
    type = lib.types.bool;
  };
};

3.3.2.1.2. Configuration#

config = lib.mkIf cfg.enable (
  lib.mkMerge [
    <<nix-flakes>>
    {
      <<nix-store-optimisation>>

      <<nix-warn-dirty>>

      <<nix-substituters>>

      <<nix-sandbox>>

      <<nix-trusted-users>>

      <<nix-gc>>

      <<nix-extra-options>>
    }
  ]
);

1. Flakes
   

   Flakes are the de facto standard for Nix project management and are used throughout this repository.

   Channels are disabled because they introduce mutable state (/nix/var/nix/profiles/per-user/*/channels) that is difficult to reproduce across machines. However, this does not break legacy commands like nix-shell — NixOS and nix-darwin automatically set NIX_PATH from the flake's inputs by default (see nixpkgs.flake.setNixPath), so <nixpkgs> lookups continue to work on all machines managed by this dotfiles repository.

   <<nix-flakes>>

   (lib.mkIf cfg.enableFlakes {
     nix = {
       settings.experimental-features = [
         "flakes"
         "nix-command"
       ];
       channel.enable = false;
     };
   })
   

2. Store Optimisation
   

   Two complementary deduplication mechanisms are enabled:

   • nix.optimise.automatic periodically runs nix-store --optimise to hard-link identical files already in the store.
   • nix.settings.auto-optimise-store deduplicates at build time as new paths are added.

   auto-optimise-store is Linux-only because enabling it on macOS corrupts the store — the build fails with error: cannot link '/nix/store/.tmp-link' to '/nix/store/.links/...': File exists. See NixOS/nix#7273.

   <<nix-store-optimisation>>

   nix.optimise.automatic = true;
   nix.settings.auto-optimise-store = pkgs.stdenv.hostPlatform.isLinux;
   

3. Garbage Collection
   

   Periodically runs nix-collect-garbage to reclaim disk space. Generations older than 7 days are deleted automatically — keeping old builds beyond that provides little value since they can always be rebuilt from the flake lock file.

   <<nix-gc>>

   nix.gc = {
     automatic = true;
     options = "--delete-older-than 7d";
   };
   

4. Dirty Warning
   

   Suppress the "Git tree is dirty" warning during flake evaluation. This warning fires on every build when there are uncommitted changes, which is the normal state during development.

   <<nix-warn-dirty>>

   nix.settings.warn-dirty = false;
   

5. Binary Caches
   

   I configure three binary caches. nix-cache.natsukium.com is my self-hosted niks3 cache (on manyara, backed by Cloudflare R2); CI pushes this dotfiles repository's pre-built artifacts to it. natsukium is my Cachix cache, which my other repositories still push to — only dotfiles has moved to niks3, so for now niks3 is dotfiles-only and Cachix covers everything else, though I may broaden niks3's scope later. nixos-cuda covers CUDA packages, which kilimanjaro needs because it builds with cudaSupport; without it, every bump to a package in that closure turns into a local rebuild. These builds came from nix-community until November 2025, when the CUDA team moved to its own Hydra.

   <<nix-substituters>>

   nix.settings = {
     substituters = [
       "https://nix-cache.natsukium.com"
       "https://natsukium.cachix.org"
       "https://cache.nixos-cuda.org"
     ];
   
     trusted-public-keys = [
       "niks3-1:SoIFTPtiPoCW3/OzUkIBKlLG5znMZfbihlr11XAOles="
       "natsukium.cachix.org-1:STD7ru7/5+KJX21m2yuDlgV6PnZP/v5VZWAJ8DZdMlI="
       "cache.nixos-cuda.org:74DUi4Ye579gUqzH4ziL9IyiJBlDpMRn9MBN8oNan9M="
     ];
   };
   

6. Sandbox
   

   The sandbox is set to "relaxed" on Darwin to avoid unexpected build failures. With sandbox = true, some packages fail to build on macOS due to sandbox restrictions — likely related to localhost networking required by test suites that start local servers, though the exact mechanism is not fully understood. Nixpkgs provides __darwinAllowLocalNetworking to allow localhost access within the sandbox, which may address the same class of issues. "relaxed" keeps normal derivations sandboxed while allowing derivations with __noChroot = true to bypass the sandbox, preventing these failures.

   <<nix-sandbox>>

   nix.settings.sandbox = if pkgs.stdenv.hostPlatform.isDarwin then "relaxed" else true;
   

7. Trusted Users
   

   On macOS, administrative users belong to the admin group, not wheel (which only contains root). Without @admin, the primary user would not be trusted by the Nix daemon on Darwin.

   <<nix-trusted-users>>

   nix.settings.trusted-users = [
     "root"
     "@wheel"
   ]
   ++ lib.optional pkgs.stdenv.hostPlatform.isDarwin "@admin";
   

8. Extra Options
   

   Terminates builds that produce no output for 3600 seconds (1 hour). Some heavy builds (e.g., Chromium, kernel compilation, CUDA-based deep learning libraries) can be silent for extended periods, so the timeout is set generously to avoid false positives while still catching genuinely hung builds.

   <<nix-extra-options>>

   nix.extraOptions = ''
     max-silent-time = 3600
   '';
   

3.3.2.3.1. Protocol#

3.3.2.3.2. Options#

options.my.nix.distributedBuilds = {
  enable = lib.mkEnableOption "distributed builds";

  connectTimeout = lib.mkOption {
    type = lib.types.ints.positive;
    default = 5;
    description = "SSH ConnectTimeout in seconds for reaching build machines.";
  };

  machines = lib.mkOption {
    type = lib.types.attrsOf (
      lib.types.submodule {
        options = {
          publicKey = lib.mkOption { type = lib.types.str; };
          systems = lib.mkOption { type = lib.types.listOf lib.types.str; };
          maxJobs = lib.mkOption { type = lib.types.ints.positive; };
          supportedFeatures = lib.mkOption {
            type = lib.types.listOf lib.types.str;
            default = [ ];
          };
          excludeHosts = lib.mkOption {
            type = lib.types.listOf lib.types.str;
            default = [ ];
          };
        };
      }
    );
    description = "Build machines the fleet can offload to.";
    default = {
      tarangire = {
        publicKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEJJYgE/dmYLXYBrVnPicd0qsaUeqcBtXB8H9LHkJ2j4";
        systems = [
          "x86_64-linux"
          "i686-linux"
        ];
        maxJobs = tarangire.config.nix.settings.max-jobs;
        supportedFeatures = tarangire.config.nix.settings.system-features;
      };
      kilimanjaro = {
        publicKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILhpfAalh6A5xDSE+HOdNE29ZgIjlP7tdlhHs82boSwp";
        systems = [
          "x86_64-linux"
          "i686-linux"
        ];
        maxJobs = kilimanjaro.config.nix.settings.max-jobs;
        supportedFeatures = kilimanjaro.config.nix.settings.system-features;
      };
      serengeti = {
        publicKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDWwhfhDSZ+M2XDwP2MlC/zFfVpk3WjUxV/JWFgGzgNW";
        systems = [ "aarch64-linux" ];
        maxJobs = serengeti.config.nix.settings.max-jobs;
        supportedFeatures = serengeti.config.nix.settings.system-features;
      };
      mikumi = {
        publicKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPfWOWKBFuDV08g6xP9MMY78CERI02CNG+5dy8CXQmXs";
        systems = [
          "aarch64-darwin"
          "x86_64-darwin"
        ];
        maxJobs = mikumi.config.nix.settings.max-jobs;
        supportedFeatures = [
          "apple-virt"
          "benchmark"
          "big-parallel"
          "nixos-test"
        ];
        excludeHosts = [ "work" ];
      };
    };
  };
};

3.3.2.3.3. Configuration#

config = lib.mkIf cfg.enable {
  nix = {
    distributedBuilds = true;

    extraOptions = ''
      builders-use-substitutes = true
    '';

    buildMachines = lib.pipe cfg.machines [
      (lib.filterAttrs (
        name: machine:
        name != config.networking.hostName && !(lib.elem config.networking.hostName machine.excludeHosts)
      ))
      (lib.mapAttrsToList (
        hostName: machine: {
          inherit hostName protocol;
          inherit (machine) systems maxJobs supportedFeatures;
          sshUser = "natsukium";
          speedFactor = 1;
          mandatoryFeatures = [ ];
        }
      ))
    ];
  };

  programs.ssh.knownHosts = lib.mapAttrs (_: machine: { inherit (machine) publicKey; }) cfg.machines;

  programs.ssh.extraConfig = ''
    Host ${lib.concatStringsSep " " (lib.attrNames cfg.machines)}
      ConnectTimeout ${toString cfg.connectTimeout}
  '';
};

3.3.3.1.1. Options#

options.my.services.tailscale = {
  enable = lib.mkEnableOption "Tailscale VPN";

  <<configureResolver-option>>
};

1. configureResolver
   

   Desktop systems may experience DNS resolution failures after suspend/resume. When the system resumes, external domain resolution (e.g., github.com) fails while Tailnet hostnames continue to work. This is a known issue with Tailscale's DNS state management during network transitions.

   Enabling configureResolver activates systemd-resolved, which helps mitigate DNS resolution issues after suspend/resume. While this doesn't completely eliminate the issue (the upstream bug remains open), it provides the most reliable MagicDNS experience.

   For headless servers, this option is typically unnecessary because servers don't suspend, and thus never encounter this resume-related DNS bug.

   See tailscale/tailscale#4254 for the upstream discussion.

   <<configureResolver-option>>

   configureResolver = lib.mkOption {
     type = lib.types.bool;
     default = false;
     description = ''
       Enable systemd-resolved for Tailscale DNS.
       Recommended for desktop systems to mitigate DNS failures after suspend/resume.
       https://github.com/tailscale/tailscale/issues/4254
     '';
   };
   

3.3.3.1.2. Configuration#

config = lib.mkIf cfg.enable (
  lib.mkMerge [
    {
      <<tailscale-service>>

      <<tailscale-networking>>

      <<tailscale-secrets>>
    }
    <<tailscale-resolver>>
  ]
);

1. Service Settings
   

   Core Tailscale service configuration.

   useRoutingFeatures = "server" enables this machine to act as a subnet router or exit node. All machines in this configuration can potentially serve as exit nodes for other devices, providing flexibility when traveling or on restricted networks.

   authKeyFile points to a SOPS-managed secret containing a Tailscale auth key. Using auth keys enables unattended authentication, which is essential for automated deployments and GitOps workflows with tools like comin.

   --ssh enables Tailscale SSH, allowing SSH access over the Tailscale network without managing SSH keys or exposing port 22 to the public internet.

   <<tailscale-service>>

   services.tailscale = {
     enable = true;
     useRoutingFeatures = "server";
     authKeyFile = config.sops.secrets.tailscale-authkey.path;
     extraUpFlags = [ "--ssh" ];
   };
   

2. Networking
   

   Firewall and DNS configuration for Tailscale integration.

   The tailscale0 interface is trusted because all traffic on this interface is authenticated by Tailscale. This allows services to be exposed only to the tailnet without additional firewall rules.

   100.100.100.100 is Tailscale's MagicDNS resolver, enabling resolution of tailnet hostnames (e.g., hostname.tail4108.ts.net). 8.8.8.8 provides fallback for non-tailnet queries, though in practice MagicDNS handles forwarding to upstream resolvers.

   The search domain is the tailnet domain, allowing short hostnames (e.g., ssh manyara instead of ssh manyara.tail4108.ts.net).

   <<tailscale-networking>>

   networking = {
     firewall = {
       trustedInterfaces = [ "tailscale0" ];
       allowedUDPPorts = [ config.services.tailscale.port ];
     };
     nameservers = [
       "100.100.100.100"
       "8.8.8.8"
     ];
     search = [ "tail4108.ts.net" ];
   };
   

3. Secrets
   

   SOPS secret declaration for the Tailscale auth key. The actual key is stored encrypted in the repository's secrets file and decrypted at activation time.

   <<tailscale-secrets>>

   sops.secrets.tailscale-authkey = { };
   

4. Resolver
   

   Conditional systemd-resolved configuration. Only enabled when configureResolver is true, typically on desktop systems that suspend/resume.

   <<tailscale-resolver>>

   (lib.mkIf cfg.configureResolver {
     services.resolved.enable = cfg.configureResolver;
   })
   

3.3.5.1.1. Interactive Shell Init#

interactiveShellInit = ''
  <<fish-keybindings>>

  <<fish-done-config>>

  <<fish-pinentry>>

  <<fish-extra-abbrs>>
'';

1. Keybindings
   

   Ctrl+S is bound to zi (zoxide interactive mode) for fuzzy directory jumping.

   <<fish-keybindings>>

   bind \cs zi
   

2. Pinentry
   

   When connected via SSH, GPG's pinentry is switched to the curses (terminal) variant. The default graphical pinentry cannot display on a remote session without X11/Wayland forwarding, so the TUI fallback is necessary for signing commits and decrypting secrets over SSH. See Gentoo Wiki: GnuPG - Changing pinentry for SSH logins.

   <<fish-pinentry>>

   # set environment variable for pinentry
   if test "$SSH_CONNECTION" != ""
     set -x PINENTRY_USER_DATA "USE_CURSES"
   end
   

3. Extra Abbreviations
   

   Position-aware abbreviations that use fish's advanced features (--position anywhere, --regex, --function) which are not available through home-manager's shellAbbrs option.

   <<fish-extra-abbrs>>

   # extra abbrs
   abbr -a L --position anywhere --set-cursor "% | less"
   abbr -a !! --position anywhere --function _abbr_last_history_item
   abbr -a extract_tar_gz --position command --regex ".+\.tar\.gz" --function _abbr_extract_tar_gz
   abbr -a dotdot --regex '^\.\.+$' --function _abbr_multicd
   

3.3.5.1.2. Abbreviations#

shellAbbrs = {
  <<fish-abbr-general>>

  <<fish-abbr-nix>>
};

1. General
   
   <<fish-abbr-general>>

   # spellchecker:off
   l = "ls";
   

2. Nix Remote Build
   

   Abbreviations for specifying Nix build target systems, primarily used when working on nixpkgs. Each abbreviation expands to --system <triple> and conditionally appends -j0 when the target system differs from the current host. -j0 sets the local job limit to zero, forcing all builds to be delegated to remote builders (see Distributed Builds). This prevents Nix from accidentally attempting to build on the host, which would fail with an architecture mismatch.

   <<fish-abbr-nix>>

   "--sxl" = {
     position = "anywhere";
     expansion =
       "--system x86_64-linux"
       + pkgs.lib.optionalString (
         pkgs.stdenv.hostPlatform.isDarwin || pkgs.stdenv.hostPlatform.isAarch64
       ) " -j0";
   };
   "--sal" = {
     position = "anywhere";
     expansion =
       "--system aarch64-linux"
       + pkgs.lib.optionalString (
         pkgs.stdenv.hostPlatform.isDarwin || pkgs.stdenv.hostPlatform.isx86_64
       ) " -j0";
   };
   "--sxd" = {
     position = "anywhere";
     expansion =
       "--system x86_64-darwin" + pkgs.lib.optionalString pkgs.stdenv.hostPlatform.isLinux " -j0";
   };
   "--sad" = {
     position = "anywhere";
     expansion =
       "--system aarch64-darwin" + pkgs.lib.optionalString pkgs.stdenv.hostPlatform.isLinux " -j0";
   };
   # spellchecker:on
   

3.3.5.1.3. Functions#

functions = {
  _abbr_last_history_item = "echo $history[1]";
  _abbr_extract_tar_gz = "echo tar avfx $argv";
  _abbr_multicd = "echo cd (string repeat -n (math (string length -- $argv[1]) - 1) ../)";
};

1. any-nix-shell
   

   any-nix-shell keeps fish as the interactive shell inside nix shell and nix develop environments; without it, entering a Nix shell drops into bash and loses fish's interactive features.

   any-nix-shell fish only emits two function definitions (nix and nix-shell), but generating them shells out to /bin/sh plus three which lookups — ~24ms on every interactive startup if sourced eagerly. Running it once at build time and splitting the output into fish's autoload directory moves that cost off the hot path (fish parses each function on first call), and uses any-nix-shell's real wrappers rather than a hardcoded copy, so its nix run version gate and --pure handling stay in sync with the upstream package.

   <<fish-any-nix-shell>>

   # Generate any-nix-shell's fish wrappers at build time. Each call extracts one
   # function definition into its own file for fish's autoload directory, so the
   # wrappers stay in sync with the package rather than being hardcoded.
   anyNixShellFunction =
     name:
     pkgs.runCommand "any-nix-shell-${name}.fish" { nativeBuildInputs = [ pkgs.any-nix-shell ]; } ''
       any-nix-shell fish | awk -v want=${name} '
         $1 == "function" { current = $2; depth = 0 }
         current == want {
           print
           if ($1 ~ /^(function|begin|if|for|while|switch)$/) depth++
           else if ($1 == "end" && --depth == 0) current = ""
         }
       ' > $out
     '';
   

3.3.5.1.4. Plugins#

plugins = [
  {
    name = "done";
    src = pkgs.fishPlugins.done.src;
  }
  {
    name = "fzf-fish";
    src = pkgs.fishPlugins.fzf-fish.src;
  }
];

# set done's variable
set -U __done_min_cmd_duration 15000

3.3.5.2.1. History#

historyFile = "$XDG_CONFIG_HOME/bash/history";

3.3.5.2.2. Completion#

enableCompletion = false;

3.3.5.2.3. Aliases#

shellAliases = {
  l = "ls -CF";
  grep = "grep --color=auto";
  fgrep = "fgrep --color=auto";
  egrep = "egrep --color=auto";
};

3.3.5.2.4. Init#

initExtra = ''
  <<bash-terminal-settings>>
''
+ lib.optionalString (!config.programs.kitty.enable) ''
  <<bash-tmux-autostart>>
'';

1. Terminal Settings
   

   stty stop undef disables Ctrl+S from sending XOFF, freeing it for use as a keybinding in fish and other TUI applications. Without it, Ctrl+S freezes the terminal until Ctrl+Q is pressed.

   <<bash-terminal-settings>>

   stty stop undef  # Ctrl-s
   

2. TMUX Auto-attach
   

   Automatically starts or attaches to a tmux session when bash is the interactive shell, but only when kitty is not the terminal emulator. Kitty has its own tab/window management (splits, layouts, tabs) that conflicts with tmux's multiplexing — running tmux inside kitty creates redundant nesting. When using a simpler terminal (e.g., xterm, alacritty, or a Linux console), tmux provides the session persistence and window management that would otherwise be missing.

   <<bash-tmux-autostart>>

   # TMUX (from ArchWiki)
   if type tmux > /dev/null 2>&1; then
     # if no session is started, start a new session
     test -z $TMUX && tmux
   
     # when quitting tmux, try to attach
     while test -z $TMUX; do
       tmux attach || break
     done
   fi
   

3.3.5.4.1. External Completer#

options.ext.programs.nushell.externalCompleter = {
  enable = lib.mkOption {
    type = lib.types.bool;
    default = config.programs.nushell.enable;
  };
  enableFishCompleter = lib.mkOption {
    type = lib.types.bool;
    default = true;
  };
};

(lib.mkIf completerCfg.enable {
  programs.nushell.extraConfig = lib.mkIf completerCfg.enableFishCompleter ''
    let fish_completer = {|spans|
        ${lib.getExe pkgs.fish} --command $'complete "--do-complete=($spans | str join " ")"'
        | $"value(char tab)description(char newline)" + $in
        | from tsv --flexible --no-infer
    }

    $env.config = ($env.config? | default {})
    $env.config.completions = ($env.config.completions? | default {})
    $env.config.completions.external = (
        $env.config.completions.external?
        | default {}
        | insert enable { true }
        | insert completer { $fish_completer }
    )
  '';
})

3.3.5.5.1. Prompt Format#

"$schema" = "https://starship.rs/config-schema.json"

format = "$shell$all$line_break$character"

3.3.5.5.2. Shell Indicator#

[shell]
fish_indicator = "󰈺"
powershell_indicator = "󰨊"
disabled = false

3.3.5.5.3. Remote Container Detection#

[custom.remote-container]
when = """ test "$REMOTE_CONTAINERS" """
symbol = "🐋"
format = " in $symbol "

3.3.5.5.4. Disabled Modules#

[gcloud]
disabled = true

3.3.5.5.5. Async Prompt Module#

(lib.mkIf cfg.enableFishAsyncPrompt {
  # use my own script to ensure the execution order
  programs.starship.enableFishIntegration = lib.mkForce false;

  programs.fish.interactiveShellInit = ''
    if test "$TERM" != dumb
        ${lib.getExe config.programs.starship.package} init fish | source
        source ${./async_prompt.fish}
    end
  '';
})

1. Async Prompt Script
   
   modules/features/starship/async_prompt.fish

   # cherry picked from https://gist.github.com/duament/bac0181935953b97ca71640727c9c029
   status is-interactive
   or exit 0
   
   if test -n "$XDG_RUNTIME_DIR"
       set -g __starship_async_tmpdir "$XDG_RUNTIME_DIR"/fish-async-prompt
   else
       set -g __starship_async_tmpdir /tmp/fish-async-prompt
   end
   mkdir -p "$__starship_async_tmpdir"
   set -g __starship_async_signal SIGUSR1
   
   # Starship
   set -g VIRTUAL_ENV_DISABLE_PROMPT 1
   builtin functions -e fish_mode_prompt
   set -gx STARSHIP_SHELL fish
   set -gx STARSHIP_SESSION_KEY (random 10000000000000 9999999999999999)
   
   # Prompt
   function fish_prompt
       printf '\e[0J' # Clear from cursor to end of screen
       if test -e "$__starship_async_tmpdir"/"$fish_pid"_fish_prompt
           cat "$__starship_async_tmpdir"/"$fish_pid"_fish_prompt
       else
           __starship_async_simple_prompt
       end
   end
   
   # Async task
   function __starship_async_fire --on-event fish_prompt
       switch "$fish_key_bindings"
           case fish_hybrid_key_bindings fish_vi_key_bindings
               set STARSHIP_KEYMAP "$fish_bind_mode"
           case '*'
               set STARSHIP_KEYMAP insert
       end
       set STARSHIP_CMD_PIPESTATUS $pipestatus
       set STARSHIP_CMD_STATUS $status
       set STARSHIP_DURATION "$CMD_DURATION"
       set STARSHIP_JOBS (count (jobs -p))
   
       set -l tmpfile "$__starship_async_tmpdir"/"$fish_pid"_fish_prompt
       fish -c '
   starship prompt --terminal-width="'$COLUMNS'" --status='$STARSHIP_CMD_STATUS' --pipestatus="'$STARSHIP_CMD_PIPESTATUS'" --keymap='$STARSHIP_KEYMAP' --cmd-duration='$STARSHIP_DURATION' --jobs='$STARSHIP_JOBS' > '$tmpfile'
   kill -s "'$__starship_async_signal'" '$fish_pid &
       disown
   end
   
   function __starship_async_simple_prompt
       set_color brgreen
       echo -n '❯'
       set_color normal
       echo ' '
   end
   
   function __starship_async_repaint_prompt --on-signal "$__starship_async_signal"
       commandline -f repaint
   end
   
   function __starship_async_cleanup --on-event fish_exit
       rm -f "$__starship_async_tmpdir"/"$fish_pid"_fish_prompt
   end
   
   # https://github.com/acomagu/fish-async-prompt
   # https://github.com/fish-shell/fish-shell/issues/8223
   

3.3.6.1.1. Core Settings#

settings = {
  <<git-user-identity>>
  <<git-github-user>>
  <<git-editor>>
  <<git-color>>
  <<git-default-branch>>
  <<git-push-safety>>
};

1. User Identity
   
   <<git-user-identity>>

   user = {
     name = "natsukium";
     email = "[email protected]";
   };
   

2. GitHub Identity
   

   I read GitHub issues and notifications in Emacs through forge, whose API layer ghub takes the account name from github.user to find the matching ~/.authinfo.age entry. Without it a pull aborts with "Cannot determine username" before any request goes out, and the notification list keeps showing whatever the last successful fetch stored. The token that goes with it is described in the forge section below.

   <<git-github-user>>

   github.user = "natsukium";
   

3. Editor
   

   core.editor = "vim" is set as the fallback editor for git operations. Although the EDITOR environment variable is set to nvim in the home configuration, some contexts (like git commit in a minimal environment) may not inherit the session's environment variables. Setting it explicitly in gitconfig ensures consistent behavior.

   <<git-editor>>

   core.editor = "vim";
   

4. Color
   

   Auto-detect terminal color support for all git subcommands.

   <<git-color>>

   color = {
     status = "auto";
     diff = "auto";
     branch = "auto";
     interactive = "auto";
     grep = "auto";
   };
   

5. Default Branch
   
   <<git-default-branch>>

   init.defaultBranch = "main";
   

6. Force Push Safety
   

   push.useForceIfIncludes enables a safety check for force pushes: git verifies that the local branch includes the remote's current tip before allowing a force push. This prevents accidentally overwriting commits pushed by others since the last fetch, which --force-with-lease alone cannot catch if the remote ref was updated in the background (e.g., by lazygit's periodic fetch or a background git fetch).

   <<git-push-safety>>

   push.useForceIfIncludes = true;
   

3.3.6.1.2. Commit Signing#

signing = {
  format = "ssh";
  key = "~/.ssh/id_ed25519.pub";
  signByDefault = true;
};

3.3.6.1.3. Global Ignores#

ignores = [
  <<git-ignores-os>>
  <<git-ignores-dev>>
  <<git-ignores-workflow>>
  <<git-ignores-private>>
];

1. OS Artifacts
   

   macOS Finder metadata files. Present in the global ignore because this is a cross-platform dotfiles repository used on both Linux and macOS.

   <<git-ignores-os>>

   ".DS_Store"
   

2. Development Environment
   

   Artifacts generated by development tools that should remain local:

   • .aider* matches aider's conversation history and configuration files. These contain session-specific context and should not leak into repositories.
   • .direnv, .envrc: direnv state and configuration. Each project may define its own .envrc, but since this repository uses flake-based devshells, the .envrc files are auto-generated and should not be committed.
   • .ipynb_checkpoints: Jupyter Notebook autosave files.
   • .pre-commit-config.yaml: Managed per-project by devshell environments rather than committed, to avoid version conflicts across contributors with different tool versions.
   • .vscode/: Editor-specific settings that vary per developer.
   • __pycache__/: Python bytecode cache, regenerated on each run.

   <<git-ignores-dev>>

   ".aider*"
   ".direnv"
   ".envrc"
   ".ipynb_checkpoints"
   ".pre-commit-config.yaml"
   ".vscode/"
   "__pycache__/"
   

3. Workflow
   
   • .worktree: Marker file used by git worktree workflows.

   <<git-ignores-workflow>>

   ".worktree"
   

4. Private Notes
   

   .private/ is a directory for personal notes, LLM context files, and other local-only documentation that should never be shared.

   <<git-ignores-private>>

   ".private/"
   

3.3.6.1.4. Scalar#

options.programs.git.scalar = {
  enable = lib.mkEnableOption "scalar";

  repo = lib.mkOption {
    type = lib.types.listOf lib.types.str;
    default = [ ];
    example = [ "${config.home.homeDirectory}/NixOS/nixpkgs" ];
  };
};

scalar = {
  enable = true;
  repo = [ "${config.programs.git.settings.ghq.root}/github.com/natsukium/nixpkgs" ];
};

(lib.mkIf scalarCfg.enable {
  programs.git = {
    settings = {
      scalar.repo = scalarCfg.repo;
      maintenance.repo = scalarCfg.repo;
    };
    includes = map (repo: {
      condition = "gitdir:${repo}/";
      contents = {
        core = {
          multipackindex = true;
          preloadindex = true;
          untrackedcache = true;
          autocrlf = false;
          safecrlf = false;
          fsmonitor = true;
        };
        am.keepcr = true;
        credential = {
          "https://dev.azure.com".usehttppath = true;
          validate = false;
        };
        gc.auto = 0;
        gui.gcwarning = false;
        index = {
          threads = true;
          version = 4;
        };
        merge = {
          stat = false;
          renames = true;
        };
        pack = {
          usebitmaps = false;
          usesparse = true;
        };
        receive.autogc = false;
        feature = {
          manyfiles = false;
          experimental = false;
        };
        fetch = {
          unpacklimit = 1;
          writecommitgraph = false;
          showforcedupdates = false;
        };
        status.aheadbehind = false;
        commitgraph.generationversion = 1;
        log.excludedecoration = "refs/prefetch/*";
        maintenance = {
          auto = false;
          strategy = "incremental";
        };
      };
    }) scalarCfg.repo;
  };
})

3.3.6.1.5. GitHub CLI#

programs.gh.enable = true;

3.3.6.1.6. Delta#

programs.delta = {
  enable = true;
  enableGitIntegration = true;
};

3.3.6.1.7. Difftastic#

programs.difftastic = {
  enable = true;
};

3.3.6.1.8. Lazygit#

programs.lazygit = {
  enable = true;
  settings = {
    <<lazygit-gui>>

    <<lazygit-git>>
  };
};

1. GUI
   

   Enable Nerd Font icons in the lazygit interface for visual clarity.

   <<lazygit-gui>>

   gui = {
     showIcons = true;
   };
   

2. Git Integration
   

   overrideGpg = true tells lazygit to run git commands inline instead of spawning a subprocess for GPG/SSH signing. By default, lazygit defers to a subprocess so the user can type a passphrase interactively. However, this subprocess mode prevents lazygit from orchestrating interactive rebase internally — rewording, reordering, or editing any commit other than HEAD is disabled entirely because the rebase would trigger multiple signing prompts that lazygit cannot handle mid-rebase. With overrideGpg = true, lazygit assumes the signing agent (ssh-agent, macOS Keychain) caches the passphrase, so no interactive prompt is needed and all rebase operations work normally.

   The pager configuration integrates both delta and difftastic into lazygit's diff views. Delta provides syntax-highlighted line diffs (--dark --paging=never since lazygit handles its own paging), and difftastic is available as the external diff command for structural comparison.

   <<lazygit-git>>

   git = {
     overrideGpg = true;
     pagers = [
       {
         colorArg = "always";
         pager = "delta --dark --paging=never";
       }
       {
         externalDiffCommand = "difft --color=always";
       }
     ];
   };
   

3.3.6.1.9. Fish Abbreviations#

programs.fish.shellAbbrs = {
  <<git-abbr-push>>
  <<git-abbr-pull>>
  <<git-abbr-commit>>
  <<git-abbr-status>>
  <<git-abbr-stash>>
  <<git-abbr-switch>>
};

1. Push
   

   Force push with lease — safer than --force as it prevents overwriting remote changes not yet fetched.

   <<git-abbr-push>>

   gpf = "git push --force-with-lease";
   

2. Pull
   

   gpm pulls from the remote's default branch, dynamically detected via git remote show rather than hardcoding main or master. This handles repositories that still use master or other branch naming conventions.

   gpu pulls from upstream — used in fork workflows to sync with the original repository.

   <<git-abbr-pull>>

   gpm = "git pull (git remote show origin | sed -n '/HEAD branch/s/.*: //p')";
   gpu = "git pull upstream";
   

3. Commit
   

   gci creates a commit. The trailing space allows directly appending -m "message".

   gca amends the last commit, frequently used during interactive rebase workflows.

   <<git-abbr-commit>>

   gci = "git commit ";
   gca = "git commit --amend";
   

4. Status
   
   <<git-abbr-status>>

   gs = "git status";
   

5. Stash
   
   <<git-abbr-stash>>

   gst = "git stash";
   gstp = "git stash pop";
   

6. Switch
   
   <<git-abbr-switch>>

   gsw = "git switch";
   gswc = "git switch -c";
   

3.3.7.1.1. nix-darwin module#

{
  config,
  lib,
  pkgs,
  ...
}:
let
  cfg = config.services.forgejo-runner;
  settingsFormat = pkgs.formats.yaml { };

  <<forgejo-runner-instance-submodule>>

  enabledInstances = lib.filterAttrs (_: i: i.enable) cfg.instances;
in
{
  <<forgejo-runner-darwin-options>>

  <<forgejo-runner-darwin-config>>
}

1. Instance options
   

   An instance carries its registration details and the tools its jobs need on PATH. Exactly one of token or tokenFile supplies the token, matching the NixOS module. Host-executed jobs inherit only the daemon's environment, so every tool a workflow expects must be listed in hostPackages.

   <<forgejo-runner-instance-submodule>>

   instanceModule =
     { name, ... }:
     {
       options = {
         enable = lib.mkEnableOption "this runner instance";
   
         name = lib.mkOption {
           type = lib.types.str;
           default = name;
           defaultText = lib.literalExpression "the attribute name";
           description = "Name the runner registers under.";
         };
   
         url = lib.mkOption {
           type = lib.types.str;
           example = "https://git.example.com";
           description = "Address of the Forgejo instance the runner registers with.";
         };
   
         token = lib.mkOption {
           type = lib.types.nullOr lib.types.str;
           default = null;
           description = ''
             Registration token as a plaintext string. Mutually exclusive with
             {option}`tokenFile`. Prefer {option}`tokenFile`: a token set here ends
             up in the world-readable launchd plist and the Nix store.
           '';
         };
   
         tokenFile = lib.mkOption {
           type = lib.types.nullOr (lib.types.either lib.types.str lib.types.path);
           default = null;
           description = ''
             Path to an environment file holding the registration token as
             `TOKEN=...`. Mutually exclusive with {option}`token`. The token is read
             on first registration and whenever it or {option}`labels` change;
             otherwise the persisted {file}`.runner` credential in {option}`stateDir`
             is used.
           '';
         };
   
         labels = lib.mkOption {
           type = lib.types.listOf lib.types.str;
           example = [ "macos:host" ];
           description = "Labels the runner advertises.";
         };
   
         settings = lib.mkOption {
           type = settingsFormat.type;
           default = { };
           description = ''
             Runner configuration written to {file}`config.yaml` and passed to the
             daemon with `--config`.
           '';
         };
   
         hostPackages = lib.mkOption {
           type = lib.types.listOf lib.types.package;
           default = with pkgs; [
             bash
             coreutils
             curl
             gawk
             gitMinimal
             gnused
             nodejs
             wget
           ];
           defaultText = lib.literalExpression ''
             with pkgs; [ bash coreutils curl gawk gitMinimal gnused nodejs wget ]
           '';
           description = ''
             Packages put on PATH for host-executed jobs. Host jobs inherit only
             the daemon's PATH, so every tool a workflow expects must be listed.
           '';
         };
   
         stateDir = lib.mkOption {
           type = lib.types.str;
           default = "/var/lib/forgejo-runner/${name}";
           defaultText = lib.literalExpression ''"/var/lib/forgejo-runner/<name>"'';
           description = "Directory holding the runner credential and working files.";
         };
       };
     };
   

2. Module options
   

   The daemons run as a dedicated unprivileged user, not root: a root daemon is a trusted-user client of the nix daemon, whose post-build-hook push path the multi-user daemon ignores — so nothing reaches my binary cache. An untrusted user takes the store-scan push path that actually uploads. I may revisit making it a trusted user once the post-build-hook path works for me.

   <<forgejo-runner-darwin-options>>

   options.services.forgejo-runner = {
     package = lib.mkPackageOption pkgs "forgejo-runner" { };
   
     user = lib.mkOption {
       type = lib.types.str;
       default = "_forgejo-runner";
       description = "Dedicated unprivileged user the runner daemons execute as.";
     };
   
     group = lib.mkOption {
       type = lib.types.str;
       default = "_forgejo-runner";
       description = "Primary group for the runner user.";
     };
   
     uid = lib.mkOption {
       type = lib.types.int;
       default = 530;
       description = "UID for the runner user (free system-range id on the host).";
     };
   
     gid = lib.mkOption {
       type = lib.types.int;
       default = 530;
       description = "GID for the runner group.";
     };
   
     instances = lib.mkOption {
       type = lib.types.attrsOf (lib.types.submodule instanceModule);
       default = { };
       description = "Runner instances; each enabled one becomes a launchd daemon.";
     };
   };
   

3. Configuration
   
   <<forgejo-runner-darwin-config>>

   config = lib.mkIf (enabledInstances != { }) {
     assertions = lib.mapAttrsToList (_: instance: {
       assertion = (instance.token == null) != (instance.tokenFile == null);
       message = "services.forgejo-runner.instances.${instance.name}: set exactly one of token or tokenFile.";
     }) enabledInstances;
   
     <<forgejo-runner-daemons>>
   
     <<forgejo-runner-user>>
   
     <<forgejo-runner-ownership>>
   };
   

   1. Launchd daemons
      

      One launchd job per enabled instance. launchd has no EnvironmentFile, so a tokenFile instance sources it in-script while an inline token rides on EnvironmentVariables; either way the script sees $TOKEN. I prepend coreutils to PATH so the script's own sha256sum=/=cut resolve even if a host trims hostPackages. Two launchd quirks shape each:

      • WorkingDirectory cannot be the state directory: launchd chdir()s into it before exec, so on first boot the spawn aborts with EX_CONFIG (78) before the script can create it. The script sets its own cwd instead.
      • The logs live in the user-owned state directory, not /var/log: launchd opens them as UserName, and an unprivileged daemon cannot create a root-owned file under /var/log, so it would fail to spawn — silently, before any log line.

      <<forgejo-runner-daemons>>

      launchd.daemons = lib.mapAttrs' (
        _: instance:
        let
          configFile = settingsFormat.generate "config.yaml" instance.settings;
        in
        lib.nameValuePair "forgejo-runner-${instance.name}" {
          script = ''
            set -eu
            mkdir -p ${lib.escapeShellArg instance.stateDir}
            cd ${lib.escapeShellArg instance.stateDir}
            ${lib.optionalString (instance.tokenFile != null) ''
              set -a
              . ${lib.escapeShellArg (toString instance.tokenFile)}
              set +a
            ''}
            labels=${lib.escapeShellArg (lib.concatStringsSep "," instance.labels)}
            state="$(printf '%s' "$TOKEN" | sha256sum | cut -d' ' -f1) $labels"
      
            if [ ! -f .runner ] || [ "$(cat .registration-state 2>/dev/null)" != "$state" ]; then
              rm -f .runner
              ${lib.getExe cfg.package} register \
                --no-interactive \
                --instance ${lib.escapeShellArg instance.url} \
                --token "$TOKEN" \
                --name ${lib.escapeShellArg instance.name} \
                --labels "$labels" \
                --config ${configFile}
              printf '%s' "$state" > .registration-state
            fi
      
            exec ${lib.getExe cfg.package} daemon --config ${configFile}
          '';
          serviceConfig = {
            UserName = cfg.user;
            GroupName = cfg.group;
            KeepAlive = true;
            RunAtLoad = true;
            ProcessType = "Background";
            EnvironmentVariables = {
              HOME = instance.stateDir;
              PATH = "${
                lib.makeBinPath ([ pkgs.coreutils ] ++ instance.hostPackages)
              }:/usr/bin:/bin:/usr/sbin:/sbin";
            }
            // lib.optionalAttrs (instance.token != null) { TOKEN = instance.token; };
            StandardOutPath = "${instance.stateDir}/forgejo-runner.log";
            StandardErrorPath = "${instance.stateDir}/forgejo-runner.err.log";
          };
        }
      ) enabledInstances;
      

   2. Runner user
      

      nix-darwin only manages accounts listed in users.knownUsers / users.knownGroups, so I add the entries.

      I leave createHome off: it runs createhomedir, which resolves the /var firmlink and records the home as /private/var/…, then nix-darwin string-compares that against the configured home and aborts activation on the mismatch. The daemon uses its state directory as HOME anyway, created and owned below.

      <<forgejo-runner-user>>

      users.users.${cfg.user} = {
        uid = cfg.uid;
        gid = cfg.gid;
        isHidden = true;
        description = "Forgejo Actions runner";
      };
      users.groups.${cfg.group}.gid = cfg.gid;
      users.knownUsers = [ cfg.user ];
      users.knownGroups = [ cfg.group ];
      

   3. State ownership
      

      Each state directory must exist and belong to the runner user before its daemon starts. With createHome off nothing else creates it, so activation makes and chowns it mkBefore the launchd step that loads the daemons.

      <<forgejo-runner-ownership>>

      system.activationScripts.launchd.text = lib.mkBefore (
        lib.concatMapStringsSep "\n" (instance: ''
          mkdir -p ${lib.escapeShellArg instance.stateDir}
          chown -R ${lib.escapeShellArg cfg.user}:${lib.escapeShellArg cfg.group} ${lib.escapeShellArg instance.stateDir}
        '') (lib.attrValues enabledInstances)
      );