Nix Config

This is my interpretation of the perfect nix flake, this powers my desktops, laptops, servers, vms, containers, and all aspects of my computers.

Features

• Automated Discovery: Hosts and users are automatically configured from filesystem structure
• Automated Persistence: TempFS with persistable components using [Impermanence] or BTRFS snapshotting
• Secret Management: Encrypted secrets in [NixOS] ([sops-nix]) and [home-manager] ([sops-nix] with [sops])
• Automated Updates: Flake dependency updates through Github Actions using [Update-flake-lock]
• Hardware Acceleration: Automatic hardware acceleration support detection and configuration
• Modular Architecture: Custom modules and overlays for extensibility

Supported Configurations

• [NixOS]-managed systems with automatic configuration discovery:
  • Desktops - Personal workstations and development environments
  • Servers - Infrastructure services and automation
  • Laptops - Portable systems with power management

Repository Structure

The repository uses an automatic discovery system that scans the filesystem to build configurations:

.
├─ home              # Root for all user homes (auto-discovered)
│  ├─── {username}   # User-specific configurations
│  └─── shared       # Shared home-manager modules
├─ hosts             # Root for all hosts (auto-discovered by device type)
│  ├─── shared       # Auto-imported modules for all hosts
│  │    ├─── global  # Core system configuration (locale, networking, etc.)
│  │    └─── optional# Optional modules for specific use cases
│  ├─── desktop      # Desktop NixOS systems
│  │    ├─── shared  # Auto-imported modules for desktops
│  │    ├─── {host}  # Individual desktop host configurations
│  ├─── laptop       # Laptop NixOS Systems
│  │    ├─── shared  # Auto-imported modules for laptops
│  │    └─── {host}  # Individual laptop host configurations
│  └─── server       # Server NixOS Systems
│       ├─── shared  # Auto-imported modules for servers
│       └─── {host}  # Individual server host configurations
├─ lib               # Extensions to nixpkgs lib and custom builders
│  └─── builders     # System and home-manager configuration builders
├─ modules           # Custom NixOS and home-manager modules
├─ overlays          # NixPkgs overlays for package modifications
├─ pkgs              # Custom packages not in nixpkgs
└─ docs              # Additional documentation

Auto-Discovery Mechanism

The flake automatically discovers:

• Hosts: By scanning hosts/{device-type}/ directories (excluding shared/)
• Users: By scanning home/ directories and matching with existing hosts
• Hardware Acceleration: Support based on predefined host lists

Welcome to the docs!

Over to the left, you’ll find the sidebar. There you’ll see several sections including “User guides”, “Modules”, “Packages”, “Overlays”, “Hosts”, and “Lib”.

If you’re looking for a specific option you may find the dedicated RacciDev Option Search (at the bottom of the sidebar) has more relevant results.

Installation Guide

This guide covers various installation scenarios for the nix-config repository.

Windows Subsystem for Linux (WSL)

Prerequisites

• Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11
• WSL 2 enabled
• Administrator access to Windows

Installation Steps

1. Install WSL 2

# Run in PowerShell as Administrator
wsl --install

# If WSL is already installed, ensure you're using WSL 2
wsl --set-default-version 2

2. Setup NixOS for WSL

Download and install NixOS-WSL via NixOS-WSL:

# Download the latest NixOS-WSL tarball
# Import the NixOS-WSL distribution
wsl --import NixOS .\NixOS\ nixos-wsl.tar.gz --version 2

# Start the NixOS instance
wsl -d NixOS

3. Configure NixOS-WSL

After starting your NixOS-WSL instance:

# Clone this repository
sudo git clone https://github.com/DaRacci/nix-config.git /etc/nixos

# Apply the WSL configuration
# Replace YOUR_WSL_HOSTNAME with your actual WSL hostname
sudo nixos-rebuild switch --flake /etc/nixos#YOUR_WSL_HOSTNAME

4. WSL-Specific Features

The WSL configuration includes:

• SSH agent relay between Windows and WSL
• Hardware acceleration support for development
• Remote desktop capabilities
• Optimized for headless operation

Native NixOS Installation

Prerequisites

• NixOS installation media
• Target hardware
• Network connectivity
• Backup of important data

Installation Process

1. Boot from NixOS Installation Media

• Download NixOS ISO from nixos.org
• Create bootable USB/DVD
• Boot from installation media

2. Network Configuration

# For WiFi connections
sudo systemctl start wpa_supplicant
wpa_cli
> add_network
> set_network 0 ssid "YourSSID"
> set_network 0 psk "YourPassword"
> enable_network 0
> quit

# Verify connectivity
ping nixos.org

3. Disk Setup

Follow standard NixOS installation procedures for disk partitioning and filesystem setup as described in the NixOS manual.

4. Generate Hardware Configuration

# Generate hardware configuration
nixos-generate-config --root /mnt

# Copy to your host configuration
mkdir -p /mnt/etc/nixos/hosts/{device-type}/{hostname}
cp /mnt/etc/nixos/hardware-configuration.nix /mnt/etc/nixos/hosts/{device-type}/{hostname}/hardware.nix

# Clone this repository
cd /mnt/etc/nixos
git clone https://github.com/DaRacci/nix-config.git .

5. Customize Host Configuration

Edit hosts/{device-type}/{hostname}/default.nix and hardware.nix according to your needs.

6. Install NixOS

# Install with your specific host configuration
nixos-install --flake .#{hostname}

# Set root password when prompted

7. Post-Installation

# Reboot into new system
reboot

# After reboot, ensure configuration is applied
sudo nixos-rebuild switch --flake /etc/nixos#{hostname}

Existing NixOS System Migration

From Traditional NixOS Configuration

1. Backup Current Configuration

# Backup current configuration (adjust path if using flakes)
sudo cp -r /etc/nixos /etc/nixos.backup

2. Clone This Repository

