NixOS Module

Hercules CI Agent can be deployed using NixOS, using either the module that is distributed with NixOS, or the hercules-ci-agent flake.

A minimal configuration looks as follows:

# NixOS configuration module
{
  imports = [
    inputs.hercules-ci-agent.nixosModules.multi-agent-service
  ];
  services.hercules-ci-agents."" = {
    # See https://docs.hercules-ci.com/hercules-ci-agent/nixos-module
  };
}

Options

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

services.hercules-ci-agents

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.

  • User: hercules-ci-agent

  • Default base directory: /var/lib/hercules-ci-agent

Otherwise:

  • User: hci-${name}

  • Default base directory: /var/lib/hercules-ci-agent-${name}

Type: attribute set of (submodule)

Default: { }

Declared by:

services.hercules-ci-agents.<name>.package

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

Type: package

Default: pkgs.hercules-ci-agent

Declared by:

services.hercules-ci-agents.<name>.allowUnknownSettings

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:

services.hercules-ci-agents.<name>.settings

These settings are written to the agent.json file.

Type: anything

Default: { }

Declared by:

services.hercules-ci-agents.<name>.settings.allowInsecureBuiltinFetchers

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:

services.hercules-ci-agents.<name>.settings.apiBaseUrl

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:

services.hercules-ci-agents.<name>.settings.baseDirectory

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

Type: path

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

Declared by:

services.hercules-ci-agents.<name>.settings.binaryCachesPath

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.

Type: path

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

Declared by:

services.hercules-ci-agents.<name>.settings.clusterJoinTokenPath

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:

services.hercules-ci-agents.<name>.settings.concurrentTasks

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:

services.hercules-ci-agents.<name>.settings.effectMountables

An attribute set of mountable directories for effects.

Type: lazy attribute set of (submodule)

Default: { }

Declared by:

services.hercules-ci-agents.<name>.settings.effectMountables.<name>.condition

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

Type: condition

Default: "true"

Declared by:

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

Type: boolean

Declared by:

services.hercules-ci-agents.<name>.settings.effectMountables.<name>.source

A mountable directory as a path string.

Type: path

Default: null

Example: "/etc/hosts"

Declared by:

services.hercules-ci-agents.<name>.settings.labels

A key-value map of user data.

Any Nix type that is representable in JSON is permitted.

Type: JSON value

Default:

{
  agent.source = "..."; # One of "nixpkgs", "flake", "override"
  lib.version = "...";
  pkgs.version = "...";
}

Declared by:

services.hercules-ci-agents.<name>.settings.logLevel

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:

services.hercules-ci-agents.<name>.settings.secretsJsonPath

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.

Type: path

Default: staticSecretsDirectory + "/secrets.json"

Declared by:

services.hercules-ci-agents.<name>.settings.staticSecretsDirectory

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:

services.hercules-ci-agents.<name>.settings.workDirectory

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

Type: path

Default: baseDirectory + "/work"

Declared by: