Remote builds are one of the biggest superpowers of Nix. But while it is in theory easy to set up, there are a fair number of footguns. I have no feet, but I must walk. So here’s a couple of tips for making sure everything is set up properly.

First, a quick recap of what’s needed: the root user on the client needs to be able to SSH into the builder as a trusted build host Nix user non-interactively. We can verify different aspects of this on the command line.

On the client host:

  • Get the builders configuration with nix config show builders, and if it points to a file, cat it to get the usernames, host names, and SSH key paths. If this configuration is missing, you might need to restart the Nix daemon.
  • Verify that your SSH keys don’t have a passphrase with ssh-keygen -f PRIVATE_KEY -y. Otherwise remove it with ssh-keygen -f PRIVATE_KEY -p.

On the builder host:

  • nix config show trusted-users lists who can trigger Nix builds. The user listed in the relevant builders entry on the client (or one of its groups if there are any @GROUP entries) needs to be in the trusted users list. That is, if the client builders configuration has an entry starting with ssh-ng://alice@big, and nix config show trusted-users on big lists root @wheel, then groups alice on big must include “wheel”.

It’s a bit clunky to verify the connection from the client to the builder, but the following should do: sudo ssh -o 'IdentityAgent none' -i PRIVATE_KEY USER@HOST true. sudo is necessary because the Nix daemon by default runs as the root user. And the IdentityAgent none setting is necessary to avoid forwarding keys from the SSH agent of the user running sudo (via $SSH_AUTH_SOCK).