Package Management

Package Management and Caching

This repository includes a robust setup for building custom software and leveraging binary caches to speed up deployments.

Custom Packages (pkgs/)

The pkgs/ directory contains custom Nix packages and derivations that are not available or are outdated in the upstream nixpkgs.

Automated Updates with nvfetcher

To maintain the custom packages automatically, this repository heavily relies on nvfetcher.

• Configuration: The tracking targets are defined in pkgs/nvfetcher.toml.
• How it Works: Running nvfetcher reads the configuration, fetches the latest upstream versions (commits, releases, tags), and generates _sources/generated.nix and _sources/generated.json.
• Usage: In the derivation (default.nix), the package consumes the updated source using pkgs.callPackage ../_sources/generated.nix {}.

Authentication & Rate Limits

Because nvfetcher constantly hits the GitHub API to check for new releases, it is highly prone to being rate-limited. To prevent this, an encrypted GitHub personal access token is stored using agenix (nix_access_tokens.age).

Important

The nix_access_tokens secret is assigned to userSecretConfig to ensure the standard desktop user has read access. Without this, running nvfetcher as a normal user will fail with 403 Forbidden GitHub errors.

Updating Packages

To pull the newest sources and automatically build/apply them to your system, use the custom zsh aliases:

• update: Wrapper around nvfetcher that automatically points to the pkgs/nvfetcher.toml and authenticates using your agenix keyfile (KEYFILE_PATH=/run/agenix/nix_access_tokens).
• upgrade: Runs update and immediately chains it into rebuild, meaning it pulls new sources and redeploys the system in a single command.

Exceptions

Some packages are intentionally left out of the nvfetcher automation:

• apk-mitm: Relies on a yarn.lock hash (offlineCache) that changes on every version bump. Automating this requires a custom updater script.
• nuvio-desktop: The upstream developer uses inconsistent release artifact naming, making it difficult for nvfetcher to reliably template the URL.

Binary Caches

To avoid recompiling large packages (like specialized kernels or gaming packages) from source, this configuration uses multiple binary caches.

Dual Configuration

Caches must be declared in two places simultaneously. They must be manually kept in sync!

1. flake.nix (nixConfig): Used during the flake evaluation phase. Nix strictly requires nixConfig to be a literal attribute set, meaning it cannot be imported from another file or derived from a function.
2. modules/system/binary-cache.nix: Applied to the system itself, so tools running inside NixOS (like nixos-rebuild) know where to fetch binaries.

Current Caches

• nix-community: Standard community binary cache.
• nix-gaming: Cache for optimal gaming packages.
• tokidoki: Dedicated cache for nix-gaming-edge overrides.
• chaotic-nyx: Cache for Chaotic/CachyOS optimizations.
• anyrun: Cache for the Anyrun Wayland launcher.

When adding a new cache to the system, ensure it is added to both files to guarantee a cache hit.