Skip to main content

Toolchain Registries

Toolchain registries define where Atmos finds tool metadata and binaries. Atmos supports multiple registry types with priority-based precedence, allowing you to use official registries, corporate mirrors, and custom tool definitions.

You will learn

  • Multiple registry support with priority ordering
  • Aqua registry integration (1,000+ pre-configured tools)
  • Inline registry for quick prototyping
  • Custom registries for private or corporate tools
  • File-based and URL-based registry sources

Registry Types​

Atmos supports two registry types, aqua and atmos, with the following configuration forms:

1. Aqua Registry​

The Aqua registry is a community-maintained collection of 1,000+ CLI tool definitions with battle-tested metadata.

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

Features:

  • Pre-configured tools: terraform, kubectl, helm, aws-cli, and more
  • Regular updates from active contributors
  • Rich metadata: download URLs, checksums, version mapping
  • Proven YAML format used by thousands of teams

2. Atmos Inline Registry​

Define tools directly in your atmos.yaml for quick prototyping or custom tools:

atmos.yaml
toolchain:
  registries:
    - name: my-tools
      type: atmos
      priority: 150
      tools:
        stedolan/jq:
          type: github_release
          url: "jq-{{.OS}}-{{.Arch}}"
        mikefarah/yq:
          type: github_release
          url: "yq_{{.Version}}_{{.OS}}_{{.Arch}}.tar.gz"

Features:

  • No external files needed
  • Perfect for quick prototyping or small tool sets
  • Supports all template variables: {{.OS}}, {{.Arch}}, {{.Version}}, {{trimV .Version}}
  • Tools defined using owner/repo format

3. Custom File-Based Registry​

Use custom registry files for corporate or private tools:

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

Registry Source Patterns​

Atmos supports two registry file organization patterns:

Single Index File (Recommended)​

All tool definitions in one file:

atmos.yaml
toolchain:
  registries:
    - name: custom
      type: aqua
      source: file://./registry.yaml  # Ends with .yaml or .yml
      priority: 100
registry.yaml
packages:
  - type: github_release
    repo_owner: hashicorp
    repo_name: terraform
    asset: "terraform_{{.Version}}_{{.OS}}_{{.Arch}}.zip"

  - type: github_release
    repo_owner: opentofu
    repo_name: opentofu
    asset: "tofu_{{.Version}}_{{.OS}}_{{.Arch}}.zip"

Benefits:

  • Simplest to maintain
  • All tools in one place
  • Matches official Aqua registry structure

Per-Package Directory​

Separate file per package for larger registries:

atmos.yaml
toolchain:
  registries:
    - name: custom
      type: aqua
      source: file://./pkgs/  # Directory, not .yaml file
      priority: 100

Directory structure:

pkgs/
├── hashicorp/
│   └── terraform/
│       └── registry.yaml
└── opentofu/
    └── opentofu/
        └── registry.yaml

Each registry.yaml contains ONE package definition.

Benefits:

  • Better organization for large registries
  • Per-tool versioning
  • Easier to maintain individual tools

Priority System​

Registries are checked in priority order (highest to lowest):

atmos.yaml
toolchain:
  registries:
    # Checked first (highest priority)
    - name: corporate
      type: atmos
      priority: 150
      tools:
        internal/custom-tool:
          type: http
          url: "https://artifacts.corp.com/custom-tool/{{.Version}}/binary"

    # Checked second
    - name: corporate-mirror
      type: aqua
      source: file://./corporate-registry/registry.yaml
      priority: 100

    # Checked third
    - name: internal-mirror
      type: aqua
      source: https://github-mirror.corp.com/aqua-registry/pkgs
      priority: 50

    # Checked last (lowest priority)
    - name: aqua-public
      type: aqua
      source: https://github.com/aquaproj/aqua-registry/tree/main/pkgs
      priority: 10

