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 can be specified by invoking hercules-ci-agent --config agent.toml. Alternatively, the NixOS and nix-darwin module can generate this file for you. See also the setup guide.
A basic agent.toml looks as follows:
# See https://docs.hercules-ci.com/hercules-ci-agent/agent-config/
baseDirectory = "/var/lib/hercules-ci-agent"
# concurrentTasks = "auto"| If you are deploying an agent, the guide is a better starting point. |
apiBaseUrl
Optional. Defaults to https://hercules-ci.com.
API base URL that the agent will connect to.
When using Hercules CI Enterprise, set this to the URL where your Hercules CI server is reachable.
baseDirectory
Required.
Directory with all the agent state: secrets, work, etc.
binaryCachesPath
Optional. Defaults to staticSecretsDirectory/binary-caches.json if that file exists. With the NixOS module this defaults to /var/lib/hercules-ci-agent/secrets/binary-caches.json.
Path to a JSON file containing binary cache secret keys.
The format is described in binary-caches.json.
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 authentication with apiBaseUrl.
concurrentTasks
Optional. Defaults to "auto". Must be an integer or "auto".
Number of tasks to perform simultaneously.
A task is a single derivation build, an evaluation or an effect run.
At minimum, you need 2 concurrent tasks for <literal>x86_64-linux</literal>
in your cluster, to allow for import from derivation.
When the value is "auto", the number becomes the number of CPU cores, but with
a lower bound of 2 in order to avoid deadlock during import from derivation.
The optimal value depends on the resource consumption characteristics of your workload, including memory usage and in-task parallelism. This is typically determined empirically.
| When scaling, it is generally better to have a double-size machine than two machines, because each split of resources causes inefficiencies; particularly with regards to build latency because of extra downloads. |
labels
Optional. A key-value map of user data.
This data will be available to organization members in the dashboard and API.
The values can be of any TOML type that corresponds to a JSON type, but arrays can not contain tables/objects due to limitations of the TOML library. Values involving arrays of non-primitive types may not be representable currently.
logLevel
Optional. Defaults to InfoS. More verbose: DebugS, less verbose: WarningS, ErrorS.
secretsJsonPath
Optional. Defaults to staticSecretsDirectory/secrets.json.
staticSecretsDirectory
Optional. Defaults to baseDirectory/secrets.
This is the default directory to look for statically configured secrets like clusterJoinTokenPath, binaryCachesPath, secretsJsonPath.
workDirectory
Optional. Defaults to baseDirectory/work.
The directory in which temporary subdirectories are created for task state. This includes sources for Nix evaluation.