The native container build step can now provision that builder and cache directly, so a build's caching strategy lives next to the rest of its configuration instead of in separate Actions.

The Problem​

A docker buildx build that starts cold rebuilds every layer, even when nothing meaningful changed. Reusing a remote cache and a purpose-built builder solves this, but doing it by hand means composing several pieces: creating a builder with the right driver, pointing it at a registry-backed cache, and keeping all of that in sync with the rest of the build step.

The Fix​

action: build now accepts driver and cache:

- name: build
  type: container
  action: build
  provider: docker
  with:
    engine: buildx
    context: .
    dockerfile: Dockerfile
    tags:
      - registry.example.com/app:latest

    driver: docker-container   # shorthand — just the driver

    cache:
      from:
        - type: registry
          ref: registry.example.com/app:buildcache
      to:
        - type: registry
          ref: registry.example.com/app:buildcache
          mode: max

Atmos creates the named builder if it doesn't already exist and reuses it on later runs, so the builder's own cache persists across builds on the same host instead of starting cold every time. driver also accepts a full form when you need driver-specific options, such as pointing Buildx at a mirrored BuildKit image to avoid Docker Hub rate limits:

with:
  driver:
    name: atmos
    provider: docker-container
    opts:
      image: mirror.gcr.io/moby/buildkit:buildx-stable-1

How to Use It​

Add driver and cache under an existing action: build step wherever you use engine: buildx. If you build with bake instead, keep cache-from/cache-to in the bake file itself — Bake already supports them natively — and use driver for builder selection either way.

See the container step documentation for the full field reference, including the three ways to avoid Docker Hub rate limits.

Get Involved​

Try driver and cache in a build step and share feedback through GitHub issues.

Atmos can now validate the files affected by a change, so pull requests get actionable feedback without rechecking unrelated project inputs.

The Problem​

Configuration schema checks, stack validation, formatting rules, and workflow linting protect different parts of a project. Running every check over an entire repository can obscure the result that matters to the change under review.

The Fix​

Add --affected to the project-wide validator or to an individual validator. Atmos compares the current worktree with the Git merge-base, including local uncommitted and untracked files. In GitHub Actions, it reads the pull request base SHA automatically.

atmos validate --affected --format rich
atmos validate config --affected --base origin/main
atmos config validate --affected --base origin/main
atmos validate stacks --affected --base origin/main
atmos stack validate --affected --base origin/main
atmos validate editorconfig --affected --base origin/main
atmos validate ci --affected --base origin/main

Schema and EditorConfig checks validate changed inputs directly. Changes to a schema or rule configuration expand validation to the relevant full set. Stack validation runs whenever stack or Atmos configuration inputs change, preserving import and duplicate-component checks. Workflow validation sends only changed workflows to actionlint unless its configuration changes.

How to Use It​

Use the new Validation (affected) GitHub Actions job as a model for a project workflow. Check out enough Git history for the merge-base, then run the command with rich output:

- uses: actions/checkout@v6
  with:
    fetch-depth: 0
- run: atmos validate --affected --format rich

Get Involved​

Try affected validation in your pull request workflow and share feedback through GitHub issues.

The atmos init command initializes an Atmos project from a template chosen for the job at hand: a minimal cloud-agnostic project, an AWS application SDLC project, or a cloud landing zone. Each template creates the configuration, structure, and operational path appropriate to that project rather than asking every team to assemble it from scratch.

View the full init example

Initialize the Project You Need​

The basic template gives a new project a small, cloud-agnostic foundation with a real greeting Terraform component. It creates a local file, so a developer can validate and deploy the generated project without a cloud account, credentials, or an emulator. The point is to prove that the initialized project works before anyone starts extending it.

For teams beginning an application project, the aws/app catalog template establishes a complete AWS application SDLC repository with dev, staging, and production stacks, native CI, and an emulator-proven application component. For a platform foundation, aws/landing-zone initializes dev, staging, and production environments with a conventional AWS baseline for audit, KMS, SSM, monitoring, and IAM. The catalog also includes GCP and Azure landing-zone starting points.

A Consistent Initialization Contract​

An interactive invocation lets a developer choose the project template and answer only the questions that shape it. Required answers, patterns, option lists, and boolean values are enforced consistently whether they come from prompts, defaults, persisted values, or --set. The same initialization can therefore be repeated from automation without bypassing the template’s contract.

Built-in templates travel with the Atmos binary. Catalog templates resolve to the source associated with that build, so a team initializes from a known template version rather than an accidental snapshot of a repository.

Build Your Organization's Golden Paths​

The init catalog distributes proven starting points with Atmos. For organization-owned golden paths that your platform team distributes through a catalog or Git repository, see the scaffolds announcement.

See the Init Command Documentation for the full template list.

Atmos scaffolds turn a golden path into an executable contract. Use a local template, register one in atmos.yaml, or point to a Git repository—including a GitHub template repository—and let the same template guide developers, automate CI, and evolve with the platform.

Creation is only day one. Golden paths accumulate improvements after projects have adopted them: updated CI conventions, guardrails, shared configuration, and boilerplate. Atmos scaffolds include an optimistic three-way merge process so a project can take those upstream improvements without blindly replacing the custom work that happened after initialization.

View the full scaffolding example

From Repository Copy to Golden Path​

The usual alternative is either a generic template that every team must customize by hand or a matrix of near-duplicate templates for every language, environment, compliance rule, and deployment option. The first creates drift. The second makes the platform team responsible for maintaining an ever-growing catalog of almost-the-same repositories.

A scaffold keeps one template and makes it adapt to the project being created. The platform team owns the contract; the consuming team supplies only the choices that belong to its project.

What the Contract Enforces​

• Validated inputs. Required fields, patterns, select and multiselect options, and boolean values are validated for interactive answers, defaults, presets, persisted values, and --set flags. Platform policy does not disappear when a template runs in CI.
• Conditional prompts and files. A field or file can use when: and the answers collected so far. A template can ask for a vendored component version only when vendoring is enabled, then generate the corresponding manifest only in that case.
• Lifecycle hooks. Templates can run declared work before or after generation—formatting, validation, or setup—with the same condition engine used by Atmos workflows and CI hooks. Teams can use --skip-hooks as an explicit per-invocation escape hatch.
• Day-two updates. The atmos scaffold generate --update command re-runs a template against an existing project and performs an optimistic three-way merge. It is a strong fit for shared boilerplate that changes infrequently across many projects: non-overlapping improvements can be carried forward, while real conflicts stay visible instead of silently overwriting local work. The --merge-strategy option selects manual, ours, or theirs conflict handling.

Both when: forms use the condition language shared by Atmos workflows and CI hooks. The answers variable exposes the values collected so far, allowing a golden path to express its decisions once rather than encode them in a pile of repository variants.

Keep GitHub Templates, Add a Platform Contract​

GitHub template repositories remain a useful ownership and discovery mechanism. Atmos adds the behavior they intentionally do not provide: typed choices, conditional generation, hooks, and a safe path for bringing template improvements back to an existing project. A remote source can be pinned to a branch, tag, or commit with --ref, so platform teams can make a deliberate release available instead of distributing an accidental snapshot.

See the Scaffold Command Documentation for the field, hook, remote-source, and update reference.

Proxies also make subcommands first-class executable names. A command-named link points back to Atmos; when it is invoked, Atmos reads the executed name, finds its proxy configuration, and runs the configured tool with its prefix arguments and the caller’s arguments. A multicall tool such as uutils/coreutils can therefore expose coreutils ls as the normal ls command—without shell aliases, copied shims, or a different invocation in every repository.

Install on Demand, Keep Versions Pinned​

An alias resolves the package name, and a proxy maps the familiar command to the package and any prefix arguments it needs:

toolchain:
  aliases:
    coreutils: uutils/coreutils
  proxies:
    ls:
      tool: coreutils
      args: [ls]

coreutils 0.9.0

Get Started​

Activate every configured proxy in the current Bash or Zsh session with one command:

eval "$(atmos toolchain env)"

The normal ls command now invokes the ls proxy, which resolves to the pinned coreutils ls implementation. On its first invocation, the proxy installs that version if it is not already available, then runs it with the supplied arguments. Later invocations reuse the installed binary.

For an intentionally eager setup—for example, a CI image or an offline preparation step—install every pinned tool in .tool-versions before activating the environment:

atmos toolchain install
eval "$(atmos toolchain env)"

Promote a Subcommand to a Command​

The same on-demand mechanism is useful when a package exposes many operations through one binary. The args list supplies the subcommand or default flags, while the proxy name becomes the command that developers and automation invoke. This turns a useful part of a larger tool into a normal, version-pinned command without a wrapper script.

Useful Beyond an Interactive Shell​

Atmos prepares the proxy environment for built-in command runners, workflows, hooks, components, and custom commands. A project can therefore use the familiar command name in its automation while retaining the tool version and source in version control. Developers can opt into the same proxy directory in their terminal without modifying the system command globally.

The boundary is deliberate: a proxy is available only to Atmos child processes or to a shell that has explicitly activated the toolchain environment. It never replaces the system ls command for the rest of the machine.

Portable by Design​

Atmos creates symbolic links on Unix-like systems and executable hard links on Windows, avoiding a Windows symlink-privilege requirement. Proxy activation also carries the configuration context across directory changes, so the selected toolchain remains associated with the project that declared it.

See Toolchain Proxies for the configuration reference, platform details, and troubleshooting guidance.

What's New​

The !terraform.state YAML function now supports Azure Blob Storage (azurerm) backends, joining existing support for S3 and local backends. This means you can retrieve Terraform outputs from Azure-backed state files at lightning speed—without the overhead of Terraform initialization.

Why This Matters​

Before this feature, if you were using Azure Blob Storage as your Terraform backend, you had two options for reading remote state:

1. !terraform.output - Slow but reliable. Requires full Terraform initialization, provider downloads, and varfile generation.
2. !store - Fast but requires extra setup. You had to manually configure external secret stores.

Now you can use !terraform.state with Azure backends—getting 10-100x faster performance compared to !terraform.output by reading directly from blob storage.

How It Works​

Backend Configuration​

Configure your Terraform component with an azurerm backend:

components:
  terraform:
    vpc:
      backend_type: azurerm
      backend:
        azurerm:
          storage_account_name: "mystorageaccount"
          container_name: "tfstate"
          key: "vpc.terraform.tfstate"

Reading State​

Use the !terraform.state function to read outputs:

components:
  terraform:
    eks-cluster:
      vars:
        # Get vpc_id output from vpc component in current stack
        vpc_id: !terraform.state vpc vpc_id

        # Get private subnet IDs
        subnet_ids: !terraform.state vpc private_subnet_ids

        # Get first subnet using YQ expression
        subnet_id: !terraform.state vpc .private_subnet_ids[0]

Cross-Stack References​

Reference components from different stacks:

components:
  terraform:
    tgw:
      vars:
        # Get VPC ID from production stack
        vpc_id: !terraform.state vpc plat-ue2-prod vpc_id

        # Use template for dynamic stack names
        vpc_id: !terraform.state vpc {{ printf "net-%s-%s" .vars.environment .vars.stage }} vpc_id

Authentication​

The Azure Blob Storage integration uses Azure DefaultAzureCredential, which supports multiple authentication methods automatically:

1. Environment variables - AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET
2. Managed Identity - When running in Azure (AKS, VMs, Functions)
3. Azure CLI credentials - az login
4. Visual Studio Code credentials - Authenticated VS Code sessions

No additional configuration needed—just authenticate using your preferred method.

Workspace Handling​

Azure Blob Storage uses a specific naming convention for workspaces:

• Default workspace: Uses the key as-is (e.g., terraform.tfstate)
• Non-default workspaces: Appends workspace as suffix (e.g., terraform.tfstateenv:dev)

Atmos handles this automatically—you don't need to worry about the naming convention.

Example​

If you have:

• Key: apimanagement.terraform.tfstate
• Workspace: dev-wus3-apimanagement-be

Atmos will look for: apimanagement.terraform.tfstateenv:dev-wus3-apimanagement-be

Performance Benefits​

Before: Using !terraform.output​

