psysonic/nixos-install.md

Installing Psysonic on NixOS (flake)

This guide is for NixOS users who want Psysonic from the upstream Git flake (github:Psychotoxical/psysonic). Supported systems match the flake: x86_64-linux and aarch64-linux.

Stability: The project is in very active development. For production or everyday use, prefer released builds: pin the flake input to a stable app-v* tag, or track the release branch (?ref=release). Following main or next is better suited to contributors and early testers.

Prerequisites

Flakes enabled (e.g. in configuration.nix):

nix.settings.experimental-features = [ "nix-command" "flakes" ];

Binary cache (Cachix)

The project publishes store paths to a public Cachix cache so you can substitute binaries instead of compiling Psysonic locally on every machine.

• Cache page: psysonic.cachix.org

• Substituter URL: https://psysonic.cachix.org

• Public key (trust this only if it matches what you expect from the cache owners):

  psysonic.cachix.org-1:M9cQyQ7tgvUWOQ5Pyt8ozlMoPLtOZir6MfRuTH9/VYA=
  

NixOS (configuration.nix or a flake module)

Add the substituter and its signing key under nix.settings. Keep cache.nixos.org in the list so ordinary nixpkgs binaries still resolve:

{
  nix.settings = {
    substituters = [
      "https://psysonic.cachix.org"
      "https://cache.nixos.org/"
    ];
    trusted-public-keys = [
      "psysonic.cachix.org-1:M9cQyQ7tgvUWOQ5Pyt8ozlMoPLtOZir6MfRuTH9/VYA="
      "cache.nixos.org-1:6NCHdSuAYQQOxGEKTGXLN9WWRXoSBT8GRiSnR6IdfGW="
    ];
  };
}

After nixos-rebuild switch, builds that hit the cache will download from Cachix. More background: Cachix — Getting started.

Install on NixOS (flake configuration)

Add the repo as an input, then reference packages.<system>.psysonic (or default, which is the same package).

Example: top-level flake.nix + nixosConfigurations

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    psysonic.url = "github:Psychotoxical/psysonic";
  };

  outputs = { self, nixpkgs, ... }@inputs: let
    system = "x86_64-linux";
  in {
    nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
      inherit system;
      modules = [
        ./configuration.nix
        {
          environment.systemPackages = [
            inputs.psysonic.packages.${system}.psysonic
          ];
        }
      ];
    };
  };
}

Inside a module where you already have pkgs and flake inputs in scope, a common pattern is:

environment.systemPackages = with pkgs; [
  # …
  inputs.psysonic.packages.${pkgs.stdenv.hostPlatform.system}.psysonic
];

Linux wrapper (default vs legacy X11)

The flake exposes three Linux attributes (two are the same derivation):

Flake attribute	Wrapper behaviour
psysonic, default, psysonic-gdk-session	Wrappers prefix libraries only (GStreamer, AppIndicator); GDK_BACKEND is not pinned. The binary invokes webkit2gtk-nvidia-quirk early on Linux (unless PSYSONIC_WEBKIT_GPU_ACCEL is set); no extra WEBKIT_DISABLE_* heuristics in main.rs. Override with GDK_BACKEND, WEBKIT_DISABLE_*, etc. whenever you want.
psysonic-x11-legacy	Former default: GDK_BACKEND=x11 pinned in the wrapper. Use if you relied on XWayland-ish stability on messy stacks. Same binary as psysonic.

psysonic-gdk-session remains a back-compat alias for psysonic (identical store path).

Example: legacy X11 wrap

inputs.psysonic.packages.${system}.psysonic-x11-legacy

Or one-shot (quote the URL in zsh — ? / # are special):

nix run 'github:Psychotoxical/psysonic#psysonic-x11-legacy' -- --help

Pinning a revision, branch, or tag

• main (default in the examples above) follows upstream development.

• Channel branches (next, release) exist for pre-release / release automation. For operational installs, prefer release (or an app-v* tag) over next or main; use ?ref=next only if you want pre-release channel builds.

  psysonic.url = "github:Psychotoxical/psysonic?ref=release";
  

• Tags (app-v*) match published GitHub releases and are the usual choice for a reproducible install aligned with a shipped version:

  psysonic.url = "github:Psychotoxical/psysonic?ref=app-v1.44.0";  # example; pick a tag that exists on GitHub
  

Use a ref (branch, tag, or commit SHA) that exists on GitHub.

How flake.lock and nix/upstream-sources.json stay in sync

CI runs a verify-nix job (Nix build, npmDepsHash refresh, flake.lock refresh, Cachix push) from .github/workflows/reusable-channel-publish.yml, invoked by:

• .github/workflows/next.yml (Next channel, branch next)
• .github/workflows/release.yml (Release channel, branch release)

So the lock and nix/upstream-sources.json (npmDepsHash) are updated as part of channel publishing, not only from a single legacy “tag-only” path. On main, nix-npm-deps-hash-sync.yml can also open PRs when package-lock.json changes so the Nix npm hash does not drift.

End users who pin main should run nix flake update psysonic (or equivalent) periodically if they want the latest lock inputs from upstream.

One-shot run (no system install)

From any machine with flakes:

nix run 'github:Psychotoxical/psysonic'

Same as nix build / packages.<system>.default (session-native GDK); uses the flake apps output. For an X11-pinned launcher (old default), use 'github:Psychotoxical/psysonic#psysonic-x11-legacy' (see Linux wrapper above). psysonic-gdk-session is an alias—same as psysonic. With a branch pin, keep the whole github:…?ref=…#… string in single quotes under zsh.

Apply configuration

• NixOS flake host

  sudo nixos-rebuild switch --flake .#my-host
  

• Home Manager (if used separately)

  home-manager switch --flake .#my-user@my-host
  

Home Manager

If you manage packages with Home Manager, add the same package to home.packages:

home.packages = [
  inputs.psysonic.packages.${pkgs.stdenv.hostPlatform.system}.psysonic
];

(Adjust how inputs / pkgs are passed into your Home Manager module.)

Development shell (contributors)

From a flake-enabled clone of the repo:

• nix develop — enters the upstream devShell (Rust, Node 22, WebKitGTK, GStreamer plugins for the webview, env hooks aligned with package.json / Tauri dev).
• nix shell .#devShells.default — same packages and hooks without nix develop’s subshell semantics.

The flake devShell uses the same nixpkgs input as packages.psysonic (see flake.nix).

Desktop entry

The flake package installs a .desktop file and icon via copyDesktopItems; after nixos-rebuild switch (or a Home Manager activation that includes the package), Psysonic should appear in your application launcher like any other desktop app.

Troubleshooting (Linux / WebKit)

Some GPU / compositor setups show a black window or broken scrolling under Wayland/EGL. The upstream Help / FAQ documents workarounds (e.g. running under X11 and compositor-related env vars). Those apply to the Nix-built binary as well as other Linux builds.

More detail in-repo

• flake.nix — packages, apps, devShells, supported systems; inline comments for nix build / nix develop / nix run.
• nix/psysonic.nix — how the app is built from this source tree (npmDepsHash from nix/upstream-sources.json).
• .github/workflows/reusable-channel-publish.yml — verify-nix job (prefetch npm deps hash, nix flake update, nix build .#psysonic, Cachix push, optional lock refresh PR).
• .github/workflows/next.yml / .github/workflows/release.yml — channel workflows that call the reusable publish workflow with verify_nix: true.
• .github/workflows/nix-npm-deps-hash-sync.yml — keeps nix/upstream-sources.json aligned with package-lock.json on main via PRs.

For the full promotion and release picture (branches, tags, automation), see RELEASE_PROCESS.md.