Skip to main content

Toolchain Installs Are Reproducible by Default Now

· 3 min read
Erik Osterman
Erik Osterman
Founder @ Cloud Posse

Atmos's toolchain has had a lockfile for a while. The lockfile records the exact resolved artifact and checksum for each platform. A package manager's lockfile pins a dependency tree the same way. But the lockfile was opt-in. The setting was not documented anywhere a user could find it. Almost nobody turned it on. Almost nobody's installs were actually reproducible. The installs only looked reproducible, because the version string matched.

The Problem​

A version in .tool-versions pins what you asked for. It does not pin what Atmos actually installed. Every atmos toolchain install command resolves that version against the live registry again. The exact download URL, checksum, and platform artifact are not fixed anywhere. Only the version number is fixed.

The Fix​

Toolchain installs now write a lockfile by default. You do not need to configure anything. Run atmos toolchain install. Atmos records the exact resolved version, download URL, checksum, and size for your platform. Installs skip a tool that already exists on disk, so an already-installed tool will not get a lockfile entry until you run atmos toolchain lock (or reinstall it with atmos toolchain install --reinstall). Once every tool has an entry, the next install resolves against the lockfile instead of asking the registry again, on your machine, a teammate's, or in CI. Reproducibility holds per platform: everyone on an operating system and architecture with a matching lock entry gets the same artifact, byte for byte.

If a project's atmos.yaml pins an edition dated before this change, the project keeps the old opt-in behavior. Nothing changes for a project that relied on the previous default. New and unpinned projects get the lockfile from the start.

How to Use It​

You do not need to opt in. Install as usual:

$ atmos toolchain install

Commit the resulting toolchain.lock.yaml file next to .tool-versions. If some of those tools were already installed before you ran this, run atmos toolchain lock too -- atmos toolchain install won't touch a tool it finds already on disk, so it can leave that tool's entry missing. Once every tool has an entry, every install resolves the exact pinned artifact for that platform. This applies on your machine, a teammate's machine, and a CI runner. Atmos does not resolve the version against the registry again.

The atmos toolchain command is still experimental. Its interface may change. The reproducibility does not depend on that.

Get Involved​

If you already use the toolchain, check whether toolchain.lock.yaml has an entry for every tool in .tool-versions. Run atmos toolchain lock to fill in any atmos toolchain install skipped because they were already installed, then commit the lockfile. If your installs still do not reproduce the same way across machines with matching lock entries, open an issue. That is exactly the gap this fix closes.