$ time atmos terraform plan eks-cluster -s plat-ue2-dev

# Must initialize Terraform for each dependency
Initializing vpc component...
Downloading providers...
Generating backend config...
Generating varfiles...
Reading outputs...

real    2m34.521s

After: Using !terraform.state​

$ time atmos terraform plan eks-cluster -s plat-ue2-dev

# Direct blob storage access
Reading state from Azure Blob Storage...

real    0m3.142s

~50x faster in this example—and the speedup grows with infrastructure complexity.

Advanced Features​

YQ Expressions​

Use YQ expressions for complex data extraction:

vars:
  # Get nested map values
  db_endpoint: !terraform.state database .config_map.endpoint

  # String concatenation
  jdbc_url: !terraform.state 'postgres .master_hostname | "jdbc:postgresql://" + . + ":5432/events"'

  # Default values for unprovisioned components
  username: !terraform.state config .username // "default-user"

Caching​

Results are cached in memory per CLI execution:

vars:
  # All three calls use the same cached result
  sg_id_1: !terraform.state vpc security_group_id
  sg_id_2: !terraform.state vpc security_group_id
  sg_id_3: !terraform.state vpc {{ .stack }} security_group_id

The first call reads from Azure; subsequent calls return cached data instantly.

Error Handling​

• Blob not found (404): Returns null (component not provisioned yet)
• Permission denied (403): Returns clear error message
• Network errors: Automatically retries up to 2 times with exponential backoff

Technical Details​

Implementation Highlights​

• Azure SDK for Go - Uses official github.com/Azure/azure-sdk-for-go/sdk/storage/azblob package
• Client caching - Azure Blob clients are cached per storage account/container
• Retry logic - Automatic retry with exponential backoff for transient failures
• Nil safety - Robust error handling prevents panics
• Test coverage - Comprehensive unit tests with mocked Azure SDK
• Cross-platform - Works on Linux, macOS, and Windows

Backend Configuration Options​

All standard Azure backend options are supported:

backend:
  azurerm:
    storage_account_name: "mystorageaccount"  # Required
    container_name: "tfstate"                  # Required
    key: "terraform.tfstate"                   # Optional (default: terraform.tfstate)
    # Authentication happens via DefaultAzureCredential

Migration Guide​

From !terraform.output to !terraform.state​

The syntax is identical—just replace !terraform.output with !terraform.state:

# Before
vpc_id: !terraform.output vpc vpc_id

# After
vpc_id: !terraform.state vpc vpc_id

From !store to !terraform.state​

Simplify your configuration by removing store setup:

# Before: Required store configuration
vpc_id: !store azurekeyvault plat-ue2-dev vpc vpc_id

# After: Direct state access
vpc_id: !terraform.state vpc vpc_id

Examples​

Basic Usage​

components:
  terraform:
    app:
      vars:
        # String output
        security_group_id: !terraform.state security-group id

        # List output
        subnet_ids: !terraform.state vpc private_subnet_ids

        # Map output
        config: !terraform.state config config_map

Cross-Region References​

components:
  terraform:
    replication:
      vars:
        # Reference component from different region
        primary_db: !terraform.state database {{ printf "%s-use1-%s" .vars.tenant .vars.stage }} endpoint

Disaster Recovery Scenarios​

components:
  terraform:
    failover:
      vars:
        # Primary region
        primary_vpc: !terraform.state vpc plat-ue2-prod vpc_id

        # DR region with default fallback
        dr_vpc: !terraform.state vpc plat-uw2-prod .vpc_id // "vpc-mock-dr"

Considerations​

• Secrets exposure: Using !terraform.state with secrets will expose them in atmos describe output
• Permission scoping: Ensure your Azure credentials have access to all referenced storage accounts
• Cross-region access: Consider latency when reading state across regions
• Cold starts: Components not yet provisioned return null (use YQ default values to handle this)

Try It Now​

Upgrade to the latest Atmos release and start using Azure Blob Storage backends:

# Check your version
atmos version

# Describe a component using Azure backend
atmos describe component vpc -s plat-ue2-dev

# Use !terraform.state in your stack configs
# (See examples above)

Documentation​

• !terraform.state Function Reference - Complete usage documentation
• Terraform Backends - Backend configuration guide
• Remote State - Data sharing patterns

Get Involved​

We're building Atmos in the open and welcome your feedback:

• 💬 Discuss - Share thoughts in GitHub Discussions.
• 🐛 Report Issues - Found a bug? Open an issue.
• 🚀 Contribute - Want to add features? Review our contribution guide.

Next up: Google Cloud Storage (GCS) backend support for !terraform.state. Stay tuned!

Atmos now includes GitHub Actions workflow validation as an experimental native-CI command. Run it from your workstation or in the workflow that it checks:

atmos ci validate

# Equivalent validation-oriented alias
atmos validate ci

Validate Before the Push​

With no arguments, atmos ci validate recursively checks every .yml and .yaml file in the current working directory's .github/workflows. It uses the built-in actionlint integration, so the linting capability ships with Atmos rather than requiring a separately installed binary.

A successful run gives a compact confirmation:

✓ Validated 3 GitHub Actions workflow file(s) in .github/workflows.

Findings include the workflow path, line, column, and actionlint rule. They fail the command, which makes validation suitable for both a pre-push check and a CI gate.

Check a Fixture or Another Directory​

Sometimes the workflows you want to validate do not live in the current directory's default location — for example, when testing generated workflows or fixtures. Use --workflow-path to point at that directory. Atmos recursively finds workflow YAML beneath it:

atmos ci validate --workflow-path tests/fixtures/scenarios/invalid-github-actions-workflows/.github/workflows

That repository fixture intentionally uses branch instead of branches in a push trigger. The command reports the line and exits with status 1, making it a quick end-to-end smoke test of the feature. You can also select specific files directly:

atmos ci validate .github/workflows/plan.yml .github/workflows/apply.yml

--workflow-path and explicit workflow-file arguments are intentionally separate selectors and cannot be combined. This keeps the validation scope unambiguous.

Put It in GitHub Actions​

Add a validation step after checkout:

name: Validate workflows

