# Install the Toolchain

# 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](/quick-start/advanced/create-atmos-stacks)), pin versions with `dependencies.tools`:

```yaml
# 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`:

```yaml
components:
  terraform:
    command: tofu
```

:::tip 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.

```bash
# 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](/cli/configuration/toolchain) for registries, aliases, and verification.

:::tip 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](/quick-start/advanced/add-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 →](/quick-start/advanced/start-sandbox)**