Install on NixOS

Polaris ships a flake with NixOS host integration and per-user services. This is a source-build/community-validation path, currently oriented toward NVIDIA on x86_64 Linux. Expect a substantial first build, including CUDA.

The example uses stable v1.4.13. The exact stable tag has not had a full Nix CI build; its Nix inputs match a later CI-built source. The public v1.4.14-beta.1 source has passed a full Nix package build. Neither result certifies the Home Manager setup below or a physical NixOS stream. See validation and limitations.

Before you start

Use an existing flake-based NixOS configuration with:

• A working NVIDIA driver and a graphical user session. Keep your existing NVIDIA configuration.
• Flakes enabled with nix-command and flakes in nix.settings.experimental-features.
• Home Manager integrated as a NixOS module, with a configured user and the appropriate home.stateVersion already set. Keep your existing NixOS and Home Manager versions and hardware configuration.

The NixOS module handles input access, discovery and firewall ports. The Home Manager module creates the user services. Both are needed for this example. Stop any other GameStream host, such as Sunshine, before starting Polaris so their default ports do not collide.

Add the flake input

Add this entry inside your existing inputs block:

polaris.url = "git+https://github.com/papi-ux/polaris?ref=refs/tags/v1.4.13&submodules=1";

Keep submodules=1: Polaris’s source includes third-party Git submodules. The git+https URL requests those files; a plain github:papi-ux/polaris reference does not include them. See the Nix flake reference documentation.

Add polaris to your existing outputs function’s input arguments, alongside nixpkgs and home-manager.

Add the host and user modules

In your existing nixosConfigurations.<hostname> definition, add the Polaris modules and configuration to its modules list. Replace alice with your existing desktop username. Keep your current configuration imports; the following shows where the additions fit:

modules = [
  ./configuration.nix
  # Keep your other existing modules here.

  polaris.nixosModules.overlay
  polaris.nixosModules.polaris
  {
    nixpkgs.config.allowUnfree = true; # The Polaris overlay enables CUDA.
    services.polaris = {
      enable = true;
      users = [ "alice" ];
    };
  }

  # Include this once; keep your existing Home Manager import if already present.
  home-manager.nixosModules.home-manager
  {
    home-manager.useGlobalPkgs = true;
    home-manager.users.alice = {
      # Keep your existing user configuration and home.stateVersion.
      imports = [ polaris.homeModules.polaris ];
      services.polaris.enable = true;
    };
  }
];

Merge the additions into existing attribute sets and lists rather than creating duplicate imports, modules or user definitions.

home-manager.useGlobalPkgs makes the system’s Polaris overlay available to the user module. It also disables Home Manager’s separate nixpkgs.* options; merge any existing per-user overlays or package configuration into the system setup before enabling it. See the Home Manager option reference.

The NixOS module installs Polaris, its Gamescope build and its portal. It enables uinput and uhid, installs packaged udev rules, enables Avahi discovery, and adds the named user to audio, uinput, video, render and input groups.

It also opens these firewall ports:

Protocol	Ports
TCP	47984, 47989, 47990, 48010
UDP	47998, 47999, 48000, 48010

47990 is the web console. These declarations apply across the interfaces covered by the NixOS firewall; review them for your network. See Network trust and VPNs before allowing remote access.

Build and start

From your configuration directory, build first. Replace myhost with your nixosConfigurations name:

sudo nixos-rebuild build --flake .#myhost

The overlay builds against your system’s nixpkgs. The flake’s own package outputs use its locked nixos-unstable input; compatibility with a different system pin needs to be checked by this build.

When the build succeeds, apply it:

sudo nixos-rebuild switch --flake .#myhost

Log out and back into your graphical session to pick up new group membership. The user modules attach Polaris and its private portal services to graphical-session.target. Check them as your desktop user:

systemctl --user status polaris.service polaris-gamescope-idle.service

If they are not running after login:

systemctl --user start polaris-gamescope-idle.service polaris.service

Open https://localhost:47990/#/welcome to create your account on a fresh installation. For an existing setup, use https://localhost:47990/#/login. Pair Nova or Moonlight, start a stream, and check the active capture and encoder in Mission Control.

The default user setup starts headless Gamescope with a private ScreenCast portal. Its initial configuration selects capture = portal and encoder = nvenc. It seeds ~/.config/polaris/polaris.conf only when the file does not exist; subsequent changes belong in the web console. Changing a module’s streamMode does not overwrite an existing configuration file.

NixOS host integration is declarative through these modules. The RPM/DEB --setup-host instructions and KMS-helper setup on the other distro pages do not apply here.

Troubleshooting

• A package or option is missing: check that both NixOS modules are imported and that Home Manager receives the system package set through home-manager.useGlobalPkgs.
• An unfree-package error: check nixpkgs.config.allowUnfree = true in the system configuration. The overlay enables CUDA.
• Missing third-party source: verify the input URL still has submodules=1, refresh that input’s lock entry, and rebuild.
• Controller input is unavailable: log in again after the rebuild and check your current groups with id -nG. The module grants input access to the users listed in services.polaris.users.
• The user service fails: read journalctl --user -u polaris.service -u polaris-portal.service -u polaris-portal-gamescope.service -b and check that a graphical user session and the NVIDIA driver are available.

For pairing and stream problems, use Troubleshooting and export diagnostics just after the affected attempt.

Update, roll back or uninstall

To update, change the release tag in polaris.url, refresh its lock entry, then build and apply your configuration again:

nix flake update polaris
sudo nixos-rebuild build --flake .#myhost
sudo nixos-rebuild switch --flake .#myhost

Updating a lock entry while keeping the same release tag keeps that release. Older Nix versions use nix flake lock --update-input polaris instead of nix flake update polaris. For the public prerelease, use ref=refs/tags/v1.4.14-beta.1 and keep submodules=1. Read Updates and beta releases first. A new release may require another source build.

NixOS keeps earlier system generations. To return to the previous one:

sudo nixos-rebuild switch --rollback

This also rolls back the Home Manager configuration managed by that system generation. It does not restore mutable Polaris settings or pairing state.

To uninstall, remove the Polaris input, both Polaris NixOS module imports, polaris.homeModules.polaris, and the services.polaris declarations you added. Rebuild and apply the configuration. Keep other Home Manager, GPU and input configuration that your system uses independently. Review nixpkgs.config.allowUnfree and home-manager.useGlobalPkgs too; keep them if other parts of your configuration need them. NVIDIA drivers commonly need unfree packages.

Your ~/.config/polaris/ remains. See Uninstall Polaris, or start over before deleting credentials, pairing data or your library.

Validation and limitations

The public flake exports packages for x86_64-linux and aarch64-linux, NixOS host modules, Home Manager modules and hjem modules. This guide covers the NVIDIA/x86_64 path using Home Manager. AMD/Intel, aarch64, hjem, and physical streaming on NixOS are unverified here. The Nix package supplies no privileged KMS wrapper; KMS capture is not covered by this installation path.

The Home Manager module and this complete system integration have not been evaluated or run for this guide. Public Nix CI on beta.1 passed the exact beta.1 package build. Stable v1.4.13’s package expression and npm lock match a later source with a successful Nix build, but that is not a build of the exact stable source.

The installation examples follow the public stable flake exports, NixOS module, shared options and user module. Nova has no package in this flake; its client installation is documented separately in Nova on Linux.