Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Options reference

selfhost.apps.bazarr.enable

Whether to enable the first-party Bazarr app (subtitle automation; wiring + reconcile, no providers).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.bazarr.apiKeyFile

Path to Bazarr’s generated API key.

Type: string (read only)

Default: the generated API-key secret path

Declared by:

selfhost.apps.bazarr.dataDir

Bazarr state directory (config.yaml, database, logs).

Type: string

Default:

"/var/lib/bazarr"

Declared by:

selfhost.apps.bazarr.defaultProfile

Profile name applied to newly-added series and movies. Null leaves new media unassigned (nothing is fetched for it).

Type: null or string

Default:

null

Declared by:

selfhost.apps.bazarr.exporterPort

exportarr listen port (localhost) for Bazarr metrics.

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default:

9712

Declared by:

selfhost.apps.bazarr.languageProfiles

Language profiles to ensure, authoritatively. None ship, and without one Bazarr downloads nothing.

Type: list of (submodule)

Default:

[ ]

Example:

[ { name = "English"; languages = [ "en" ]; cutoff = "en"; } ]

Declared by:

selfhost.apps.bazarr.languageProfiles.*.cutoff

Language that ends the search once found; null keeps searching for all of them.

Type: null or string

Default:

null

Declared by:

selfhost.apps.bazarr.languageProfiles.*.languages

Two-letter language codes to search for, in priority order.

Type: list of string

Default:

[ ]

Declared by:

selfhost.apps.bazarr.languageProfiles.*.name

Profile name.

Type: string

Declared by:

selfhost.apps.bazarr.radarr

Radarr to pull the movie library from. Null = Bazarr handles no movies.

Type: null or (submodule)

Default:

null

Declared by:

selfhost.apps.bazarr.radarr.apiKeyFile

Path to Radarr’s API key.

Type: string

Default: the local Radarr’s generated API key when apps.radarr.enable

Declared by:

selfhost.apps.bazarr.radarr.baseUrl

Radarr URL base.

Type: string

Default:

"/"

Declared by:

selfhost.apps.bazarr.radarr.host

Radarr host reachable from Bazarr.

Type: string

Default: the local Radarr’s host when apps.radarr.enable

Declared by:

selfhost.apps.bazarr.radarr.port

Radarr port.

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default: the local Radarr’s port when apps.radarr.enable

Declared by:

selfhost.apps.bazarr.sonarr

Sonarr to pull the series library from. Null = Bazarr handles no TV.

Type: null or (submodule)

Default:

null

Declared by:

selfhost.apps.bazarr.sonarr.apiKeyFile

Path to Sonarr’s API key.

Type: string

Default: the local Sonarr’s generated API key when apps.sonarr.enable

Declared by:

selfhost.apps.bazarr.sonarr.baseUrl

Sonarr URL base.

Type: string

Default:

"/"

Declared by:

selfhost.apps.bazarr.sonarr.host

Sonarr host reachable from Bazarr.

Type: string

Default: the local Sonarr’s host when apps.sonarr.enable

Declared by:

selfhost.apps.bazarr.sonarr.port

Sonarr port.

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default: the local Sonarr’s port when apps.sonarr.enable

Declared by:

selfhost.apps.bentopdf.enable

Whether to enable the first-party BentoPDF app (static, client-side PDF toolkit).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.coturn.enable

Whether to enable the first-party coturn app (STUN/TURN relay).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.coturn.advertisedAddresses

Addresses clients reach this relay on, in the order they should try them. Read by whoever advertises the relay.

Type: list of non-empty string

Default:

[ ]

Example:

[
  "192.168.1.10"
  "10.100.0.1"
]

Declared by:

selfhost.apps.coturn.allowedPeerRanges

Peers relaying is permitted to, in coturn’s allowed-peer-ip syntax. Every other address is denied, so empty relays nowhere and 0.0.0.0-255.255.255.255 is a public relay.

Type: list of non-empty string

Default:

[ ]

Example:

[
  "192.168.1.0-192.168.1.255"
]

Declared by:

selfhost.apps.coturn.credential

Per login: the generated password’s file, and its placeholder for a runtimeTemplates body.

Type: attribute set of attribute set of string (read only)

Default: derived from logins

Declared by:

selfhost.apps.coturn.logins

Long-term credential logins to provision, one generated password each. An app needing the relay appends the login it authenticates with.

Type: list of non-empty string

Default:

[ ]

Example:

[
  "romm"
]

Declared by:

selfhost.apps.coturn.openFirewall

Open the listening port and the relay port range on every interface. Off because a relay serving LAN or VPN clients wants an interface-scoped rule instead.

Type: boolean

Default:

false

Declared by:

selfhost.apps.couchdb.enable

Whether to enable the first-party CouchDB app (document database).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.desec.enable

Whether to enable deSEC dynamic DNS updates.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.desec.domains

Hostnames to keep pointed at the current public IP.

Type: non-empty (list of string)

Example:

[
  "squirrel-plaza.dedyn.io"
]

Declared by:

selfhost.apps.desec.interval

Refresh period (systemd time span); a boot-time update also runs.

Type: string

Default:

"30min"

Declared by:

selfhost.apps.desec.tokenFile

File holding a deSEC API token authorized for domains.

Type: string

Declared by:

selfhost.apps.filebrowser-quantum.enable

Whether to enable the first-party FileBrowser Quantum app (per-user file sharing).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.gitea.enable

Whether to enable the first-party Gitea app (git server with OIDC login).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.gitea.ssh.enable

Whether to enable Gitea’s built-in SSH server for git-over-SSH (off by default — exposes a TCP port; HTTPS git works without it).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.gitea.ssh.openFirewall

Whether to enable opening the SSH port in the firewall (all interfaces); leave off to scope it yourself.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.gitea.ssh.port

Listen port for the built-in SSH server.

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default:

2222

Declared by:

selfhost.apps.homepage.enable

Whether to enable the first-party homepage dashboard app (gethomepage).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.immich.enable

Whether to enable the first-party Immich app (photo and video library).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.jellyfin.enable

Whether to enable the first-party Jellyfin app (media server).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.jellyfin.branding

Fields merged into Jellyfin’s branding configuration. Merged, not replaced, so a login disclaimer owned by an SSO plugin survives.

Type: attribute set of anything

Default:

{ }

Declared by:

selfhost.apps.jellyfin.defaultPolicy

Policy fields applied to every account, under each user’s own policy. The baseline most deployments want the same for everyone.

Type: attribute set of anything

Default:

{ }

Example:

{
  EnableSubtitleManagement = true;
}

Declared by:

selfhost.apps.jellyfin.encoding

EncodingOptions merged onto what Jellyfin holds. Never combine with services.jellyfin.transcoding (see the Jellyfin chapter).

Type: attribute set of anything

Default:

{ }

Example:

{
  TonemappingAlgorithm = "bt2390";
}

Declared by:

selfhost.apps.jellyfin.libraries

Libraries to create and keep pointed at their directories.

Type: list of (submodule)

Default:

[ ]

Declared by:

selfhost.apps.jellyfin.libraries.*.collectionType

Jellyfin collection type. Closed set, so a typo fails evaluation rather than the library create.

Type: one of “unknown”, “movies”, “tvshows”, “music”, “musicvideos”, “trailers”, “homevideos”, “boxsets”, “books”, “photos”, “livetv”, “playlists”, “folders”

Example:

"movies"

Declared by:

selfhost.apps.jellyfin.libraries.*.locations

Directories this library scans. Reconciled, so moving a path moves the library.

Type: list of string

Default:

[ ]

Declared by:

selfhost.apps.jellyfin.libraries.*.name

Library name in Jellyfin; also its reconcile identity, so renaming creates a second one.

Type: string

Declared by:

selfhost.apps.jellyfin.libraries.*.options

Fields merged into this library’s Jellyfin LibraryOptions, applied verbatim.

Type: attribute set of anything

Default:

{ }

Example:

{
  EnableRealtimeMonitor = false;
}

Declared by:

selfhost.apps.jellyfin.serverName

Server name Jellyfin reports to clients.

Type: string

Default: the service’s displayName

Declared by:

selfhost.apps.jellyfin.startup.metadataCountryCode

Metadata country code, applied once by the startup wizard.

Type: string

Default:

"US"

Declared by:

selfhost.apps.jellyfin.startup.preferredMetadataLanguage

Preferred metadata language, applied once by the startup wizard.

Type: string

Default:

"en"

Declared by:

selfhost.apps.jellyfin.startup.uiCulture

Interface culture, applied once by the startup wizard.

Type: string

Default:

