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:
- modules/nixos/services/radicale/service-account.nix
- modules/nixos/services/gitea/service-account.nix
- modules/nixos/service-accounts.nix
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:
- modules/nixos/services/radicale/user.nix
- modules/nixos/services/miniflux/user.nix
- modules/nixos/services/jellyfin/user.nix
- modules/nixos/services/immich/user.nix
- modules/nixos/services/gitea/user.nix
- modules/nixos/services/couchdb/user.nix
- modules/nixos/services/filebrowser-quantum/selfhost.nix
- modules/nixos/users.nix
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: