The canonical new-host template lives in hosts/TEMPLATE/. This is the intended source of truth for which host-facing settings shapes the repo supports today.

Template files

/home/ftmahringer/nixos-config/hosts/TEMPLATE/default.nix
/home/ftmahringer/nixos-config/hosts/TEMPLATE/configuration.nix
/home/ftmahringer/nixos-config/hosts/TEMPLATE/home.nix
/home/ftmahringer/nixos-config/hosts/TEMPLATE/hardware-configuration.nix

How to use it

Copy hosts/TEMPLATE/ to hosts/<new-name>/.
Replace placeholder values like HOSTNAME, USERNAME, NAME, and EMAIL.
Remove sections you do not need and keep the settings shape consistent.
Put system-facing settings in configuration.nix.
Put user-facing settings in home.nix.

The sections below are generated from the structured @section, @field, @options, @shape, and @note comments in the template files.

configuration.nix schema

Source: /home/ftmahringer/nixos-config/hosts/TEMPLATE/configuration.nix

Host

Host identity and bootstrap values. Keep these flat. They are always-needed values, not optional feature flags.

`hostname`

Type: string
Required: true
Example: minipc

Runtime machine hostname. This becomes networking.hostName.

`profile`

Type: string
Required: false
Example: personal

Free-form profile label exported to the user environment.

Locale

Locale and keyboard settings used by both console and desktop sessions.

`timezone`

Type: string
Required: true
Example: Europe/Vienna

`locale`

Type: string
Required: true
Example: de_AT.UTF-8

`keyboardLayout`

Type: string
Required: true
Example: at

`keyboardVariant`

Type: string
Required: false
Example: nodeadkeys

`consoleKeyMap`

Type: string
Required: true
Example: de

Desktop

Desktop selection. Picking a compositor is enough to auto-enable the feature.

`desktop.compositor`

Type: string
Required: false
Example: hyprland
Options: hyprland
Shape: single-choice

`desktop.type`

Type: string
Required: false
Example: wayland
Options: wayland
Shape: single-choice

`desktop.greeter.name`

Type: string
Required: false
Example: tuigreet
Options: tuigreet
Shape: single-choice

Stylix

Global theme selection. Choosing a theme auto-enables the shared Stylix layer. Themes must live in modules/themes//.

`stylix.theme`

Type: string
Required: true
Example: dracula
Shape: single-choice
Note: Use a theme name from modules/themes//.

`stylix.icons`

Type: string
Required: false
Example: papirus
Options: papirus|candy-icons
Shape: single-choice

`stylix.backgroundImage`

Type: path
Required: false
Example: ./wallpaper.png
Shape: direct-value
Note: Machine-specific wallpaper overrides should stay rare.
Note: Only add this when the machine truly must differ from the theme background.

Storage

Disko integration for fresh installs. Use an empty attrset to keep Disko disabled for an existing host.

`disko.enable`

Type: bool
Required: false
Default: false

`disko.layout`

Type: string
Required: false
Example: single-disk-ext4
Options: single-disk-ext4
Shape: single-choice

`disko.device`

Type: string
Required: false
Example: /dev/sda
Note: Disabled shape example:

Tuning

Optional system tuning. Enable only if this host should get zram/sysctl tuning.

`tuning.zram.enable`

Type: bool
Required: false
Default: false

`tuning.zram.percent`

Type: int
Required: false
Default: 50

`tuning.sysctl`

Type: attrset
Required: false
Shape: key-value attrset
Note: Example overrides:

Firewall

Shared firewall module. Nested blocks with ports and interface exceptions.

`firewall.enable`

Type: bool
Required: false
Default: false

`firewall.allowedTCPPorts`

Type: list<int>
Required: false
Shape: list

`firewall.allowedUDPPorts`

Type: list<int>
Required: false
Shape: list

`firewall.interfaces`

Type: attrset
Required: false
Shape: named attrset
Note: Per-interface overrides. allowAll promotes the interface to trusted.

SSH

SSH identity metadata used by the wrapper and generated SSH config. If this block contains real values, the settings normalization layer should treat it as enabled without needing an explicit enable = true.

`ssh.hostName`