on:
  pull_request:

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: cloudposse/github-action-setup-atmos@v2
      - run: atmos ci validate

When native CI is enabled, Atmos turns findings into line-anchored GitHub Actions annotations:

ci:
  enabled: true

Annotations are enabled by default once ci.enabled is true; set ci.annotations.enabled: false to suppress them. Outside GitHub Actions, the same command has no provider side effects and simply renders its diagnostics.

SARIF Is Explicit​

For a separate Code Scanning upload or an artifact, request SARIF explicitly:

atmos ci validate --format=sarif > actionlint.sarif

Atmos does not upload SARIF automatically. That avoids duplicate pull-request feedback and keeps security-events: write unnecessary unless your workflow deliberately adds a SARIF upload step.

The validator respects .github/actionlint.yaml and .github/actionlint.yml. Its optional ShellCheck and Pyflakes integrations are disabled for now, so the command stays deterministic and does not depend on tools installed on the runner.

Learn More​

• atmos ci validate — usage, flags, and output formats
• Native CI — native CI behavior and configuration
• CI configuration — enable annotations and other CI features

What Changed​

YQ expressions with default values now work correctly in all scenarios:

# This now works reliably when vpc component isn't provisioned
vars:
  vpc_id: !terraform.output vpc {{ .stack }} .vpc_id // "default-vpc"
  subnets: !terraform.state vpc {{ .stack }} .subnets // ["subnet-1", "subnet-2"]

The Problem​

Previously, when a terraform component wasn't provisioned or an output didn't exist, the YAML function wrappers would return nil or exit before the YQ pipeline could evaluate default expressions. This caused sporadic failures where users expected the YQ // operator to provide fallback values.

The issue manifested as:

• Stack configurations failing when referencing unprovisioned components
• Inconsistent behavior depending on component state
• No way to gracefully handle missing outputs with defaults

The Solution​

We refactored the YAML function processing to:

1. Properly classify errors: Distinguish between recoverable errors (component not provisioned, output missing) and non-recoverable API errors (S3 timeouts, network failures)

2. Evaluate YQ defaults for recoverable errors: When a component isn't provisioned but the expression includes a default (//), evaluate the YQ expression against an empty map to extract the default value

3. Propagate API errors: Infrastructure failures like S3 timeouts correctly propagate as errors rather than silently using defaults

Examples​

String Defaults​

vars:
  bucket_name: !terraform.output s3 {{ .stack }} .bucket_name // "default-bucket"

If the s3 component isn't provisioned, bucket_name will be "default-bucket".

List Defaults​

vars:
  subnets: !terraform.state vpc {{ .stack }} .private_subnets // ["subnet-a", "subnet-b"]

If the vpc component isn't provisioned, subnets will be ["subnet-a", "subnet-b"].

Map Defaults​

vars:
  tags: !terraform.output 'common {{ .stack }} .tags // {"env": "dev", "team": "platform"}'

No Default (Error on Missing)​

vars:
  # This will error if vpc component isn't provisioned (expected behavior)
  vpc_id: !terraform.output vpc {{ .stack }} .vpc_id

Error Handling Behavior​

Migration​

No migration is required. Existing configurations that use YQ defaults will now work as expected. Configurations without defaults maintain their existing behavior.

Related Links​

• PR #1836: Fix YQ defaults for terraform.state/output YAML functions
• YAML Functions Documentation
• Terraform Output Function
• Terraform State Function

The Problem​

Your atmos.yaml is the control plane for everything Atmos does — stacks, components, commands, auth, toolchains, integrations. It's also the file where mistakes hide best:

• A typo like worfklows: is ignored without a warning, and the real setting silently keeps its default.
• Nothing in your editor tells you what keys exist, what type they expect, or what they mean.
• Configuration is spread across atmos.yaml, atmos.d/ fragments, and profiles — partial files that no hand-written schema handled.
• Hand-maintained schemas rot. Every release adds configuration options, and a schema updated by memory falls behind the moment someone forgets.

The Fix​

Atmos now ships a complete JSON Schema for atmos.yaml — and it's generated from the configuration code itself, on every change, enforced by CI. If a release adds a configuration option, the schema already models it. There is no separate document to remember to update, so it cannot drift from what Atmos actually reads.

The schema understands how real Atmos configurations are written:

• YAML functions are first-class. Where a section expects a map, the schema also accepts !include shared.yaml, !env, !exec, and every other function atmos.yaml supports — so dynamic configs validate cleanly.
• Fragments validate standalone. No field is required, so atmos.d/ files and profile fragments — which each carry only a slice of the configuration — pass on their own.
• Descriptions come from the source. Hover documentation in your editor is sourced from the same documentation the code carries.

How to Use It​

Validation now happens out of the box. With no configuration at all, atmos validate schema checks atmos.yaml, atmos.d/ fragments, and project-local profiles:

atmos validate schema

✓ Validated atmos.yaml
✓ Validated atmos.d/logs.yaml
✓ Validated profiles/dev/settings.yaml
✓ All schemas validated successfully

To validate just the CLI configuration, atmos config validate is a shorthand alias for atmos validate schema config, and exits non-zero on violations — handy for CI and pre-commit hooks. Symmetrically, atmos stack validate now aliases atmos validate stacks. Validation is also fast in large repositories: file matching no longer walks the whole tree for plain file names, so results stream immediately.

Print the schema for the exact Atmos version you're running with the new atmos config schema command — a sibling of atmos stack schema:

atmos config schema                     # print to stdout
atmos config schema atmos-config.json   # write to a file

For editor auto-completion and inline validation, add one comment to the top of atmos.yaml:

# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-config/1.0/atmos-config.json
base_path: "./"

The schema reaches every surface where you touch atmos.yaml: the experimental Atmos LSP server (atmos lsp start) now reports schema violations as inline diagnostics with line positions, and AI assistants connected through the Atmos MCP server get a new atmos_validate_schema tool alongside atmos_validate_stacks.

The floating URL above always tracks the latest release. Every release also publishes an immutable, version-pinned snapshot at https://atmos.tools/schemas/atmos/atmos-config/<atmos-version>/atmos-config.json, and a schemas.config entry in atmos.yaml lets you pin validation to a reviewed schema version or point it at your own:

