cashapp/hermit: per-project tool isolation for Linux and macOS

What cashapp/hermit solves for a project that depends on external tools

A project's build usually depends on more than its source code: a Go toolchain, a linter, a code generator, a packaging CLI. Those tools are installed on the developer's machine once and drift over time. One contributor has version 3 of a formatter, CI has version 2, and a formatting check fails on a diff nobody wrote. Hermit's answer is to treat the tool set as part of the project rather than part of the machine. The README describes it as installing tools for software projects in self-contained, isolated sets, so the team, contributors and CI share the same tooling. The intended audience is a team with a checked-in repository and a CI pipeline, not an individual who wants a global package manager for their laptop. Because the set is scoped to a project, two repositories on the same machine can hold different versions of the same tool without interfering.

How the isolated environment is built and activated

The repository layout shows how the pieces fit. There is a manifest package, a sources package, a state package, a shell package and an env.go at the top level. The manifest package is where tool definitions live, the sources package is where archives are fetched from, and the state directory holds what has been installed for a given project. The shell package, together with env.go, is what constructs the environment that a shell session or a CI step runs inside. The mechanism is activation rather than global installation: the environment is assembled for the current project and applied to the process, so the tools on PATH are the ones the project declared. The dependency list in go.mod is consistent with that design. It includes archive and package handling for several formats (go7z, xz, go-rpmutils, klauspost/compress), HTML and XPath libraries for scraping download pages, a shell parser (mvdan.cc/sh) and a shell-quoting library. Hermit is not merely downloading tarballs; it is resolving where a tool lives, fetching it, and then describing the resulting paths to a shell. That is a heavier design than a plain downloader, and it is the reason the project can claim isolation rather than just installation.

Installing Hermit and activating a first environment

The README does not include install commands or a getting-started walkthrough. It points to https://cashapp.github.io/hermit for full documentation, and that is where the install instructions and the first-use steps are published. Rather than reproduce commands that may not match the current release, the honest summary is: get the binary from the documentation site, then run it inside a project directory to create and activate the environment. The README does state that a skill for AI coding agents working in Hermit-managed repositories is available in the skills/hermit directory, which is a useful signal if your team uses coding agents in the repository. It also points to RELEASE.md for the release process. Beyond those pointers the README is silent on flags, subcommands and shell integration, so anything more specific would be guesswork. If you are evaluating Hermit, the documentation site is the first thing to read, and the second is the skills/hermit directory if it applies to your workflow.

Where Hermit is the wrong tool

Isolation at the project level is not the same as isolation at the machine level. Hermit manages the tools a project declares; it does not sandbox what those tools do. If your requirement is that a build cannot touch the host filesystem outside a defined root, Hermit's model does not provide that, and a container or a virtual machine is the appropriate boundary. The README's own framing is uniform tooling for Linux and Mac, and it does not claim Windows support, so a team with Windows developers is not the audience. There is also a cost to activation: the environment has to be constructed before the tools are available, which means any script that assumes a globally installed binary will need to run inside an activated context. And because tool definitions live in manifests, a tool that is not covered by an existing manifest is work you have to do yourself. The repository shows a manifest package and a cache directory, but the README does not document the process for adding a new tool, so that effort is real and undocumented in the README.

Hermit compared with container-based tool pinning

The obvious alternative is to pin the toolchain in a container image and run builds and tests inside it. The difference in approach matters. A container image pins everything at once, including the operating system libraries, and it is reproducible because the image is immutable. Hermit pins the tools but leaves the host operating system in place, so a developer on macOS and a CI runner on Linux share the tool versions while still using their own system libraries. That is lighter for day-to-day development: no image rebuild to change a linter version, and no container runtime needed to run a formatter. It is weaker as a guarantee, because the host still contributes to the result. A second alternative is a language-specific version manager, which typically handles one runtime and nothing else. Hermit's scope is broader by design, which is the reason it carries its own archive handling and source resolution. The trade-off is that a broader tool manager has more surface area to maintain than a single-runtime version file.

Maintenance, upgrades and the Apache-2.0 licence

The repository is not archived and the last push was on 2026-06-16, so there is recent activity, but the README itself is short and defers to the documentation site. Recent releases are v0.52.1 on 2026-04-21, v0.52.2 on 2026-06-16 and v0.52.3 on 2026-06-16, which suggests a versioned, incremental release cadence rather than long-lived major versions. For an adopter, the upgrade question is whether a new Hermit release changes how existing manifests resolve. The repository does not document a compatibility policy for manifests, so that is something to confirm from the documentation before you depend on it in CI. On licensing: the project is Apache-2.0, and the README carries the standard notice that the software is distributed on an as-is basis without warranties or conditions of any kind. Apache-2.0 is a permissive licence that permits commercial use and modification, but this is a description of the licence text, not legal advice. If you redistribute Hermit or bundle it into a product, have your own counsel review the notice and any third-party licences in the dependency tree.

Editorial conclusion

Adopt Hermit if your build or test scripts depend on a specific compiler, linter or CLI version and you want that version pinned in the repository rather than in a setup document. Skip it if your toolchain is already pinned by a container image you control, or if you need Windows support, which the README does not claim. Before rolling it out, check the repository's docs site for the current install command, confirm which shells it supports, and decide how you will regenerate the environment when a manifest changes.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes