Configuration file

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

If you don’t use an existing configuration manager such those previously mentioned, you can create a config file directly, in JSON. TOML is still supported, but not recommended because of limitations:

It does not support null in JSON-like fields such as labels.
The TOML parsing library currently requires that intermediate tables are specified explicitly. If you don’t, the subtables are ignored WITHOUT WARNING.
```
[labels]      # <-- Without this line, labels.foo will be ignored.
[labels.foo]
bar = true
```

Its location can be specified by invoking hercules-ci-agent --config agent.json, although using a configuration manager is recommended. See also the setup guide.

A basic agent.json looks as follows:

{
  "baseDirectory": "/var/lib/hercules-ci-agent"
}

If you are deploying an agent, the guide is a better starting point.

allowInsecureBuiltinFetchers

Optional. Defaults safely to false.

Whether to allow the built-in fetchers to access http:// and other unencrypted URL schemes.

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 x86_64-linux 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.

effectMountables

Since hercules-ci-agent 0.10.1

Default: { }

A mapping from names to mountable definitions.

Example value:

{
  "hosts" = {
    source = "/etc/hosts";
    readOnly = true;
    condition = {
      isRepo = "configurations";
    };
  };
}

Mountables can be mounted into the filesystem of effects that satisfy the condition, and request a mount using __hci_effect_mounts.

The location in the sandbox is not configured here, but in the field names of __hci_effect_mounts.

You may visualize the mounting process as the joining of the two maps:

                        effect                         agent

┌──────────────┐  __hci_effect_mounts  ┌──────┐  effectMountables  ┌───────────┐
│ sandbox path ├──────────────────────►│ name ├───────────────────►│ mountable │
└──────────────┘                       └──────┘                    └───────────┘

virtual location                      convention                   host location

Attributes:

source

The location on the host system that can be mounted into an effect’s sandbox. Make sure that the system user running hercules-ci-agent is allowed to access this location.

readOnly

If true, the mount into the sandbox will be a read-only bind mount. If false, the mount is not mounted read-only, and it will be writable if it is for the user that runs hercules-ci-agent.

condition

A condition expression that controls under what circumstances an effect is allowed to mount this mountable.

remotePlatformsWithSameFeatures

Default: empty

Example: remotePlatformsWithSameFeatures = ["aarch64-linux"]

A list of extra platforms to advertize to the scheduler. This is like configuring extra-platforms in Nix, except builds may be dispatched to a remote builder.

The recommended method for running a cluster is to install hercules-ci-agent on each machine, instead of using this option.

Although the more efficient and recommended method for configuring builders is by installing hercules-ci-agent on each, this option can be used to make the agent accept builds for other platforms.

Note that this is a stop gap solution as it does not provide a mechanism to configure systemFeatures for these extra platforms; they match the Nix configuration.

labels

Optional. A key-value map of user data.

This data is made available to organization members in the dashboard and API.

When using the TOML format, the values can be of any TOML type that corresponds to a JSON type, but nested structures (tables, lists) may be problematic due to limitations of the TOML library. Values involving arrays of non-primitive types may not be representable currently. The JSON configuration format is recommended, and allows all JSON types.

logLevel

Optional. Control the importance threshold for messages are logged to the system log.

Defaults to "InfoS". More verbose: "DebugS", less verbose: "WarningS", "ErrorS".

nixSettings

Since hercules-ci-agent 0.10.2

Optional. A key-value map of Nix settings.

Nix interprets keys that start with extra- as additions to the existing (e.g. system) value. However, nixSettings is unordered, so make sure to use extra-${x} or plain ${x}, but not both.

Example, to ignore other system caches:

"nixSettings": {
  "substituters": "https://cache.nixos.org"
}