Skip to main content

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

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"

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
install_path

Directory where toolchain binaries will be installed.

  • Default: .tools
  • Supports relative or absolute paths
  • Tools are organized by name and version: .tools/bin/{os}/{tool}/{version}/{tool}
versions_file

Alternative name for file_path. Use file_path for consistency.

tools_dir

Alternative name for install_path. Use install_path for consistency.

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.

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​

After installation, tools are organized as follows:

.tools/
├── bin/
│   └── darwin/                    # OS-specific directory
│       ├── terraform/
│       │   └── 1.9.8/
│       │       └── terraform      # Binary
│       ├── kubectl/
│       │   └── 1.28.0/
│       │       └── kubectl
│       └── helm/
│           └── 3.13.0/
│               └── helm
└── cache/
    └── downloads/                 # Downloaded archives

Advanced Configuration​

For advanced toolchain features, see:

  • Registries - Configure tool registries (Aqua, custom, inline)
  • Aliases - Define tool name aliases
  • Verification - Configure checksum, signature, and attestation verification

Complete Example​

atmos.yaml
toolchain:
  # Basic settings
  file_path: ".tool-versions"
  install_path: ".tools"

  # 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

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

CLI Precedence​

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

  1. CLI flags: atmos toolchain install --install-path=/custom/path
  2. Environment variables: ATMOS_TOOLCHAIN_INSTALL_PATH=/custom/path
  3. Configuration file: toolchain.install_path in atmos.yaml
  4. Defaults: .tools for install_path, .tool-versions for file_path