Atmos Toolchain

Atmos Toolchain

Purpose

The Atmos toolchain manages CLI tool installation and versioning natively, using the Aqua package registry ecosystem. It replaces external version managers (asdf, mise, aqua CLI) with a built-in system that integrates directly with atmos.yaml configuration.

Default Rule

Declare tool requirements where they are used, then run the owning Atmos command. Do not add atmos toolchain install before component, workflow, custom-command, or hook execution when the tool can be declared with dependencies.tools. Atmos installs missing declared tools and injects them into PATH for that execution context.

Use explicit atmos toolchain install only for shell bootstrap, cache warming, ad-hoc troubleshooting, or job-level tools that are not owned by a component, workflow, custom command, or hook.

Agents repeatedly get two things wrong here: putting an operation-specific tool version only in .tool-versions, and wrapping atmos itself in atmos toolchain exec. Both are covered below.

❌ Wrong — a component needs a pinned Terraform version, declared only in .tool-versions:

# .tool-versions
terraform 1.10.3

This is a repo-wide default. Nothing ties it to the vpc component, so a different component (or a different environment's .tool-versions) can silently drift the version this component actually needs.

✅ Right — pin it on the component that requires it:

components:
  terraform:
    vpc:
      dependencies:
        tools:
          terraform: "1.10.3"

.tool-versions still sets the repo-wide developer-shell default; dependencies.tools overrides it for this component's execution context, and travels with the component if it's vendored or reused elsewhere.

Core Concepts

.tool-versions File

The .tool-versions file (asdf-compatible format) declares which tools and versions a project needs:

terraform 1.9.8
opentofu 1.10.3
kubectl 1.28.0
helm 3.13.0
jq 1.7.1

• One tool per line, format: toolname version [version2 version3...]
• Multiple versions per tool are supported; first version is the default
• File location: project root (default), overridable via toolchain.versions_file in atmos.yaml, --tool-versions, or ATMOS_TOOL_VERSIONS

Use .tool-versions for repo-wide developer shell defaults and general tools that every developer, agent, or interactive shell should see. Atmos can auto-install these defaults for custom commands and shell integration, but .tool-versions is not the preferred home for operation-specific requirements.

Use dependencies.tools when the tool is part of a stack/component/workflow/command contract. Those dependencies are installed and injected into that execution context and can override .tool-versions defaults. Do not rely on .tool-versions alone when CI or a stack requires a specific Terraform, OpenTofu, scanner, or generator version.

Where to Declare a Tool

Tool Installation Path

By default, tools are installed in the XDG data directory for Atmos, such as ~/.local/share/atmos/toolchain on Linux/macOS. If the XDG data directory cannot be created, Atmos falls back to .tools in the current project.

Installed tools use this layout under the selected install path:

<install-path>/bin/{os}/{tool}/{version}/{binary}

Override the install path with toolchain.install_path in atmos.yaml or ATMOS_TOOLCHAIN_PATH when tools must be stored in a project-local, shared, or cached directory.

Registries

Atmos supports three registry types for discovering and downloading tools:

Aqua Registry -- The primary source, providing 1,000+ tools:

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

Inline (Atmos) Registry -- Define tools directly in atmos.yaml:

registries:
  - name: custom
    type: atmos
    priority: 150
    tools:
      owner/repo:
        type: github_release
        url: "asset_{{.Version}}_{{.OS}}_{{.Arch}}"
        format: tar.gz

File-Based Registry -- Local or remote Aqua-format files:

registries:
  - name: corporate
    type: aqua
    source: file://./custom-registry.yaml
    priority: 100

Priority System: Higher numbers are checked first. First match wins. Typical ordering: inline (150) > corporate (100) > public aqua (10).

Aliases

Map short names to fully qualified tool identifiers:

toolchain:
  aliases:
    terraform: hashicorp/terraform
    tf: hashicorp/terraform
    kubectl: kubernetes-sigs/kubectl

Package Verification

Atmos verifies downloaded packages before extraction when Aqua or inline registry metadata provides checksums, signatures, or attestations. Defaults are non-breaking: verify when metadata exists, allow packages without metadata.

toolchain:
  verification:
    checksums: when_available   # when_available | required | disabled
    signatures: when_available  # when_available | required | disabled
    verifier_install: auto      # auto | path_only

Supported methods: checksums (sha256, sha512, sha1, md5), cosign, slsa-verifier, GitHub artifact attestations via gh, and minisign.

Configuration in atmos.yaml

toolchain:
  install_path: .tools              # Optional override; default is XDG data dir
  versions_file: .tool-versions     # Path to version file

  aliases:
    terraform: hashicorp/terraform
    tf: hashicorp/terraform

  registries:
    # Inline tools (highest priority)
    - name: my-tools
      type: atmos
      priority: 150
      tools:
        jqlang/jq:
          type: github_release
          url: "jq-{{.OS}}-{{.Arch}}"

    # Aqua registry (fallback)
    - name: aqua
      type: aqua
      source: https://github.com/aquaproj/aqua-registry/tree/main/pkgs
      priority: 10

  verification:
    checksums: when_available
    signatures: when_available
    verifier_install: auto

Key Commands

See references/commands-reference.md for the full command/flag reference. Common commands:

atmos toolchain install [tool@version]      # Bootstrap/cache warm, or ad-hoc install
atmos toolchain update [tool...]            # Update pinned tools to newest available version
atmos toolchain uninstall <tool@version>    # Remove installed tool
atmos toolchain add/remove/set/get <tool>   # Manage .tool-versions entries
atmos toolchain search/info/list/which      # Discovery and inspection
atmos toolchain exec <tool@version> -- ...  # Run a pinned third-party binary
atmos toolchain env/path                    # Shell PATH integration
atmos toolchain registry list/search        # Registry inspection
atmos toolchain du / clean                  # Disk usage / cleanup

Prefer dependencies.tools for normal Atmos execution. Component, workflow, custom-command, and hook runs install missing declared tools automatically.

Anti-pattern: never run atmos toolchain exec -- atmos .... Every atmos command is already toolchain-aware — it resolves and injects declared tool paths for its own execution automatically (see "Default Rule" above). Wrapping atmos in atmos toolchain exec is redundant at best and a sign the tool declaration is missing at worst. toolchain exec exists only to run a third-party binary (terraform, kubectl, a scanner CLI) directly, pinned to a specific managed version, outside of an atmos-orchestrated command — never to invoke atmos itself.

If a workflow/custom-command/hook step needs to confirm a tool is present on PATH without installing it, use the require step type (alias assert) instead of dependencies.tools (which auto-installs) or a hand-rolled command -v shell check — see atmos-workflows for the tools:/files:/ dirs: config.

Environment Variables

Precedence Order

1. CLI flags (highest)
2. Environment variables
3. atmos.yaml configuration
4. XDG data directory
5. .tools fallback