Skip to main content

Install the Toolchain

You don't have OpenTofu installed — and you don't need to install it by hand. Atmos has a built-in toolchain that installs and pins the exact tools your stacks depend on, so every developer and every CI run uses the same versions.

Experimental

By the end of this step, Atmos will install OpenTofu (and a security scanner) for you, the first time a component needs them — no asdf, tfenv, or aqua required.

The transparent way: declare what you depend on​

The toolchain works automatically with the default configuration. Atmos uses the Aqua registry to resolve declared tools and installs them on demand.

Declare the tools your stacks depend on. In your stack defaults (you'll build these out in Create Stacks), pin versions with dependencies.tools:

# stacks/orgs/acme/_defaults.yaml
dependencies:
  tools:
    opentofu: 1.10.10
    checkov: "3.2.529"   # security scanner, used by a hook later

That's it. The next time you run a Terraform command, Atmos resolves these versions from the Aqua registry, installs them in its toolchain cache, and records artifact checksums in its lockfile. Tell Atmos to use OpenTofu as the Terraform binary in atmos.yaml:

components:
  terraform:
    command: tofu
Commit the lockfile

To use a committed project lockfile, set toolchain.lock_file: toolchain.lock.yaml in atmos.yaml, then populate and review entries for each platform your team and CI use. The lockfile records the artifact URL and checksum for each included platform; installing on one platform does not automatically populate every other platform.

The manual way: manage tools yourself​

You can also drive the toolchain directly — useful for installing everything up front, adding a tool, or checking what's resolved.

# Install a specific tool and version up front.
atmos toolchain install opentofu@1.10.10

# Install the tools listed in .tool-versions, if your project uses one.
atmos toolchain install

# See what's installed and where it resolves.
atmos toolchain list
atmos toolchain which opentofu

Need a tool your components depend on that isn't OpenTofu — kubectl, helm, tflint, jq? Declare it the same way (dependencies.tools or atmos toolchain add), and Atmos installs it from the Aqua registry.

The payoff: the tools your infrastructure needs are declared next to the infrastructure that needs them, version-controlled in the same repo, and resolved identically everywhere — no second tool to install, no drift between laptops and CI. See the toolchain configuration reference for registries, aliases, and verification.

Tools aren't added to your system PATH — on purpose

Atmos installs tools in its toolchain cache and puts them on the PATH only for the commands it runs (Terraform, hooks, custom commands). It deliberately does not install them globally, so different projects can pin different versions of the same tool without colliding. When you want the pinned tools in your own shell:

  • Run eval "$(atmos toolchain env)" to add the toolchain to the current shell's PATH.
  • Run atmos toolchain exec opentofu version to invoke a single pinned tool without touching PATH.
  • Run atmos toolchain which opentofu (or atmos toolchain path) to print where a tool — or the toolchain's bin directory — resolves.

Next: with tools handled, start the sandbox your components will deploy against → Start the Local Sandbox →