schemas:
  config:
    schema: "https://atmos.tools/schemas/atmos/atmos-config/1.219.0/atmos-config.json"

See CLI Configuration Schemas for the full reference.

Get Involved​

Try atmos validate schema on your project and add the modeline to your atmos.yaml. If the schema rejects a configuration that Atmos accepts — or your editor's completions are missing something — open an issue; the generator makes those fixes one small change away. Join us in the Cloud Posse community to share feedback.

Faster installs without shared-state races​

Tool downloads, extraction, version markers, toolchain.lock.yaml, and .tool-versions are all coordinated with granular advisory locks. Independent tools continue in parallel, but operations that mutate the same cache asset, installation directory, or configuration file wait safely instead of corrupting one another. The locks work across separate Atmos processes as well as parallel workers in one process.

The progress display now keeps download totals visible on the right edge of the terminal and changes the active state to Verifying once the asset is available. Non-interactive output and the existing completed-result summary remain unchanged.

Configure concurrency​

Set the maximum number of simultaneous installs in atmos.yaml:

toolchain:
  max_concurrency: 4

Or override it for a single command:

atmos toolchain install --max-concurrency 8

Atmos rejects values lower than one. The command-line flag takes precedence over configuration.

Reliable signature verification​

Atmos also isolates its bootstrap verifier from concurrent use and retries only transient, pre-verdict verifier failures. Legacy releases that publish detached Cosign certificates and signatures are verified with the compatible Cosign v2 path; newer bundle-based verification continues to use the current verifier. Verification remains required—retries never treat an invalid signature or identity mismatch as success.

See the toolchain documentation for installation and configuration details.

Atmos now supports component mocks: literal, component-owned Terraform outputs that you enable explicitly with --use-mocks.

The problem: a small dependency can make a plan non-local​

Consider an app component that takes its VPC ID from a vpc component:

components:
  terraform:
    app:
      vars:
        vpc_id: !terraform.state vpc vpc_id

Normally, Atmos resolves that lookup from the VPC's real Terraform state. That is the right default for regular operations, but it can be inconvenient when you are developing the application configuration before the VPC exists, reviewing a change offline, or deliberately avoiding access to a remote backend.

The old choices were usually to provision the dependency first, change the consumer temporarily, or build an ad hoc fixture outside the component that owns the output. None of those makes the intended fake surface obvious.

The fix: declare the fake surface next to the producer​

Declare the outputs a Terraform component can stand in for under mocks:

components:
  terraform:
    vpc:
      mocks:
        vpc_id: vpc-local
        private_subnet_ids: [subnet-a, subnet-b]
        network:
          cidr: 10.0.0.0/16

    app:
      vars:
        vpc_id: !terraform.state vpc vpc_id
        private_subnet_id: !terraform.output vpc '.private_subnet_ids[0]'

Then choose the mock path at invocation time:

atmos describe component app -s dev --use-mocks
atmos terraform plan app -s dev --use-mocks

Both !terraform.state and !terraform.output resolve from vpc.mocks. The familiar output and YQ-expression syntax stays the same; only the source of the value changes.

This is intentionally a narrow model. There are no mock profiles, provider simulations, resource emulation, or consumer-side override DSLs. A component declares the broad fake output surface once, and the command makes an explicit decision to use it.

The advanced quick start uses this pattern for its first, state-free plan: its regional KMS, storage, and messaging components declare provider-shaped outputs, while its normal deploy continues to use real state.

What mock mode bypasses​

When a Terraform lookup is mocked, Atmos loads the referenced component's merged mocks map and evaluates the requested expression against it. It does not initialize Terraform, resolve the referenced component's credentials, read a backend, or populate the real-state lookup cache.

That makes mock mode useful for local plans and describe component output that should be independent of the remote dependency. It also means --use-mocks never silently falls back to real state: a missing mock map or output is an actionable error, not a surprise backend read.

Mock values themselves are literal. Atmos does not evaluate templates or YAML functions inside mocks, so a mock cannot accidentally call the real dependency it was meant to replace.

Guardrails keep normal operations normal​

Mocks are opt-in. Without --use-mocks, existing !terraform.state and !terraform.output behavior is unchanged.

The flag is supported by:

• atmos terraform plan
• atmos describe component

Mutating Terraform commands—including apply, deploy, and destroy—and Terraform passthrough commands reject it before stack resolution. --use-mocks also requires YAML function processing to remain enabled.

Because mocks follows normal component inheritance and deep-merge behavior, a base component can provide shared fixtures while a concrete component replaces only the outputs that differ.

Try it​

The repository includes a provider-free example with a producer, a consumer, the normal real-state flow, and the mocked flow:

cd examples/terraform-component-mocks

# Resolve app's VPC ID from the vpc mock, without creating state.
atmos terraform plan app -s dev --use-mocks

# Inspect the final component configuration with the same mock resolution.
atmos describe component app -s dev --use-mocks

For the normal path, create the producer's state and omit the flag:

atmos terraform apply vpc -s dev
atmos terraform plan app -s dev

Read more about !terraform.state and !terraform.output, or use the example as the smallest starting point for adding mocks to your own stack.

The Fix​

After Atmos installs and checksum-verifies a verifier binary, it now strips the macOS quarantine extended attributes (com.apple.quarantine, com.apple.provenance) and ad-hoc re-signs the binary — the same trick Homebrew uses for downloaded formula binaries. This only ever runs on binaries Atmos itself just downloaded into its own bootstrap path; a verifier already found on PATH is user-managed and already OS-trusted, so it's left untouched. On Linux and Windows, this is a no-op — only macOS re-validates trust on every exec.

How to Use It​

This is on by default (verifier_trust: auto) — most users won't need to touch it. To opt out entirely:

toolchain:
  verification:
    verifier_trust: disabled

See the toolchain verification docs for the full settings reference.

Get Involved​

Questions or feedback? Open an issue on GitHub or join the conversation in our community Slack.

The Fix​

