nixflix: a declarative NixOS config for the whole *arr stack

The problem is a dozen web interfaces that do not talk to each other

Nixflix is described as a declarative media server configuration manager for NixOS, and the aim is to automate all of the connective tissue required to get the Starr and Jellyfin services working together. The services named in the README are Sonarr, Radarr, Lidarr, Prowlarr, Jellyfin and Seerr. The author's stated aim is that users configure the module and it just works, and the pain it names is specific: no version control for settings, tedious navigation through UI systems, and annoying interservice configuration.

That last one is the reason the project exists. The individual applications have APIs, and the README's argument is that surely we can use those APIs to automate the whole thing. The claim is that Nixflix is API-based, using the official REST APIs of each service with a couple of minor exceptions, and that it is idempotent, so all services can safely execute the same configuration repeatedly. The design intent is that your code is the source of truth, with no fear of drift, which is the usual promise of a declarative system applied to services that were not designed for it.

Opinionated, and that is stated as a feature

The README lists four properties with a slightly jokey tone, and one of them deserves unpacking. Nixflix is opinionated, and the question for any user is whether your taste matches the author's. The other three are more conventional: it is API-based, idempotent, and commanding, with your code as the source of truth.

The opinionated part shows up concretely in the defaults. The feature list says the default configuration follows TRaSH Guides, which is a well-known set of conventions for how the *arr applications should be set up, so a user who already knows those guidelines will find the defaults familiar. The unified theming feature goes further: all supported services can be themed to look the same, powered by theme.park, which is a shared theme catalogue rather than a per-service stylesheet. That is the kind of decision that saves a homelab operator an evening of CSS and prevents it, and it is also the kind that you cannot opt out of if you disagree.

The stack itself is a media server with a lot of moving parts, and the module list makes the scope clear. The media server stack covers pre-configured modules for Sonarr, Radarr, Lidarr and Prowlarr, and the broader service list adds Seerr for media requests, Navidrome as a music server supporting the OpenSubsonic API, SABnzbd and qBittorrent for downloads, Maintainerr for automatic cleanup of old media, and a Soulseek integration through slskd that is marked as coming soon.

What the module actually configures for the Starr services

The README lists the same set of capabilities for all four Arr services, API-based configuration, PostgreSQL integration, reverse proxy with nginx or Caddy, automatic directory creation, root folder management and custom media directories. That symmetry is the point of the project, since the *arr applications share a common shape, and a hand-configured stack usually has one service set up differently from the other three.

The directory handling is worth noting because it is where a hand-built stack usually goes wrong. Configurable media and state directories with automatic setup means the module creates the paths the applications expect, and root folder management means the *arr applications are told where their libraries live in a way that matches the filesystem layout the module has just created. PostgreSQL integration is optional and covers all the Arr services, so you can move them off their default embedded database without leaving the declarative model. The reverse proxy support is configurable per service with a per-service opt-out, which matters because some people want a local-only service that is not exposed at all.

There is also a service dependencies option for custom systemd service dependencies, which is the mechanism for ordering things that NixOS does not otherwise know are related.

Jellyfin, Seerr and the services that are not Arr applications

The non-Arr services get their own, smaller, treatment, and the differences tell you what each one can do. For Jellyfin the list is basic server management, libraries automatically configured based on selected media managers, plugin management and subtitle downloader management. So Jellyfin is not configured from scratch here, it is kept in step with whatever the Arr services are doing. Seerr handles media request management with automatic integration with the Starr services and with Jellyfin libraries, which is what closes the loop between a request and a download.

Navidrome is treated as the music server and supports the OpenSubsonic API. SABnzbd and qBittorrent both get automatic integration with the Starr services, so downloads land where the Arr applications expect them. Maintainerr does automatic cleanup of old media, which is the retention policy piece. Soulseek, through slskd, is listed with automatic integration with Aurral marked as coming soon, so the README is honest that that path is not finished. The Upcoming Features section lists better music tooling as an open item, which is consistent with the music side being the least developed.

PostgreSQL, WireGuard and the reverse proxy layer

Three infrastructure features cut across the whole stack, and each one addresses a homelab requirement that comes up again and again. PostgreSQL integration gives the Arr services a shared database backend rather than their default embedded one. WireGuard VPN integration is built in, with a kill switch and custom DNS, so the media services are reachable from outside without being exposed directly, and the kill switch means traffic does not silently fall back to the open network if the tunnel drops. Configurable nginx or Caddy integration puts a reverse proxy in front of the services, with the per-service opt-out again, and with automatic TLS through the proxy rather than in each application.

The Theming feature is the one that crosses service boundaries too. Unified theming through theme.park means the login pages and dashboards of the different applications can be made to look like one product, which for a family of services that each shipped their own visual identity is a substantial change to how the stack feels. Whether that is a benefit or a constraint depends on whether you want your services distinguishable from each other.

Working on the module: a dev shell, a formatter and a flake check

The Development section gives three commands, and for a Nix project they are the conventional ones. The development shell is entered with nix develop.

nix develop

Formatting is nix fmt.

nix fmt

And checking formatting and linting is nix flake check.

nix flake check

The repository layout explains what those commands operate on. There is a flake.nix with a flake.lock, a modules/ directory for the NixOS modules, a lib/ directory, a pkgs/ directory for packaging, a default.nix, a docs/ directory, a tests/ directory, a treefmt.nix for the formatter configuration, an update.sh script and a CHANGELOG.md. The presence of a tests/ directory and a treefmt.nix indicates that formatting and evaluation are both part of the normal workflow rather than something a contributor sets up by hand. The licence is MPL 2.0, the default branch is main, the last push was on 2026-10-20, and the recent releases are v3.2.0 from 2026-10-05, v3.1.0 from 2026-09-04 and v3.0.0 from 2026-07-12.

Where a declarative media stack is the wrong answer

Three situations point elsewhere. The first is a user who does not already run NixOS. Nixflix is a set of NixOS modules, so adopting it means adopting NixOS as the operating system of the machine that runs the stack, and the module assumes systemd units, NixOS options and the rest of that model. It is not a docker-compose alternative for a Synology or a NAS running something else.

The second is a user who wants the upstream web interfaces to stay authoritative. The module is commanding by design, and it applies its configuration over what the services have in their own databases. If you prefer to click through the settings in the Sonarr UI, or you have a colleague who does, that preference and the module will fight, and the README's framing, that your code is the source of truth, is the answer to the question of who wins.

The third is a stack with a service the module does not cover, since the integration list is finite and one entry is already marked as coming soon. The realistic alternative to compare against is configuring the services by hand through their own web interfaces, which is tedious and unversioned but gives you full control of every setting and no dependency on the module staying in step with upstream API changes. Nixflix wins that comparison on repeatability and loses it on coverage, and for a homelab operator the size of the *arr stack usually decides which side you land on.

Editorial conclusion

Nixflix fits a NixOS user who already runs the *arr stack and finds configuring it across a dozen web interfaces tedious, and who wants the configuration to live in version control next to the rest of their system. It does not fit someone who has never used NixOS, since this is a set of NixOS modules rather than a standalone installer, and it does not fit a user who wants to keep using the upstream web interfaces as the source of truth, because the module applies its own configuration over them. Before you adopt it, read the documentation site rather than the README, since the README explicitly points there for setup, and check the service list, because Jellyfin, Seerr, Navidrome, SABnzbd, qBittorrent, slskd and Maintainerr are configured differently from the Starr services and the Soulseek integration is marked as coming soon.

Frequently asked questions

Official sources

1. kiriwalawren/nixflix on GitHub
2. License: MPL-2.0
3. Project website
4. README
5. Releases