Imported from Ginner/ApexOS (nixosModules/services/AGENTS.md). Install upstream with npx skills add Ginner/ApexOS --skill services. Copyright stays with the author.

AGENTS.md — nixosModules/services/

System-level daemons and services. A module belongs here if it manages a running system process (systemd service, udev rule, kernel feature).

What belongs here vs programs/

• services/: background daemons, hardware management, kernel features
  • Examples: pipewire (audio), greetd (login manager), tlp (power), tailscale (network), xremap (input), bolt (Thunderbolt), fwupd (firmware), brightnessctl (backlight), kde-connect, openssh, podman
• programs/: system-level CLI tools or programs that require system-level enablement
  • Examples: hyprland (requires system setuid/capabilities), zsh (requires /etc/shells), usbutils, agenix

Current services

Module conventions

{ config, lib, pkgs, ... }:
let cfg = config.myModules.services.<name>; in
{
  options.myModules.services.<name> = {
    enable = lib.mkEnableOption "<description>";
    # Additional configurable options with sensible defaults
  };
  config = lib.mkIf cfg.enable {
    services.<name>.enable = true;
    # ...
  };
}

Patterns observed:

• greetd.nix: exposes sessionCommand option (default: tuigreet with Hyprland). Session type is configurable without touching the module.
• tlp.nix: exposes batteryThresholds.BAT0/BAT1.{start,stop} and extraSettings. Uses lib.mkMerge for multiple config blocks.
• xremap.nix: exposes modmaps, extraConfig, includeDefaults (CapsLock → Super/Esc remap). Reads config.userGlobals.username to add the user to input/uinput groups.

Accessing the primary user: Use config.userGlobals.username when the service needs to add the user to a group or create user-specific paths.

Using flake inputs in services: Some services reference inputs.xremap-flake.packages.* (xremap.nix). Declare inputs in the module's argument list and it arrives via specialArgs. Note: inputs.rose-pine-hyprcursor is used in nixosModules/shared/stylix.nix, not in any file under services/.

Adding a new service module

See skills/new-nixos-module.md.