diff --git a/nixos/modules/services/continuous-integration/hercules-ci-agent/common.nix b/nixos/modules/services/continuous-integration/hercules-ci-agent/common.nix
index 9f9b86ee61c..c6f743a71d4 100644
--- a/nixos/modules/services/continuous-integration/hercules-ci-agent/common.nix
+++ b/nixos/modules/services/continuous-integration/hercules-ci-agent/common.nix
@@ -37,15 +37,22 @@ let
description = ''
Number of tasks to perform simultaneously.
- A task is a single derivation build or an evaluation.
+ 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 = types.int;
- default = 4;
+ type = types.either types.ints.positive (types.enum [ "auto" ]);
+ default = "auto";
};
workDirectory = mkOption {
description = ''