Type: string
Required: false
Example: 10.0.10.111

`ssh.aliases`

Type: list<string>
Required: false
Shape: list

`ssh.port`

Type: int
Required: false
Default: 22

`ssh.user`

Type: string
Required: false

`ssh.identityFile`

Type: list<string>
Required: false
Shape: list

`ssh.extraOptions`

Type: attrset
Required: false
Shape: key-value attrset

Bootloader

Bootloader selection and overrides.

`bootloader.type`

Type: string
Required: false
Example: systemd-boot
Options: systemd-boot|grub
Shape: single-choice
Note: EFI-specific overrides:
Note: GRUB-specific overrides:

Virtualisation

Optional container and VM stack.

`virtualisation.containerRuntime`

Type: string
Required: false
Example: podman
Options: podman|docker
Shape: single-choice

`virtualisation.registries`

Type: attrset
Required: false
Shape: attrset with search/insecure/block lists

`virtualisation.libvirt.enable`

Type: bool
Required: false
Default: false

App Support

Optional support for non-Nix app ecosystems.

`appSupport.enable`

Type: bool
Required: false
Default: false

`appSupport.flatpak.enable`

Type: bool
Required: false
Default: false

`appSupport.appimage.enable`

Type: bool
Required: false
Default: false

Syncthing

Optional Syncthing service owned by the configured user.

`syncthing.enable`

Type: bool
Required: false
Default: false

`syncthing.openDefaultPorts`

Type: bool
Required: false
Default: true

`syncthing.devices`

Type: attrset
Required: false
Shape: named attrset

`syncthing.folders`

Type: attrset
Required: false
Shape: named attrset

home.nix schema

Source: /home/ftmahringer/nixos-config/hosts/TEMPLATE/home.nix

Identity

User identity values. Keep these flat.

`username`

Type: string
Required: true
Example: ftmahringer

`fullName`

Type: string
Required: true
Example: Fynn Mahringer

`email`

Type: string
Required: true
Example: name@example.com

`homeDirectory`

Type: string
Required: true
Example: /home/USERNAME

Browser

Browser selection.

`browser`

Type: string-or-attrset
Required: true
Example: librewolf
Options: librewolf|brave|edge
Shape: plain-string or { default = <option>; extra = [ <option> ... ]; }

Editor

Editor selection.

`editor`

Type: string-or-attrset
Required: true
Example: zed
Options: zed|neovim|vscodium
Shape: plain-string or { default = <option>; extra = [ <option> ... ]; }

Git CLI

Git forge CLI selection.

`gitCli.default`

Type: string
Required: true
Example: github
Options: github|gitlab|gitea|forgejo
Shape: default+extra attrset

`gitCli.extra`

Type: list<string>
Required: false
Options: github|gitlab|gitea|forgejo
Shape: list

Desktop Tools

Single-choice desktop programs should stay as plain strings.

`bar`

Type: string
Required: true
Example: waybar
Options: waybar
Shape: single-choice

`launcher`

Type: string
Required: true
Example: fuzzel
Options: fuzzel
Shape: single-choice

`notifications`

Type: string
Required: true
Example: mako
Options: mako
Shape: single-choice

`fileManager`

Type: string
Required: true
Example: yazi
Options: yazi
Shape: single-choice

Terminal

Terminal selection.

`terminal.default`

Type: string
Required: true
Example: kitty
Options: kitty|alacritty
Shape: default+extra attrset

`terminal.extra`

Type: list<string>
Required: false
Options: kitty|alacritty
Shape: list

Shell

Shell selection.

`shell.default`

Type: string
Required: true
Example: zsh
Options: bash|zsh|fish
Shape: default+extra attrset

`shell.extra`

Type: list<string>
Required: false
Options: bash|zsh|fish
Shape: list

Wallpaper

Wallpaper behavior for the user session.

`wallpaper.mode`

Type: string
Required: true
Example: fill
Options: stretch|fit|fill|center|tile
Shape: single-choice

default.nix

Source: /home/ftmahringer/nixos-config/hosts/TEMPLATE/default.nix
Purpose: wires configuration.nix, hardware-configuration.nix, and home.nix together for one host.

Home