How Hercules CI works

This article explores how Hercules CI helps you run a build cluster on your own infrastructure.

Hercules CI consists primarily of two components. Hercules CI Agent is the open source build agent that performs both Nix evaluation and builds. It is a stateless service with minimal configuration.

The other component is the service. It coordinates the evaluation, builds and integrations like the GitHub App. It maintains the metadata about your agents and builds, so you don't have to.

Let's dive into how Hercules CI supports your development workflow.


The first step is to log in using your GitHub account and add an organization. Alternatively, you can connect your GitHub user account. Next, you can click the agents tab to deploy your first agent. We provide instructions for several deployment methods.

You can now start using Hercules CI by adding a ci.nix file to a repository. It behaves a lot like nix-build.


When you've pushed to GitHub, Hercules CI will send an evaluation command to one of your agents. It will evaluate your Nix expressions, which is the process of computing the build instructions called derivations. These derivations are uploaded to your binary cache, but only metadata about the derivations will be sent back to This allows the distribution of work without having to process your source code.

The builds resulting from evaluation are then dispatched to your agents. Logs from the evaluation and builds are streamed back to the dashboard.


When the build is in progress, has encountered an error or has completed successfully, Hercules CI will set the appropriate commit statuses on your commit. This way you know at a glance whether a change passes your quality criteria. To help you find the problem, the commit status includes a link to the relevant page in the dashboard.

To get the most out of Nix, the evaluation process may involve dispatching builds before completing evaluation. Support for this is first-class.

Binary cache

If you've configured a binary cache, the build outputs are uploaded, so you and your team can use the software instead of wasting valuable time recompiling. Thanks to the design of Nix, you don't even have to be aware of the binary cache while you use it to boost development.

Hercules CI Agent can work with Cachix, S3 and all cache URIs that Nix can push to.

An illustration of data flows in Hercules CI


Further documentation is available at

Feel free to contact [email protected]. We're happy to help.

Hercules CI is free for open source and comes with a
1-month trial for use with private repositories.

Get Started