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

## 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
  </dd>

  <dt>`install_path`</dt>
  <dd>
    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}`
  </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>`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>

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

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

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](/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