atmos mcp add and atmos mcp remove manage mcp.servers in atmos.yaml directly — no YAML editing required. Two built-in presets skip the boilerplate entirely: self wires up Atmos's own MCP server, and atmos-pro wires up the Atmos Pro MCP server. Run atmos mcp add with no arguments at all and it defaults to atmos mcp add self, so the entire "let my AI assistant use Atmos" flow is one command.

On the other side, atmos mcp uninstall is the mirror image of the existing atmos mcp install — it removes servers from an AI client's config without touching atmos.yaml. add/remove manage the declarative source of truth; install/uninstall push and pull it to your client. They compose, but never step on each other.

atmos mcp list and atmos mcp status also now mention these commands directly instead of just saying "no servers configured," and nudge you to run atmos mcp add atmos-pro if Atmos Pro is already configured but its MCP server hasn't been added yet.

How to Use It​

# Let your AI assistant use Atmos's own tools -- writes mcp.servers.atmos,
# prompts to enable mcp.enabled if it's off, and installs into detected clients.
atmos mcp add self --install

# Add the Atmos Pro MCP server.
atmos mcp add atmos-pro

# Add an external server -- name and transport are inferred.
atmos mcp add "uvx awslabs.aws-documentation-mcp-server@latest"
atmos mcp add https://mcp.example.com/mcp --header "Authorization: Bearer ${TOKEN}"

# Remove a server, and uninstall it from wherever it was pushed.
atmos mcp remove aws-docs
atmos mcp uninstall aws-docs

See the MCP documentation for the full command reference and built-in preset details.

Get Involved​

Questions or feedback? Open an issue on GitHub or join the conversation in our community Slack.

The Problem​

ai.tools.enabled was designed for atmos ai chat/ask/exec — Atmos's own assistant deciding whether it's allowed to call tools during a conversation. atmos mcp start reused that same flag as a hard gate, even though the MCP server has nothing to do with Atmos's own chat loop: its only job is exposing Atmos tools to external clients like Claude Desktop or Cursor. mcp.enabled: true was already the explicit, purpose-built opt-in for that — requiring a second, differently-named flag on top of it just to get a non-empty server was pure friction, not safety.

The Fix​

atmos mcp start no longer checks ai.tools.enabled at all. Once mcp.enabled: true, tools register unconditionally — ai.tools.enabled now only governs atmos ai chat/ask/exec's own tool-use loop, which is what it was always meant for.

While in there, we also renamed three related settings for consistency. They're already nested under tools:, so the _tools suffix was redundant:

tools.allowed also picked up a second job. Previously it only skipped the confirmation prompt — every tool was still registered and callable, just some needed a "yes" first. Now, when non-empty, it also controls which tools exist at all: unlisted tools aren't registered, aren't visible in tools/list, and aren't offered to the AI. An empty or unset list still means "everything is registered, subject to normal confirmation rules" — unchanged.

How to Use It​

mcp:
  enabled: true

ai:
  enabled: true
  tools:
    # Optional -- omit entirely for a fully-populated MCP server.
    # When set, ONLY these are registered, and they skip confirmation:
    allowed:
      - atmos_describe_*
      - atmos_list_*
    blocked:
      - execute_bash_command

atmos mcp start

No ai.tools.enabled required.

Breaking Change​

tools.allowed_tools, tools.restricted_tools, and tools.blocked_tools are no longer read — there's no fallback or deprecation warning, just the new names. If your atmos.yaml sets any of these under ai.tools, rename them before upgrading. If you were relying on allowed_tools to skip confirmation for a subset of tools while still allowing everything else to run with a prompt, note the semantics changed: an unlisted tool is no longer registered at all. Move it to an empty allowed (or drop the list) and lean on restricted/blocked instead.

See AI Tools Configuration for the full reference.

Tags and labels give components that organizational context directly — components get both; auth identities and providers get tags — so you can select and act on infrastructure by what it is instead of by where you filed it.

The Problem​

A hierarchy can only organize infrastructure one way, but you need to operate on it along lines that hierarchy doesn't capture:

• A component's path describes its place in the tree, not what it is. It tells you the org, account, and region; it says nothing about tier, ownership, or compliance scope — and those apply across stacks and component types, not within one branch.
• That context ended up living outside the system instead of on the resource. A --query expression like .settings.tier == "network" encoded "tier-1" for one command; a hand-maintained --components list encoded it for another. Neither traveled with the component, and both went stale the moment something changed.
• The same gap showed up wherever Atmos manages many things. Components across every type (Terraform, Kubernetes, Helm, containers), plus auth identities and providers, all needed a way to carry their own organizational context instead of relying on someone remembering it.

The Fix​

Atmos now carries that organizational context as metadata, in two shapes:

• Tags — a simple list of words, for basic categorical membership. Filtering matches any of the given tags.
• Labels — a set of key-value pairs, for richer metadata. Filtering requires all of the given key=value pairs, the same semantics as a Kubernetes label selector.

components:
  terraform:
    vpc:
      metadata:
        tags: [production, networking, tier-1]
        labels:
          cost-center: platform
          compliance: sox

auth:
  providers:
    sso-prod:
      kind: aws/iam-identity-center
      start_url: https://my-org.awsapps.com/start
      tags: [production, aws, sso]

  identities:
    prod-admin:
      kind: aws/permission-set
      via:
        provider: sso-prod
      principal:
        name: AdministratorAccess
        account: {name: production}
      tags: [admin, production, elevated-access]

How to Use It​

Listing and filtering components:

atmos list components --tags production,tier-1
atmos list components --labels cost-center=platform,compliance=sox

Bulk operations — --tags/--labels compose with --all/--affected everywhere Atmos already supports bulk selection, across every component type:

atmos terraform apply --affected --tags production
atmos kubernetes apply --all --labels cost-center=platform
atmos helm apply --affected --tags production
atmos container up --all --tags production

Because this lives in the shared component registry (pkg/component), any component type — built-in or custom — that adopts the standard bulk-execution pattern gets --tags/--labels filtering automatically, with no per-type code.

The same filtering works for auth, since providers and identities are tagged the same way:

atmos auth list --tags production
atmos auth login --tags admin,production   # auto-selects if exactly one match, else prompts
atmos auth logout --tags production        # logs out every matching provider

