Configuration file

When deploying with NixOS, NixOps or nix-darwin you should use the module documentation instead, or skip ahead to read about less frequently used options to use with extraOptions.

The configuration format for the agent is TOML markup. Its location must always be specified by invoking hercules-ci-agent --config agent.toml.

A basic agent.toml looks as follows:

baseDirectory = "/var/lib/hercules-ci-agent"
concurrentTasks = 4
To get started with a manual deployment read this Guide.

apiBaseUrl

Optional. Defaults to hercules-ci.com.

HTTP API agent will connect to.

baseDirectory

Required.

Directory with all the agent state: secrets, work, etc.

binaryCachesPath

Optional. Defaults to staticSecretsDirectory/binary-caches.json if that file exists.

Path to a JSON file containing binary cache secret keys.

The contents of the file are described in binary-caches.json.

Note that binary cache configuration affects the whole system’s Nix configuration.

clusterJoinTokenPath

Optional. Defaults to staticSecretsDirectory/cluster-join-token.key.

Path to a secret token retrieved when creating a new agent via hercules-ci.com/dashboard.

This token is used for authenticating to apiBaseUrl.

concurrentTasks

Optional. Defaults to 4.

Combined number of workers to use for building and evaluating Nix derivations.

The optimal value depends on the resource consumption characteristics of your workload, including memory usage and in-task parallelism. This is typically determined empirically.

staticSecretsDirectory

Optional. Defaults to baseDirectory/secrets.

This is the default directory to look for statically configured secrets like clusterJoinTokenPath.

workDirectory

Optional. Defaults to baseDirectory/work.

The directory in which temporary subdirectories are created for task state. This includes sources for Nix evaluation.