"en-US"

Declared by:

selfhost.apps.jellyfin.trickplay

Fields merged into Jellyfin’s trickplay options.

Type: attribute set of anything

Default:

{ }

Declared by:

selfhost.apps.miniflux.enable

Whether to enable the first-party Miniflux app (RSS reader with OIDC login).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.open-webui.enable

The Open WebUI app. Unfree in nixpkgs, so allow open-webui in your unfree predicate.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.prowlarr.enable

Whether to enable the first-party Prowlarr app (indexer manager; wiring only, no indexers).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.prowlarr.apiKeyFile

Path to Prowlarr’s generated API key, for the consumer indexer-sync reconciler.

Type: string (read only)

Default: the generated API-key secret path

Declared by:

selfhost.apps.prowlarr.exporterPort

exportarr listen port (localhost) for Prowlarr metrics. Each *arr needs its own — exportarr defaults them all to 9708.

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default:

9711

Declared by:

selfhost.apps.radarr.enable

Whether to enable the first-party Radarr app (media automation; ingress + auth + secrets wired, zero acquisition config).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.radarr.apiKeyFile

Path to Radarr’s generated API key, for consumer reconcilers (e.g. Prowlarr sync, recyclarr).

Type: string (read only)

Default: the generated API-key secret path

Declared by:

selfhost.apps.radarr.configureAfter

Extra units the reconcile must start after and want. Radarr connection-tests a download client on save, so order this after the client’s service (e.g. your torrent/usenet daemon).

Type: list of string

Default:

[ ]

Example:

[
  "transmission.service"
]

Declared by:

selfhost.apps.radarr.delayProfile

Optional default delay profile. Null = leave Radarr’s own default untouched. Carries the protocol preference — acquisition taste, no framework default.

Type: null or (submodule)

Default:

null

Declared by:

selfhost.apps.radarr.delayProfile.enableTorrent

Whether this profile may grab torrent releases.

Type: boolean

Default:

true

Declared by:

selfhost.apps.radarr.delayProfile.enableUsenet

Whether this profile may grab usenet releases.

Type: boolean

Default:

true

Declared by:

selfhost.apps.radarr.delayProfile.bypassIfHighestQuality

Grab immediately, ignoring the delays above, when the release already meets the highest wanted quality.

Type: boolean

Default:

true

Declared by:

selfhost.apps.radarr.delayProfile.preferredProtocol

Protocol preference.

Type: one of “torrent”, “usenet”

Declared by:

selfhost.apps.radarr.delayProfile.torrentDelay

Minutes to hold a torrent release before grabbing it, letting a better one appear first.

Type: signed integer

Default:

0

Declared by:

selfhost.apps.radarr.delayProfile.usenetDelay

Minutes to hold a usenet release before grabbing it, letting a better one appear first.

Type: signed integer

Default:

0

Declared by:

selfhost.apps.radarr.downloadClients

Download clients to register. The framework applies them via the *arr schema; it ships none and assumes no protocol.

Type: list of (submodule)

Default:

[ ]

Declared by:

selfhost.apps.radarr.downloadClients.*.fields

Implementation-specific fields passed through to the client schema (host, port, category, …).

Type: attribute set of anything

Default:

{ }

Declared by:

selfhost.apps.radarr.downloadClients.*.implementation

The *arr download-client implementation (e.g. “Transmission”, “Sabnzbd”). No default — you choose.

Type: string

Declared by:

selfhost.apps.radarr.downloadClients.*.name

Client name in Radarr.

Type: string

Declared by:

selfhost.apps.radarr.downloadClients.*.protocol

Client protocol.

Type: one of “torrent”, “usenet”

Declared by:

selfhost.apps.radarr.exporterPort

exportarr listen port (localhost) for Radarr metrics. Each *arr needs its own — exportarr defaults them all to 9708.

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default:

9710

Declared by:

selfhost.apps.radarr.mediaManagement.unmonitorDeleted

Unmonitor an item when its file disappears. Off by default: an unmounted or half-restored share is indistinguishable from a deleted library, so one rescan unmonitors everything.

Type: boolean

Default:

false

Declared by:

selfhost.apps.radarr.notifyOnImport

Notify on import or upgrade. Turn off when something downstream already announces arrivals. Failures always notify.

Type: boolean

Default:

true

Declared by:

selfhost.apps.radarr.rootFolders

Root library folders to ensure. Paths only — storage/protocol-agnostic.

Type: list of (submodule)

Default:

[ ]

Declared by:

selfhost.apps.radarr.rootFolders.*.defaultQualityProfile

Name of a quality profile (consumer/recyclarr-managed) to seed as this folder’s default; null = none.

Type: null or string

Default:

null

Declared by:

selfhost.apps.radarr.rootFolders.*.path

Library path (must exist on disk; typically a selfhost storage mount).

Type: string

Declared by:

selfhost.apps.radicale.enable

Whether to enable the first-party Radicale app (CalDAV/CardDAV server).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.romm.enable

Whether to enable the first-party RomM app (ROM library manager).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.romm.netplay.enable

Point EmulatorJS netplay at the coturn app, with a generated TURN credential and a STUN/TURN pair per advertised address.

Type: boolean

Default:

config.selfhost.apps.coturn.enable

Declared by:

selfhost.apps.romm.settings

RomM’s config.yml: platform bindings, scan exclusions, EmulatorJS. Linked in rather than written, so RomM reports it read-only and its own config editor refuses to save. Empty leaves the file to RomM. Keys are upstream’s, see https://github.com/rommapp/romm/blob/master/examples/config.example.yml.

Type: YAML 1.1 value

Default:

{ }

Example:

{
  exclude = {
    roms = {
      multi_file = {
        names = [
          "artwork"
        ];
      };
    };
  };
  system = {
    platforms = {
      megadrive = "genesis";
    };
  };
}

Declared by:

selfhost.apps.sonarr.enable

Whether to enable the first-party Sonarr app (media automation; ingress + auth + secrets wired, zero acquisition config).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.sonarr.apiKeyFile

Path to Sonarr’s generated API key, for consumer reconcilers (e.g. Prowlarr sync, recyclarr).

Type: string (read only)

Default: the generated API-key secret path

Declared by:

selfhost.apps.sonarr.configureAfter

Extra units the reconcile must start after and want. Sonarr connection-tests a download client on save, so order this after the client’s service (e.g. your torrent/usenet daemon).

Type: list of string

Default:

[ ]

Example:

[
  "transmission.service"
]

Declared by:

selfhost.apps.sonarr.delayProfile

Optional default delay profile. Null = leave Sonarr’s own default untouched. Carries the protocol preference — acquisition taste, no framework default.

Type: null or (submodule)

Default:

null

Declared by:

selfhost.apps.sonarr.delayProfile.enableTorrent

Whether this profile may grab torrent releases.

Type: boolean

Default:

true

Declared by:

selfhost.apps.sonarr.delayProfile.enableUsenet

Whether this profile may grab usenet releases.

Type: boolean

Default:

true

Declared by:

selfhost.apps.sonarr.delayProfile.bypassIfHighestQuality

Grab immediately, ignoring the delays above, when the release already meets the highest wanted quality.

Type: boolean

Default:

true

Declared by:

selfhost.apps.sonarr.delayProfile.preferredProtocol

Protocol preference.

Type: one of “torrent”, “usenet”

Declared by:

selfhost.apps.sonarr.delayProfile.torrentDelay

Minutes to hold a torrent release before grabbing it, letting a better one appear first.

Type: signed integer

Default:

0

Declared by:

selfhost.apps.sonarr.delayProfile.usenetDelay

Minutes to hold a usenet release before grabbing it, letting a better one appear first.

Type: signed integer

Default:

0

Declared by:

selfhost.apps.sonarr.downloadClients

Download clients to register. The framework applies them via the *arr schema; it ships none and assumes no protocol.

Type: list of (submodule)

Default:

[ ]

Declared by:

selfhost.apps.sonarr.downloadClients.*.fields

Implementation-specific fields passed through to the client schema (host, port, category, …).

Type: attribute set of anything

Default:

{ }

Declared by:

selfhost.apps.sonarr.downloadClients.*.implementation

The *arr download-client implementation (e.g. “Transmission”, “Sabnzbd”). No default — you choose.

Type: string

Declared by:

selfhost.apps.sonarr.downloadClients.*.name

Client name in Sonarr.

Type: string

Declared by:

selfhost.apps.sonarr.downloadClients.*.protocol

Client protocol.

Type: one of “torrent”, “usenet”

Declared by:

selfhost.apps.sonarr.exporterPort

