---
title: NixOS
description: Install the Punktfunk host on NixOS from the repo's flake — add the binary cache, import the module, enable the host.
---

The repo's `flake.nix` builds `punktfunk-host`, `punktfunk-client`, `punktfunk-web` and
`punktfunk-scripting` and ships a NixOS module. **`x86_64-linux` only**, NixOS **24.11 or newer**.

## 1. Add the binary cache

Without it a build compiles the whole Rust workspace *and* gamescope from source — about an hour.
With it you get prebuilt binaries:

```nix
nix.settings = {
  substituters = [ "https://nix.unom.io" ];
  trusted-public-keys = [ "punktfunk-cache-1:yhOJmHxzg6tzXpxSFzlYn6Pc6r0jHprsWqt8MZC654o=" ];   # curl https://nix.unom.io/punktfunk-cache.pub
};
```

Off NixOS, put the same two values in `/etc/nix/nix.conf` as `extra-substituters` /
`extra-trusted-public-keys`. One trap: setting `inputs.punktfunk.inputs.nixpkgs.follows = "nixpkgs"`
changes every store path and misses the cache entirely —
[packaging/nix](https://git.unom.io/unom/punktfunk/src/branch/main/packaging/nix/README.md#binary-cache-do-this-before-your-first-build).

## 2. Import the module and enable the host

<Install platform="nixos" />

A typical host block:

```nix
services.punktfunk.host = {
  enable = true;
  users = [ "alice" ];     # added to the `input` group, for virtual gamepads
  openFirewall = true;
  desktopSession = true;   # on a machine you log into — see below
  settings = { RUST_LOG = "info"; };   # these become host.env
};
```

The module does declaratively what the deb/RPM scriptlets do — the systemd user services, udev
rules, kernel modules, sysctl tuning, the firewall ports and `input` group membership — and brings
the web console in alongside the host. `settings` writes `host.env` for you.

**Set `desktopSession = true` on any machine somebody logs into.** It ties the host to
`graphical-session.target`, so restarting Plasma or GNOME restarts the host with it; without it the
host keeps running against a compositor that no longer exists and fails capture on every later
session. Leave it off for the headless appliance route (a pinned compositor or a gamescope box),
which may never reach that target — same reasoning as
[Restart the host with your desktop](/docs/running-as-a-service#restart-the-host-with-your-desktop).

## 3. Start it

The host and console user services are defined but not started (set `autoStart = true` for an
appliance). From your graphical session:

```sh
systemctl --user enable --now punktfunk-host punktfunk-web
```

The plugin runner needs no such step — the module starts it, because the game-library scanners ship
as plugins (`services.punktfunk.scripting.autoStart = false;` to opt out).

**That's the install.** Continue with the [Quick Start from step 3](/docs/quickstart#3-open-the-web-console)
— open the console, pair a client, stream.

## When you want more

- **Run it without NixOS** (other distros, wrapped in [nixGL](https://github.com/nix-community/nixGL)
  so the GPU drivers resolve): `nix run git+https://git.unom.io/unom/punktfunk#punktfunk-host -- serve`.
- The full option reference — client, console and scripting options, GPU driver notes, headless
  appliance setup — is in
  [packaging/nix](https://git.unom.io/unom/punktfunk/src/branch/main/packaging/nix/README.md).
- Updating: `nix flake update punktfunk` in your flake directory, then `sudo nixos-rebuild switch`
  ([Updating](/docs/updating)). Removing: [Uninstall](/docs/uninstall#nixos).
