Toolchain Configuration

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.

You will learn

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

CI and security-sensitive environments

Enable toolchain.frozen_lock_file: true 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:

atmos.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

Configuration Options

file_path

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

install_path

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

versions_file

Alternative name for file_path. Use file_path for consistency.

tools_dir

Alternative name for install_path. Use install_path for consistency.

lock_file

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.

use_lock_file

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.

frozen_lock_file

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.

max_concurrency

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

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:

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 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 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

toolchain:
  lock_file: toolchain.lock.yaml

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

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:

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:

.tool-versions

terraform 1.9.8
opentofu 1.10.3
kubectl 1.28.0
helm 3.13.0
tflint 0.44.1

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:

atmos toolchain install

Install a specific tool:

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):

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

Advanced Configuration

For advanced toolchain features, see:

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

Complete Example

atmos.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

Environment Variables

Configure toolchain behavior via environment variables:

ATMOS_TOOLCHAIN_FILE_PATH

Override the tool versions file path

ATMOS_TOOLCHAIN_INSTALL_PATH

Override the tool installation directory

ATMOS_TOOLCHAIN_MAX_CONCURRENCY

Override the maximum number of simultaneous tool installs. Supply a positive integer; values lower than 1 are rejected.

ATMOS_GITHUB_TOKEN or GITHUB_TOKEN

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

ATMOS_TOOLCHAIN_GITHUB_URL / ATMOS_TOOLCHAIN_GITHUB_API_URL / ATMOS_TOOLCHAIN_AQUA_REGISTRY_URL

Override the hosts used for toolchain release assets, repository API calls, and the aqua-registry mirror — see GitHub Enterprise Server below.

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

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:

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

Toolchain Commands - Full command reference
Workflows - Integrate toolchain with workflows
Stack Dependencies - Declare tool requirements per component

You will learn

Basic Configuration​

Configuration Options​

Environment Variables​

Package Verification​

Automatic Installation and Lockfiles​

Frozen Installs in CI​

Tool Versions File​

Installing Tools​

Directory Structure​

Advanced Configuration​

Complete Example​

Environment Variables​

GitHub Enterprise Server (GHES)​

CLI Precedence​

Related Documentation​

Basic Configuration

Configuration Options

Environment Variables

Package Verification

Automatic Installation and Lockfiles

Frozen Installs in CI

Tool Versions File

Installing Tools

Directory Structure

Advanced Configuration

Complete Example

Environment Variables

GitHub Enterprise Server (GHES)

CLI Precedence

Related Documentation