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 evaluations, builds and deployments and the integration with GitHub. It maintains the metadata about your agents and builds, so you don’t have to.

image: A graphical outline of how Hercules CI Agent interacts with various services

Hercules CI Agent interacting with various services.


When you push a new commit, the Hercules CI Agent you’ve installed will start evaluating it. It reads your Nix file and computes the packages to build, sends the .drv files to the binary cache and sends metadata to This way, your builds can be coordinated without sending your sources.

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.

You can now start using Hercules CI by adding a ci.nix file to a repository.


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.


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