# Toolchain Configuration

import Intro from '@site/src/components/Intro';
import KeyPoints from '@site/src/components/KeyPoints';
import File from '@site/src/components/File';

<Intro>
The toolchain feature enables you to manage CLI tool versions (Terraform, kubectl, helm, etc.) directly within Atmos, ensuring consistency across your team and CI/CD environments.
</Intro>

<KeyPoints>
- Manage tool versions with `.tool-versions` files
- Install CLI binaries from GitHub releases and other sources
- Integrate with the Aqua registry ecosystem for 1,000+ pre-configured tools
- Verify package checksums and signatures when registry metadata provides them
- Version control your tools for team consistency
- Automatic tool provisioning in workflows
</KeyPoints>

:::tip CI and security-sensitive environments

Enable [`toolchain.frozen_lock_file: true`](#frozen-installs-in-ci) to require artifacts already
recorded in the committed lockfile and reject missing tool or platform entries. Prepare and
review lockfile updates before running CI. Existing checksum verification applies with ordinary
lockfile use too; frozen mode additionally prevents installations from accepting and recording
new artifacts automatically.

:::

## Basic Configuration

Configure toolchain behavior in your `atmos.yaml`:

<File title="atmos.yaml">
```yaml
# Toolchain configuration
toolchain:
  # Path to .tool-versions file (relative or absolute)
  file_path: ".tool-versions"

  # Directory where tools are installed (relative or absolute)
  install_path: ".tools"

  # Maximum simultaneous tool installs (default: 4)
  max_concurrency: 4
```
</File>

### Configuration Options

<dl>
  <dt>`file_path`</dt>
  <dd>
    Path to the `.tool-versions` file that tracks tool versions for your project.
    - Default: `.tool-versions`
    - Supports relative or absolute paths
    - Compatible with asdf format
    - Override with `ATMOS_TOOLCHAIN_FILE_PATH`
  </dd>

  <dt>`install_path`</dt>
  <dd>
    Directory where toolchain binaries will be installed.
    - Default: the XDG cache directory (`~/.cache/atmos/toolchain` on Linux/macOS)
    - Supports relative or absolute paths
    - Tools are organized by owner, repository, and version: `<install_path>/bin/<owner>/<repo>/<version>/`
    - Override with `ATMOS_TOOLCHAIN_INSTALL_PATH`
  </dd>

  <dt>`versions_file`</dt>
  <dd>
    Alternative name for `file_path`. Use `file_path` for consistency.
  </dd>

  <dt>`tools_dir`</dt>
  <dd>
    Alternative name for `install_path`. Use `install_path` for consistency.
  </dd>

  <dt>`lock_file`</dt>
  <dd>
    Path to the existing `toolchain.lock.yaml` artifact lockfile. Defaults to
    `<install_path>/toolchain.lock.yaml`, including the XDG installation default.
    An explicitly configured relative path resolves against the project's `base_path`.
    Set `lock_file: toolchain.lock.yaml` to keep a committed project lockfile alongside `atmos.yaml`
    while sharing binaries in XDG storage.
  </dd>

  <dt>`use_lock_file`</dt>
  <dd>
    Verify downloaded artifacts against recorded checksums and record missing version/platform
    entries after successful installation. Defaults to `true`. Existing matching entries remain
    unchanged; a checksum mismatch fails before extraction.
  </dd>

  <dt>`frozen_lock_file`</dt>
  <dd>
    Require an existing URL and checksum for every requested tool version and current platform,
    even when its binary is cached. Defaults to `false`. Implies lockfile verification even if
    `use_lock_file` is `false`. Prohibits lockfile updates, including explicit lock refreshes.
    Override with `ATMOS_TOOLCHAIN_FROZEN_LOCK_FILE=true` for CI.
  </dd>

  <dt>`max_concurrency`</dt>
  <dd>
    Maximum number of independent tool installs that may run at the same time.
    - Default: `4`
    - Must be a positive integer; values lower than `1` are rejected
    - Applies to explicit multi-tool installs and installs from `.tool-versions`
  </dd>
</dl>

## Environment Variables

These overrides apply during configuration loading, including automatic dependency installation
and Atmos version switching:

| Environment variable | Overrides |
| --- | --- |
| `ATMOS_TOOLCHAIN_FILE_PATH` | The version manifest path, including both `file_path` and `versions_file`. |
| `ATMOS_TOOLCHAIN_INSTALL_PATH` | The binary installation directory, `install_path`. |

Absolute paths are used as supplied. Relative paths resolve from the configured project base.
Without a project, an explicit installation path is still honored; XDG storage remains the default.
Automatic installs continue to leave the version manifest unchanged.

For example, install the project's tools into a shared directory:

```shell
ATMOS_TOOLCHAIN_INSTALL_PATH=/shared/atmos-tools atmos toolchain install
```

The toolchain command's existing `--tool-versions` and `--toolchain-path` flags take precedence
over these environment variables.

## Package Verification

Atmos verifies downloaded toolchain packages before extraction when registry metadata includes checksums, signatures, or attestations. The default behavior is non-breaking: verification runs when metadata is available, and packages without verification metadata can still install.

See [Toolchain Verification](/cli/configuration/toolchain/verification) for checksum policies, signature policies, verifier CLI resolution, and strict verification settings.

## Automatic Installation and Lockfiles

Automatic dependency installation, proxy execution, `toolchain exec`, and Atmos version
switching install missing binaries without adding or changing declarations in `.tool-versions`.
They use the same `toolchain.lock.yaml` as explicit installations: existing checksums are
constraints, and missing version/platform entries are recorded after successful installation.
No additional configuration file is needed.

Checksums are also computed when upstream checksum metadata is unavailable. This records the
artifact for subsequent integrity checks; it does not replace upstream signature verification.
Use the [verification policies](/cli/configuration/toolchain/verification) to require upstream evidence.

Project-driven Atmos version switching honors the active project's registry, installation,
and lockfile settings, including profiles. Without project configuration, bootstrap uses XDG
storage for binaries and metadata and does not create `.tool-versions` in the invoking directory.

The `.tool-versions.lock` sidecar coordinates concurrent file access. It is not an artifact
lockfile and should not be committed.

### Frozen Installs in CI

```yaml
toolchain:
  lock_file: toolchain.lock.yaml
```

Generate and commit the lockfile for the platforms used by your team, then enable frozen mode in CI:

```shell
atmos toolchain lock
ATMOS_TOOLCHAIN_FROZEN_LOCK_FILE=true atmos toolchain install
```

Frozen mode fails before download if the file or the requested version/platform entry is missing
or incomplete. It never refreshes the lockfile. Disable frozen mode explicitly when refreshing:

```shell
ATMOS_TOOLCHAIN_FROZEN_LOCK_FILE=false atmos toolchain lock
```

Use exact release versions with frozen mode. Mutable `latest` requests and Atmos PR/SHA/ref
artifact bootstrap are unsupported in frozen mode. Frozen checks validate archive checksums
on download and require lock entries on cache hits; they do not rehash extracted cached binaries.

## Tool Versions File

Create a `.tool-versions` file to track tool dependencies:

<File title=".tool-versions">
```
terraform 1.9.8
opentofu 1.10.3
kubectl 1.28.0
helm 3.13.0
tflint 0.44.1
```
</File>

This file follows the asdf format:
- One tool per line
- Format: `<tool-name> <version>`
- Commit to version control for team consistency

## Installing Tools

Install all tools from `.tool-versions`:

```bash
atmos toolchain install
```

Install a specific tool:

```bash
atmos toolchain install terraform@1.9.8
atmos toolchain install kubectl@1.28.0
```

## Directory Structure

Tools are grouped by owner, repository, and version under the configured installation path
(the XDG toolchain cache by default):

```text
<install_path>/
└── bin/
    ├── hashicorp/
    │   └── terraform/
    │       └── 1.9.8/
    │           └── terraform
    └── helm/
        └── helm/
            └── 3.13.0/
                └── helm
```

## Advanced Configuration

For advanced toolchain features, see:

- [Registries](/cli/configuration/toolchain/registries) - Configure tool registries (Aqua, custom, inline)
- [Aliases](/cli/configuration/toolchain/aliases) - Define tool name aliases
- [Proxies](/cli/configuration/toolchain/proxies) - Run toolchain tools under familiar command names
- [Verification](/cli/configuration/toolchain/verification) - Configure checksum, signature, and attestation verification

## Complete Example

<File title="atmos.yaml">
```yaml
toolchain:
  # Basic settings
  file_path: ".tool-versions"
  install_path: ".tools"
  max_concurrency: 4

  # Tool name aliases
  aliases:
    terraform: hashicorp/terraform
    tf: hashicorp/terraform
    tofu: opentofu/opentofu
    kubectl: kubernetes-sigs/kubectl
    helm: helm/helm

  # Registries
  registries:
    - name: aqua
      type: aqua
      source: https://github.com/aquaproj/aqua-registry/tree/main/pkgs
      priority: 10

  # Package verification
  verification:
    checksums: when_available
    signatures: when_available
    verifier_install: auto
    verifier_trust: auto
```
</File>

## Environment Variables

Configure toolchain behavior via environment variables:

<dl>
  <dt>`ATMOS_TOOLCHAIN_FILE_PATH`</dt>
  <dd>Override the tool versions file path</dd>

  <dt>`ATMOS_TOOLCHAIN_INSTALL_PATH`</dt>
  <dd>Override the tool installation directory</dd>

  <dt>`ATMOS_TOOLCHAIN_MAX_CONCURRENCY`</dt>
  <dd>
    Override the maximum number of simultaneous tool installs. Supply a
    positive integer; values lower than `1` are rejected.
  </dd>

  <dt>`ATMOS_GITHUB_TOKEN` or `GITHUB_TOKEN`</dt>
  <dd>
    GitHub personal access token for:
    - Higher API rate limits (5,000 req/hour vs 60 unauthenticated)
    - Access to private repositories
    - Better reliability during bulk operations
  </dd>

  <dt>`ATMOS_TOOLCHAIN_GITHUB_URL` / `ATMOS_TOOLCHAIN_GITHUB_API_URL` / `ATMOS_TOOLCHAIN_AQUA_REGISTRY_URL`</dt>
  <dd>
    Override the hosts used for toolchain release assets, repository API calls, and the
    aqua-registry mirror — see [GitHub Enterprise Server](#github-enterprise-server-ghes) below.
  </dd>
</dl>

## GitHub Enterprise Server (GHES) {#github-enterprise-server-ghes}

If your own repositories live on a GitHub Enterprise Server instance, Atmos honors
`GITHUB_SERVER_URL` / `GITHUB_API_URL` for imports, vendoring, and the CI provider (see
[Environment Variables](/cli/environment-variables#github-enterprise-server-ghes)). The
toolchain deliberately does **not** follow those variables: aqua-registry tools and their
release assets are hosted on public `github.com` regardless of where your own repositories
live, so pointing `GITHUB_SERVER_URL` at a GHES instance must never break `atmos toolchain
install` on a GHES-hosted CI runner.

If you mirror or proxy GitHub releases through a corporate artifact repository, use the
toolchain-specific variables instead:

```shell
export ATMOS_TOOLCHAIN_GITHUB_URL=https://releases.corp.example.com
export ATMOS_TOOLCHAIN_GITHUB_API_URL=https://releases.corp.example.com/api/v3
export ATMOS_TOOLCHAIN_AQUA_REGISTRY_URL=https://releases.corp.example.com/aqua-registry/main
```

## CLI Precedence

Configuration is resolved in this order (highest to lowest priority):

For install concurrency, the resolved value is:

1. **CLI flag**: `atmos toolchain install --max-concurrency 8`
2. **Environment variable**: `ATMOS_TOOLCHAIN_MAX_CONCURRENCY=6`
3. **Configuration file**: `toolchain.max_concurrency` in `atmos.yaml`
4. **Default**: `4`

## Related Documentation

- [Toolchain Commands](/cli/commands/toolchain/usage) - Full command reference
- [Workflows](/workflows) - Integrate toolchain with workflows
- [Stack Dependencies](/stacks/dependencies) - Declare tool requirements per component