# Clone to a working directory
git clone https://github.com/DaRacci/nix-config.git /tmp/nix-config
sudo cp -r /tmp/nix-config/* /etc/nixos/

3. Create Host Configuration

# Create your host directory
sudo mkdir -p /etc/nixos/hosts/{device-type}/{hostname}

# Migrate your hardware configuration
sudo cp /etc/nixos.backup/hardware-configuration.nix /etc/nixos/hosts/{device-type}/{hostname}/hardware.nix

# Create default.nix based on your old configuration
# Edit to follow the new structure

4. Test and Apply

# Test the new configuration
sudo nixos-rebuild build --flake .#{hostname}

# Apply if build succeeds
sudo nixos-rebuild switch --flake .#{hostname}

IO Guardian - Database Availability System

Purpose

The IO Guardian system ensures that services across the infrastructure are aware of the availability of centralized databases hosted on the Database Coordinator. It provides graceful startup and shutdown coordination between the database host and dependent services on other servers.

Entry Point

• Main file: modules/nixos/server/database/guardian.nix

Architecture / Services / Scope

The system consists of two components:

1. Guardian Server (runs on client servers)

   • WebSocket server that listens for commands from the coordinator
   • Secures connections with a pre-shared key (PSK) from the DB_GUARDIAN_PSK secret
   • Executes drain/undrain commands by controlling db-databases.target

2. Guardian Client (runs on the Database Coordinator)

   • WebSocket client that connects to all guardian servers
   • Sends undrain command after databases are online (start dependent services)
   • Sends drain command before database shutdown (stop dependent services)

How It Works

System Startup

1. Client servers boot and run wait-for-db-databases.service
2. This service waits (with retries) until PostgreSQL and Redis on the Database Coordinator are reachable
3. Once databases are confirmed available, the service completes
4. The db-databases.target is now ready to be activated
5. When the Database Coordinator’s db-database-coordinator.service starts, it sends undrain to all clients
6. Clients start db-databases.target, which starts all dependent services

Database Shutdown (Graceful Drain)

1. When db-database-coordinator.service stops (before databases stop)
2. It connects to all guardian servers via WebSocket
3. Sends drain command to each server
4. Guardian servers stop db-databases.target
5. Dependent services stop gracefully before databases go down

Database Startup (Undrain)

1. When databases come online on the Database Coordinator
2. db-database-coordinator.service starts
3. It sends undrain command to all guardian servers
4. Guardian servers start db-databases.target
5. All dependent services start

Systemd Units

On Client Servers

On the Database Coordinator

Protocol Reference

The guardian uses a simple JSON-based WebSocket protocol:

Authentication

Client sends:

{ "type": "auth", "key": "<psk>" }

Server responds:

{ "type": "auth", "status": "ok", "message": "Authentication successful" }

Commands

Coordinator sends one of the supported actions (drain, undrain, or ping):

{ "type": "command", "action": "drain" }

Server responds:

{ "type": "response", "action": "<action>", "status": "ok", "message": "..." }

Secrets

Communication is secured using a Pre-Shared Key (PSK) that must be at least 32 characters. All WebSocket connections must authenticate with this key before commands are accepted.

Declared secrets

Operational Notes / Assumptions

Configuration

Port: The guardian WebSocket server listens on port 9876 by default. This port is automatically opened to local subnets on servers with database dependencies.

Dependent Services: Dependent Services will be automatically populated with service names where there is a systemd.service.<name> defined from the names in server.database.postgres or server.database.redis. To manually add a service bind to the database availability target, add it to the server.database.dependentServices option. Services listed here will start only when db-databases.target is active, stop when it stops, and restart when the target restarts.

Troubleshooting

Checking Guardian Status

On client servers:

systemctl status db-guardian.service
systemctl status db-databases.target
systemctl status wait-for-db-databases.service
journalctl -u db-guardian.service -f

On the Database Coordinator:

systemctl status db-database-coordinator.service
journalctl -u db-database-coordinator.service

Manual Commands

To manually start/stop dependent services on a client:

systemctl start db-databases.target
systemctl stop db-databases.target

Common Issues

Guardian server won’t start:

• Check that DB_GUARDIAN_PSK secret is properly configured
• Verify the SOPS decryption is working and the secret is non-empty: test -s /run/secrets/DB_GUARDIAN_PSK

Services not starting after boot:

• Check wait service logs: journalctl -u wait-for-db-databases.service
• Verify network connectivity to the Database Coordinator on ports 5432 (Postgres) and 6379 (Redis)
• Ensure the Database Coordinator has sent the undrain command

Authentication failures in logs:

• Ensure the same PSK is deployed to all servers
• Re-encrypt secrets if the key was changed

References

• Database Coordinator

Server Cluster Monitoring — Observability Stack

Purpose

The monitoring module provides a comprehensive observability stack for the server cluster using Prometheus (metrics), Loki (logs), Grafana (visualization), and Grafana Alloy for authenticated OTLP ingestion. All components are configured as reusable NixOS modules with automatic cross-host discovery.

The system consists of three layers:

• Exporters (run on all servers)

  • node_exporter for system-level metrics (CPU, memory, disk, network, per-process stats)
  • Grafana Alloy for shipping journald logs and Caddy access logs to Loki
  • Conditional Exporters: The following exporters are enabled if their corresponding services are configured on the host:
    • Caddy access logs are parsed and sent to Loki
    • fail2ban exporter available on the IO Coordinator
    • PostgreSQL exporter available on the Database Coordinator
    • Redis exporter available on the Database Coordinator
    • Proxmox exporter available on the Monitoring Coordinator

• Collectors (run on the Monitoring Coordinator)

  • Prometheus for metrics aggregation
  • Loki for log aggregation with 90-day retention
  • Alertmanager for alert routing and notifications
  • OTLP/HTTP ingestion on otlp.<domain> with bearer-token authentication

• Visualization (runs on the Monitoring Coordinator)

  • Grafana with provisioned datasources and dashboards

Entry Point

• Main file: modules/nixos/server/monitoring/default.nix

Architecture / Services / Scope

Configuration

Enabling Monitoring

Monitoring is enabled by default on all servers, this can be disabled with server.monitoring.enable = false.

Options

server.monitoring.collector.alerting.enable

Whether to enable Alertmanager and alert rules.

server.monitoring.collector.alerting.homeAssistant.enable

Whether to enable Home Assistant webhook alerting.

server.monitoring.collector.alerting.nextcloudTalk.enable

Whether to enable Nextcloud Talk webhook alerting.

server.monitoring.collector.enable

Whether to enable monitoring collector services (Prometheus, Loki, Grafana).

server.monitoring.collector.grafana.kanidm.enable

Whether to enable Kanidm OAuth2 authentication for Grafana.

server.monitoring.collector.otlp.bearerTokenSecret

SOPS secret path used as the bearer token for OTLP/HTTP ingestion.

server.monitoring.collector.otlp.enable

Whether to enable OTLP/HTTP ingestion via Grafana Alloy.

server.monitoring.collector.otlp.port

Port for the OTLP/HTTP ingestion endpoint.

server.monitoring.collector.otlp.subdomain

Subdomain used for the OTLP/HTTP ingestion endpoint.

server.monitoring.collector.proxmox.enable

Whether to enable Proxmox VE metrics collection.

server.monitoring.enable

Whether to enable monitoring for this server.

server.monitoring.exporters.caddy.enable

Whether to enable Caddy metrics exporter.

server.monitoring.exporters.fail2ban.enable

Whether to enable fail2ban metrics exporter.

server.monitoring.exporters.node.enable

Whether to enable node_exporter for system-level metrics.

server.monitoring.exporters.postgres.enable

Whether to enable PostgreSQL exporter.

server.monitoring.exporters.process.enable

Whether to enable Process exporter for monitoring specific processes.

server.monitoring.exporters.redis.enable

Whether to enable Redis exporter.

server.monitoring.logs.enable

Whether to enable Alloy log shipping.

server.monitoring.logs.extraConfiguration

Additional configuration for the alloy log processor. This is useful for adding custom Loki stages, relabeling rules, or write targets.

Note that the default configuration for processing the system journal is always included and does not need to be specified here.

server.monitoring.retention.logs

Loki log retention period.

server.monitoring.retention.metrics

Prometheus TSDB retention period.

server.monitoring.scrapeConfigs

Declarative scrape configs for services running on this host. These are collected by the monitoring primary host and converted into Prometheus scrape configurations.

server.monitoring.scrapeConfigs.<name>.bearer_token_secret

SOPS secret path for bearer token authentication. When set, the secret will be created on the monitoring primary host.

server.monitoring.scrapeConfigs.<name>.host

Host to scrape metrics from.

server.monitoring.scrapeConfigs.<name>.job_name

Prometheus job name for this scrape target.

server.monitoring.scrapeConfigs.<name>.metrics_path

HTTP path to the metrics endpoint.

server.monitoring.scrapeConfigs.<name>.port

Port the metrics endpoint listens on.

server.monitoring.scrapeConfigs.<name>.scheme

URL scheme for scraping.

Secrets

Declared secrets

Generating Secrets

Generating secure random secrets can be done with the following command:

cat /dev/urandom | tr -dc 'A-Za-z0-9' | head -c 48

The MONITORING/GRAFANA/OAUTH_SECRET must match the value in hosts/server/<Application Server>/secrets.yaml under KANIDM/OAUTH2/GRAFANA_SECRET (the Kanidm provisioning side).

Caddy Virtual Hosts

The module configures four virtual hosts on Monitoring Coordinator:

Grafana remains protected by the existing Kanidm-backed login flow. The OTLP ingestion endpoint is intended for machine-to-machine clients and requires an Authorization: Bearer <token> header on every request. The exposed OTLP/HTTP paths are the standard /v1/metrics and /v1/logs endpoints.

These are defined in hosts/server/nixmon/default.nix and collected by the IO Coordinator’s Caddy configuration.

Alert Rules

The following alerts are configured by default:

Alerts are routed to:

• Home Assistant: All critical and warning alerts via webhook (requires collector.alerting.homeAssistant.enable = true)
• Nextcloud Talk: Critical alerts only via webhook (requires collector.alerting.nextcloudTalk.enable = true)

Module Structure

modules/nixos/server/monitoring/
├── default.nix              # Entry point, imports sub-modules
├── options.nix              # All server.monitoring.* options
├── collector/
│   ├── default.nix          # Imports collector sub-modules
│   ├── prometheus.nix       # Prometheus server + scrape targets
│   ├── loki.nix             # Loki server + storage config
│   ├── grafana.nix          # Grafana + Kanidm OAuth2
│   ├── otlp.nix             # OTLP ingestion
│   ├── alerting.nix         # Alertmanager + alert rules
│   └── dashboards.nix       # Dashboard provisioning
├── exporters/
│   ├── default.nix          # Imports exporter sub-modules
│   ├── node.nix             # node_exporter
│   ├── caddy.nix            # Caddy metrics
│   ├── postgres.nix         # PostgreSQL exporter
│   ├── redis.nix            # Redis exporter
│   └── fail2ban.nix         # fail2ban metrics exporter
├── logs/
│   └── alloy.nix            # Alloy log shipping
└── integrations/
    └── proxmox.nix          # PVE exporter for Proxmox API

Operational Notes / Assumptions

Troubleshooting

Checking Service Status

On the monitoring host (Monitoring Coordinator):

systemctl status prometheus.service
systemctl status loki.service
systemctl status grafana.service
systemctl status prometheus-alertmanager.service
systemctl status prometheus-pve-exporter.service

On any server:

systemctl status prometheus-node-exporter.service
systemctl status prometheus-fail2ban-exporter.service
systemctl status alloy.service

Verifying Metrics Collection

Check Prometheus targets are up:

curl -s http://localhost:9090/api/v1/targets | jq '.data.activeTargets[] | {instance: .labels.instance, health: .health}'

Verifying Log Collection

Alloy applies ingest-time parsing for journal stdout logs and Caddy access logs before forwarding to Loki:

• Caddy access logs are read as JSON, not plain text

• Legacy timestamps in form YYYY/MM/DD HH:MM:SS are parsed and used as event timestamps

• ISO-8601 timestamps with a log level prefix are parsed and normalized

• detected_level defaults to info when the source log line does not provide one

• Caddy JSON fields level, ts, logger, and status are extracted into Loki labels and timestamps

• Caddy access logs are read from /var/log/caddy-access-*.log and use the timestamp and level prefix in each line when present

node_exporter also enables the processes collector, which exposes per-process metrics such as CPU and memory usage for running processes.

Check Alloy is shipping logs:

journalctl -u alloy.service -f

Query Loki directly:

curl -s 'http://localhost:3100/loki/api/v1/labels' | jq

Common Issues

Grafana OAuth login fails:

• Verify MONITORING/GRAFANA/OAUTH_SECRET in the Monitoring Coordinator matches KANIDM/OAUTH2/GRAFANA_SECRET in the Identity Coordinator
• Check Kanidm provisioning has the Grafana OAuth2 client configured
• Verify DNS resolves auth.<domain> correctly

Prometheus targets showing as down:

• Check firewall rules allow traffic on exporter ports from the monitoring host
• Verify the exporter service is running on the target host
• Check network connectivity between Monitoring Coordinator and the target host

Proxmox metrics missing:

• Verify PROXMOX/TOKEN_ID and PROXMOX/TOKEN_SECRET are valid
• Check PVE API is accessible from Monitoring Coordinator: curl -k https://pve.<domain>/api2/json
• Review PVE exporter logs: journalctl -u prometheus-pve-exporter.service

References

• IO Coordinator
• Monitoring Coordinator
• Database Coordinator
• Storage Coordinator
• Identity Coordinator

Creating New Users

To add a new user configuration:

1. Create User Directory

mkdir -p home/newuser

2. Create User Configuration Files

Create host-specific configurations in home/newuser/{hostname}.nix:

{ pkgs, lib, ... }:
{
  imports = [
    # Import shared configurations
    ./features/cli              # Common CLI tools
    ./features/desktop/common   # Desktop environment basics
  ];

  # User-specific configuration
  home = {
    username = "newuser";
    homeDirectory = "/home/newuser";
    stateVersion = "25.05"; # Set this to the Home Manager state version from initial setup; keep it unchanged during normal NixOS or Home Manager upgrades, and only change it during a planned migration
  };

  # Add user-specific packages and configuration
  programs = {
    git = {
      userName = "Your Name";
      userEmail = "your.email@domain.com";
    };
  };
}

Create feature modules in home/newuser/features/:

mkdir -p home/newuser/features/{cli,desktop,development}

3. Link User to Hosts

The auto-discovery system will automatically link users to hosts if:

• A file home/{username}/{hostname}.nix exists
• The hostname matches an existing host configuration

4. Test User Configuration

# Build home-manager configuration
home-manager build --flake .#newuser@hostname

# Switch to new configuration
home-manager switch --flake .#newuser@hostname

Creating New Hosts

To add a new host to your configuration:

1. Create Host Directory Structure

# For a new desktop host named "mydesktop"
mkdir -p hosts/desktop/mydesktop

# For a new server host named "myserver"
mkdir -p hosts/server/myserver

# For a new laptop host named "mylaptop"
mkdir -p hosts/laptop/mylaptop

2. Create Required Configuration Files

Create hosts/{device-type}/{hostname}/default.nix:

{ self, pkgs, ... }:
{
  imports = [
    # Hardware configuration (required)
    ./hardware.nix

    # Optional: device-specific modules
    # "${self}/hosts/shared/optional/containers.nix"
    # "${self}/modules/nixos/custom-module.nix"
  ];

  # Host-specific configuration
  host = {
    device.isHeadless = false; # Set to true for servers
  };

  # Add your system configuration here
  # networking.hostName is automatically set from directory name
}

Create hosts/{device-type}/{hostname}/hardware.nix:

{ inputs, ... }:
{
  imports = [
    # Include relevant hardware modules
    inputs.nixos-hardware.nixosModules.common-cpu-amd
    inputs.nixos-hardware.nixosModules.common-pc-ssd

    # For laptops, also include:
    # inputs.nixos-hardware.nixosModules.common-pc-laptop
  ];

  # Boot configuration
  boot.loader = {
    systemd-boot.enable = true;
    efi.canTouchEfiVariables = true;
  };

  # Filesystem configuration (use disko for declarative disk setup)
  fileSystems."/" = {
    device = "/dev/disk/by-label/nixos";
    fsType = "ext4";
  };

  # Add hardware-specific configuration
}

3. Add Hardware Acceleration (Optional)

If your host supports hardware acceleration, add it to the acceleration lists in flake.nix:

accelerationHosts = {
  cuda = [
    "your-new-host"  # Add here for CUDA support
  ];
  rocm = [
    "your-amd-host"  # Add here for ROCm support
  ];
};

4. Build and Test

# Build the configuration (don't switch yet)
sudo nixos-rebuild build --flake .#your-new-host

# Test the configuration
sudo nixos-rebuild test --flake .#your-new-host

# Switch to the new configuration
sudo nixos-rebuild switch --flake .#your-new-host

Updating SOPS Rules

update-sops first regenerates managed sops-keys.nix, then regenerates .sops.yaml from repository layout. Host and home entries are sorted by name for stable output. Run it after adding, removing, or rotating a host key or home user.

Host Discovery

A host is discovered only when this file exists:

hosts/{device-type}/{hostname}/ssh_host_ed25519_key.pub

The script converts each OpenSSH public key with ssh-to-age and creates rules for:

• hosts/secrets.yaml — every discovered host
• hosts/server/secrets.yaml — every discovered server
• hosts/{device-type}/{hostname}/ — each discovered host directory

Host-specific rules also cover nested SOPS files under that host directory.

Managed Key Map

update-sops writes sops-keys.nix as a readable inventory of discovered recipients:

{
  deployer = "age1gmc8dd4mj5q0zncy5gq4lccjlq9v84t8cqnlananmxt8g0jezv6szawll8";
  homes = {
    racci = "...";
  };
  hosts = {
    server = {
      nixauth = "...";
    };
  };
}

Host recipients come from ssh_host_ed25519_key.pub. Home recipients come from home/{username}/id_ed25519.pub. The current user’s name comes from whoami; that user’s home recipient is used as the personal recipient in every generated SOPS rule. The current user must have a home public key file.

Every directory under home/, except home/shared/, gets a rule for:

home/{username}/secrets.yaml

Home directories without id_ed25519.pub still get SOPS rules, but do not get an entry in sops-keys.nix.

Common Recipients

Every generated rule starts with two always-present recipients, in this order:

1. current user’s home/{username}/id_ed25519.pub converted with ssh-to-age — personal age key
2. sops-keys.nix deployer value — automated deployer age key

The updater defines this policy in get-always-present-age-keys. Host-specific rules append that host’s age recipient. Global host rules append all applicable host recipients in the same stable order used by sops-keys.nix.

Usage

Regenerate rules:

update-sops

Check for drift without writing:

update-sops --check

By default, updater changes only sops-keys.nix and .sops.yaml. To also update recipient metadata in every encrypted SOPS file under hosts/ and home/, opt in explicitly:

update-sops --update-secrets

This runs sops updatekeys --yes for each file reported as encrypted by sops filestatus, including non-YAML formats. It can re-encrypt file metadata and requires an available SOPS decryption identity. --update-secrets cannot be combined with --check.

Using a Nix Package or NixOS Module from a Separate Fork of Nixpkgs

This guide will show you how to use a Nix package or NixOS module from a separate fork of nixpkgs.

Step 1: Define the Forked Repository

In your Nix file, define the forked repository using fetchFromGitHub function:

nixpkgs.overlays = [
  (self: super: {
    <your-package> = (import
      (pkgs.fetchzip (
        let owner = "<owner>"; branch = "<branch>"; in {
          url = "https://github.com/${owner}/nixpkgs/archive/${branch}.tar.gz";
          # Change to 52 zeros when archive needs to be redownloaded.
          sha256 = "<sha256>";
        }
      ))
      { overlays = [ ]; config = super.config; }).<your-package>;
  })
];

In this example, replace <your-package>, <owner>, <branch>, and <sha256> with the actual values from the forked repository.

Step 2: Use Packages or Modules from the Forked Repository

Now you can use packages or modules from the forked repository in your Nix expressions. For example, if you want to use a package from the forked repository, you can refer to it using the <your-package> attribute. Here’s an example:

{
  environment.systemPackages = with pkgs; [
    <your-pckage>
  ];
}

In this example, replace <your-package with the actual name of the package you want to use.

Declarative GNOME DConf

Description

When changing GNOME or GNOME extension settings, it is recommended to use dconf2nix and cherry pick its output. This allows for easy configuration using the GUI, but requires copying the settings back into the respective dconf settings in home-manager to save them.

DConf Locations

The locations for where to save DConf settings to is:

• Base.nix for standard GNOME DConf Settings.
• Extensions.nix for Extensions DConf Settings
• Per User Settings should be saved in the format of home/${username}/desktop/gnome.nix

Getting the Output

dconf2nix will be installed as part of this flakes dev shell.

Running the following will output the current dconf settings into a temporary file so you can Cherry Pick your changes.

dconf dump / | dconf2nix > dconf.nix

Using a Package/Module from a Fork

Default Development Shell

The default devenv shell in this repository includes common CLI, Nix, and setup tools used across day-to-day development.

Entering the Shell

Automatic shell entry via direnv, to enable this, run:

direnv allow

Or directly with nix:

nix develop --override-input devenv-root file+file://<path-to-nix-config>/.devenv/root

Helper Commands

The shell also exposes repository helper commands from flake/dev/scripts/. rebuild-target accepts action host, or just host; when the action is omitted it defaults to switch. Extra args are forwarded to nh / nix after --accept-flake-config, and args that start with -- must be separated with a literal --:

rebuild-target build nixmi -- --fallback
rebuild-target switch nixmi

Generated .luarc.json

Entering the default shell refreshes .luarc.json in the repository root.

The shell task manages the "workspace.library" key by:

• creating .luarc.json when missing
• ensuring the current Hyprland stub path is present
• removing stale entries containing share/hypr/stubs/
• respect and preserve any other existing keys in .luarc.json that are not managed by the shell task.

Python Development Shell

This repository contains multiple Python scripts and packages. A dedicated Python development environment is provided via devenv to simplify development of these components, by providing all necessary dependencies for proper LSP support.

Entering the Python Shell

To access the Python development environment with all required dependencies:

direnv allow
devenv shell python

Or with devenv directly:

devenv shell --file devenv.nix --shell python

Included Packages

The Python shell inherits from the default development environment and adds:

Python Runtime & Tools

• python312 - Python 3.12 interpreter
• pip - Package installer
• virtualenv - Virtual environment management
• pytest - Testing framework
• black - Code formatter
• ruff - Fast Python linter
• mypy - Static type checker

Python Libraries

Libraries are organized by the components they support:

Image Compression

• pillow - Image processing
• rich - Terminal formatting & progress bars
• python-magic - File type detection

Memory/Knowledge Systems

• pyyaml - YAML parsing
• cryptography - Encryption utilities
• anyio - Async I/O framework

I/O Guardian & Networking

• websockets - WebSocket protocol
• pystemd - Systemd D-Bus interface

Utilities

• requests - HTTP library (for Lidarr plugin updates)

Development Workflow

Testing Scripts

Run pytest on project Python files:

pytest pkgs/scripts/test_image_compressor.py -v

Code Quality

Format Python code:

nix fmt -- pkgs/scripts/compressor.py

Check types with mypy:

mypy pkgs/scripts/

Running Scripts Directly

Scripts can be executed directly in the shell:

python3 pkgs/scripts/compressor.py --help
python3 docs/preprocessor/gen-options-md.py --help

Adding New Python Dependencies

To add a new Python library:

1. Identify the python312Packages. attribute in nixpkgs
2. Add it to the packages list in /persist/nix-config/flake/dev/devenv.nix under devenv.shells.python
3. Run nix fmt flake/dev/devenv.nix to format
4. Test with nix flake check
5. Update this documentation

Example:

# In devenv.nix, add to packages list:
python312Packages.your-new-package

Troubleshooting

ModuleNotFoundError

If you see ModuleNotFoundError: No module named 'xxx', the package may not be in the python shell. Verify it’s included in the packages list in flake/dev/devenv.nix.

Python Version Mismatch

Some packages require Python 3.12. If you need a different version:

1. Modify python312 reference in flake/dev/devenv.nix
2. Update corresponding python312Packages references
3. Run nix flake check to validate

Permissions Errors with pystemd

The pystemd package requires D-Bus access. Ensure you’re running within a proper devenv session, not in a sandboxed environment.

See Also

• Main development documentation
• Nix Python packaging
• Devenv documentation

Modules Overview

Purpose

This section provides an overview of the custom NixOS and Home-Manager modules defined in this repository. These modules allow for modular and reusable configurations across different hosts and users.

Architecture / Services / Scope

Entry Points

• modules/nixos/: Contains NixOS-specific modules.
  • Core Module
    • Display Manager
    • Remote Desktop & Streaming
    • Virtualisation
  • Server Module
    • Dashboard Module
    • Network Module
    • Distributed Builds Module
    • Database Module
    • Storage Module
    • Proxy Module
    • SSH Module
  • Services
    • AI Agent
    • Huntress
    • MCPO
    • Metrics
    • Tailscale
• modules/flake/: Flake-level modules for cross-host configuration.
  • Flake Allocations
• modules/home-manager/: Contains Home-Manager-specific modules.
  • Programs
    • list-ephemeral
  • DIY & Making
  • AI Editors & Assistants
  • Hyprland

NixOS Modules — Overview

Purpose

This section covers all NixOS modules provided by this flake, including core baseline configuration, server orchestration, custom services, and AI infrastructure.

Entry Point

• Main file: modules/nixos/default.nix

Architecture / Services / Scope

Modules are categorized into directories based on their target:

• core/: Shared baselines for all hosts.
• server/: Cluster-aware server modules.
• services/: Custom NixOS services (e.g., Dashy, Tailscale).
• ai/: AI infrastructure daemons.

References

• Core Modules
• Server Modules
• Services Modules
• AI Modules

NixOS Services — Overview

Purpose

This section documents the custom NixOS service modules available in this configuration. These modules provide specialised integrations and monitoring capabilities.

Entry Point

• Main file: modules/nixos/services/default.nix

Architecture / Services / Scope

Nested service modules emit generated fragments for options, which are included in their respective documentation pages.

Operational Notes / Assumptions

• Services should be toggled per-host.

References

• AI Agent
• Huntress
• MCPO
• Metrics
• Tailscale

AI Agent — Hermes Autonomous Agent

Purpose

Autonomous AI Agent service powered by Hermes, providing intelligent task automation with security controls for code review and development tasks.

Entry Point

• Main file: ai-agent.nix
• Upstream: Hermes Agent
• Package: The module routes services.hermes-agent.package through the local pkgs.hermes-agent overlay, which carries a few upstream patches.

Options

services.ai-agent.apiServer.enable

Whether to enable the OpenAI comptable endpoint.

services.ai-agent.apiServer.host

The host/IP for the API server to bind to.

services.ai-agent.apiServer.port

The port for the API server to listen on.

services.ai-agent.apiServer.tokenReference

The sops secret attribute for the API server authentication token.

services.ai-agent.containerPostStart

Shell commands to run inside the AI agent container after startup.

A plain string runs inside the container as root via docker exec. An attrset { command = "..."; host = true; } runs on the host.

Commands to run after the AI agent container starts. Container commands get automatic retry to wait for Docker + container readiness.

services.ai-agent.dashboard.enable

Whether to enable Hermes web dashboard.

services.ai-agent.dashboard.oidc.clientId

The OIDC client ID for dashboard authentication.

services.ai-agent.dashboard.oidc.enable

Whether to enable OpenID Connect authentication for the dashboard.

services.ai-agent.dashboard.oidc.issuer

The OIDC issuer URL for dashboard authentication.

services.ai-agent.dashboard.oidc.provider

The OIDC plugin to use for dashboard authentication.

services.ai-agent.dashboard.oidc.scopes

The OIDC scopes to request for dashboard authentication.

services.ai-agent.dashboard.port

The port for the dashboard to listen on.

services.ai-agent.dashboard.publicURL

The public URL for the dashboard, used for generating links in notifications and similar. If not set, localhost URLs will be used.

If set, must be a valid URL starting with http:// or https://.

services.ai-agent.enable

Whether to enable autonomous AI Agent service.

services.ai-agent.extras.browser

Whether to enable headless browser for web scraping and automation.

services.ai-agent.extras.plugins

Whether to enable extra plugins for the agent.

services.ai-agent.extras.scraper.enable

Whether to enable web scraping and search plugins for the agent.

services.ai-agent.extras.scraper.searxEndpoint

The SearxNG endpoint to use for web search.

services.ai-agent.memory.enable

Whether to enable long-term memory

When enabled this disables the builtin user profile and memory markdown features, to nudge the agent towards using the configured long-term memory provider for all memory. .

services.ai-agent.models.brains

The smartest model to use for complex reasoning and decision-making tasks.

Used for auxiliary models:

services.ai-agent.models.compression

The model to use for compression of context, summorisation and similar tasks that don’t require reasoning. This model still needs a decently sized context window to be effective.

Used for auxiliary models:

services.ai-agent.models.primary

The primary language model to use for the AI agent.

services.ai-agent.models.provider

The model provider to use.

services.ai-agent.models.simpleton

The simpleton model to delegate tasks to that require less reasoning, basic understanding and small context windows.

Used for auxiliary models:

services.ai-agent.models.vision

The vision model to delegate image understanding tasks to.

services.ai-agent.platform.discord.allowedUsers

A list of Discord user IDs that the agent is allowed to interact with.

services.ai-agent.platform.discord.enable

Whether to enable Discord as a messaging channel.

services.ai-agent.platform.discord.homeChannel

The Discord channel ID to use as the home channel for the agent.

services.ai-agent.platform.discord.tokenReference

The sops secret attribute for the Discord bot token.

services.ai-agent.platform.hassio.enable

Whether to enable Home Assistant as a tool and notification channel.

services.ai-agent.platform.hassio.tokenReference

The sops secret attribute for the Home Assistant long-lived access token.

services.ai-agent.platform.hassio.url

The URL for the Home Assistant instance, including the scheme.

services.ai-agent.platform.webhook.port

The port for the webhook listener to listen on.

services.ai-agent.settings

Hermes config to merge into services.hermes-agent.settings.

This is a local option that merges correctly across feature toggles. The upstream services.hermes-agent.settings uses lib.recursiveUpdate for its config type, which replaces lists instead of concatenating them, so separate blocks would clobber each other. This option deep-merges with list concatenation and is emitted once as the final value of services.hermes-agent.settings.

services.ai-agent.voice.enable

Whether to enable voice input and output using the TTS and STT.

services.ai-agent.voice.wyoming-stt.enable

Whether to enable use existing Wyoming faster-whisper server for STT instead of running a separate Whisper instance.

services.ai-agent.voice.wyoming-stt.host

The host of the Wyoming faster-whisper server.

services.ai-agent.voice.wyoming-stt.port

The port of the Wyoming faster-whisper server.

Architecture / Services / Scope

The module enables services.hermes-agent (running inside a Docker container) and adds optional components on top:

• Dashboard — a separate hermes-dashboard systemd service runs docker exec into the hermes-agent container to serve the dashboard under the hermes user. Environment files configured via services.hermes-agent.environmentFiles are loaded by systemd’s EnvironmentFile directive (read as root) and passed into the container via docker exec --env-file. The dashboard stays local by default and does not open a browser.
• Voice & STT — optional voice input and output. With services.ai-agent.voice.wyoming-stt.enable, Hermes reuses an existing Wyoming faster-whisper server instead of running a separate Whisper instance: HERMES_LOCAL_STT_COMMAND is set to invoke wyoming-transcribe, which sends audio over the Wyoming protocol and returns the transcript. No second Whisper process needed.
• OIDC Authentication — optional OpenID Connect authentication for the dashboard using a public PKCE client (no client_secret). The client ID is a public identifier — it does not need to be stored as a secret. The module generates a HERMES_DASHBOARD_OIDC_ENV environment file with the OIDC settings, loaded by the hermes-dashboard service.
• Memory (Mnemosyne) — with services.ai-agent.memory.enable, the memory provider switches from the built-in user profile (USER.md injection) to Mnemosyne, a local SQLite-backed memory system with semantic recall (SQLite with FTS5 hybrid ranking + vector search).

Secrets

Hermes requires API keys via environment files. Configure via sops-nix:

sops = {
  secrets = {
    "AI_AGENT/OPENROUTER_API_KEY" = { };
  };
  templates."HERMES_ENV".content = ''
    OPENROUTER_API_KEY=${config.sops.placeholder."AI_AGENT/OPENROUTER_API_KEY"}
  '';
};

services.hermes-agent.environmentFiles = [ config.sops.templates."HERMES_ENV".path ];

The module itself declares secrets for the enabled optional components:

• API server token (default AI_AGENT/API_SERVER_TOKEN) — authenticates the OpenAI-compatible API server.
• Discord bot token (default AI_AGENT/DISCORD_BOT_TOKEN) — Discord platform.
• Home Assistant token (default AI_AGENT/HASSIO_TOKEN) — Home Assistant platform.
• Dashboard OIDC uses a public PKCE client, so no client secret is stored.

Operational Notes / Assumptions

Usage Example

{ ... }: {
  services.ai-agent = {
    enable = true;
  };
}

Voice & STT

Enable voice input and output with services.ai-agent.voice.enable = true;. To reuse an existing Wyoming faster-whisper server instead of running a separate Whisper instance:

{ ... }: {
  services.ai-agent = {
    enable = true;
    voice = {
      enable = true;
      wyoming-stt.enable = true;
    };
  };
}

Dashboard & OIDC

Enable the web dashboard with services.ai-agent.dashboard.enable = true;, and OIDC authentication with services.ai-agent.dashboard.oidc.enable = true;:

{ ... }: {
  services.ai-agent = {
    enable = true;
    dashboard = {
      enable = true;
      publicURL = "https://dashboard.example.com";
      oidc = {
        enable = true;
        provider = "self-hosted";
        issuer = "https://auth.example.com/oauth2/openid/hermes";
        clientId = "hermes";
        scopes = [ "openid" "profile" "email" ];
      };
    };
  };
}

Memory (Mnemosyne)

Enable long-term memory with services.ai-agent.memory.enable = true;:

{ ... }: {
  services.ai-agent = {
    enable = true;
    memory.enable = true;
  };
}

References

• Hermes Agent
• Mnemosyne

Huntress — Managed EDR

Purpose

Managed EDR (Endpoint Detection and Response) platform that protects systems by detecting malicious footholds used by attackers.

Entry Point

• Main file: huntress.nix
• Upstream: Huntress Managed EDR

Options

services.huntress.accountKeyFile

The account key for the Huntress agent.

services.huntress.enable

Whether to enable Huntress service.

services.huntress.organisationKeyFile

The organisation key for the Huntress agent.

services.huntress.package

The Huntress package to use.

Architecture / Services / Scope

The module runs a single huntress-agent systemd service as root. The agent configuration is generated at /etc/huntress/agent_config.yaml during the service’s preStart phase: a default configuration is written on first start, after which the account and organisation keys are merged in using yaml-merge.

Secrets

• accountKeyFile — Huntress account key, loaded into the service via systemd LoadCredential.
• organisationKeyFile — Huntress organisation key, loaded into the service via systemd LoadCredential.

Operational Notes / Assumptions

• Both keys are validated during preStart; the service fails to start if either is empty.
• The merged configuration persists across restarts in /etc/huntress/agent_config.yaml.

Usage Example

{ config, ... }: {
  services.huntress = {
    enable = true;
    accountKeyFile = config.sops.secrets.huntress_account_key.path;
    organisationKeyFile = config.sops.secrets.huntress_org_key.path;
  };
}

References

• Huntress Managed EDR

MCPO — Model Context Protocol Orchestrator

Purpose

Orchestrates Model Context Protocol (MCP) servers, providing a centralized way to manage and expose multiple MCP servers.

Entry Point

• Main file: mcpo.nix
• Upstream: MCPO GitHub Repository

Options

services.mcpo.apiTokenFile

Path to a file containing the API token for the mcpo service. This file will be exposed to the service through a systemd credential named “apiToken”.

services.mcpo.configuration

This option has no description.

services.mcpo.configuration.<name>.args

Arguments to pass to the command.

services.mcpo.configuration.<name>.command

Command to render the config file.

services.mcpo.configuration.<name>.headers

Headers to pass to the command.

services.mcpo.configuration.<name>.type

This option has no description.

services.mcpo.configuration.<name>.url

This option has no description.

services.mcpo.enable

Whether to enable mcpo (Model Context Protocol Orchestrator) service.

services.mcpo.environment

Additional environment variables for the service.

services.mcpo.extraPackages

Additional packages to include in the service’s PATH.

services.mcpo.helpers

Helper functions for constructing mcpo server command blocks.

services.mcpo.package

Package providing the mcpo executable.

Architecture / Services / Scope

MCPO runs as a DynamicUser with a state directory at /var/lib/mcpo. The configuration is rendered via sops.templates and loaded into the service via systemd credentials. The service’s PATH includes bash, nodejs, and uv by default to support various MCP server types; additional packages can be added with services.mcpo.extraPackages.

Secrets

• apiTokenFile (optional) — API token exposed to the service as the systemd credential apiToken.
• Server configuration and environment are rendered through sops templates (mcpoConfiguration, mcpoEnvironment) and consumed via LoadCredential / EnvironmentFile.

Operational Notes / Assumptions

Usage Example

{ config, ... }: {
  services.mcpo = {
    enable = true;
    configuration = {
      everything = config.services.mcpo.helpers.npxServer "@modelcontextprotocol/server-everything";
    };
  };
}

Package Patches

• mcpo-union-repr-compat.patch — Applied via overlay in overlays/patches/. Upstream test src/mcpo/tests/test_main.py asserts Union repr starts with "typing.Union[", but Python 3.12+ may stringify unions as str | float. Patch uses get_origin(result_type) is Union instead. Build/test compatibility only; no runtime impact.

References

• MCPO GitHub Repository

Metrics & Hacompanion — Metrics Collection & Home Assistant Integration

Purpose

Comprehensive metrics collection and integration with Home Assistant via hacompanion.

Entry Point

• Main file: metrics.nix
• Upstream: Hacompanion GitHub Repository

Options

services.metrics.enable

Whether to enable Metrics collection service.

services.metrics.hacompanion.enable

Whether to enable Enable Home Assistant Companion service.

services.metrics.hacompanion.script

This option has no description.

services.metrics.hacompanion.script.<name>.device_class

The device class for the script in Home Assistant.

services.metrics.hacompanion.script.<name>.icon

The icon to use for the script in Home Assistant.

services.metrics.hacompanion.script.<name>.name

The name of the script as it will appear in Home Assistant.

services.metrics.hacompanion.script.<name>.path

The path to the script to execute.

services.metrics.hacompanion.script.<name>.type

The type of the script in Home Assistant.

services.metrics.hacompanion.script.<name>.unit_of_measurement

The unit of measurement for the script in Home Assistant.

services.metrics.hacompanion.sensor.audio_volume.enable

Whether to enable Enable the audio_volume sensor.

services.metrics.hacompanion.sensor.companion_running.enable

Whether to enable Enable the companion_running sensor.

services.metrics.hacompanion.sensor.cpu_temp.enable

Whether to enable Enable the cpu_temp sensor.

services.metrics.hacompanion.sensor.cpu_usage.enable

Whether to enable Enable the cpu_usage sensor.

services.metrics.hacompanion.sensor.load_avg.enable

Whether to enable Enable the load_avg sensor.

services.metrics.hacompanion.sensor.memory.enable

Whether to enable Enable the memory sensor.

services.metrics.hacompanion.sensor.online_check.enable

Whether to enable Enable the online_check sensor.

services.metrics.hacompanion.sensor.power.enable

Whether to enable Enable the power sensor.

services.metrics.hacompanion.sensor.uptime.enable

Whether to enable Enable the uptime sensor.

services.metrics.hacompanion.sensor.webcam.enable

Whether to enable Enable the webcam sensor.

services.metrics.hacompanion.storage

Storage devices and ZFS pools to monitor

services.metrics.hacompanion.storage.<name>.name

The pretty display name for this storage device in Home Assistant.

services.metrics.hacompanion.storage.<name>.sensors.avail

Whether to enable Enable available space sensor.

services.metrics.hacompanion.storage.<name>.sensors.read

Whether to enable Enable read speed sensor.

services.metrics.hacompanion.storage.<name>.sensors.temperature

Whether to enable Enable temperature sensor.

services.metrics.hacompanion.storage.<name>.sensors.used

Whether to enable Enable used space sensor.

services.metrics.hacompanion.storage.<name>.sensors.write

Whether to enable Enable write speed sensor.

services.metrics.hacompanion.test

This option has no description.

services.metrics.upgradeStatus.enable

Whether to enable Enable Upgrade Status service.

services.metrics.upgradeStatus.uptimeKuma.enable

Whether to enable Enable Uptime Kuma tracking for Upgrade Status.

Architecture / Services / Scope

• hacompanion — Home Assistant companion daemon that publishes system sensors (CPU, memory, storage, uptime, and more) to Home Assistant. It uses a generated TOML configuration file and loads the Home Assistant API token from sops.secrets.HACOMPANION_ENV.
• upgradeStatus — reports NixOS upgrade state (idle / running / failed / dirty). When upgradeStatus.uptimeKuma.enable is set, it also sends heartbeat notifications to Uptime Kuma on successful upgrades.

Secrets

• HACOMPANION_ENV — Home Assistant API token, declared in hosts/secrets.yaml and consumed via EnvironmentFile.
• UPGRADE_STATUS_ID — Uptime Kuma push monitor ID (host-level secrets.yaml), required when upgradeStatus.uptimeKuma.enable is set.

Operational Notes / Assumptions

• Hacompanion runs as a DynamicUser with its state in /var/lib/hacompanion.
• The upgradeStatus feature can integrate with Uptime Kuma to provide heartbeat notifications for successful system upgrades.

Usage Example

{ ... }: {
  services.metrics.hacompanion = {
    enable = true;
    sensor.cpu_temp.enable = true;
    sensor.memory.enable = true;
    storage.main = {
      name = "Main OS Drive";
      sensors.used = true;
    };
  };
}

References

• Hacompanion GitHub Repository

Tailscale — Tag Management Extensions

Purpose

Extensions to the standard NixOS Tailscale module, providing easier tag management.

Entry Point

• Main file: tailscale.nix

Options

services.tailscale.tags

Additional tags to advertise for this device.

Tags are used for access control and routing in Tailscale. See https://tailscale.com/kb/1018/tags/ for more information.

Architecture / Services / Scope

This module extends the standard NixOS services.tailscale module by automatically constructing the --advertise-tags flag from the configured services.tailscale.tags list.

Operational Notes / Assumptions

• Ensure the device has the necessary permissions in your Tailscale ACLs to apply the requested tags.

Usage Example

{ ... }: {
  services.tailscale = {
    enable = true;
    tags = [ "server" "internal" ];
  };
}

References

• Tailscale Tags

Core Module

Documents shared NixOS core modules used across hosts.

Purpose

modules/nixos/core/ contains reusable host-level defaults and feature modules.

It also defines top-level baseline options under core.* that control this shared behavior for most hosts.

Options

core.activation.enable

Whether to enable report diff on activation.

core.audio.enable

Whether to enable Enable audio support.

core.auto-upgrade.enable

Whether to enable auto-upgrade.

core.auto-upgrade.hostName

The hostName to use for auto-upgrade

core.bluetooth.enable

Whether to enable Enable Bluetooth support.

core.containers.enable

Whether to enable container support.

core.defaultGroups

Additional groups to add all users to by default.

core.display-manager.enable

Whether to enable display manager configuration.

core.enable

Whether to enable Enable core features.

core.gaming.enable

Whether to enable Enable gaming features.

core.hm-helper._1password.enableCli

Whether to enable Enable 1Password Cli support.

core.hm-helper._1password.enableGUI

Whether to enable Enable 1Password GUI support.

core.hm-helper.enable

Whether to enable Home Manager helper functions.

core.hm-helper.ff2mpv.enable

Whether to enable Enable ff2mpv native messaging host for Firefox..

core.hm-helper.hmUsers

List of Home Manager users that also exist in config.users.users.

core.hm-helper.kde-connect.enable

Whether to enable Enable KDE Connect firewall rules if any user has KDE Connect enabled..

core.hm-helper.nautilus.enable

Whether to enable Enable Nautilus extensions and integration helpers..

core.locale.enable

Whether to enable locale configuration.

core.network.enable

Whether to enable Enable network support.

core.networking.enable

Whether to enable opinionated networking defaults.

core.networking.tailscale.enable

Whether to enable tailscale configuration.

core.openssh.enable

Whether to enable OpenSSH server and client opinionated configuration.

core.openssh.hostPrivateKeyPath

Canonical path of the provisioned ed25519 host private key used by OpenSSH, SOPS age decryption, and server-to-server SSH.

core.printing.enable

Whether to enable printing support.

core.remote.enable

Whether to enable remote features.

core.remote.remoteDesktop

This option has no description.

core.remote.remoteDesktop.enable

Whether to enable remote desktop.

core.remote.remoteDesktop.startCommand

Command to start remote desktop session.

core.remote.streaming

This option has no description.

core.remote.streaming.enable

Whether to enable remote streaming.

core.security.enable

Whether to enable security features.

core.security.userLimit

The maximum number of open files per user.

This is used to set the limits for both PAM and systemd.

core.sops.enable

Whether to enable SOPS auto configuration.

core.sops.hostSecretsFile

Where the SOPS secret file of this host is located in the flake.

core.stylix.enable

Whether to enable Stylix configuration.

core.virtualisation.bridgeInterface

Bridge interface used for libvirt networking.

core.virtualisation.cpuCores

Total CPU core/thread count used for isolation helpers. Must be >= 4.

core.virtualisation.enable

Whether to enable virtualisation support.

core.virtualisation.externalInterface

Physical interface attached to bridge.

core.virtualisation.gpu.audio

PCI address for passthrough GPU audio device.

core.virtualisation.gpu.video

PCI address for passthrough GPU video device.

core.virtualisation.isolatedGuests

List of guests to apply isolation helpers to.

core.virtualisation.vmUsers

Users that should receive kvm and libvirtd group membership for VM management.

core.wsl.enable

Whether to enable WSL specific configurations, optimisations, and fixes.

core.wsl.user

The default user to use for WSL.

Architecture / Services / Scope

Baseline Behaviour

When core.enable is true, module applies shared defaults from modules/nixos/core/default.nix:

• sets services.dbus.implementation = "broker",
• enables PipeWire audio stack and disables PulseAudio when core.audio.enable is on,
• enables Bluetooth stack, Blueman, and persisted Bluetooth state when core.bluetooth.enable is on,
• enables NetworkManager and adds network to shared default groups when core.network.enable is on, and
• on non-headless hosts, adds video and i2c groups and enables dleyna, gnome-keyring, udisks2, colord, xserver.updateDbusEnvironment, and polkit.

Audio baseline also enables security.rtkit, adds audio, pipewire, and rtkit groups, installs udev rules for rtc0 and hpet, and sets PAM limits for realtime audio workloads.

Bluetooth baseline unblocks rfkill during activation and persists /var/lib/bluetooth.

Usage Example

{ ... }: {
  core = {
    enable = true;
    audio.enable = true;
    bluetooth.enable = true;
    network.enable = true;
  };
}

References

• Activation
• Auto Upgrade
• Containers
• Display Manager
• Gaming
• Generators
• Default Groups
• Locale
• Nix
• OpenSSH
• Printing
• Remote Access
• Security
• SOPS
• Stylix
• Virtualisation
• WSL

Operational Notes / Assumptions

These modules are imported through modules/nixos/core/default.nix. Most feature pages document their own core.<name> option namespaces, while some baseline modules such as Nix apply unconditionally once imported.

Activation

Reports system generation changes during NixOS activation.

Purpose

Provide visibility into what changed between system generations by comparing the previous and newest generation during NixOS activation, so each upgrade shows a readable package and closure diff.

Entry Point

• Main file: activation.nix

Architecture / Services / Scope

When enabled, the module installs an activation script (system.activationScripts.report-changes) that:

• locates the previous and newest system profile generations under /nix/var/nix/profiles,
• resolves both links to their store paths, and
• runs nvd diff between them.

If no previous generation exists yet, the script does nothing.

Operational Notes / Assumptions

• Diff output is informational only; the script tolerates a non-zero nvd exit so activation never fails because of a diff error.
• Default follows top-level core.enable, so most hosts get generation diff reporting automatically.

Auto Upgrade

Schedules automatic NixOS upgrades from flake host outputs.

Purpose

Keep hosts current by rebuilding them from the flake on a schedule, with randomized start times to spread load across hosts and resource limits so upgrades do not starve interactive workloads.

Entry Point

• Main file: auto-upgrade.nix

Options

core.auto-upgrade.enable

Whether to enable auto-upgrade.

core.auto-upgrade.hostName

The hostName to use for auto-upgrade

Architecture / Services / Scope

When enabled, the module configures system.autoUpgrade to rebuild the host from the configured GitHub flake output for that host, using the --refresh, --accept-flake-config, and --no-update-lock-file flags, and applies CPU and IO resource limits to nixos-upgrade.service.

Operational Notes / Assumptions

• Auto-upgrade only turns on when the flake has a revision (self.rev), meaning the repository is in a clean, revisioned state. Dirty working trees or non-revisioned evaluations leave system.autoUpgrade.enable = false.
• Upgrades always target the GitHub flake source, not the local checkout.

Containers

Enables Docker-based container runtime defaults.

Purpose

Provide a Docker-backed container runtime for workloads that still rely on Docker-specific features, with automatic image pruning and persistent state.

Entry Point

• Main file: containers.nix

Options

core.containers.enable

Whether to enable container support.

Architecture / Services / Scope

When enabled, the module:

• enables virtualisation.docker with the default Docker package,
• enables CDI device support in the Docker daemon,
• enables weekly automatic image pruning,
• sets virtualisation.oci-containers.backend = "docker",
• adds docker to core.defaultGroups, and
• persists Docker state directories under /var/lib/docker (overlay storage, images, volumes, containers, containerd, and buildkit data).

Operational Notes / Assumptions

• Docker is intentionally preferred because current workloads still need features not covered by Podman or podman-compose.
• Users receive Docker access through the shared core.defaultGroups handling.

Display Manager

Configures the display manager for graphical sessions on desktop and laptop hosts.

Purpose

Provide a consistent, terminal-based login experience via greetd and tuigreet on hosts with a display.

Entry Point

• Main file: display-manager.nix

Options

core.display-manager.enable

Whether to enable display manager configuration.

Architecture / Services / Scope

Enabled by default on hosts where host.device.isHeadless = false. The greetd greeter runs as the greeter user and:

• shows the current time,
• remembers the last logged-in user and last selected session, and
• exposes both Wayland and X11 session directories when services.displayManager.sessionPackages is non-empty.

Greeter cache is persisted to /var/cache/tuigreet through host.persistence.directories.

Operational Notes / Assumptions

• Both Wayland (wayland-sessions) and X11 (xsessions) session paths are built dynamically from installed session packages, so adding a new session package is enough to make it appear in the greeter.

Gaming — Gaming, VR, and Steam-focused desktop features

Purpose

Enable a desktop gaming stack around Steam, 32-bit graphics, Android ADB tooling, and WiVRn VR streaming, plus firewall, udev, and optional Decky Loader lifecycle integration.

Entry Point

• Main file: gaming.nix

Options

core.gaming.enable

Whether to enable Enable gaming features.

Architecture / Services / Scope

When enabled, module:

• adds adbusers to core.defaultGroups,
• enables hardware.steam-hardware and 32-bit graphics support,
• installs android-tools,
• enables Steam with Steam Deck style launch arguments, extest, xwayland-run/xwininfo extras, and proton-ge-bin compatibility,
• opens Steam Remote Play and local transfer firewall rules,
• enables WiVRn with highPriority, OpenXR runtime import, firewall access, and JSON config,
• installs udev rules for PlayStation controller, Oculus Quest, and tty ACM devices, and
• overlays gamescope-session for 4K resolution and wider refresh limits.

Firewall ports opened: UDP 41492, 9943, 9944 plus TCP 8082, 9943, 9944, 24070.

Decky Loader Integration

If config.jovian.decky-loader.enable is true, module additionally:

• prevents decky-loader.service from auto-starting at boot,
• adds Polkit rule so active local user can start and stop decky-loader.service, and
• when Home Manager is present, installs user service that polls Steam PID file, starts Decky Loader once Steam is running, and stops it after Steam exits.

WiVRn Socket Activation

WiVRn is activated on-demand through systemd user socket activation instead of running for the full session.

• systemd.user.sockets.wivrn listens on %t/wivrn/comp_ipc (UNIX socket, mode 0770).
• Socket is WantedBy=default.target, so it’s available throughout the session, but WiVRn itself only starts when a client connects.
• Service env override: IPC_EXIT_ON_DISCONNECT=on — WiVRn exits after client disconnects.
• Steam’s OpenXR runtime path resolves to the socket; activating a SteamVR/OpenXR game triggers socket activation.
• Parent dir created with 0750, socket with 0770.

Operational Notes / Assumptions

• Module assumes desktop-class host with graphics stack and Steam support.
• WiVRn config uses NVENC H.265 encoder entries and enables wayvr as application.
• Some extra behavior only appears when related modules already exist, such as Jovian Decky Loader and Home Manager.

Generators

Groups

Locale

Sets shared timezone and locale defaults.

Purpose

Provide opinionated regional defaults for timezone and locale so all hosts start from a consistent baseline without forcing per-host overrides.

Entry Point

• Main file: locale.nix

Options

core.locale.enable

Whether to enable locale configuration.

Architecture / Services / Scope

The module applies an Australian timezone default and enables Australian and US English UTF-8 locales.

Operational Notes / Assumptions

• Module is enabled by default.
• Because settings use mkDefault, the module acts as a baseline rather than a hard override.

Nix

Defines shared Nix daemon, cache, and registry defaults.

Purpose

Establish global Nix configuration for every host in the flake: overlays, state version, trusted users, experimental features, binary caches, garbage collection, registry-derived nixPath, plus automatic uploads to the remote Attic cache.

Entry Point

• Main file: nix.nix

Architecture / Services / Scope

The module applies shared baseline configuration directly (no core.* options). It:

• installs the nix4vscode overlay,
• sets system.stateVersion from the state.version file at the flake root,
• configures trusted users, automatic store optimisation, experimental features, substituters and trusted public keys for the project’s binary caches, daily automatic GC, and a nixPath derived from config.nix.registry.

It also:

• enables services.angrr to retain recent system profiles, and
• creates systemd.services.attic-watch-store, which waits for network-online.target, restarts on failure, logs into Attic using a SOPS-managed cache push key, and watches the store for uploads.

Secrets

The module declares the SOPS secret CACHE_PUSH_KEY (from hosts/secrets.yaml) and restarts attic-watch-store.service when it changes. This key authenticates automatic uploads to the remote Attic cache.

Operational Notes / Assumptions

• Because the module has no enable flag, it is always active and applied to all hosts.
• attic-watch-store depends on sops.secrets.CACHE_PUSH_KEY from hosts/secrets.yaml.
• services.angrr keeps a bounded set of recent system profile generations.

OpenSSH

Configures opinionated SSH server and client defaults.

Purpose

Provide a hardened, consistent SSH experience across hosts: ed25519-only host keys, no password authentication, automatically generated known-host entries, PAM ssh-agent authentication, and GatewayPorts = "clientspecified" so clients may request non-loopback forwarding binds when needed. That forwarding flexibility can expose tunnels beyond localhost if the client explicitly asks for it.

Entry Point

• Main file: openssh.nix

Options

core.openssh.enable

Whether to enable OpenSSH server and client opinionated configuration.

core.openssh.hostPrivateKeyPath

Canonical path of the provisioned ed25519 host private key used by OpenSSH, SOPS age decryption, and server-to-server SSH.

Architecture / Services / Scope

When enabled, the module:

• enables services.openssh with socket activation disabled so SSH runs as a traditional always-on service (avoiding disconnects during nixos-rebuild switch over SSH),
• disables password authentication and sets PermitRootLogin = "prohibit-password",
• configures the ed25519 host key from core.openssh.hostPrivateKeyPath, persists that file via host.persistence.files, and publishes the matching public key at /etc/ssh/ssh_host_ed25519_key.pub,
• enables security.pam.sshAgentAuth,
• adds the current host’s public host key to root’s authorized keys, and
• generates programs.ssh.knownHosts entries for every host in outputs.nixosConfigurations.

Client configuration restricts host key algorithms and accepted public key types to ssh-ed25519.

Operational Notes / Assumptions

• Module expects a matching host public key file to exist in the flake for each host.
• The current host gets localhost as an extra known-host alias in the generated SSH client config.
• Root authorization uses host key material from the flake, not per-user login keys.
• Socket activation is disabled (startWhenNeeded = false): the default NixOS setup spawns per-connection sshd@...service instances, and restarting them during a configuration switch disconnects active SSH sessions. An always-on service prevents remote disconnection during nixos-rebuild switch.

Printing

Enables shared printer support for workstation-class NixOS hosts.

Purpose

Provide CUPS printing and common printer drivers on non-server, non-virtual hosts so local and network printing work out of the box.

Entry Point

• Main file: printing.nix

Options

core.printing.enable

Whether to enable printing support.

Architecture / Services / Scope

When both top-level core.enable and core.printing.enable are on, the module:

• enables services.printing with HP and Gutenprint driver stacks plus Brother colour laser driver packages, and
• adds lp to core.defaultGroups.

Operational Notes / Assumptions

• Module does not activate unless top-level core.enable is also enabled.
• Default is tuned for physical desktop or laptop systems where local or network printer access is expected.
• lp group membership is granted through the shared core.defaultGroups handling.

Remote Access — Optional remote desktop and game-streaming capabilities for desktop hosts

Purpose

Expose the host remotely through two independent sub-features: Remote Desktop (xrdp) for full desktop access over RDP, and Streaming (Sunshine) for low-latency game or desktop streaming.

Entry Point

• Main file: remote.nix

Options

core.remote.enable

Whether to enable remote features.

core.remote.remoteDesktop

This option has no description.

core.remote.remoteDesktop.enable

Whether to enable remote desktop.

core.remote.remoteDesktop.startCommand

Command to start remote desktop session.

core.remote.streaming

This option has no description.

core.remote.streaming.enable

Whether to enable remote streaming.

Architecture / Services / Scope

When core.remote.enable = true:

• remoteDesktop.enable turns on services.xrdp, sets defaultWindowManager, and opens firewall for RDP.
• streaming.enable turns on services.sunshine, opens firewall for TCP 47989, and sets capSysAdmin = true.
• Sunshine does not run continuously. A socket-activated TCP proxy on port 47989 starts Sunshine on-demand when a client connects.
• When the client disconnects and no new connection arrives for 5 minutes, the proxy exits and Sunshine stops.
• if Home Manager is present, streaming also persists .config/sunshine through shared Home Manager module.

Hyprland Integration

When both core.remote.streaming.enable and programs.hyprland.enable are true, module additionally:

• sets services.sunshine.settings.output_name,
• adds two Sunshine application entries named Shared Desktop and Exclusive Desktop,
• creates headless output at login via Home Manager, and
• keeps HEADLESS-1 disabled by default until Sunshine prep commands enable it.

Lua Mode Handling

If Home Manager Hyprland is in Lua mode (wayland.windowManager.hyprland.configType = "lua"), the shared module uses Lua-safe equivalents:

• Startup hook: settings.on with hyprland.start event triggers hyprctl output create headless.
• Monitor rule: { output = "HEADLESS-1"; disabled = true; }
• Screencopy permission: routed through wayland.windowManager.hyprland.custom-settings.permission.screenCopy, which handles both Lua and hyprlang modes automatically.

The socket proxy and Hyprland monitor helpers are shipped together in the shared sunshine-tools package so Sunshine startup and prep/undo hooks reuse one tested implementation across hosts.

On-Demand Activation & Idle Stop

Sunshine stays on its standard port family rooted at TCP/UDP 47989–47990+ (no port-family offset). External inbound TCP 47989 is firewall-redirected to internal proxy port 48989. The proxy wakes Sunshine and forwards to 127.0.0.1:47989.

Dependency Model

sunshine-proxy.socket (:48989)
    ↓ activates
sunshine-proxy.service  ──bindsTo──→  sunshine.service (:47989)

No cycle: proxy starts Sunshine, proxy bindsTo Sunshine (proxy dies if Sunshine fails), Sunshine uses StopWhenUnneeded (stops when proxy exits).

Firewall Flow

External client → TCP :47989
    ↓ (NAT PREROUTING REDIRECT)
Local port :48989
    ↓ (conntrack ctorigdstport 47989 match → nixos-fw-accept)
sunshine-proxy.socket
    ↓
sunshine-proxy.service → sunshine.service (:47989)

Redirect covers only inbound network traffic. Locally-originated traffic to :47989 (e.g. from Moonlight running on the same machine) is unaffected.

Operational Notes / Assumptions

• Two sub-features are independent. You can enable streaming without RDP, or RDP without streaming.
• Sunshine persistence and Hyprland settings are only added when Home Manager is present in system configuration.
• Hyprland-specific Sunshine application entries are only added when both streaming and Hyprland are enabled.

Caveats

• No LAN discovery while idle. Sunshine needs to run for mDNS/SSDP advertisements to appear on LAN. While stopped (idle), clients will not auto-discover the host. Users must add the host manually by IP/hostname in Moonlight or use a previously-added host entry (Moonlight remembers known hosts).
• TCP wake only. This proxy covers the control/initial TCP connection on 47989. Sunshine’s UDP audio/video streams (standard port range) will only work after Sunshine runs. Since Sunshine sets up its UDP sockets itself after startup, no UDP wake is needed in practice (the rendezvous happens over TCP first).
• Delayed first connect. The first TCP connection may stall ~1–2 seconds while Sunshine starts up. Clients (Moonlight) retry or timeout gracefully.
• Firewall. Sunshine opens its standard ports via openFirewall. The redirect only touches TCP 47989 for the wake path. No port-family offset anymore — all media/data ports remain at standard values.
• Redirect scope. The firewall redirect applies to inbound network traffic only. Local loopback connections to :47989 bypass the redirect and reach Sunshine directly if it is already running.

Security — Shared host security defaults

Purpose

Enable baseline host security: sudo-rs, TPM2 support, Polkit, kernel protection flags, and open-file limits for users.

Entry Point

• Main file: security.nix

Architecture / Services / Scope

When enabled, module:

• enables sudo-rs in place of sudo, restricted to the wheel group,
• enables TPM2 and Polkit,
• enables kernel image protection while leaving lockKernelModules off,
• sets PAM and user systemd service open-file limits from core.security.userLimit, and
• raises fs.file-max to a multiple of userLimit.

Operational Notes / Assumptions

• Module leaves security.lockKernelModules = false even while enabling other hardening defaults.
• userLimit affects both PAM sessions and user systemd services, keeping file descriptor limits aligned.

SOPS — Shared SOPS and age decryption defaults

Purpose

Provide a shared baseline for SOPS-managed secrets on every host: point sops-nix at the host’s secrets file and teach age to use the host’s provisioned SSH keys.

Entry Point

• Main file: sops.nix

Architecture / Services / Scope

When enabled, module:

• imports sops-nix (skipped when function argument importExternals = false),
• sets sops.defaultSopsFile to core.sops.hostSecretsFile,
• builds sops.age.sshKeyPaths from core.openssh.hostPrivateKeyPath first, then appends configured ed25519 OpenSSH host keys without duplicating the canonical path.

Operational Notes / Assumptions

• Default age key path is core.openssh.hostPrivateKeyPath.
• Only ed25519 entries from config.services.openssh.hostKeys are appended to the age key paths.
• Secrets file defaults to secrets.yaml inside the host directory, overridable via core.sops.hostSecretsFile.

Stylix — Shared system theme defaults via Stylix

Purpose

Apply a consistent dark theme across graphical hosts by importing Stylix and enabling dark Tokyo Night theming by default.

Entry Point

• Main file: stylix.nix

Architecture / Services / Scope

When enabled, module:

• imports stylix (skipped when function argument importExternals = false),
• enables Stylix with dark polarity, and
• selects the Tokyo Night dark Base16 scheme from the tinted-schemes input.

Operational Notes / Assumptions

• Intended for graphical (non-headless) hosts; enabled by default there.
• Theme source comes from the tinted-schemes input.

Virtualisation — libvirt, VFIO passthrough, bridge networking, and guest isolation helpers

Purpose

Enable libvirt/QEMU virtualisation with VFIO GPU passthrough, Looking Glass shared memory, bridge networking, custom OVMF firmware metadata, and per-guest isolation helpers that reserve host CPUs, detach GPUs, and block host sleep while guests run.

Entry Point

• Main file: virtualisation.nix

Architecture / Services / Scope

When enabled, module:

• imports external virtualisation helpers from crtified.modules.virtualisation.nix and ../desktop/vfio.nix,
• enables virtualisation.libvirtd, Spice USB redirection, and services.spice-autorandr,
• enables VFIO with AMD IOMMU, disableEFIfb, and the configured GPU devices,
• configures Looking Glass shared memory file owned by the libvirt group,
• adds virt-manager, virtiofsd, virtio-win, and win-spice to system packages,
• sets LIBVIRT_DEFAULT_URI to qemu:///system,
• creates bridge networking with DHCP on bridgeInterface and externalInterface enslaved into the bridge,
• adds kvmfr kernel module package and modprobe config,
• installs udev rule for /dev/kvmfr access, and
• persists libvirt and swtpm state under host.persistence.directories.

Isolation and Hook Helpers

For each guest in core.virtualisation.isolatedGuests, module creates libvirt hook entries backed by the shared virtualisation-tools package that:

• restrict host user.slice, system.slice, and init.scope CPU sets during guest startup,
• restore full CPU set when guest stops,
• for <guest>-single, detach GPU and stop display-related services before launch, and
• reattach GPU, reload drivers, restart saved services, and rebind VT consoles after shutdown.

It also creates libvirt-nosleep@<guest> service that uses systemd-inhibit to block sleep while guest is running. Guest-specific CPU ranges are passed through tiny generated wrappers, while shared hook logic stays in the packaged helpers.

Firmware and Persistence

Module extends libvirt startup to populate /run/libvirt/nix-ovmf with secure-boot and Microsoft-enrolled OVMF firmware files, then publishes matching firmware JSON metadata under /var/lib/qemu/firmware.

Persisted paths include:

• /var/lib/libvirt/qemu
• /var/lib/libvirt/images
• /var/lib/libvirt/swtpm
• /var/lib/libvirt/secrets
• /var/lib/swtpm-localca

Operational Notes / Assumptions

• core.virtualisation.cpuCores is validated by both option type and assertion, so values below 4 fail evaluation.
• vmUsers is opt-in. Only listed users receive kvm and libvirtd access.
• Hook generation assumes guest naming convention where <name>-single means single-GPU passthrough workflow.

WSL — Windows Subsystem for Linux integration and fixes

Purpose

Make the NixOS host behave correctly inside WSL: default user, Windows interop, graphics library paths, nix-ld, and Start Menu launcher syncing.

Entry Point

• Main file: wsl.nix

Architecture / Services / Scope

Base layer (always applied when enabled):

• allows passwordless login,
• installs wslu,
• enables nix-ld with a C toolchain library for VS Code Remote WSL compatibility,
• sets session variables for WSL graphics and library paths,
• enables hardware.graphics with the configured graphics packages and libvdpau-va-gl, and
• when NVIDIA graphics are present, appends CUDA and NVIDIA library paths.

If the wsl module exists in the option tree, module additionally:

• enables WSL with core.wsl.user as default user,
• enables Start Menu launchers and Windows driver usage,
• enables Windows interop and PATH appending,
• exposes dirname, readlink, and uname through wsl.extraBin for VS Code Remote WSL compatibility, and
• copies per-user Home Manager applications and icons into /usr/share during activation so launchers appear in the Windows Start Menu.

Operational Notes / Assumptions

• core.wsl.user is required when WSL integration is enabled.
• Extra binaries dirname, readlink, and uname are exposed for VS Code Remote WSL compatibility.
• Behavior is conditional on the separate wsl module being available in options.

Server Module

The Server module provides a cluster-aware configuration for server hosts in the flake. It must be explicitly enabled using the server.enable option.

Purpose

The primary purpose of this module is to establish a shared environment for servers in the cluster, defining coordinator nodes for discrete roles (IO, monitoring, database, storage, identity) and providing helper functions for inter-server communication and attribute collection.

Entry Point

• Main file: modules/nixos/server/default.nix

Options

server.dashboard.displayData

Display data for the section in the dashboard.

server.dashboard.icon

Icon for the section in the dashboard.

server.dashboard.items

Additional configuration for items managed by the IO Hosts dashy instance. This will be merged with the automatically generated configuration that is nested in a section with the name of the machine.

server.dashboard.items.<name>.icon

Icon for the item.

server.dashboard.items.<name>.title

Title of the item.

server.dashboard.items.<name>.url

URL for the item.

server.dashboard.name

Name of the section in the dashboard.

server.database.dependentServices

List of systemd service names that depend on io databases. These services will be automatically bound to the io-databases.target and will stop/start when databases become unavailable/available.

server.database.host

The hostname or IP address to use when connecting to managed databases.

This is “localhost” when running on the host, and when connecting from other hosts.

server.database.postgres

This option has no description.

server.database.postgres.<name>.database

This option has no description.

server.database.postgres.<name>.host

This option has no description.

server.database.postgres.<name>.password

This option has no description.

server.database.postgres.<name>.password.group

This option has no description.

server.database.postgres.<name>.password.owner

This option has no description.

server.database.postgres.<name>.password.path

This option has no description.

server.database.postgres.<name>.port

This option has no description.

server.database.postgres.<name>.user

This option has no description.

server.database.redis

This option has no description.

server.database.redis.<name>.database_id

This option has no description.

server.database.redis.<name>.host

This option has no description.

server.database.redis.<name>.port

This option has no description.

server.database.redis.<name>.prefix

This option has no description.

server.distributedBuilds.builderUser

The user to use when connecting to remote build daemons.

server.distributedBuilds.builders

A list of hostnames of remote build daemons to connect to for distributed builds.

server.enable

Whether to enable enable the server module.

server.fail2ban.enable

Whether to enable fail2ban intrusion detection.

server.fail2ban.exporterPort

Port for the fail2ban Prometheus exporter.

server.ioPrimaryHost

Which host is the primary coordinator for IO in the cluster.

This host will run the primary instances of databases, Operate the reverse proxy for handling incoming traffic, and will run the MinIO distributed storage cluster’s master node.

server.monitoring.collector.alerting.enable

Whether to enable Alertmanager and alert rules.

server.monitoring.collector.alerting.homeAssistant.enable

Whether to enable Home Assistant webhook alerting.

server.monitoring.collector.alerting.nextcloudTalk.enable

Whether to enable Nextcloud Talk webhook alerting.

server.monitoring.collector.enable

Whether to enable monitoring collector services (Prometheus, Loki, Grafana).

server.monitoring.collector.grafana.kanidm.enable

Whether to enable Kanidm OAuth2 authentication for Grafana.

server.monitoring.collector.otlp.bearerTokenSecret

SOPS secret path used as the bearer token for OTLP/HTTP ingestion.

server.monitoring.collector.otlp.enable

Whether to enable OTLP/HTTP ingestion via Grafana Alloy.

server.monitoring.collector.otlp.port

Port for the OTLP/HTTP ingestion endpoint.

server.monitoring.collector.otlp.subdomain

Subdomain used for the OTLP/HTTP ingestion endpoint.

server.monitoring.collector.proxmox.enable

Whether to enable Proxmox VE metrics collection.

server.monitoring.enable

Whether to enable monitoring for this server.

server.monitoring.exporters.caddy.enable

Whether to enable Caddy metrics exporter.

server.monitoring.exporters.fail2ban.enable

Whether to enable fail2ban metrics exporter.

server.monitoring.exporters.node.enable

Whether to enable node_exporter for system-level metrics.

server.monitoring.exporters.postgres.enable

Whether to enable PostgreSQL exporter.

server.monitoring.exporters.process.enable

Whether to enable Process exporter for monitoring specific processes.

server.monitoring.exporters.redis.enable

Whether to enable Redis exporter.

server.monitoring.logs.enable

Whether to enable Alloy log shipping.

server.monitoring.logs.extraConfiguration

Additional configuration for the alloy log processor. This is useful for adding custom Loki stages, relabeling rules, or write targets.

Note that the default configuration for processing the system journal is always included and does not need to be specified here.

server.monitoring.retention.logs

Loki log retention period.

server.monitoring.retention.metrics

Prometheus TSDB retention period.

server.monitoring.scrapeConfigs

Declarative scrape configs for services running on this host. These are collected by the monitoring primary host and converted into Prometheus scrape configurations.

server.monitoring.scrapeConfigs.<name>.bearer_token_secret

SOPS secret path for bearer token authentication. When set, the secret will be created on the monitoring primary host.

server.monitoring.scrapeConfigs.<name>.host

Host to scrape metrics from.

server.monitoring.scrapeConfigs.<name>.job_name

Prometheus job name for this scrape target.

server.monitoring.scrapeConfigs.<name>.metrics_path

HTTP path to the metrics endpoint.

server.monitoring.scrapeConfigs.<name>.port

Port the metrics endpoint listens on.

server.monitoring.scrapeConfigs.<name>.scheme

URL scheme for scraping.

server.monitoringPrimaryHost

Which host is the primary collector for monitoring in the cluster.

This host will run Prometheus, Loki, Grafana, and Alertmanager for centralized observability of the entire server cluster.

server.network.openPortsForSubnet.tcp

List of TCP ports to open on the firewall for each subnet.

server.network.openPortsForSubnet.udp

List of UDP ports to open on the firewall for each subnet.

server.network.subnets

This option has no description.

server.network.subnets.*.dns

DNS server for the subnet.

server.network.subnets.*.domain

Domain name for the subnet.

server.network.subnets.*.ipv4

IPv4 configuration for the subnet.

server.network.subnets.*.ipv4.arpa