exportarr listen port (localhost) for Sonarr metrics. Each *arr needs its own — exportarr defaults them all to 9708.

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default:

9709

Declared by:

selfhost.apps.sonarr.mediaManagement.unmonitorDeleted

Unmonitor an item when its file disappears. Off by default: an unmounted or half-restored share is indistinguishable from a deleted library, so one rescan unmonitors everything.

Type: boolean

Default:

false

Declared by:

selfhost.apps.sonarr.notifyOnImport

Notify on import or upgrade. Turn off when something downstream already announces arrivals. Failures always notify.

Type: boolean

Default:

true

Declared by:

selfhost.apps.sonarr.rootFolders

Root library folders to ensure. Paths only — storage/protocol-agnostic.

Type: list of (submodule)

Default:

[ ]

Declared by:

selfhost.apps.sonarr.rootFolders.*.defaultQualityProfile

Name of a quality profile (consumer/recyclarr-managed) to seed as this folder’s default; null = none.

Type: null or string

Default:

null

Declared by:

selfhost.apps.sonarr.rootFolders.*.path

Library path (must exist on disk; typically a selfhost storage mount).

Type: string

Declared by:

selfhost.apps.transmission.enable

Whether to enable the first-party Transmission app (torrent client).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.wireguard.enable

Whether to enable WireGuard VPN server (interface, server keys, and runtime peer provisioning via wg-manage).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.wireguard.address

Server address with CIDR (e.g. 10.100.0.1/24).

Type: string

Declared by:

selfhost.apps.wireguard.clientSubnet

Client address subnet (e.g. 10.100.0.0/24).

Type: string

Declared by:

selfhost.apps.wireguard.dns

DNS server pushed to clients. Naming this host needs restrictedPeers.udpPorts = [ 53 ].

Type: string

Example:

"1.1.1.1"

Declared by:

selfhost.apps.wireguard.endpoint

Public endpoint host/IP that clients dial.

Type: string

Declared by:

selfhost.apps.wireguard.exporterPort

Prometheus wireguard-exporter listen port (localhost).

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default:

9586

Declared by:

selfhost.apps.wireguard.fullAccessSubnet

Block within clientSubnet whose devices skip restrictedPeers and, with lanAccess.enable, reach the LAN. Every other client address is restricted, so a device’s tier is its address. Null grants full access to nobody.

Type: null or string

Default:

null

Example:

"10.100.0.0/28"

Declared by:

selfhost.apps.wireguard.interface

WireGuard interface name.

Type: string

Default:

"wg0"

Declared by:

selfhost.apps.wireguard.lanAccess.enable

Whether to enable opt-in nftables forwarding/NAT so clients reach the LAN (else clients reach only the server).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.wireguard.lanAccess.masquerade

Whether to enable srcnat masquerade of client traffic into the LAN (enable only if the LAN lacks routes back to the client subnet).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.wireguard.lanAccess.serverAddress

This host’s own address on subnet. Restricted devices route just this instead of the whole subnet, so a client whose home network overlaps it keeps its local devices. Null leaves them routing the whole subnet.

Type: null or string

Default:

null

Example:

"192.168.1.10"

Declared by:

selfhost.apps.wireguard.lanAccess.subnet

LAN subnet full-access clients may reach; added to their AllowedIPs and used as the masquerade destination. Required when lanAccess.enable.

Type: string

Declared by:

selfhost.apps.wireguard.lanAccess.wakeOnLan

Whether to enable forwarding Wake-on-LAN magic packets (UDP 7 and 9) from full-access clients to the LAN broadcast address; every other directed broadcast stays in the tunnel.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.apps.wireguard.listenPort

WireGuard UDP listen port (opened in the firewall).

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default:

51820

Declared by:

selfhost.apps.wireguard.openFirewall

Open the WireGuard listen UDP port in the firewall.

Type: boolean

Default:

true

Declared by:

selfhost.apps.wireguard.restrictedPeers.tcpPorts

TCP ports on this host a device outside fullAccessSubnet may reach. Everything else another service opened on the tunnel interface is dropped for it. Empty allows none.

Type: list of 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default:

[
  80
  443
]

Declared by:

selfhost.apps.wireguard.restrictedPeers.udpPorts

UDP ports on this host a device outside fullAccessSubnet may reach. Empty allows none, which is why dns normally names a resolver these devices reach without the server. Open 53 here instead if the resolver is this host.

Type: list of 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default:

[ ]

Example:

[
  53
]

Declared by:

selfhost.auth.forwardAuth.active

Whether a forward-auth provider is active. Compose service defaults against this.

Type: boolean (read only)

Default: true once a provider defines url

Declared by:

selfhost.auth.forwardAuth.path

Verify path appended to url for the ingress forward-auth middleware (e.g. /api/auth/traefik); set by the active provider.

Type: string

Default:

""

Declared by:

selfhost.auth.forwardAuth.tinyauth.enable

Whether to enable tinyauth forward-auth gateway (federates to the selfhost OIDC provider).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.auth.forwardAuth.url

Base URL of the forward-auth endpoint, set by the active provider and consumed by the ingress provider. Left undefined until one is, which is what active reads.

Type: string

Declared by:

selfhost.auth.oidc.active

Whether an OIDC provider is active. Compose service defaults against this.

Type: boolean (read only)

Default: true once a provider defines provider.issuerUrl

Declared by:

selfhost.auth.oidc.clients

Derived OIDC client configs keyed by service name (read-only)

Type: attribute set of raw value (read only)

Default:

{ }

Declared by:

selfhost.auth.oidc.credentials.dir

Base directory holding each client’s id and secret. Persistent, not tmpfs: these have no source to re-derive from, so a tmpfs would mint new ones every boot.

Type: string (read only)

Default:

"/var/lib/homelab-oidc"

Declared by:

selfhost.auth.oidc.pocket-id.enable

Whether to enable Pocket-ID OIDC implementation.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.auth.oidc.provider.discoveryUrl

OIDC discovery document URL (derived from issuerUrl); for consumers that need the full well-known URL rather than the bare issuer.

Type: string (read only)

Default: <issuerUrl>/.well-known/openid-configuration

Declared by:

selfhost.auth.oidc.provider.displayName

Display name of the OIDC provider (shown in UI)

Type: string

Declared by:

selfhost.auth.oidc.provider.internalName

Internal name for URLs and identifiers

Type: string

Declared by:

selfhost.auth.oidc.provider.issuerUrl