Bridging into your modules — four new YAML functions read a component's own metadata.tags/metadata.labels without the usual !template/toJson boilerplate: !tags and !labels return the values directly, and !labels.keys/!labels.values return just the label map's keys or values. The most common use is feeding metadata.labels into the var.tags a terraform-null-label-style module expects (Terraform and AWS call a map "tags"; Atmos calls it a "label" — same data, different name):

components:
  terraform:
    vpc:
      metadata:
        labels:
          Namespace: eg
          Environment: prod
      vars:
        tags: !labels   # var.tags (map) <- metadata.labels

Get Involved​

Tags and labels are supported today on components across Terraform, Kubernetes, Helm, and container components; auth identities and providers support tags. Auto-discovering tags/labels from cloud provider metadata (for example, mapping AWS SSO PermissionSet tags into Atmos labels automatically) is a natural next step — if that's something you need, open an issue and let us know your use case.

That's fixed. Multi-file tools now install completely and actually run.

The Problem​

Atmos installed tools by copying just the entrypoints named in the registry's files: list out of the downloaded archive — and throwing the rest away. That works for a single self-contained binary like jq or terraform. It breaks for "onedir" bundles that ship a binary plus the files it needs at runtime:

• aws/aws-cli bundles its own Python runtime. Atmos kept aws and aws_completer and dropped the ~8,600 supporting files, including libpython. The install reported success, but the binary was dead on arrival (#2743).
• nodejs/node exposes npm, npx, and corepack as symlinks into a sibling lib/ tree, and publishes under a v-prefixed path. Atmos skipped the symlinks as an "unknown type" and looked for node-24.18.0-... instead of node-v24.18.0-..., so the install failed outright (#2744).

The Fix​

Atmos now mirrors how the upstream aqua CLI installs these packages:

• Preserves the whole archive for multi-file tools under a .pkg directory — so every executable stays next to the runtime files it needs — and records each entrypoint's real path in a small sidecar manifest, without creating any symlinks of its own (a design choice used consistently across Atmos).
• Keeps the archive's own symlink entrypoints (like npm → ../lib/node_modules/...) instead of dropping them.
• Resolves versions consistently, so a pinned 24.18.0 correctly finds the v24.18.0 archive that actually downloads.
• Fails honestly: a broken or incomplete extraction no longer reports success or leaves an orphaned binary behind.

Single-binary tools are completely unaffected — they keep the exact same flat layout as before.

How to Use It​

Nothing new to learn. Pin the tools and install:

atmos toolchain install aws/aws-cli@2.35.15
atmos toolchain install nodejs/node@24.18.0

$ aws --version
aws-cli/2.35.15 Python/3.14.5 Linux/... exe/x86_64
$ node --version
v24.18.0
$ npm --version
11.16.0

See How tools are installed on disk for details on the layout.

Get Involved​

Toolchain is an experimental feature and we're actively hardening it. If a tool doesn't install cleanly, please open an issue with the owner/repo and version — those reports are exactly what drove this fix.

The Problem​

This surfaced while migrating a Terragrunt Lambda example (Lambda + DynamoDB + IAM role) to Atmos. The source unit used a before_hook "package" wrapping scripts/package.sh, which itself wrapped the zip binary, before every plan/apply/destroy. Translating that directly meant an equivalent shell-based hook:

hooks:
  package:
    kind: command
    command: bash
    args: ["-c", "cd src && zip -r ../handler.zip . -x '*.test.js'"]
    events: [before.terraform.plan, before.terraform.apply, before.terraform.destroy]

Three problems with this, once you look past "it worked when I tested it":

• The invocation isn't even portable between macOS and Linux, let alone Windows. zip -x and tar --exclude take different glob syntax; BSD tar (what macOS ships) and GNU tar (most Linux CI images) disagree on flags like --exclude vs. -X excludefile. Two engineers on the same team can get different results running the "same" hook.
• Failures are opaque. A typo in a glob, a missing source directory — all of it surfaces as a shell exit code with no structure Atmos can validate ahead of time.
• The output isn't reproducible. Zip and tar both bake in each file's real modification time and permission bits. A fresh git clone sets every file's mtime to checkout time, and umask varies across machines and CI images — so identical source content produces a different archive on every rebuild. This is the same failure mode Terraform's own archive_file provider has been reported for over the years: two runs, same input, different checksum. Anything downstream that keys off the archive's hash — Lambda only redeploying when the zip's checksum changes, a build cache, a provenance check — sees a "change" that isn't one.

A data "archive_file" Terraform data source was tried first for the packaging step itself. It works fine when a config references the data source's own output attribute directly (output_path, output_base64sha256) — Terraform's graph orders that correctly. It broke here because the migrated module computed the zip path independently in a locals block, mirroring the original Terragrunt script's own variable, instead of referencing the data source's attribute — so there was no dependency edge forcing archive_file to run first. That's not a one-off: it's a documented class of bug, closed once the reporter switched to referencing the output attribute directly — the same fix this migration's module hadn't made. A before.terraform.* hook sidesteps the whole class of problem structurally — it runs and completes before Terraform's graph is even evaluated, so there's no reference to get wrong.

The Fix​

The new archive step type packages a directory or file into a zip, tar, or tgz archive using only Go's standard library — archive/zip, archive/tar, compress/gzip. No shelling out, so the same config produces the same archive structure everywhere Atmos runs:

steps:
  - name: package
    type: archive
    source: src/
    destination: handler.zip
    exclude:
      - "**/*.test.js"
      - "**/node_modules/**"

It has no dedicated hook kind — like every step type added since kind: step shipped, it reaches hooks through the same bridge, so it works as a lifecycle hook with zero extra plumbing:

hooks:
  package:
    kind: step
    type: archive
    events: [before.terraform.plan, before.terraform.apply, before.terraform.destroy]
    with:
      source: src/
      destination: handler.zip

How to Use It​

• source / destination — required. What to archive, and where to write it.
• format — zip, tar, tgz, tar.bz2, or tar.xz. Inferred from destination's extension when omitted (writing tar.bz2/tar.xz isn't implemented yet — see below).
• subpath — nests source's content under a path inside the archive, e.g. subpath: opt/nodejs for a Lambda Layer.
• include / exclude — glob filters, evaluated exclude-then-include.
• action — replace (default) always rebuilds the archive fresh from source. update adds/refreshes entries in an existing archive without touching the rest — supported for zip and uncompressed tar only, since tgz/tar.bz2/tar.xz compress the whole stream as one unit and can't be edited surgically. Selecting update on one of those formats fails with a clear error instead of silently falling back to a full rebuild.

create and extract are reserved in the schema for a future release, so it won't need a breaking change to add them later.

Reproducible Output​

A native step type fixes the shelling-out problems, but not the reproducibility one by itself — by default, entries still carry the source files' real mtime and permission bits (same as omitting the field, or setting it to filesystem explicitly). Set mtime: epoch or mtime: git to fix that too:

steps:
  - name: package
    type: archive
    source: src/
    destination: handler.zip
    mtime: epoch

mtime names the mechanism, not an outcome: it's the modification-time metadata stamped into each archive entry — not the source files on disk, and not the archive file's own OS-level mtime.

• filesystem — the default. Every entry carries the source file's real mtime and permission bits.
• epoch — every entry gets the same timestamp: the most recent Git commit that touched anything under source. One timestamp, whole archive. Named after the SOURCE_DATE_EPOCH reproducible-builds convention, which this mirrors conceptually — one shared reference timestamp for the whole build — even though the value here comes from Git history rather than an environment variable.
• git — each entry gets its own timestamp, from its most recent commit. Files with no Git history (build output, node_modules/) fall back to the same value epoch would use.

epoch and git both also normalize permission bits (0644, or 0755 if the source is executable), since inconsistent umask-derived permissions produce different archive bytes just as reliably as inconsistent timestamps do. Timestamps come from Git commit history via go-git — no shelling out to git log, and no dependency on SOURCE_DATE_EPOCH being threaded through every tool in the chain. Outside a Git repository, both modes fall back to a fixed reference date rather than failing the step. It's opt-in: existing workflows that don't set mtime see no change in behavior.

action: replace + mtime is idempotent — action: update is not. With replace, the same source produces the same bytes on every rerun, because replace always rebuilds from scratch. update doesn't get that guarantee even with mtime set: its existing entries keep whatever mtime/mode a prior write already gave them, and only the entries a given update call adds or refreshes get normalized — so the final bytes depend on the archive's history, not just source's current content. If you need the idempotent guarantee, use replace.

Get Involved​

See the archive step reference for the full field list, and the hooks reference for using it as a lifecycle hook. Questions or ideas? Join us in the Cloud Posse community Slack.

The Problem​

• JIT auto-provisioning and atmos vendor pull had two separate, non-overlapping implementations of "download a source." Only the vendor-pull one understood oci://.
• Registries publishing modules via OpenTofu's native "install modules from OCI registries" format ship their content as a ZIP-archive layer, not the tar+gzip layer Atmos expected. Pulling one failed with archive/tar: invalid tar header regardless of which path you used.
• OCI pulls also had no timeout, so a slow or unresponsive registry could hang a command indefinitely.

The Fix​

• The OCI-fetch implementation moved into a shared pkg/oci package so both atmos vendor pull and JIT auto-provisioning use the same implementation instead of two divergent ones.
• The puller now recognizes ZIP-layer OCI artifacts (OpenTofu's module-package format) in addition to Atmos's own tar+gzip format, with the same directory-traversal and decompression-size guards either way.
• OCI pulls are now bounded by a 10-minute timeout, matching the existing go-getter download path.

How to Use It​

components:
  terraform:
    my-component:
      source:
        uri: "oci://ghcr.io/my-org/my-module:v1.2.0"
      provision:
        workdir:
          enabled: true

Running atmos terraform plan my-component -s <stack> now auto-provisions the source before running, the same way it already does for git and HTTP sources.

Authentication works the same way it already does for atmos vendor pull: your existing registry credentials are picked up automatically, with an anonymous fallback if none are configured.

Get Involved​

See the Workdir Provisioning docs for the full provision.workdir reference, or open an issue if you hit an OCI registry format that still doesn't extract cleanly.

The Problem​

• Bulk execution flags --all and --affected landed on apply/plan/destroy when Terraform bulk execution moved onto the scheduler-backed dependency graph, but init was left out.
• Reinitializing every component after a provider upgrade, or bootstrapping a new environment, meant looping atmos terraform init <component> -s <stack> by hand.
• The scheduler also capped concurrency to 1 for any subcommand it didn't explicitly recognize, so there was no way to route around it either.

The Fix​

• terraform init now accepts --all, --affected, --max-concurrency, --failure-mode, and --log-order, matching destroy.
• Init keeps the natural forward dependency order — prerequisites before dependents — unlike destroy, which reverses the graph.
• Concurrent bulk init automatically disables the shared provider plugin cache for worker subprocesses, since sharing it isn't safe across concurrent terraform init runs.

How to Use It​

# Initialize every Terraform component, in dependency order
atmos terraform init --all -s prod

# Initialize only the affected components
atmos terraform init --affected

# Run independent components concurrently
atmos terraform init --all -s prod --max-concurrency 4

# Keep going past a failed component instead of stopping
atmos terraform init --all -s prod --failure-mode keep-going

Get Involved​

Have a bulk-execution flag you'd like to see on another command? Open an issue or join the discussion on GitHub.

The Fix​

A new command, atmos stack schema, prints the JSON Schema Atmos uses to validate stack manifests — the exact one built into the binary you're running, not a version fetched from the internet. Pass a path and it writes the schema to a file instead of stdout.

This is useful for:

• Offline/air-gapped environments — no network call needed, since the schema comes straight out of the binary already on disk.
• IDE setup — point your editor's YAML language server at a local file instead of a URL.
• Version certainty — the output always matches the atmos version you ran it with, so there's no risk of validating against a schema that's ahead of or behind your binary.

How to Use It​

# Print the schema to stdout.
atmos stack schema

# Write it to a file for your editor or CI to use.
atmos stack schema ./atmos-manifest.json

It lives under the existing atmos stack command group, alongside the other stack-manifest commands (get, set, delete, format, config).