Deploy with NixOS

NixOS deployment can be performed on the target machine itself or remotely by means of nixos-rebuild --target-host.

These instructions will use /etc/nixos as the location for the configuration modules. This directory is only used at evaluation time. If you perform remote deployment, you will use some project directory in place of /etc/nixos.

1. Bootstrap

To avoid compiling the agent you can use binary cache to speed it up:

$ nix-env -iA cachix -f
$ cachix use hercules-ci

Add this configuration to /etc/nixos/configuration.nix:

  imports = [
    ( builtins.fetchTarball ""
      + "/module.nix"

  services.hercules-ci-agent.enable = true;
  services.hercules-ci-agent.concurrentTasks = 4; # Number of jobs to run

2. Get a cluster join token.

  1. In the dashboard, find the account for which you would like to deploy the agent,

  2. Click the "Agents" button and the button in "Generate token" tab. This produces a private token that should be protected like a password.

  3. Copy the token into a plain text file /var/lib/hercules-ci-agent/secrets/cluster-join-token.key.

3. Configure a binary cache

If you’re using more than one agent or would like to share resulting binaries outside the build farm you’ll need a binary cache.

On Cachix you can create a binary cache. After you complete the process, gather the keys into a binary-caches.json file, replacing all placeholders:

{ "mycache": (1)
    { "kind": "CachixCache"
    , "authToken": "eyJhaf23GH53a.bc23BUSI.9q3048hWHh" (2)
    , "publicKeys": [""] (3)
    , "signingKeys": ["uAhqM3jG..."] (4)
1 The name of the Cachix cache; for example the mycache part from
2 Optional; only required for private binary caches. You may retrieve this from the Cachix Getting started instructions, step 3.
3 The public part of the signing key. Look for "Public Key" on your cache page (example page:
4 A cache-specific secret key to sign store paths. You can find it in ~/.config/cachix/cachix.dhall or your key backup after following the setup instructions on Make sure you copy the right key if you have multiple in your cachix.dhall.
For more detail, see The binary-caches.json format in the Reference.

Continue with an applicable section below.

Local deployment

If you’re deploying to the local machine, move it to /var/lib/hercules-ci-agent/secrets/binary-caches.json and add this line to your /etc/nixos/configuration.nix:

services.hercules-ci-agent.binaryCachesFile = /var/lib/hercules-ci-agent/secrets/binary-caches.json;

Make sure that /var/lib/hercules-ci-agent/secrets can only be read by hercules-ci-agent.

Remote deployment

If you’re deploying to a remote machine, you need to store it in two locations. One for evaluation, in the directory of your configuration.nix file and one for the deployed agent to read. Add this line to your configuration.nix:

services.hercules-ci-agent.binaryCachesFile = ./binary-caches.json;

Install the same file on the target machine as /var/lib/hercules-ci-agent/secrets/binary-caches.json.

Make sure that /var/lib/hercules-ci-agent/secrets can only be read hercules-ci-agent.

If your deployment solution lacks a method to store configuration files confidentially, you may choose to maintain the binary-caches.json file separately in both locations. This allows you to censor the secrets like {"signingKeys": [], "authToken": ""} in the file used for evaluation only.

Make sure not to lose the signing keys and do deploy them to the target machine!

4. Activation

Apply the configuration by running nixos-rebuild switch.


To inspect the agent’s local log, run journalctl -u hercules-ci-agent -n 100 on the target machine to see the last 100 lines.