OIDC issuer URL (e.g. https://auth.example.com). Left undefined until a provider sets it, which is what active reads.

Type: string

Declared by:

selfhost.auth.oidc.provisionConfig

Provisioning config derived from OIDC-enabled users and services (read-only)

Type: raw value (read only)

Default:

{
  groups = [
    {
      name = "admin";
    }
    {
      name = "guests";
    }
    {
      name = "users";
    }
  ];
  users = [ ];
}

Declared by:

selfhost.auth.oidc.rotation.enable

Whether to enable a timer that rotates all OIDC client secrets on a schedule.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.auth.oidc.rotation.schedule

systemd OnCalendar expression for the rotation timer (default: weekly, Sunday 03:00).

Type: string

Default:

"Sun *-*-* 03:00:00"

Example:

"monthly"

Declared by:

selfhost.auth.oidc.systemd.baseProvisionUnit

Systemd unit for base OIDC provisioning (users/groups)

Type: null or string

Default:

null

Declared by:

selfhost.auth.oidc.systemd.clientProvisionUnitPrefix

Prefix for per-client provisioning unit names (provider sets this; e.g. ‘<provider>-provision-client-’ yields ‘<provider>-provision-client-<name>.service’).

Type: null or string

Default:

null

Declared by:

selfhost.backup.package

The rustic-manage package to use (shared by all targets).

Type: package

Default:

pkgs.selfhost.rustic-manage

Declared by:

selfhost.backup.targets

Backup destinations, each an independent rustic pipeline. See the security chapter before sharing a repository.

Type: attribute set of (submodule)

Default:

{ }

Declared by:

selfhost.backup.targets.<name>.enable

Whether this target runs. Off keeps the configuration but drops the units, for pausing one destination without deleting how it is set up.

Type: boolean

Default:

true

Declared by:

selfhost.backup.targets.<name>.backendCredentialsFile

Storage backend access credentials as a rustic secrets TOML ([repository.options]); symlinked to /etc/rustic/<name>-secrets.toml. Null for local-path repositories (no backend auth).

Type: null or string

Default:

null

Declared by:

selfhost.backup.targets.<name>.backupSchedule

systemd OnCalendar schedule for the backup timer.

Type: string

Default:

"*-*-* 03:00:00"

Declared by:

selfhost.backup.targets.<name>.bindings

Virtual backup path (key, must start with ‘/’) -> source path (value), mounted read-only into this target’s tree.

Type: attribute set of string

Default:

{ }

Example:

{
  "/nas/notes" = "/mnt/nas/notes";
}

Declared by:

selfhost.backup.targets.<name>.globs

rustic include/exclude globs (! excludes), matched inside the staging tree. Defaults exclude NAS, sync and OS metadata.

Type: list of string

Default:

[
  "!@eaDir"
  "!.stfolder"
  "!.stversions"
  "!.Trash*"
  "!@Recycle"
  "!$RECYCLE.BIN"
  "!.DS_Store"
  "!Thumbs.db"
  "!#snapshot"
  "!#recycle"
  "!.zfs"
]

Declared by:

selfhost.backup.targets.<name>.hooks

Standalone pre-backup hooks not tied to a registry service (e.g. GitHub), run for this target.

Type: attribute set of (submodule)

Default:

{ }

Declared by:

selfhost.backup.targets.<name>.hooks.<name>.package

Package providing a backup script. OUTPUT_DIR points to a fresh, empty directory for the hook’s output.

Type: package

Declared by:

selfhost.backup.targets.<name>.hooks.<name>.after

Systemd units this hook must run after (e.g. the service whose data it snapshots).

Type: list of string

Default:

[ ]

Declared by:

selfhost.backup.targets.<name>.passwordFile

rustic repository encryption password file.

Type: string

Declared by:

selfhost.backup.targets.<name>.prune

Whether forget also prunes. In a repository shared by several hosts, exactly one may.

Type: boolean

Default:

true

Declared by:

selfhost.backup.targets.<name>.repository

rustic repository string (e.g. ‘opendal:b2’).

Type: string

Declared by:

selfhost.backup.targets.<name>.retention

Snapshot retention policy (rustic forget keep-within-*).

Type: submodule

Declared by:

selfhost.backup.targets.<name>.retention.daily

How long to keep daily snapshots (rustic keep-within-daily; e.g. 7 days).

Type: string

Declared by:

selfhost.backup.targets.<name>.retention.monthly

How long to keep monthly snapshots (e.g. 1 year).

Type: string

Declared by:

selfhost.backup.targets.<name>.retention.weekly

How long to keep weekly snapshots (e.g. 1 month).

Type: string

Declared by:

selfhost.backup.targets.<name>.retention.yearly

How long to keep yearly snapshots (e.g. 2 years).

Type: string

Declared by:

selfhost.backup.targets.<name>.services

Registry services whose backup hook to run for this target (must declare services.<name>.backup.package).

Type: list of impossible (empty enum)

Default:

[ ]

Declared by:

selfhost.backup.targets.<name>.verifySchedule

systemd OnCalendar schedule for the verification timer.

Type: string

Default:

"Sun *-*-* 05:00:00"

Declared by:

selfhost.dashboards.generatedTiles

Service/external tiles keyed by integrations.homepage.group (read-only). The bundled apps.homepage renders these; otherwise read them into a dashboard you own and decide tabs/layout.

Type: attribute set of list of anything (read only)

Default: derived from services and externals that opt into integrations.homepage

Declared by:

selfhost.external

External services not managed by this host (shown on homepage dashboard via integrations.homepage)

Type: attribute set of (submodule)

Default:

{ }

Declared by:

selfhost.external.<name>.displayName

Human-readable name (defaults to attribute name)

Type: string

Default:

"‹name›"

Declared by:

selfhost.external.<name>.integrations.homepage

Homepage dashboard integration

Type: submodule

Default:

{ }

Declared by:

selfhost.external.<name>.integrations.homepage.enable

Whether to enable homepage entry for this service.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.external.<name>.integrations.homepage.group

Free-form tile group this service belongs to; you map groups to tabs/layout in your dashboard.

Type: string

Default:

"Services"

Declared by:

selfhost.external.<name>.integrations.homepage.icon

Icon name from dashboard-icons (e.g. ‘miniflux.svg’)

Type: null or string

Default:

"‹name›.svg"

Declared by:

selfhost.external.<name>.integrations.homepage.settings

Extra homepage tile settings merged into the generated entry (e.g. a widget).

Type: attribute set

Default:

{ }

Declared by:

selfhost.external.<name>.meta.category

Canonical grouping key; a consumer surface (e.g. a landing page) groups services by this.

Type: null or string

Default:

null

Declared by:

selfhost.external.<name>.meta.description

Short description (nixpkgs meta.description); shown under the name on a dashboard tile. Empty renders no subtitle.

Type: string

Default:

""

Declared by:

selfhost.external.<name>.meta.homepage

Upstream project homepage (nixpkgs meta.homepage).

Type: null or string

Default:

null

Declared by:

selfhost.external.<name>.name

Registry identifier (defaults to attribute name)

Type: string

Default:

"‹name›"

Declared by:

selfhost.external.<name>.url

Direct URL to the external service

Type: string

Declared by:

selfhost.groups.admin

Name of the admin group

Type: string

Default:

"admin"

Declared by:

selfhost.groups.guests

Name of the guests group

Type: string

Default:

"guests"

Declared by:

selfhost.groups.users

Name of the users group

Type: string

Default:

"users"

Declared by:

selfhost.ingress.acme.dns01.credentialsEnvFile

Path to an env file with the DNS-01 provider’s credentials (e.g. CF_DNS_API_TOKEN). Provided by the host, e.g. via sops-nix.

Type: string

Declared by:

selfhost.ingress.acme.dns01.provider

DNS-01 challenge provider name for the ACME client.

Type: string

Example:

"cloudflare"

Declared by:

selfhost.ingress.acme.email

ACME account email for certificate registration

Type: string

Declared by:

selfhost.ingress.allowedInterfaces

Interfaces to scope the opened ports to. Empty opens them on all interfaces. To open nothing at all, set openFirewall = false rather than clearing this.

Type: list of string

Default:

[ ]

Example:

[
  "eth0"
]

Declared by:

selfhost.ingress.domain

Base domain for publicly routed services (e.g. ‘home.example.com’). Required once any service enables ingress; a host that routes nothing may leave it null.

Type: null or string

Default:

null

Declared by:

selfhost.ingress.hosts

Public hostnames this host’s ingress serves, for consumers that resolve or publish them.

Type: list of string (read only)

Default: every ingress-enabled service’s publicHost

Declared by:

selfhost.ingress.openFirewall

Whether the ingress implementation opens 80/443. Enabling ingress means wanting it reachable, so this follows. Turn it off to place the rules yourself.

Type: boolean

Default:

true

Declared by:

selfhost.ingress.traefik.enable

Whether to enable Traefik reverse-proxy ingress implementation.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.ingress.traefik.metricsPort

Port for Traefik’s Prometheus metrics endpoint (localhost only)

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default:

8082

Declared by:

selfhost.internal.listeningPorts.*.host

Listen address.

Type: string

Default:

"127.0.0.1"

Declared by:

selfhost.internal.listeningPorts.*.name

Owner identifier, shown in collision messages.

Type: string

Declared by:

selfhost.internal.listeningPorts.*.port

Listen port.

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Declared by:

selfhost.internal.listeningPorts.*.protocol

Transport the socket binds; only sockets sharing one can collide.

Type: one of “tcp”, “udp”

Default:

"tcp"

Declared by:

selfhost.mail.active

Whether outbound mail is configured. Compose against this: a consumer that never sets selfhost.mail gets the features that need no SMTP, and nothing asks for a value nobody supplied.

Type: boolean (read only)

Default: true once host is set

Declared by:

selfhost.mail.from

Sender email address

Type: string

Declared by:

selfhost.mail.host

SMTP server hostname. Setting it is what makes active true, so the rest of this block is expected alongside it.

Type: string

Declared by:

selfhost.mail.passwordFile

Path to a root-readable file containing the SMTP password, loaded into each consumer via systemd credentials.

Type: string

Declared by:

selfhost.mail.port

SMTP server port

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default:

587

Declared by:

selfhost.mail.tls

TLS mode for SMTP connection

Type: one of “none”, “starttls”, “tls”

Default:

"starttls"

Declared by:

selfhost.mail.user

SMTP authentication username

Type: string

Declared by:

selfhost.monitoring.enable

Prometheus monitoring (metrics, healthchecks, alert rules). Prometheus and Alertmanager stay unrouted until a forward-auth provider is active.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.monitoring.alertmanager.enable

Whether to enable Alertmanager alert delivery (routes fired alerts to notify).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.monitoring.alertmanager.port

Alertmanager listen port (localhost, behind ingress).

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default:

9093

Declared by:

selfhost.monitoring.blackboxPort

Blackbox-exporter listen port (localhost) for service healthchecks.

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default:

9116

Declared by:

selfhost.monitoring.prometheusPort

Prometheus listen port (localhost, behind ingress).

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default:

9090

Declared by:

selfhost.monitoring.retentionSize

Prometheus metrics retention size cap (the effective bound).

Type: string

Default:

"5GB"

Declared by:

selfhost.monitoring.retentionTime

Prometheus metrics retention time.

Type: string

Default:

"365d"

Declared by:

selfhost.monitoring.scopes

Monitoring scopes: infrastructure, hardware, and other non-service metric sources

Type: attribute set of (submodule)

Default:

{ }

Declared by:

selfhost.monitoring.scopes.<name>.enable

Whether to enable this monitoring scope.

Type: boolean

Default:

true

Example:

true

Declared by:

selfhost.monitoring.scopes.<name>.exporters

Prometheus exporter definitions merged into services.prometheus.exporters

Type: attribute set of anything

Default:

{ }

Declared by:

selfhost.monitoring.scopes.<name>.rules

Prometheus alert rule groups

Type: list of (attribute set)

Default:

[ ]

Declared by:

selfhost.monitoring.scopes.<name>.scrapeConfigs

Prometheus scrape configurations

Type: list of (attribute set)

Default:

[ ]

Declared by:

selfhost.monitoring.scopes.<name>.systemdOverrides

Systemd service overrides for monitoring-related units

Type: attribute set of anything

Default:

{ }

Declared by:

selfhost.monitoring.scrapeInterval

Global Prometheus scrape and evaluation interval.

Type: string

Default:

"60s"

Declared by:

selfhost.notify.package

send-notification implementation. Contract: send-notification --topic <t> --message <m> [--title <T>] [--priority <p>] [--tags <x>], reading NOTIFY_URL and NOTIFY_TOKEN_FILE from the env.

Type: package

Default:

pkgs.selfhost.send-notification

Declared by:

selfhost.notify.active

Whether a notify provider is active. Compose service defaults against this.

Type: boolean (read only)

Default: true once a provider defines url

Declared by:

selfhost.notify.defaultTopic

Topic a publisher falls back to when it names none. This is the consumer’s own default, not the framework’s, so it creates no topic nobody asked for; what it changes is whether forgetting to route something means silence or means hearing about it on one known topic.

Type: null or impossible (empty enum)

Default:

null

Declared by:

selfhost.notify.ntfy.enable

Whether to enable ntfy notification implementation (server + provisioning).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.notify.ntfy.remotePublishers

Publishers that run on another host. Their user, ACL and token are provisioned here; there is no secret transport between hosts, so copying the token into the other host’s own secrets stays manual.

Type: attribute set of (submodule)

Default:

{ }

Declared by:

selfhost.notify.ntfy.remotePublishers.<name>.tokenFile

Where the provisioned token lands, root-owned 0400.

Type: string

Default:

"/var/lib/homelab-secrets/notify-publishers/‹name›"

Declared by:

selfhost.notify.ntfy.remotePublishers.<name>.topics

Topics this publisher may write to. A remote task that routes failures separately needs both its topic and its failureTopic here, since this host cannot read the other one’s config.

Type: non-empty (list of impossible (empty enum))

Declared by:

selfhost.notify.provisioningUnit

Systemd unit of the active provider that provisions publisher tokens; consumers that read a token via LoadCredential order after it. null = no provider, or a provider with no provisioning step.

Type: null or string

Default:

null

Declared by:

selfhost.notify.topics

Notification topics and their visibility. Naming them is the consumer’s: no framework subsystem registers or defaults one, so a topic cannot outlive the publisher a default pointed at.

Type: attribute set of (submodule)

Default:

{ }

Declared by:

selfhost.notify.topics.<name>.public

Whether the topic can be read without authentication (grants everyone ro). Publishing always needs a per-service token, so this decides who can see the messages, not who can send them.

Type: boolean

Default:

false

Declared by:

selfhost.notify.url

Base URL of the notification endpoint, set by the active notify provider and consumed by send-notification (NOTIFY_URL). Left undefined until one is, which is what active reads.

Type: string

Declared by:

selfhost.oidcPlaceholder

Opaque placeholder pair per OIDC client.

Type: attribute set of (submodule) (read only)

Default:

{ }

Declared by:

selfhost.oidcPlaceholder.<name>.id

Placeholder standing in for this client’s OIDC client ID.

Type: string

Declared by:

selfhost.oidcPlaceholder.<name>.secret

Placeholder standing in for this client’s OIDC client secret.

Type: string

Declared by:

selfhost.runtimePlaceholder

Opaque placeholder string per declared runtime secret.

Type: attribute set of string (read only)

Default:

{ }

Declared by:

selfhost.runtimeSecrets

Runtime-generated secret files (one-shot openssl rand).

Type: attribute set of (submodule)

Default:

{ }

Declared by:

selfhost.runtimeSecrets.<name>.bytes

Random bytes (hex-encoded; file is 2x chars).

Type: signed integer

Default:

32

Declared by:

selfhost.runtimeSecrets.<name>.group

Unix group; defaults to owner’s primary group.

Type: null or string

Default:

null

Declared by:

selfhost.runtimeSecrets.<name>.mode

File mode (octal) of the secret file.

Type: string

Default:

"0400"

Declared by:

selfhost.runtimeSecrets.<name>.onMissing

When the file is missing: generate a new value, warn and leave it absent, or generate only while the guarded data is empty.

Type: one of “regenerate”, “warn” or (submodule)

Default:

"regenerate"

Example:

{
  generateOnce = "/var/lib/pocket-id";
}

Declared by:

selfhost.runtimeSecrets.<name>.owner

Unix owner of the file.

Type: string

Default:

"root"

Declared by:

selfhost.runtimeSecrets.<name>.path

Where this secret is generated; read it to feed a consumer that wants a file path.

Type: string (read only)

Default: /var/lib/homelab-secrets/<name>

Declared by:

selfhost.runtimeSecrets.<name>.restartUnits

Units consuming this secret; wired requires+after on the generator (ordering only; values are persistent).

Type: list of string

Default:

[ ]

Declared by:

selfhost.runtimeSecretsDir

Persistent directory containing runtime-generated secret files. Include in backups.

Type: string (read only)

Default:

"/var/lib/homelab-secrets"

Declared by:

selfhost.runtimeTemplates

Templates rendered from runtime secrets and OIDC credentials.

Type: attribute set of (submodule)

Default:

{ }

Declared by:

selfhost.runtimeTemplates.<name>.content

Template body; reference secrets via runtimePlaceholder.<name> and OIDC creds via oidcPlaceholder.<client>.{id,secret}.

Type: strings concatenated with “\n”

Declared by:

selfhost.runtimeTemplates.<name>.group

Unix group; defaults to owner’s primary group.

Type: null or string

Default:

null

Declared by:

selfhost.runtimeTemplates.<name>.mode

File mode (octal) of the rendered file.

Type: string

Default:

"0400"

Declared by:

selfhost.runtimeTemplates.<name>.owner

Unix owner of the rendered file.

Type: string

Default:

"root"

Declared by:

selfhost.runtimeTemplates.<name>.path

Rendered output path (tmpfs; regenerated each boot).

Type: string

Default:

"/run/homelab-secrets/templates/‹name›"

Declared by:

selfhost.runtimeTemplates.<name>.restartUnits

Units restarted when the template body changes between deploys.

Type: list of string

Default:

[ ]

Declared by:

selfhost.serviceAccounts

Non-human principals, keyed by account name. Per-app config mirrors the registry at serviceAccounts.<name>.services.<app>.

Type: attribute set of (submodule)

Default:

{ }

Declared by:

selfhost.serviceAccounts.<name>.description

What this account is for. Used as the gecos field when a POSIX user is created.

Type: string

Default:

""

Declared by:

selfhost.serviceAccounts.<name>.services.gitea.enable

Whether to enable a non-UI Gitea account for this service account.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.serviceAccounts.<name>.services.gitea.sshKeys

SSH keys for git-over-SSH; registered via the admin API on account creation.

Type: list of (submodule)

Default:

[ ]

Declared by:

selfhost.serviceAccounts.<name>.services.gitea.sshKeys.*.key

Public key in authorized_keys format.

Type: string

Declared by:

selfhost.serviceAccounts.<name>.services.gitea.sshKeys.*.readOnly

Register as a read-only (deploy) key.

Type: boolean

Default:

false

Declared by:

selfhost.serviceAccounts.<name>.services.radicale.enable

Whether to enable a Radicale login for this service account.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.serviceAccounts.<name>.services.radicale.passwordFile

File holding the login’s password, generated by default for its client elsewhere to copy.

Type: string

Default: a password generated under runtimeSecretsDir

Declared by:

selfhost.serviceAccounts.<name>.storage.smb.enable

Whether to enable an SMB account for this principal on a host serving selfhost.storage.shares.smb.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.serviceAccounts.<name>.storage.smb.passwordFile

File holding this principal’s SMB password, read at activation through a credential and never placed in the store. Generated by default, like Radicale’s and CouchDB’s: a person types it into a device once, so nobody needs to pick it. Set it instead when the same value has to exist somewhere else too, as for a machine principal whose client reads it from your own secret store: generating here would leave you hand-copying it there.

Type: string

Default: a password generated for this principal under runtimeSecretsDir

Declared by:

selfhost.serviceAccounts.<name>.unixAccount.enable

Whether to enable a POSIX account and matching primary group for this account on the host that declares it, so a service can resolve a session to a Unix identity.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.serviceAccounts.<name>.unixAccount.gid

As in users.groups.<name>.gid. Same reasoning as uid.

Type: null or signed integer

Default:

null

Declared by:

selfhost.serviceAccounts.<name>.unixAccount.uid

As in users.users.<name>.uid. Null picks a free one on activation; pin it where this account owns data that outlives the root filesystem, since the allocation is recorded only on root.

Type: null or signed integer

Default:

null

Declared by:

selfhost.services

Registry of selfhost services: routing, metadata, and integrations (HTTP ingress optional via ingress.enable).

Type: attribute set of (submodule)

Default:

{ }

Declared by:

selfhost.services.<name>.access.allowedGroups

Groups authorized to access this service (canonical groups or any a user is in). Empty means unrestricted (any authenticated user).

Type: list of (one of “admin”, “guests”, “users”)

Default:

[ ]

Declared by:

selfhost.services.<name>.access.model

Who authenticates its users: oidc, forwardAuth, native or open (see the Authentication section of the concepts chapter).

Type: one of “oidc”, “forwardAuth”, “native”, “open”

Default:

"native"

Declared by:

selfhost.services.<name>.access.oidc

OIDC client configuration, provisioned when access.model = "oidc".

Type: submodule

Default:

{ }

Declared by:

selfhost.services.<name>.access.oidc.callbackURLs

Callback URLs for the OIDC client

Type: list of string

Default: [ <publicUrl>/oauth2/oidc/callback ]

Declared by:

selfhost.services.<name>.access.oidc.group

Group name for this client’s credentials

Type: string (read only)

Default:

"homelab-oidc-‹name›"

Declared by:

selfhost.services.<name>.access.oidc.id.file

Path to the file containing the client ID

Type: string (read only)

Default:

"/var/lib/homelab-oidc/‹name›/id"

Declared by:

selfhost.services.<name>.access.oidc.id.placeholder

Stable stand-in for the client ID in config the framework does not render. Substitute it yourself from id.file.

Type: string (read only)

Default:

"@HOMELAB_OIDC_‹name›_ID@"

Declared by:

selfhost.services.<name>.access.oidc.name

Display name of the OIDC client in the provider

Type: string

Default:

"‹name›"

Declared by:

selfhost.services.<name>.access.oidc.pkce

Enable PKCE for this client

Type: boolean

Default:

false

Declared by:

selfhost.services.<name>.access.oidc.secret.file

Path to the file containing the client secret

Type: string (read only)

Default:

"/var/lib/homelab-oidc/‹name›/secret"

Declared by:

selfhost.services.<name>.access.oidc.secret.placeholder

Stable opaque stand-in for the client secret, substituted by the consumer. See id.placeholder.

Type: string (read only)

Default:

"@HOMELAB_OIDC_‹name›_SECRET@"

Declared by:

selfhost.services.<name>.access.oidc.systemd.dependentServices

Systemd services needing this client’s credentials; auto-wired requires/after/partOf.

Type: list of string

Default:

[ ]

Declared by:

selfhost.services.<name>.access.oidc.systemd.loadCredentials

Ready-to-use LoadCredential entries for systemd services

Type: list of string (read only)

Default:

[
  "oidc-id:/var/lib/homelab-oidc/‹name›/id"
  "oidc-secret:/var/lib/homelab-oidc/‹name›/secret"
]

Declared by:

selfhost.services.<name>.access.oidc.systemd.supplementaryGroups

Groups to add for direct credential file access

Type: list of string (read only)

Default:

[
  "homelab-oidc-‹name›"
]

Declared by:

selfhost.services.<name>.backend

Another entry whose backend this one routes to, for a second hostname onto one process. Null means it owns its backend.

Type: null or string

Default:

null

Example:

"radicale"

Declared by:

selfhost.services.<name>.backup.package

Package providing backup script. Use writeShellApplication with runtimeInputs for dependencies. OUTPUT_DIR is provided as an environment variable pointing to a fresh, empty directory for the hook’s output.

Type: null or package

Default:

null

Declared by:

selfhost.services.<name>.backup.after

Systemd services this backup hook requires and orders after.

Type: list of string

Default:

[ ]

Declared by:

selfhost.services.<name>.displayName

Human-readable name (defaults to attribute name)

Type: string

Default:

"‹name›"

Declared by:

selfhost.services.<name>.extraConfig

Consumer-owned per-service data with no first-class option (e.g. a landing-page tag); selfhost-nix never reads it. Co-located on the service entry instead of a parallel tree keyed by name. Read back at config.selfhost.services.<name>.extraConfig.

Type: open submodule of attribute set of anything

Default:

{ }

Declared by:

selfhost.services.<name>.healthcheck.path

Path for health checks (used by monitoring and homepage)

Type: string

Default:

"/"

Declared by:

selfhost.services.<name>.healthcheck.probeModule

Blackbox exporter module for health probes. Use http_any for services that require authentication on all endpoints.

Type: one of “http_2xx”, “http_any”

Default:

"http_2xx"

Declared by:

selfhost.services.<name>.healthcheck.url

Full health check URL (derived from url and healthcheck path)

Type: string (read only)

Default: <url><healthcheck.path>

Declared by:

selfhost.services.<name>.host

Hostname or IP where the service listens (local or remote)

Type: string

Default: 127.0.0.1, or the backend entry’s host

Declared by:

selfhost.services.<name>.ingress.enable

Whether to enable HTTP ingress route for this service.

Type: boolean

Default: on once the entry has a backend to route to and its access.model is satisfied

Example:

true

Declared by:

selfhost.services.<name>.integrations.homepage

Homepage dashboard integration

Type: submodule

Default:

{ }

Declared by:

selfhost.services.<name>.integrations.homepage.enable

Whether to enable homepage entry for this service.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.services.<name>.integrations.homepage.group

Free-form tile group this service belongs to; you map groups to tabs/layout in your dashboard.

Type: string

Default:

"Services"

Declared by:

selfhost.services.<name>.integrations.homepage.icon

Icon name from dashboard-icons (e.g. ‘miniflux.svg’)

Type: null or string

Default:

"‹name›.svg"

Declared by:

selfhost.services.<name>.integrations.homepage.settings

Extra homepage tile settings merged into the generated entry (e.g. a widget).

Type: attribute set

Default:

{ }

Declared by:

selfhost.services.<name>.integrations.monitoring.enable

Whether to enable monitoring for this service.

Type: boolean

Default: follows selfhost.monitoring.enable

Example:

true

Declared by:

selfhost.services.<name>.integrations.monitoring.exporters

Custom Prometheus exporters for this service

Type: attribute set of anything

Default:

{ }

Declared by:

selfhost.services.<name>.integrations.monitoring.healthcheck

Whether to auto-generate a blackbox healthcheck probe for this service

Type: boolean

Default:

true

Declared by:

selfhost.services.<name>.integrations.monitoring.rules

Custom Prometheus alert rule groups

Type: list of (attribute set)

Default:

[ ]

Declared by:

selfhost.services.<name>.integrations.monitoring.scrapeConfigs

Custom Prometheus scrape configurations

Type: list of (attribute set)

Default:

[ ]

Declared by:

selfhost.services.<name>.integrations.monitoring.systemdOverrides

Systemd service overrides for monitoring-related units

Type: attribute set of anything

Default:

{ }

Declared by:

selfhost.services.<name>.integrations.notify

notification integration

Type: submodule

Default:

{ }

Declared by:

selfhost.services.<name>.integrations.notify.enable

Publish notifications for this service/task.

Type: boolean

Default: on when a notify provider is active and topic is set

Declared by:

selfhost.services.<name>.integrations.notify.failureTopic

Topic for task-failure notifications. Defaults to topic; point it somewhere louder to separate failures from routine summaries. The publisher is granted write on both.

Type: null or impossible (empty enum)

Default: topic

Declared by:

selfhost.services.<name>.integrations.notify.titlePrefix

Prepended to failure-notification titles as <prefix>: . Set it when several hosts publish to one topic, where the unit name alone does not say which host failed.

Type: string

Default:

""

Declared by:

selfhost.services.<name>.integrations.notify.tokenFile

Root-owned path to this publisher’s access token. Non-root publishers receive it via LoadCredential (see the security chapter).

Type: string

Default:

"/var/lib/homelab-secrets/notify-publishers/‹name›"

Declared by:

selfhost.services.<name>.integrations.notify.topic

Notification topic this service/task publishes to (null = none). A task falls back to notify.defaultTopic, since the hook reporting its failure is the framework’s own; a service names one when it has something to say.

Type: null or impossible (empty enum)

Default: notify.defaultTopic for a task, null for a service

Declared by:

selfhost.services.<name>.meta.category

Canonical grouping key; a consumer surface (e.g. a landing page) groups services by this.

Type: null or string

Default:

null

Declared by:

selfhost.services.<name>.meta.description

Short description (nixpkgs meta.description); shown under the name on a dashboard tile. Empty renders no subtitle.

Type: string

Default:

""

Declared by:

selfhost.services.<name>.meta.homepage

Upstream project homepage (nixpkgs meta.homepage).

Type: null or string

Default:

null

Declared by:

selfhost.services.<name>.name

Registry identifier (defaults to attribute name)

Type: string

Default:

"‹name›"

Declared by:

selfhost.services.<name>.ownsBackend

Whether this entry’s host:port is a socket it actually listens on (read-only).

Type: boolean (read only)

Default: true when port is set and backend is not

Declared by:

selfhost.services.<name>.port

Port the service listens on. Leave unset for a service with no HTTP backend (a UDP daemon, say).

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Declared by:

selfhost.services.<name>.publicHost

Public hostname (derived from subdomain and ingress.domain)

Type: string

Default: <subdomain>.<ingress.domain>

Declared by:

selfhost.services.<name>.publicUrl

Full public URL (derived from publicHost)

Type: string

Default: https://<publicHost>

Declared by:

selfhost.services.<name>.scheme

URL scheme for backend connection

Type: one of “http”, “https”

Default: http, or the backend entry’s scheme

Declared by:

selfhost.services.<name>.storage.mounts

Named selfhost SMB shares this entry may access; their automount guards start before its units.

Type: list of impossible (empty enum)

Default:

[ ]

Declared by:

selfhost.services.<name>.storage.users

POSIX users this entry’s units run as. Each joins the group of every mounts share that grants by group, so adding a share is one edit rather than two. Empty grants nothing, which is right for a unit running as root or under DynamicUser. A share owned by a uid is skipped, so a second consumer of one still needs its group granted by hand.

Type: list of non-empty string

Default:

[ ]

Example:

[
  "romm"
  "nginx"
]

Declared by:

selfhost.services.<name>.subdomain

Subdomain prefix (combined with domain for publicHost)

Type: string

Default:

"‹name›"

Declared by:

selfhost.services.<name>.systemdServices

Systemd units this service owns, which concerns attach to. Names are not checked, so set this when they differ from the service.

Type: (list of string) or string convertible to it

Default: the backend entry’s units, else the matching OCI container’s unit, else <name>

Declared by:

selfhost.services.<name>.traefik.middlewares

Extra Traefik middleware definitions to attach to this service’s router

Type: attribute set of attribute set of unspecified value

Default:

{ }

Declared by:

selfhost.services.<name>.url

Full URL for proxying (derived from scheme, host and port)

Type: string

Default: <scheme>://<host>:<port>

Declared by:

selfhost.storage.mounts.smb.enable

Whether to enable Home-server storage.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.storage.mounts.smb.credentialsPath

Path to the SMB credentials file (must be provided by the host, e.g. via sops-nix)

Type: string

Declared by:

selfhost.storage.mounts.smb.hostname

IP or hostname of the SMB server; prefer an IP or /etc/hosts entry for reliable resolution at boot.

Type: string

Declared by:

selfhost.storage.mounts.smb.shares

CIFS shares keyed by remote root folder, each behind its own access group and mounted on demand.

Type: attribute set of (submodule)

Default:

{ }

Example:

{
  bphenriques = { };
  media = { };
}

Declared by:

selfhost.storage.mounts.smb.shares.<name>.gid

GID for the mount group (required for SMB mount options)

Type: signed integer

Declared by:

selfhost.storage.mounts.smb.shares.<name>.group

Name of the group with access to the mount

Type: string

Default:

"homelab-‹name›"

Declared by:

selfhost.storage.mounts.smb.shares.<name>.localMount

Local mount point for the share

Type: string

Default:

"/mnt/homelab-‹name›"

Declared by:

selfhost.storage.mounts.smb.shares.<name>.systemd.dependentServices

Extra systemd service names to order after this share’s automount guard.

Type: list of string

Default:

[ ]

Declared by:

selfhost.storage.mounts.smb.shares.<name>.uid

File-owner UID on the client (default 0/root → access via group; set per-user for owner-level ops like chmod/git).

Type: signed integer

Default:

0

Declared by:

selfhost.storage.shares.smb.enable

Whether to enable an SMB server exporting the shares declared here.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.storage.shares.smb.openFirewall

Whether to open TCP 445. Only 445: netbios is disabled, so 137-139 never listen.

Type: boolean

Default:

false

Declared by:

selfhost.storage.shares.smb.shares

Shares exported over SMB, keyed by the name clients connect to.

Type: attribute set of (submodule)

Default:

{ }

Declared by:

selfhost.storage.shares.smb.shares.<name>.access

Who may reach this share, and at what level. Every name must have storage.smb.enable in its registry.

Type: submodule

Default:

{ }

Declared by:

selfhost.storage.shares.smb.shares.<name>.access.groups

Groups let into this share, by selfhost.users.<name>.groups. Additive: a person holding several gets the most permissive. No none here, because a group grant is taken away per person under users.

Type: attribute set of (one of “rw”, “ro”)

Default:

{ }

Example:

{
  family = "rw";
}

Declared by:

selfhost.storage.shares.smb.shares.<name>.access.serviceAccounts

Service accounts granted, by selfhost.serviceAccounts name. They hold no groups, so this is their only way in, and there is nothing for none to revoke.

Type: attribute set of (one of “rw”, “ro”)

Default:

{ }

Example:

{
  machine-backup = "ro";
}

Declared by:

selfhost.storage.shares.smb.shares.<name>.access.users

People granted directly, by selfhost.users name. Takes precedence over groups for that person, so none revokes what a group gave.

Type: attribute set of (one of “rw”, “ro”, “none”)

Default:

{ }

Example:

{
  teenager = "none";
}

Declared by:

selfhost.storage.shares.smb.shares.<name>.path

Absolute path exported under this share name. The host prepares and mounts it, ownership included; this module never touches what is there. Two shares may open onto one tree.

Type: string

Example:

"/srv/storage/media"

Declared by:

selfhost.storage.shares.smb.shares.<name>.resolvedAccess

Every principal let in, and at what level: what reaches valid users and read list. Read it to give the host’s own groups the same members.

Type: attribute set of (one of “rw”, “ro”) (read only)

Default: access, with groups expanded and none dropped

Declared by:

selfhost.tasks

Registry of externally-defined systemd units that opt into selfhost concerns (notify, storage).

Type: attribute set of (submodule)

Default:

{ }

Declared by:

selfhost.tasks.<name>.integrations.notify

notification integration

Type: submodule

Default:

{ }

Declared by:

selfhost.tasks.<name>.integrations.notify.enable

Publish notifications for this service/task.

Type: boolean

Default: on when a notify provider is active and topic is set

Declared by:

selfhost.tasks.<name>.integrations.notify.failureTopic

Topic for task-failure notifications. Defaults to topic; point it somewhere louder to separate failures from routine summaries. The publisher is granted write on both.

Type: null or impossible (empty enum)

Default: topic

Declared by:

selfhost.tasks.<name>.integrations.notify.titlePrefix

Prepended to failure-notification titles as <prefix>: . Set it when several hosts publish to one topic, where the unit name alone does not say which host failed.

Type: string

Default:

""

Declared by:

selfhost.tasks.<name>.integrations.notify.tokenFile

Root-owned path to this publisher’s access token. Non-root publishers receive it via LoadCredential (see the security chapter).

Type: string

Default:

"/var/lib/homelab-secrets/notify-publishers/‹name›"

Declared by:

selfhost.tasks.<name>.integrations.notify.topic

Notification topic this service/task publishes to (null = none). A task falls back to notify.defaultTopic, since the hook reporting its failure is the framework’s own; a service names one when it has something to say.

Type: null or impossible (empty enum)

Default: notify.defaultTopic for a task, null for a service

Declared by:

selfhost.tasks.<name>.name

Task identifier (defaults to the attribute name).

Type: string

Default:

"‹name›"

Declared by:

selfhost.tasks.<name>.storage.mounts

Named selfhost SMB shares this entry may access; their automount guards start before its units.

Type: list of impossible (empty enum)

Default:

[ ]

Declared by:

selfhost.tasks.<name>.storage.users

POSIX users this entry’s units run as. Each joins the group of every mounts share that grants by group, so adding a share is one edit rather than two. Empty grants nothing, which is right for a unit running as root or under DynamicUser. A share owned by a uid is skipped, so a second consumer of one still needs its group granted by hand.

Type: list of non-empty string

Default:

[ ]

Example:

[
  "romm"
  "nginx"
]

Declared by:

selfhost.tasks.<name>.systemdServices

Systemd units this task owns; selfhost concerns attach to them (storage automount guards, failure notifications). Names are trusted, not checked.

Type: (list of string) or string convertible to it

Default: <name>

Declared by:

selfhost.users

People, keyed by username. Per-service config mirrors the registry at users.<name>.services.<service>.

Type: attribute set of (submodule)

Default:

{ }

Declared by:

selfhost.users.<name>.auth.oidc.enable

Whether to enable OIDC account for this user.

Type: boolean

Default:

true

Example:

true

Declared by:

selfhost.users.<name>.auth.oidc.inviteByEmail

Whether to enable emailing this user a one-time enrolment link when the account is first created; otherwise provisioning prints the command to mint one.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.users.<name>.email

Email address, used by services that identify accounts by one (OIDC, Gitea, Immich).

Type: string

Declared by:

selfhost.users.<name>.extraConfig

Consumer-owned per-user data with no first-class option; selfhost-nix never reads it. Per-service config mirrors the registry at users.<name>.services.<name>, not here. Read back at config.selfhost.users.<name>.extraConfig.

Type: open submodule of attribute set of anything

Default:

{ }

Declared by:

selfhost.users.<name>.firstName

Given name, used to build name and by services that store it separately.

Type: string

Declared by:

selfhost.users.<name>.groups

Groups assigned to this user. If admin group is included, the user is marked as admin.

Type: list of string

Default:

[ ]

Declared by:

selfhost.users.<name>.isAdmin

Whether this user is an admin (derived from groups; set the group, not this).

Type: boolean (read only)

Default: true if the user’s groups include the admin group

Declared by:

selfhost.users.<name>.lastName

Family name, used to build name and by services that store it separately.

Type: string

Declared by:

selfhost.users.<name>.name

Display name shown by services that take a single full name.

Type: string

Default: <firstName> <lastName>, and just <firstName> when lastName is empty

Declared by:

selfhost.users.<name>.services.couchdb.enable

Whether to enable a CouchDB account for this user.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.users.<name>.services.couchdb.databases

Databases created for this user, with the user as their sole admin and member.

Type: list of string

Default:

[ ]

Declared by:

selfhost.users.<name>.services.filebrowser-quantum.enable

Whether to enable a FileBrowser entry for this user (access is gated by the service auth, not this flag).

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.users.<name>.services.filebrowser-quantum.admin

Whether to enable FileBrowser admin.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.users.<name>.services.filebrowser-quantum.storage

selfhost SMB mounts this user may access, keyed by permission; unioned into their scope (read-write iff any is rw).

Type: attribute set of (one of “ro”, “rw”)

Default:

{ }

Declared by:

selfhost.users.<name>.services.gitea.enable

Whether to enable a Gitea account for this user.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.users.<name>.services.gitea.admin

Gitea site-admin (reconciled each run); defaults to the user’s fleet isAdmin.

Type: boolean

Default:

false

Declared by:

selfhost.users.<name>.services.immich.enable

Whether to enable an Immich account for this user.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.users.<name>.services.immich.admin

Grant this account Immich administrator rights.

Type: boolean

Default: the user’s isAdmin

Declared by:

selfhost.users.<name>.services.immich.libraries

External libraries owned by this user: existing directories Immich scans in place. Empty leaves the account upload-only, which is the common case.

Type: list of (submodule)

Default:

[ ]

Declared by:

selfhost.users.<name>.services.immich.libraries.*.exclusionPatterns

Glob patterns skipped during the scan.

Type: list of string

Default:

[ ]

Declared by:

selfhost.users.<name>.services.immich.libraries.*.importPaths

Directories Immich scans for this library. The app grants the service write access to them.

Type: list of string

Default:

[ ]

Declared by:

selfhost.users.<name>.services.immich.libraries.*.name

Library name as shown in Immich; also its reconcile identity, so renaming creates a new one.

Type: string

Declared by:

selfhost.users.<name>.services.immich.passwordFile

Path to a file holding the initial password, applied at account creation and never reconciled. Null generates a random one, for accounts that sign in through OIDC.

Type: null or string

Default:

null

Declared by:

selfhost.users.<name>.services.immich.quotaBytes

Upload quota for this account in bytes. Null is unlimited. Reconciled, so changing it moves the existing account’s quota.

Type: null or (unsigned integer, meaning >=0)

Default:

null

Example:

107374182400

Declared by:

selfhost.users.<name>.services.immich.storageLabel

Folder name for this account under a {{label}} storage template. Null falls back to the account’s UUID. Reconciled.

Type: null or string

Default:

null

Declared by:

selfhost.users.<name>.services.jellyfin.enable

Whether to enable a Jellyfin account for this user.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.users.<name>.services.jellyfin.passwordFile

Path to a file holding the initial password, applied at account creation and never reconciled. Null generates a random one.

Type: null or string

Default:

null

Declared by:

selfhost.users.<name>.services.jellyfin.policy

Fields merged into this account’s Jellyfin UserPolicy on every run, applied verbatim. Anything not named here keeps whatever Jellyfin holds.

Type: attribute set of anything

Default:

{ }

Example:

{
  EnableSubtitleManagement = true;
  IsHidden = false;
}

Declared by:

selfhost.users.<name>.services.miniflux.settings

Per-user Miniflux preferences, applied verbatim via the user-update API (is_admin is framework-managed and ignored here).

Type: attribute set of anything

Default:

{ }

Example:

{
  display_mode = "fullscreen";
  theme = "dark_serif";
}

Declared by:

selfhost.users.<name>.services.radicale.enable

Whether to enable Radicale CalDAV/CardDAV access for this user.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.users.<name>.services.radicale.access.serviceAccounts

Service accounts that may read, add and change this user’s items and collections, but never delete, replace, rename or share a collection.

Type: list of string

Default:

[ ]

Declared by:

selfhost.users.<name>.storage.smb.enable

Whether to enable an SMB account for this principal on a host serving selfhost.storage.shares.smb.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.users.<name>.storage.smb.passwordFile

File holding this principal’s SMB password, read at activation through a credential and never placed in the store. Generated by default, like Radicale’s and CouchDB’s: a person types it into a device once, so nobody needs to pick it. Set it instead when the same value has to exist somewhere else too, as for a machine principal whose client reads it from your own secret store: generating here would leave you hand-copying it there.

Type: string

Default: a password generated for this principal under runtimeSecretsDir

Declared by:

selfhost.users.<name>.unixAccount.enable

Whether to enable a POSIX account for this person on the host that declares it, for services that resolve a session to a Unix identity. Identity only: no home and no shell, since the account exists for a service rather than for signing in. Add those on users.users.<name> where a person actually does.

Type: boolean

Default:

false

Example:

true

Declared by:

selfhost.users.<name>.unixAccount.uid

As in users.users.<name>.uid. Null picks a free one on activation; pin it where this account owns data that outlives the root filesystem, since the allocation is recorded only on root.

Type: null or signed integer

Default:

null

Declared by:

selfhost.users.<name>.username

Login name used by the services this user is enabled on.

Type: string

Default: the attribute name

Declared by: