NixOS Module

The hercules-ci-agent flake provides an attribute nixosModules.multi-agent-service with the following options.

Multiple instances of hercules-ci-agent can be specified.

If you specify an instance named "", it will behave just as the services.hercules-ci-agent options did.

Otherwise:

Type: attribute set of (submodule)

Default: { }

Declared by:

Package containing the bin/hercules-ci-agent executable.

Type: package

Default: pkgs.hercules-ci-agent

Declared by:

Allow unknown settings to be written to the agent.json file.

This is useful for forward compatibility - if you’ve overridden the package.

Type: boolean

Default: false

Declared by:

These settings are written to the agent.json file.

Type: anything

Default: { }

Declared by:

Allow the use of insecure fetching protocols, such as http.

Disabled by default, because most users do not need this, but note that Nix by default does allow this.

Type: boolean

Default: false

Declared by:

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.

Type: string

Default: "https://hercules-ci.com"

Declared by:

State directory (secrets, work directory, etc) for agent

Type: path

Default: "/var/lib/hercules-ci-agent"

Declared by:

Path to a JSON file containing binary cache secret keys.

As these values are confidential, they should not be in the store, but copied over using other means, such as agenix, NixOps deployment.keys, or manual installation.

The format is described on docs.hercules-ci.com/hercules-ci-agent/binary-caches-json/.

Type: path

Default: staticSecretsDirectory + "/binary-caches.json"

Declared by:

Location of the cluster-join-token.key file.

You can retrieve the contents of the file when creating a new agent via hercules-ci.com/dashboard.

As this value is confidential, it should not be in the store, but installed using other means, such as agenix, NixOps deployment.keys, or manual installation.

The contents of the file are used for authentication between the agent and the API.

Type: path

Default: staticSecretsDirectory + "/cluster-join-token.key"

Declared by:

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.

concurrentTasks can be around the CPU core count or lower if memory is the bottleneck.

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.

Type: positive integer, meaning >0, or value “auto” (singular enum)

Default: "auto", meaning equal to the number of CPU cores.

Declared by:

An attribute set of mountable directories for effects.

See docs.hercules-ci.com/hercules-ci-agent/agent-config#effectMountables

Type: lazy attribute set of (submodule)

Default: { }

Declared by:

A condition expression that decides whether a mountable is accessible to an effect.

Type: condition

Default: "true"

Declared by:

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 system user that runs hercules-ci-agent (i.e. hercules-ci-agent or hci-${name}).

Type: boolean

Declared by:

A mountable directory as a path string.

Type: path

Default: null

Example: "/etc/hosts"

Declared by:

A key-value map of user data.

Any Nix type that is representable in JSON is permitted.

Type: JSON value

Default:

Declared by:

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

More verbose: "DebugS", less verbose: "WarningS", "ErrorS".

Type: one of “DebugS”, “InfoS”, “WarningS”, “ErrorS”

Default: "InfoS"

Declared by:

Since hercules-ci-agent 0.10.2.

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.

Type: lazy attribute set of string

Default: { }

Example:

Declared by:

Path to a JSON file containing secrets for effects.

As these values are confidential, they should not be in the store, but copied over using other means, such as agenix, NixOps deployment.keys, or manual installation.

The format is described on docs.hercules-ci.com/hercules-ci-agent/secrets-json/.

Type: path

Default: staticSecretsDirectory + "/secrets.json"

Declared by:

This is the default directory to look for statically configured secrets like cluster-join-token.key.

See also clusterJoinTokenPath and binaryCachesPath for fine-grained configuration.

Type: path

Default: baseDirectory + "/secrets"

Declared by:

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

Type: path

Default: baseDirectory + "/work"

Declared by: