Client Setup

Client Setup Guide#

Configure your Nix clients to use your ncps cache.

Get Public Key#

First, retrieve the public key from your ncps instance:

curl http://your-ncps-hostname:8501/pubkey

Example output:

your-ncps-hostname:abc123def456...=

Save this public key - you'll need it for client configuration.

NixOS Configuration#

Add ncps to your /etc/nixos/configuration.nix:

{
  nix.settings = {
    substituters = [
      "http://your-ncps-hostname:8501"  # Add your ncps cache
      "https://cache.nixos.org"          # Keep official cache as fallback
    ];

    trusted-public-keys = [
      "your-ncps-hostname:abc123def456...="  # Paste public key here
      "cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY="
    ];
  };
}

Then rebuild:

sudo nixos-rebuild switch

Behind HTTPS Reverse Proxy#

If ncps is behind an HTTPS reverse proxy:

{
  nix.settings = {
    substituters = [
      "https://cache.example.com"  # Use HTTPS
      "https://cache.nixos.org"
    ];

    trusted-public-keys = [
      "cache.example.com:abc123def456...="
      "cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY="
    ];
  };
}

Non-NixOS Configuration#

Edit your Nix configuration file (typically /etc/nix/nix.conf or ~/.config/nix/nix.conf):

substituters = http://your-ncps-hostname:8501 https://cache.nixos.org
trusted-public-keys = your-ncps-hostname:abc123def456...= cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=

Then restart Nix daemon:

# On systemd systems
sudo systemctl restart nix-daemon

# On macOS
sudo launchctl stop org.nixos.nix-daemon
sudo launchctl start org.nixos.nix-daemon

Verify Configuration#

Check Configuration#

nix show-config | grep substituters
nix show-config | grep trusted-public-keys

Verify your ncps cache appears in the output.

Test Cache Connectivity#

curl http://your-ncps-hostname:8501/nix-cache-info

Should return cache information.

Test Package Download#

# Try building something
nix-build '<nixpkgs>' -A hello

# Check ncps logs for cache hits/misses
# Docker: docker logs ncps
# Systemd: journalctl -u ncps -f

Look for log messages like:

serving nar from cache - Cache hit!
downloading nar from upstream - Cache miss, fetching from upstream

Priority and Order#

Nix tries substituters in order. Place your ncps cache first for best performance:

{
  nix.settings.substituters = [
    "http://your-ncps:8501"        # Try ncps first
    "https://cache.nixos.org"       # Fallback to official cache
  ];
}

Multiple ncps Caches#

You can configure multiple ncps caches:

{
  nix.settings = {
    substituters = [
      "http://ncps-local:8501"     # Local cache (fastest)
      "http://ncps-remote:8501"    # Remote cache
      "https://cache.nixos.org"     # Official cache (fallback)
    ];

    trusted-public-keys = [
      "ncps-local:key1="
      "ncps-remote:key2="
      "cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY="
    ];
  };
}

Trusted Users#

For multi-user Nix installations, the Nix daemon restricts certain operations (like specifying extra substituters) to trusted users.

{
  nix.settings.trusted-users = [ "root" "youruser" ];
}

Or in /etc/nix/nix.conf:

trusted-users = root youruser

When to use this#

Configuring trusted-users makes sense if:

You are the primary user and administrator of your own machine.
You are a developer who needs the flexibility to frequently use different, project-specific binary caches without modifying the global system configuration.

Better Alternatives#

For most multi-user environments, it is safer to configure ncps globally in your system configuration (as shown in the NixOS Configuration or Non-NixOS Configuration sections above).

By adding substituters and trusted-public-keys to the global configuration:

Security: Nix will only use the caches you have explicitly trusted.
Accessibility: The cache becomes available to all users on the system automatically.
No Root Access Required: Regular users can benefit from the cache without needing elevated privileges.

Per-Project Configuration#

Override cache settings for specific projects using --option:

nix-build \
  --option substituters "http://project-cache:8501 https://cache.nixos.org" \
  --option trusted-public-keys "project-cache:key= cache.nixos.org-1:key=" \
  ...

Troubleshooting#

Cache Not Being Used#

Check configuration:

nix show-config | grep substituters

Check ncps is reachable:

curl http://your-ncps:8501/nix-cache-info

Check public key is trusted:

nix show-config | grep trusted-public-keys

Permission Denied#

Add your user to trusted users:

nix.settings.trusted-users = [ "root" "youruser" ];

Still Downloading from Official Cache#

Possible causes:

ncps doesn't have the package cached yet (first download)
ncps cache listed after official cache (order matters)
Public key not trusted

Check ncps logs to see if requests are reaching it.

See the Troubleshooting for more help.

Next Steps#

Monitoring - Set up monitoring
Cache Management - Configure LRU cleanup
Reference - Explore more options