Resolution order:

  1. Corporate inline tools (priority: 150)
  2. Corporate registry file (priority: 100)
  3. Internal mirror (priority: 50)
  4. Public Aqua registry (priority: 10)
  5. Error if tool not found in any registry

The curated atmos-builtin registry is always included at priority 100. Set a custom registry's priority above 100 to override its definitions. When toolchain.registries is omitted, Atmos adds the default aqua-public registry at priority 10.

Inspect Configured Registries​

Use the configured name when browsing a registry:

atmos toolchain registry list --format json
atmos toolchain registry list corporate --format json

The first command returns descriptors (name, type, and priority) without downloading catalogs. The second lists only the named registry's tools, when its backend supports enumeration. Inline registries support stable name ordering and pagination; per-package URL registries resolve tools by name but do not provide a complete catalog listing.

Registry Configuration Options​

name
Unique identifier for the registry
type

Registry type:

  • aqua - Aqua registry format (file or URL)
  • atmos - Inline tool definitions
source

Registry location (required for aqua type):

  • File: file://./path/to/registry.yaml
  • Directory: file://./path/to/pkgs/
  • URL: https://github.com/aquaproj/aqua-registry/tree/main/pkgs
priority

Search priority (higher numbers checked first):

  • Inline registries: 100-200
  • Corporate registries: 50-100
  • Public registries: 1-50
  • Omitted configured priority: 0
  • Default Aqua registry when no registries are configured: 10
tools

Inline tool definitions (required for atmos type):

  • Key format: owner/repo
  • Value: Tool configuration object

Tool Definition Format​

Tools in Aqua registries use this format:

registry.yaml
packages:
  - type: github_release
    repo_owner: hashicorp
    repo_name: terraform
    asset: "terraform_{{.Version}}_{{.OS}}_{{.Arch}}.zip"
    format: zip
    version_constraint: "semver"
    version_overrides:
      - version_constraint: ">= 1.0.0"
        asset: "terraform_{{.Version}}_{{.OS}}_{{.Arch}}.zip"

Template Variables​

Use template variables in asset URLs:

{{.Version}}
Full version string (e.g., 1.9.8)
{{trimV .Version}}
Version without 'v' prefix (e.g., 1.9.8 from v1.9.8)
{{.OS}}
Operating system (linux, darwin, windows)
{{.Arch}}
Architecture (amd64, arm64)
{{trimPrefix .Version "v"}}
Remove prefix from string
{{trimSuffix .Version "-beta"}}
Remove suffix from string
{{replace .Version "." "_"}}
String replacement

Package Types​

GitHub Release​

Download from GitHub release assets:

registry.yaml
packages:
  - type: github_release
    repo_owner: hashicorp
    repo_name: terraform
    asset: "terraform_{{.Version}}_{{.OS}}_{{.Arch}}.zip"

HTTP Download​

Download from direct URLs:

registry.yaml
packages:
  - type: http
    url: "https://releases.hashicorp.com/terraform/{{trimV .Version}}/terraform_{{trimV .Version}}_{{.OS}}_{{.Arch}}.zip"

Supported Archive Formats​

Atmos automatically detects and extracts:

  • .tar.gz - Gzip-compressed tarballs
  • .zip - ZIP archives
  • .gz - Single gzip-compressed binaries
  • Raw binaries (no extension)

Complete Example​

atmos.yaml
toolchain:
  install_path: ".tools"
  versions_file: ".tool-versions"

  registries:
    # Corporate inline tools (highest priority)
    - name: corporate
      type: atmos
      priority: 150
      tools:
        corp/internal-cli:
          type: http
          url: "https://artifacts.corp.com/cli/{{.Version}}/cli-{{.OS}}-{{.Arch}}"

    # Corporate Aqua registry mirror
    - name: corporate-aqua
      type: aqua
      source: file://./corporate-registry/registry.yaml
      priority: 100

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

Registry definitions are cached locally for performance. Use atmos toolchain clean --cache-only --force to clear registry/download caches while preserving installed binaries.

Related Documentation​