Build a declarative media stack first, verify it locally, then publish only the web endpoint you intend to use
Nixflix is a declarative NixOS configuration manager that coordinates Jellyfin, Seerr, Navidrome, Starr applications, download clients, and related media-server infrastructure. This guide explains what Nixflix manages, how to plan and configure a deployment using the documented NixOS options, how to verify the resulting services without assuming ports or hostnames, and how to troubleshoot common integration problems. Once the selected web interface works locally, we show how to expose that specific HTTP endpoint with Localtonet without configuring inbound router port forwarding, changing firewall rules, setting up a VPN, or requiring a public IP address.
📋 What's in this guide
What Nixflix manages on NixOS
Nixflix is designed to make the configuration connecting a media-server stack reproducible. Instead of relying entirely on manual changes made across several web interfaces, it lets a NixOS configuration describe supported applications and selected application settings. Nixflix then uses the services' REST APIs, with a small number of documented exceptions, to apply that configuration.
This distinction matters. Nixflix is not a media player, a media library, or a tunneling service. It is a NixOS configuration manager for assembling and coordinating a stack. Its documented scope includes Sonarr, Radarr, Lidarr, Prowlarr, Jellyfin, Seerr, Navidrome, SABnzbd, qBittorrent, Maintainerr, PostgreSQL integration, and optional WireGuard support. You choose which components to enable. A basic deployment does not have to include every supported service.
Nixflix describes its operations as idempotent, meaning supported configuration work is intended to be safe to execute repeatedly. It also treats the configuration as the source of truth. That model is useful for rebuilding a host, reviewing changes through version control, and avoiding an undocumented collection of settings spread among multiple dashboards.
The repository lists nix develop, nix fmt, and nix flake check for working on the Nixflix source. They enter its development shell, format code, and run project checks. Do not treat them as deployment commands for a media server.
Prerequisites and decisions to make first
The verified project documentation identifies Nixflix as a NixOS configuration manager, so this guide assumes that the target machine already runs NixOS and that you can modify its system configuration. It also assumes you have an established, tested way to evaluate and activate configuration changes on that machine. The evidence available for this article does not establish a specific supported NixOS release, a required Nix version, or one universal activation command, so we do not invent those details.
Before editing the configuration, decide which services you actually need. Enabling a smaller stack is easier to validate and exposes fewer administrative interfaces. For example, a first deployment could enable Jellyfin plus one media manager, then add request management, indexer management, or download clients after the foundation works.
Storage planning
Choose a media directory and a state directory before enabling services. The official quick example uses /data/media as the media directory and /var/lib as the state directory, but those are examples rather than mandatory paths. Your paths must match the disks, mounts, permissions, backup policy, and storage layout of your own NixOS machine.
Media data and application state have different operational characteristics. Media files can be large and may live on dedicated storage. Application state can contain databases, indexes, metadata, and configuration needed to restore the stack. Confirm that each configured filesystem is mounted before dependent services start and that the relevant service identities can access the directories they need.
Secrets planning
Nixflix configuration can reference secret files for API keys. The documented example uses paths under /run/secrets for Sonarr, Prowlarr, and SABnzbd keys. This is important because values embedded directly in ordinary Nix expressions can end up in the world-readable Nix store. Use your existing NixOS-compatible secret-management process to create runtime secret files with appropriate ownership and permissions.
Keep media-service API keys in protected runtime files and keep Localtonet authentication tokens out of Nix files, shell history, screenshots, and public repositories. A device token identifies the client that can run a tunnel and must be treated as a credential.
Network and access planning
Decide whether users should reach one application directly or reach applications through nginx or Caddy. Nixflix supports reverse-proxy integration, but the correct choice depends on your configuration. A reverse proxy can provide one intentionally designed entry point, while direct service access can be simpler during initial local testing.
Do not select a tunnel target until the local deployment is working. Nixflix does not establish one universal hostname, URL, or port for every installation. Service ports, URL bases, bind addresses, and reverse-proxy routes depend on the options selected by the operator. The endpoint configured on your machine is the authoritative value.
Choose the services and public entry point
A media stack often contains both user-facing applications and administrative applications. Jellyfin and Navidrome are primarily content interfaces. Seerr accepts media requests. Sonarr, Radarr, Lidarr, Prowlarr, download clients, and maintenance tools generally expose operational controls. Those interfaces do not all need to be public simply because they run on the same host.
| Component | Documented role | Remote-access consideration |
|---|---|---|
| Jellyfin | Media server with managed libraries, plugins, subtitles, and related settings | A likely user-facing candidate, provided authentication and library permissions are configured appropriately |
| Seerr | Media request management integrated with Starr services and Jellyfin libraries | May be useful remotely, but should be exposed only after its users and permissions are configured |
| Navidrome | Music server supporting the OpenSubsonic API | Can be a user-facing endpoint if remote music access is intended |
| Sonarr, Radarr, and Lidarr | Media management applications configured through their APIs | Administrative interfaces should normally remain private unless there is a specific secured access requirement |
| Prowlarr | Indexer management integrated with the Starr stack | Usually an administrative interface rather than the first public endpoint |
| SABnzbd or qBittorrent | Download clients that Nixflix can integrate with Starr applications | Avoid exposing their control interfaces unless remote administration is explicitly required and protected |
| nginx or Caddy | Supported reverse-proxy options for services | Can provide a deliberate HTTP entry point instead of tunneling several application listeners independently |
The safest practical default is to expose only the interface required by remote users. If the goal is remote playback, that may be Jellyfin. If the goal is submitting requests, it may be Seerr. If your nginx or Caddy configuration already routes authorized users to selected applications, the reverse proxy may be the appropriate target. Avoid publishing every dashboard for convenience.
Localtonet standard HTTP tunneling is not the same as Nixflix's optional WireGuard feature, and it is not our VPN Manager. An HTTP tunnel publishes a chosen local HTTP service through a public address. Nixflix's WireGuard integration concerns networking configured as part of the media stack. Keep these designs conceptually separate when diagnosing routing or access.
Install and configure Nixflix
Nixflix's documentation directs new users to its installation guide to add the project to a NixOS configuration, followed by its examples and option reference. The extracted project evidence supplied for this draft does not include the installation guide's actual flake declaration, import expression, compatibility constraints, or activation command. Because those details determine whether a NixOS module can be evaluated correctly, we will not manufacture a flake input, module name, revision, or command.
The sequence below is therefore a configuration workflow, not a substitute for the project's version-specific installation page. During editorial review, the exact import syntax should be checked against the Nixflix release selected for the deployment. Pinning a reviewed release is preferable to silently changing module behavior during unrelated system rebuilds.
Add the selected Nixflix release to the NixOS configuration
Follow the Nixflix installation instructions that correspond to the release you intend to deploy. Add its module to the same configuration that defines the target NixOS host. Do not substitute the repository's development-shell commands for this module installation step.
Enable Nixflix and define the storage locations
Set nixflix.enable, then provide media and state directories that exist in your storage design. Check mount ordering, free space, ownership, and backup coverage before adding application data.
Enable only the first group of required services
Start with a manageable combination, such as Jellyfin and the specific Starr applications needed for the library. Add Seerr, Navidrome, download clients, PostgreSQL, theming, or other integrations after the initial services evaluate and start successfully.
Reference protected API-key files
Create required API keys through the relevant service workflow, place them in protected runtime secret files, and point the corresponding Nixflix secret options at those files. Verify that the services applying API configuration can read them without making them broadly accessible.
Evaluate and activate the NixOS configuration
Use the tested deployment and activation process for your NixOS environment. Review evaluation failures before activation, then inspect the resulting services rather than assuming every API configuration action completed because the system configuration evaluated.
Complete local validation before adding remote access
Confirm that each enabled application starts, reaches its storage, reads its secret files, and communicates with dependent applications. Identify the exact browser-accessible endpoint that will later become the Localtonet target.
A documented minimal configuration shape
The official quick example demonstrates the structure below. It enables Nixflix, sets media and state directories, enables Sonarr, Prowlarr, SABnzbd, and Jellyfin, and references runtime secret files for three API keys.
{
nixflix = {
enable = true;
mediaDir = "/data/media";
stateDir = "/var/lib";
sonarr = {
enable = true;
config.apiKey = {
_secret = "/run/secrets/sonarr-api-key";
};
};
prowlarr = {
enable = true;
config.apiKey = {
_secret = "/run/secrets/prowlarr-api-key";
};
};
sabnzbd = {
enable = true;
settings.misc.api_key = {
_secret = "/run/secrets/sabnzbd-api-key";
};
};
jellyfin.enable = true;
};
}Treat this as an illustration of the option hierarchy, not as a complete host configuration. It does not show how Nixflix is imported, how filesystems are mounted, how secret files are provisioned, how user permissions are assigned, or how a reverse proxy is configured. It also does not establish that these paths are appropriate for your server.
If you add nginx or Caddy integration, verify the project reference for the selected release before assigning hostnames, URL bases, or per-service proxy options. Nixflix supports both proxy choices and per-service opt-out, but there is no evidence-backed universal proxy configuration that can safely be copied into every deployment.
Nixflix can apply supported settings through service APIs. A manual dashboard change may later conflict with declarative values. Record intended changes in the NixOS configuration where Nixflix exposes the relevant option. Before upgrades, review release notes for changed defaults, fixes, and newly managed settings.
Verify the stack on the local network
Local verification should proceed from infrastructure to application behavior. This prevents an external tunnel from hiding a problem that already exists on the host. It also gives you the exact local target instead of relying on a default port copied from an unrelated installation.
1. Confirm that configuration activation succeeded
Start with the result of your NixOS activation process. An evaluation error generally indicates an invalid option, missing import, incompatible project revision, or malformed expression. An activation that succeeds does not necessarily prove that an application subsequently started or that API-based configuration completed.
2. Inspect the enabled services
Use the normal service-management and logging tools on your NixOS host to inspect each component you enabled. Service names are not listed here because the supplied evidence does not establish every generated unit name for every Nixflix version. Look for startup loops, inaccessible directories, missing secret files, database connection failures, and dependency timing errors.
Release v3.1.0 documents fixes involving Starr root-folder configuration racing application startup, ignored host configuration values, stale Jellyfin transcoding paths, nested secret references, and dependencies among Seerr, Sonarr, Radarr, and library configuration. These examples illustrate why logs and release notes matter when an application starts but declarative integration does not complete as expected.
3. Test the application on the host or LAN
Open the configured URL from the NixOS host or another permitted LAN device. The correct address comes from your service or reverse-proxy configuration. Do not assume that Jellyfin, Seerr, Navidrome, or any Starr application is using a particular port. Confirm the actual scheme, local IP address, hostname, port, and any URL base.
If the interface is bound only to loopback, a Localtonet client on the same host may still be able to reach it using its loopback address. If the client runs on another device, the service must be reachable from that device through an appropriate LAN address and network policy. Test from the same machine that will run our client whenever possible.
4. Validate application relationships
A page loading successfully does not prove that the stack is integrated. Confirm the relationships you configured. Examples include Seerr seeing the intended Jellyfin libraries, Seerr reaching selected Starr services, download clients appearing in the relevant Starr applications, and root folders resolving to the correct media paths.
Check permissions with a real low-risk operation rather than relying only on a settings page. A service may be able to read a directory but not create or rename content. Likewise, two applications can display the same textual path while seeing different underlying storage if mounts or namespaces differ.
5. Record the exact endpoint to publish
Write down the verified local target in the form required by an HTTP tunnel: the local IP address or hostname reachable from the Localtonet client, plus the listening port. Also record whether a reverse proxy expects a particular hostname or URL path. Do not place credentials in this note.
If the page cannot be reached locally from the device running our client, creating a public URL will not repair the service. Resolve binding, startup, storage, proxy, and firewall-policy issues first.
Expose the verified web endpoint with Localtonet
Once the chosen interface works locally, an HTTP tunnel can make it reachable from the public internet. Our client establishes an outbound connection from the device to a Localtonet relay server. This means the normal workflow does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
Install and run the Localtonet client on the NixOS machine if that client environment is supported by the current download, or on another supported device that can reach the Nixflix endpoint over the LAN. The supplied product context does not provide a verified NixOS-specific package, Nix expression, or installation command, so this article does not invent one. Use the current Localtonet installation instructions for an available client platform.
Install and run the Localtonet client
Run our client on the device that can reach the verified Nixflix service or reverse-proxy endpoint. Confirm that the local page is reachable from that device before continuing.
Authenticate or select the client device
Use the device-specific authentication token assigned through Localtonet. Keep the token private and select the device that will maintain the tunnel connection.
Select an available relay server
Choose from the server or region values currently presented by our platform. Availability can vary, so do not copy a hardcoded server code from an old tutorial.
Create an HTTP tunnel to the verified target
Enter the local IP address and port recorded during verification. Target the individual web application or the configured nginx/Caddy listener, depending on the entry point you deliberately selected.
Start the tunnel and test the public URL
Creating a tunnel does not start it. Use the Start button, then open the assigned public address from a network outside the server's LAN. Test authentication, navigation, and the specific user workflow you intend to support.
Stop or delete access when it is no longer required
Stop the tunnel to make the public endpoint unavailable while retaining its configuration, or delete it when the exposure is no longer needed. The tunnel is available only while the selected client is connected and the tunnel is running.
For the current dashboard workflow, consult our Localtonet HTTP tunnel documentation. Exact client installation methods, relay choices, and available options should always be taken from the current platform rather than assumed from a static example.
Selecting an HTTP process type
Localtonet HTTP tunnels can use a random subdomain, a custom subdomain, or a custom domain. All three process types serve the configured content through a public HTTPS address. Choose based on how stable and branded the address needs to be.
| Process type | Best fit | Important consideration |
|---|---|---|
| Random Sub Domain | Initial testing and temporary access | Use the address assigned by Localtonet and verify the complete application workflow before sharing it |
| Custom Sub Domain | A selected Localtonet subdomain where supported | Availability can depend on current dashboard options and plan details |
| Custom Domain | An operator-controlled public hostname | Check current Localtonet documentation for exact DNS requirements before changing records |
A working local login page is not automatically ready for internet exposure. Configure strong application authentication, remove unused accounts, apply least privilege, and expose only the required interface. Prefer a user-facing endpoint such as the intended Jellyfin, Seerr, or Navidrome interface over administrative dashboards unless remote administration is genuinely necessary.
Operate and update the deployment safely
A declarative stack still needs operational discipline. Nixflix reduces repetitive configuration work, but it does not replace backups, update review, account management, storage monitoring, or application-level authorization.
Pin and review changes
Keep the Nixflix revision deliberate. Before moving to a newer release, review changes to defaults, option names, managed API resources, dependency ordering, and service behavior. Version 3.1.0, for example, changed the default theme to catppuccin-mocha, added a Jellyfin Universal Plugin Repository manifest, expanded Lidarr profile management, added Navidrome, and fixed several configuration and startup issues.
Evaluate an update before activating it, then validate the same local checklist used during installation. Because supported API configuration is declarative, also inspect whether the update will create, modify, or remove remotely managed application resources.
Back up the right data
Back up the NixOS configuration, protected secret material through an appropriate secure process, application state, and any irreplaceable media or metadata. A copy of the declarative configuration helps reconstruct intended settings, but it is not automatically a replacement for application databases or user-generated state.
Test restoration procedures rather than assuming the presence of backup files is sufficient. Pay particular attention to filesystem permissions, mount points, database state, and secret-file locations on a rebuilt host.
Monitor tunnel and service availability separately
A remote page depends on two distinct layers. First, the Nixflix-managed application or reverse proxy must be running and reachable locally. Second, the selected Localtonet client must be connected and the tunnel must be running. A failure at either layer makes the public address unavailable.
Localtonet supports platform-wide Token/Tunnel webhooks for Connected and Disconnected changes in a selected Token Group. These webhooks are separate from application monitoring and do not prove that Jellyfin or another local service is healthy. Use them to observe tunnel or device connectivity, then monitor the application independently.
Limit the exposed surface
Do not create one public tunnel per service merely because it is possible. Start with one intentional endpoint. If a reverse proxy provides the routing design you need, confirm that it exposes only approved routes. If you tunnel an application directly, keep unrelated listeners private.
Stop unused tunnels. Remove obsolete users and API keys. Rotate credentials if they may have been disclosed. Continue applying operating-system and application updates through a reviewed NixOS workflow.
Troubleshooting Nixflix and Localtonet access
The NixOS configuration does not evaluate
Check that the Nixflix module was imported using the instructions for the selected release. Confirm option spelling and nesting against that release's reference. An example from another revision may contain options unavailable in yours. Also distinguish module installation from repository development commands, since entering the source development shell does not add the module to a host.
A service starts, but declarative configuration is not applied
Check the service's own logs and the logs of any Nixflix-generated configuration operation. Verify that the API key file exists when needed, contains the intended value, has usable permissions, and is referenced by the correct option. Confirm that the application endpoint configured for API access matches its actual bind address, port, and URL base.
Review the Nixflix release notes if behavior resembles a known startup-order or host-configuration problem. Do not work around a dependency problem by publishing an unhealthy interface.
Jellyfin starts but cannot use a library
Verify that the configured media path exists and is mounted. Confirm that Jellyfin and the relevant media managers refer to the intended directory layout and possess the required filesystem permissions. If a cache or transcoding directory changed, check for stale application configuration referring to an inaccessible old path.
The reverse proxy works locally by hostname but not through the tunnel
A reverse proxy can route requests according to the HTTP host name or path. Compare the request expected by nginx or Caddy with the public request arriving through the selected tunnel configuration. The supplied evidence does not define a universal Nixflix virtual-host rule or a Localtonet host-header setting, so inspect the actual configuration rather than applying a guessed directive.
As a diagnostic step, test the reverse proxy from the Localtonet client device using the same local address and routing assumptions configured in the tunnel. If only one application is required, targeting its verified local HTTP listener may simplify the design, provided the listener is intended to be reached that way.
The Localtonet URL does not load
Confirm that the selected device is connected and that the tunnel was explicitly started. Then test the configured local IP and port from that same device. Check for an incorrect target address, a service bound to a different interface, an inactive reverse proxy, or a local network policy preventing the client device from reaching the host.
Remember that a tunnel remains available only while the selected client is connected and the tunnel is running. A NixOS reboot can therefore affect both the application and the Localtonet client. Verify each layer separately after maintenance.
The public page opens, but login or application actions fail
First reproduce the operation locally. If it also fails locally, inspect application permissions, API relationships, storage access, and logs. If it fails only through the public address, investigate URL-base assumptions, absolute redirects, cookies, origin checks, reverse-proxy routing, and the hostname expected by the application. Change only settings documented for the deployed application version.
Remote playback is unreliable
Test local playback first and inspect the media server's behavior. Remote playback can depend on the server's available resources, transcoding configuration, source media, client capabilities, and both ends of the network path. The supplied evidence contains no performance guarantee or bandwidth figure for either Nixflix or Localtonet, so capacity should be measured in the actual environment rather than predicted from a generic benchmark.
Frequently asked questions
What is Nixflix?
Nixflix is a declarative media-server configuration manager for NixOS. It provides modules and API-based configuration for supported services including Jellyfin, Seerr, Navidrome, Sonarr, Radarr, Lidarr, Prowlarr, SABnzbd, qBittorrent, and related infrastructure. It is not itself a media player or public tunnel.
Can I install Nixflix with nix develop?
No. The repository documents nix develop as a command for entering the project's development shell. It also lists nix fmt and nix flake check for formatting and checks. Deployment requires adding the Nixflix module to the NixOS configuration according to the installation instructions for the selected release.
Does Nixflix require every supported media service?
No. Services are enabled through configuration. Start with the applications needed for your intended workflow and add integrations incrementally. This makes local verification and troubleshooting easier.
What port should I enter in the Localtonet HTTP tunnel?
Use the port from your deployed service or reverse-proxy configuration. Nixflix does not establish one universal public endpoint for every stack, and the supplied project evidence does not support assuming a specific port. Verify the endpoint locally from the Localtonet client device before creating the tunnel.
Should I expose Jellyfin directly or tunnel nginx or Caddy?
Either can be appropriate. Direct application access can be simpler for one interface. An existing nginx or Caddy configuration can provide a deliberate shared entry point and routing layer. Choose the endpoint you have verified locally, expose only required routes, and avoid publishing unrelated administrative services.
Does creating a Localtonet tunnel make it active immediately?
No. Creating the tunnel stores its configuration, but the tunnel must be started with the Start button. It remains available only while the selected client device is connected and the tunnel is running.
Is a Localtonet HTTP tunnel the same as a VPN?
No. An HTTP tunnel publishes a selected local web endpoint through a public address. Localtonet VPN Manager is our private mesh VPN feature. Nixflix also documents optional WireGuard integration, which is a separate part of the media-server network configuration.
Do I need router port forwarding or a public IP address?
Not for the normal Localtonet tunnel workflow. Our client creates an outbound connection to a relay server, so you can expose the configured endpoint without inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
Should API keys be written directly into the NixOS configuration?
Avoid placing plaintext secrets directly in ordinary Nix expressions. The documented Nixflix example references files under /run/secrets. Provision those files with a suitable secret-management process, restrict their permissions, and never commit real values to version control.
Connect your verified Nixflix endpoint with Localtonet
Finish the NixOS deployment, confirm the selected Jellyfin, Seerr, Navidrome, or reverse-proxy endpoint locally, then create an HTTP tunnel to that exact address without opening an inbound router port.
Get Started Free →
