nix-cache-login

CLI tool for authenticating with a Nix binary cache via Keycloak OIDC. Obtains access tokens and writes them to a netrc file so Nix can use them transparently.

Canonical Repository: https://guardianproject.dev/ops/nix-cache-login

Overview

Nix binary caches can be protected with OIDC-based authentication backed by Keycloak. This tool handles the token lifecycle:

• Workstation users: authenticate via browser (Authorization Code + PKCE), get a 1-hour access token and a 24-hour refresh token
• Servers: authenticate headlessly via client credentials, get a short-lived access token refreshed on a timer

The access token is written to a netrc file, which Nix reads automatically when fetching from the cache.

Installation

# run directly
nix run guardianproject.dev/ops/nix-cache-login  

Or add as a flake input:

{
  inputs.nix-cache-login.url = "git+https://guardianproject.dev/ops/nix-cache-login";

  # use the package
  # nix-cache-login.packages.${system}.default
}

Configuration

Create $XDG_CONFIG_HOME/nix-cache-login/config.toml (default ~/.config/nix-cache-login/config.toml):

Workstation:

issuer = "https://id.guardianproject.info/realms/gp"
client_id = "nix-cache"
cache_host = "cache.guardianproject.dev"
netrc_path = "$XDG_CONFIG_HOME/nix/netrc"

Server (service account):

issuer = "https://id.guardianproject.info/realms/gp"
client_id = "nix-cache-server"
client_secret_file = "/run/secrets/nix-cache-client-secret"
cache_host = "cache.guardianproject.dev"
netrc_path = "$XDG_CONFIG_HOME/nix/netrc"

Path values support environment variable expansion ($VAR and ${VAR}).

netrc_path is the path this tool writes tokens to.

Configure Nix to read that same path.

This supports both cppnix and detsysnix. The latter has special requirements around netrc files, so set additionalNetrcSources to include the configured netrc_path.

Usage

nix-cache-login login            # authenticate via browser (default command)
nix-cache-login refresh          # refresh token without browser
nix-cache-login service-account  # headless client credentials flow
nix-cache-login status           # show token expiry info
nix-cache-login logout           # revoke tokens and clean up

Config path resolution order:

1. --config
2. $NIX_CACHE_LOGIN_CONFIG
3. $XDG_CONFIG_HOME/nix-cache-login/config.toml
4. /etc/nix-cache-login/config.toml (server fallback)

The NixOS server module exports NIX_CACHE_LOGIN_CONFIG and installs /etc/nix-cache-login/config.toml from services.nix-cache-login-server.configFile.

Module Integration

The Home Manager and NixOS modules in this repo install the package and refresh services.

Nix and detsysnix daemon configuration stays outside these modules.

Set your daemon to read the netrc_path configured in config.toml.

Maintenance

This tool is actively maintained by Guardian Project.

Issues

For bug reports and feature requests, please use the Issues page.

Security

For security-related issues, please contact us through our security policy.

License

Copyright (c) 2026 Abel Luck abel@guardianproject.info

This project is licensed under the GNU General Public License v3.0 or later - see the LICENSE file for details.