The Problem​

When a run fails, the important question is usually not "what did the terminal print?" It is "what command ran, with which arguments, from which directory, for how long, and how did it exit?"

Humans can sometimes reconstruct that from logs. Agents and support tooling should not have to scrape terminal prose to find the root cause.

The Change​

Atmos now supports an opt-in diagnostics stream: machine-readable JSONL events written to a file.

diagnostics:
  enabled: true
  file: .atmos/diagnostics.jsonl
  include_output: false

The same settings can be controlled with environment variables:

ATMOS_DIAGNOSTICS_ENABLED=true \
ATMOS_DIAGNOSTICS_FILE=.atmos/diagnostics.jsonl \
atmos terraform plan vpc -s plat-ue2-dev

Because the output is JSONL, it is easy to inspect with tools like jq:

jq 'select(.type == "process.exit")' .atmos/diagnostics.jsonl

Diagnostics vs. Logging​

Logs are human-readable status and narrative output. They explain what Atmos is doing for someone watching the run.

Diagnostics are machine-readable event records for tooling, agents, and post-run inspection. They are designed to accelerate root-cause analysis by giving agents structured facts about subprocesses, exits, durations, cancellation, and failures without requiring them to parse terminal output.

diagnostics.include_output can include masked subprocess stdout and stderr chunks, but it is disabled by default. Diagnostic output is masked before it is written.

Why It Matters​

• Agentic troubleshooting gets faster. Agents can reason from structured events, identify the failing step, and move from diagnosis to remediation.
• CI artifacts become more useful. Save the JSONL file with a failed job and inspect it after the terminal session is gone.
• Logs stay for people. Diagnostics add a tooling-oriented layer without replacing human-readable logs.

Get Involved​

Enable diagnostics when you need a structured troubleshooting artifact, especially for CI and agent-driven workflows.

The Problem​

Many teams keep authentication, identity, terminal, and CI defaults in a central infrastructure repository. That works well for governance, but it creates friction for workload or app repositories: every repo needs the same profile definitions, and every update has to be copied everywhere.

That duplication is especially painful for auth profiles. The central platform team owns the provider and identity shape, while each app repository only wants to consume the right profile and add a small local override.

The Change​

Profile config files can now use import:, including remote imports. That means a profile in a workload or app repository can pull shared configuration from a central repository and then override only the local pieces it owns.

import:
  - "github.com/my-org/platform-atmos//profiles/shared-auth.yaml?ref=v1.4.0"

logs:
  level: Debug

settings:
  terminal:
    max_width: 140

The imported file provides the baseline. Values in the local profile are merged over it, so the workload repository can keep its local preferences without forking the shared auth profile.

Why It Matters​

• Centralize auth profiles. Platform teams can publish shared provider and identity configuration once.
• Keep app repos small. Workload or app repositories can consume the shared profile instead of duplicating it.
• Override locally when needed. Imported profile configuration is still just layered Atmos configuration, so local profile values win.

Get Involved​

See the profiles documentation for profile discovery, activation, and merge behavior.

The Problem​

Shell checks work until they have to be portable, readable, and friendly. A workflow might need vhs, ffmpeg, a generated config file, and a local output directory before the real work starts. Encoding that as inline shell makes the workflow harder to scan and usually produces a poor error when something is missing.

The Change​

Atmos now has a declarative require step type for workflow and custom command prerequisites. The assert step type is an alias for the same behavior.

steps:
  - name: require recording tools
    type: require
    tools:
      - vhs
      - ffmpeg
    files:
      - ./Taskfile.yml
    dirs:
      - ./demo
    hint: "on macOS run: brew install vhs ffmpeg"

The step checks that tools are executable on PATH, files exist, and directories exist. If anything is missing, Atmos fails fast with one aggregated error and the remediation hint.

Why It Matters​

• Prerequisites are visible. The workflow declares what it needs before the work starts.
• Errors are actionable. Missing tools and paths are reported together with a hint.
• It is read-only. require never installs tools and never mutates PATH; use dependencies.tools when you want Atmos to manage tool installation.

Get Involved​

See the require step reference for all supported fields and examples.

The Problem​

Some Atmos commands produce rich, multi-line output that is useful in a real terminal but awkward in demos, docs, and recorded walkthroughs. When everything appears at once, important transitions are easy to miss.

That is especially noticeable with VHS recordings and scripted demos, where readable pacing matters as much as the final output.

The Change​

Atmos now supports settings.terminal.speed, also available as ATMOS_TERMINAL_SPEED, to pace terminal output by lines per second.

settings:
  terminal:
    speed: 18

ATMOS_TERMINAL_SPEED=18 atmos describe stacks

A value of 0 keeps the existing unlimited output behavior. That is the default, so normal interactive and CI usage does not change unless you opt in.

Why It Matters​

• Better recordings. Output appears at a readable pace for demos, tutorials, and screengrabs.
• No command rewrites. Keep the same Atmos command and control pacing through config or an environment variable.
• Default behavior is unchanged. Unlimited output remains the default.

Get Involved​

See the terminal settings documentation for the full terminal configuration reference.

What Changed​

kind: step runs one registered step type as a lifecycle hook. kind: steps runs several registered step types in order:

hooks:
  test-fixtures-up:
    events: [before.terraform.test]
    kind: steps
    on_failure: fail
    with:
      - type: emulator
        component: aws
        stack: fixtures
        action: up

      - type: atmos
        command: terraform apply vpc -s fixtures -auto-approve

The hook envelope stays the same: events, when, on_failure, retry, and env are still hook-level controls. The ordered payload lives under with:, the same conventional payload key used by kind: step.

Why This Matters​

Some test fixtures need real lifecycle ordering. For example, a component test may need a local AWS emulator before it can provision a VPC fixture, and the fixture must be destroyed after the test even if the test fails.

Before kind: steps, the choices were awkward:

• split the lifecycle across multiple hooks and rely on unordered map iteration,
• move component-specific fixture setup into a custom command or workflow, or
• fall back to a helper script.

kind: steps keeps the fixture lifecycle declarative and component-local:

hooks:
  test-fixtures-up:
    events: [before.terraform.test]
    kind: steps
    on_failure: fail
    with:
      - type: emulator
        component: aws
        stack: fixtures
        action: up
      - type: atmos
        command: terraform apply vpc -s fixtures -auto-approve

  test-fixtures-down:
    events: [after.terraform.test]
    when: always
    kind: steps
    with:
      - type: atmos
        command: terraform destroy vpc -s fixtures -auto-approve
      - type: emulator
        component: aws
        stack: fixtures
        action: down

Steps run in list order. If a step fails, Atmos stops the list and applies the hook's on_failure policy. A hook-level retry retries the whole ordered list.

For Terraform tests, Atmos still owns the normal component preparation. It generates the tested component varfile from the selected stack and can pass a second generated test varfile from test.vars. Because test.vars resolves after before.terraform.test hooks run, it can use !terraform.state to pass fixture outputs into Terraform test without scripts.

Learn More​

See the Hooks reference for the full kind: steps syntax.

What Changed​

Two things came together:

1. Flags are now template variables. When a custom command declares flags, each one is exposed to its steps as {{ .Flags.<name> }}. Step titles, shell commands, working directories, and table data all resolve those values.
2. table steps are fully templated. A table step's title, columns, and every cell in data are rendered as Go templates, so the table content can depend on flags and other step variables.

How to Use It​

Here's a real example now shipping in examples/demo-stacks — a platform command group whose subcommands take a --stack flag and build their output from it:

commands:
  - name: platform
    description: Platform team shortcuts for stack discovery and day-two commands.
    commands:
      - name: status
        description: Show stacks, components, and common next actions for one stack.
        flags:
          - name: stack
            shorthand: s
            description: Target stack.
            required: true
        steps:
          - type: stage
            title: Components in {{ .Flags.stack }}
          - type: shell
            command: atmos list components -s {{ .Flags.stack }}
          - type: table
            title: Platform commands
            columns:
              - task
              - command
            data:
              - task: Show variables
                command: atmos list vars myapp -s {{ .Flags.stack }}
              - task: Plan affected
                command: atmos terraform plan --affected

Run it like any other command:

atmos platform status -s plat-ue2-dev

Every {{ .Flags.stack }} resolves to plat-ue2-dev, the stage titles and table rows fill in, and the shell steps run against the right stack.

Why It Matters​

• Build your own shortcuts. Wrap your team's day-two operations — discovery, planning, secret access — into named commands that adapt to their flags.
• Rich output without scripts. Tables, staged sections, and dynamic titles are declared in YAML, not hand-rolled in bash with printf and column.
• Consistent across workflows and custom commands. The same step library powers both, so what you learn in one applies to the other.

Get Involved​

See the workflow step types and the table step reference to start building. Share what you create with the Atmos community.

The Problem​

As infrastructure grows, the relationships between components matter as much as the components themselves. A vpc is a prerequisite for the eks cluster, which is a prerequisite for the alb-controller, and so on. Until now, answering "what would break if I change this?" or "what has to exist before I deploy that?" meant reading atmos describe dependents for one component at a time and stitching the picture together in your head.

The Solution​

atmos list dependencies gives you the whole graph at a glance, as a tree:

atmos list dependencies

Tree output keeps stack context next to the component hierarchy, with component type as secondary metadata on the right:

Dependencies
Stack         Component                 Type
plat-ue2-dev  app-config                terraform
              ├──depends on ↓
              │  ├──▶ dynamodb-table
              │  └──▶ kms-key
              └──required by ↑
                 └──(none)

Triangle markers show edge direction: ▶ means the component depends on that child, and ◀ means that child depends on the selected component.

By default it walks every component and renders both directions — prerequisites and dependents. Scope it to a stack, focus on a single component, pick a direction, or emit structured data instead:

# Limit to one stack
atmos list dependencies --stack plat-ue2-dev

# Focus on a single component in a stack
atmos list dependencies vpc --stack plat-ue2-dev

# Only what the component depends on (its prerequisites)
atmos list dependencies vpc --stack plat-ue2-dev --direction forward

# Only what depends on the component (its dependents)
atmos list dependencies vpc --stack plat-ue2-dev --direction reverse

# Machine-readable output for scripts and CI
atmos list dependencies --format json

Why It Matters​

• See blast radius before you change anything. --direction reverse answers "what depends on this?" so you know what a change could affect.
• Understand deployment order. --direction forward shows prerequisites, so you know what must exist first.
• Consistent with the rest of Atmos. Dependencies come from the same dependencies.components / settings.depends_on sources used by atmos describe dependents, so the tree never contradicts your CI change-detection.

Get Involved​

See the atmos list dependencies reference for all flags and output formats. As always, feedback and ideas are welcome in the Atmos community.

What Changed​

Previously, installing an Atmos skill meant fetching it from a GitHub repository. But this also meant that the skills could be out of sync with the version of Atmos that you're running.

Now the complete catalog of official skills (and their reference files) ships inside the binary via an embedded filesystem. Two user-facing improvements fall out of that:

• Offline install by name. atmos ai skill install atmos-terraform copies the skill straight out of the binary — instant, deterministic, and air-gap friendly. Community skills can still be installed from any GitHub repository.
• A unified available-vs-installed listing. atmos ai skill list merges the bundled catalog with what's installed locally, alphabetically sorted, with a status marker per skill (● installed, ○ available).

How to Use It​

# Browse everything — bundled catalog plus anything you've installed
atmos ai skill list

# Show only what's installed
atmos ai skill list --installed

# More detail per skill
atmos ai skill list --detailed

# Install an official skill offline, by its bare name
atmos ai skill install atmos-terraform

The --installed view is also bound to ATMOS_AI_SKILL_INSTALLED for scripting. Once a skill is installed, use it with any command via the global --skill flag (with --ai):

atmos terraform plan vpc -s plat-ue2-prod --ai --skill atmos-terraform

Why It Matters​

• Works anywhere. No network or Git access required to install the official skills — ideal for locked-down CI runners and air-gapped environments.
• Discoverable. One command shows the full catalog and your install state together, instead of guessing what's available.
• Versioned with Atmos. The bundled skills travel with the binary, so the catalog always matches the Atmos you're running.

Get Involved​

See the atmos ai skill command reference and the Agent Skills guide. Skill ideas and contributions are welcome in the Atmos community.

The Problem​

Plenty of workflows need a service running alongside the steps, not as a step. End-to-end tests need a cloud emulator. Integration steps need a database or a local registry. Until now, standing up that dependency meant leaving the workflow and dropping into shell:

docker run -d --name emulator -p 4566:4566 localstack/localstack
until curl -sf http://localhost:4566/_localstack/health; do sleep 2; done
# ... run the real steps ...
docker rm -f emulator

That works until it doesn't:

• Readiness is a hand-rolled until curl … sleep loop that's different in every workflow.
• A failed or interrupted run leaks the container — the cleanup line never runs.
• The dependency is invisible in the workflow file; it lives in shell glue.
• Local workflows and CI drift apart because each reinvents the same bring-up dance.

A workflow runner should be able to say "start this service, wait until it's healthy, run my steps, then clean it up" as part of the workflow itself.

What's New​

A container step with background: true starts a long-running service detached and lets the workflow continue. Three pieces work together:

• background: true on an action: run step starts the service detached.
• healthcheck (under with:) gates readiness — Atmos blocks until the container is healthy before the next step runs.
• cancel stops and removes the service; if you never cancel it, Atmos tears it down automatically when the workflow ends.

There are also two readiness-gating control steps: wait blocks on named services, and wait-all blocks on every background service started so far.

A Background Emulator​

Start an emulator, run Terraform against it, then tear it down — all in one declarative workflow:

workflows:
  e2e:
    steps:
      - name: emulator
        type: container
        action: run
        background: true
        with:
          image: localstack/localstack
          ports:
            - host: 4566
              container: 4566
          healthcheck:
            test: ["CMD", "curl", "-f", "http://localhost:4566/_localstack/health"]
            interval: 5s
            retries: 10
            start_period: 30s

      - name: apply
        type: atmos
        command: terraform apply vpc -s dev

      - type: cancel
        for: emulator

Atmos starts the emulator, blocks until its health check reports healthy, runs apply, then cancel stops and removes the container.

Readiness Reuses the Health Check​

The key idea is that readiness is not a new concept — it's the container's own healthcheck, the same shape you already use for container components. When a background service declares a health check, Atmos blocks until it's healthy before continuing. No sleep guesses, no polling scripts.

For a service, "wait" means until healthy, never until exit. A long-running service never exits on its own, so its health check defines readiness. You can gate readiness implicitly (the step after a healthchecked background service waits automatically) or explicitly with a wait step:

- type: wait
  for: [emulator]

Start several services and wait for all of them at once with wait-all:

- type: wait-all

The ordinary needs field is unchanged — it expresses step ordering, while wait/wait-all express service readiness.

Teardown You Don't Have to Remember​

The most common shell-script bug is the cleanup line that never runs. Background services fix that by default: if you never cancel a service explicitly, Atmos tears down all background services when the workflow ends — including on failure. A crashed or short-circuited workflow does not leave orphaned containers behind.

Use cancel when you want to free a service early, before the rest of the workflow finishes, or simply to make teardown explicit in the file:

- type: cancel
  for: emulator

Why This Matters​

Background services turn "stand up a dependency for these steps" into a first-class, declarative part of the workflow:

• Readiness is the container health check, not a bespoke polling loop.
• Teardown is automatic, so failed runs don't leak containers.
• The dependency is visible in the workflow file, not hidden in shell glue.
• The same workflow runs locally, in CI, or inside a larger runbook.

This is especially useful for end-to-end tests against emulators, integration steps that need a database or registry, and any workflow where a service has to be up while the real work runs.

Get Involved​

For the full reference, see background services on the container step page, and the wait and cancel step types. Try it on a real end-to-end workflow and tell us where the readiness and teardown semantics feel right — or where you want more control.

The Problem​

A meaningful Terraform test applies resources and asserts on the result:

run "provisions_resources_against_emulator" {
  command = apply

  assert {
    condition     = output.bucket_id == "atmos-demo-test"
    error_message = "The S3 bucket was not created"
  }
}

Because command = apply provisions for real, this almost never runs locally. It needs cloud credentials, it costs money, and it leaves residue you have to clean up. So the most valuable tests — the ones that actually create infrastructure — rarely run until CI, against a real account.

The Solution​

Atmos emulators provide a local, containerized stand-in for AWS (and GCP, Azure, and more). Bind a component to an aws/emulator identity and Atmos wires the AWS provider — endpoint, dummy credentials, path-style S3, skip-flags — into every Terraform run, including terraform test. Your component code doesn't change between local and real cloud:

atmos terraform test app -s fixtures

That's it. The component hook starts the emulator, applies the fixture VPC, the apply run blocks create the app resources against that VPC, and everything is torn down — no AWS account, no credentials, no providers.tf.

Lifecycle Hooks Bring Fixtures Up and Down​

You don't even start the emulator or provision fixtures yourself. The component declares ordered lifecycle hooks using kind: steps, bound to the new before.terraform.test and after.terraform.test events:

components:
  terraform:
    app:
      hooks:
        test-fixtures-up:
          kind: steps
          on_failure: fail
          events: [before.terraform.test]
          with:
            - type: emulator
              component: aws
              action: up
            - type: atmos
              command: terraform apply vpc -s fixtures -auto-approve

        test-fixtures-down:
          kind: steps
          events: [after.terraform.test]
          when: always
          with:
            - type: atmos
              command: terraform destroy vpc -s fixtures -auto-approve
            - type: emulator
              component: aws
              action: down

atmos terraform test fires these hooks around the run: the emulator comes up, the fixture VPC is applied, the app test uses that VPC, and when: always guarantees teardown even when a test fails. The app component owns its test fixture lifecycle without scripts or a custom command wrapper.

When a test needs fixture outputs, define them under the component's test.vars. Atmos resolves those values after the setup hook, so test.vars can use !terraform.state to read the fixture VPC ID and pass it into .tftest.hcl as a declared Terraform test variable.

In CI: Test Summaries​

terraform test now plugs into Atmos's native-CI reporting, the same path as plan and apply. Turn it on in atmos.yaml — ci.enabled is the master switch:

ci:
  enabled: true
  summary:
    enabled: true

In a GitHub Actions job, a passing or failing step summary is then written to the job summary — per-run pass / fail / skip results, with the failing assertions inlined — so you see what broke without digging through logs.

Why This Matters​

• Run the valuable tests locally. Apply-backed assertions — the ones that actually create infrastructure — run on a laptop in seconds, for free.
• Hermetic and repeatable. No shared account, no drift, no cleanup. Every run starts from a clean sandbox.
• Identical config everywhere. Because the emulator is bound through Atmos identity and provider generation, the component is byte-for-byte the same locally and in CI.

Get Involved​

Try the terraform-tests example, read the emulator component reference, and see the original emulators announcement for the bigger picture. A container runtime (Docker or Podman) is the only prerequisite.

This is the stack-scoped counterpart to the native container steps shipped earlier. The step is ephemeral and workflow-scoped; the component is addressable infrastructure that lives in your stacks alongside Terraform and Helmfile — same imports, inheritance, catalogs, deep-merge, templating, and secrets.

One Component, One Container​

Container components use first-class sections (image, build, run) — consistent with the container step, NOT nested under vars:

components:
  container:
    api:
      composition: storefront            # composition membership (optional)
      image: nginx:alpine
      env:
        NGINX_ENTRYPOINT_QUIET_LOGS: "1"
      run:
        ports:
          - host: 8080
            container: 80
        restart:
          policy: unless-stopped         # Docker Compose-style restart policy
        healthcheck:                      # first-class health check
          test: ["CMD-SHELL", "wget -q -O /dev/null http://localhost/ || exit 1"]
          interval: 30s
          timeout: 5s
          retries: 3
          start_period: 10s

build, run.command, mounts, ports, user, restart, and healthcheck all map onto the Docker Compose shapes you already know. Inheritance (metadata.inherits), abstract base components, catalogs, and deep-merge work exactly like every other component kind, so shared run/build defaults live in one place.

Operated by Labels, Not State Files​

Each instance is named and labeled from its canonical address <stack>/container/<component> (e.g., atmos-dev-container-api). Lifecycle commands discover the container by label — there are no local state files to drift or lose:

atmos container build api -s dev      # build the image from `build`
atmos container up api -s dev         # create/start the long-running container (build-on-missing)
atmos container list                  # all container components + running/health state
atmos container ps|logs|exec api -s dev
atmos container down api -s dev       # stop + rm

Compositions​

A composition groups components into a system. Declare membership on the component with the composition field; the top-level compositions section declares the closed set of services:

compositions:
  storefront:
    description: Storefront system
    services: [api, worker, database]

Run atmos composition validate storefront -s dev to see which declared services are fulfilled vs. not yet provided in a given stack — a closed contract for membership, open for fulfillment.

Try It​

The new examples/container-component example defines an abstract base, a long-running web service with a health check, and a built-from-Dockerfile worker — all under one composition:

cd examples/container-component
atmos container up api -s local
atmos container list

Container components are experimental while the surface settles. The goal is unchanged: run the same declared system locally, in CI, and against real environments — without one-off shell scripts.

What Changed​

Until now, a hook's kind selected from a fixed list — store, command, infracost, checkov, kics, trivy, git. Anything else meant falling back to kind: command and hand-rolling a shell invocation. Every new capability meant a new hook kind.

kind: step removes that ceiling. Instead of growing the hook-kind list one tool at a time, hooks now reach the entire step library:

hooks:
  notify-slack:
    kind: step
    type: http                 # any registered step type
    events: [after-terraform-apply]
    on_failure: warn           # warn | fail | ignore
    retry:
      max_attempts: 3
    with:                      # the step's own parameters
      url: https://hooks.slack.com/services/XXX
      method: POST
      body: '{"text": "Deployed {{ .atmos_component }} to {{ .stack }}"}'

The split is deliberate: the envelope (kind, type, events, on_failure, retry, env) is what the hook runner interprets; with: is the step's own parameter block, written exactly as you'd write it in a workflow. on_failure and retry are applied around the step — the step never sees them.

Why This Matters​

You already describe a lot of automation as steps. Reusing those steps as lifecycle hooks means one mental model and zero duplication:

# Build and push an image after apply — retried, non-blocking.
hooks:
  publish-image:
    kind: step
    type: container
    action: build
    events: [after-terraform-apply]
    on_failure: warn
    with:
      context: .
      tags: [example:latest]

Values inside with: are rendered with the standard hook template context and YAML functions, so {{ .atmos_component }} and !store ... work there. Each step receives the usual ATMOS_* environment (ATMOS_STACK, ATMOS_COMPONENT, ATMOS_COMPONENT_PATH, …) plus any env: you add.

Announce Success — or Failure​

Hooks can now react to the operation's outcome. By default an after-* hook runs only on success (so a store hook never writes outputs after a failed apply), but when: failure / when: always opt in to failures — and the outcome, component, and stack are all available to the step:

hooks:
  announce:
    kind: step
    type: say                 # (or http/toast)
    events: [after-terraform-apply]
    when: always
    with:
      message: >-
        The {{ .atmos_component }} component in the {{ .stack }} stack
        {{ if eq .status "failure" }}failed{{ else }}deployed{{ end }}

The same values are exported as ATMOS_HOOK_STATUS, ATMOS_HOOK_EXIT_CODE, ATMOS_HOOK_ERROR, ATMOS_COMPONENT, and ATMOS_STACK for steps that read the environment. Under the hood, user hooks now fire on the failure path too — not just on success — so "deployment failed" announcements actually reach you.

How to Use It​

1. Set kind: step and a type: naming any registered step type.
2. Put the step's parameters under with:.
3. Use events: to choose when it fires, on_failure: for warn/fail/ignore, and retry: to wrap the step in Atmos's retry policy.

A typo'd type: fails the preflight check before Terraform runs, so you find out immediately. All step types are available, including interactive ones — whether an interactive step makes sense on a (usually headless) lifecycle event is the step's responsibility, not the hook's.

Get Involved​

See the Hooks reference for the full kind: step documentation, and the step types reference for the available steps.

The Problem​

Iterating on a Terraform component is always coupled to something real:

• A real account. You can't apply without one, so even a small experiment starts with a prerequisites checklist.
• Real money and real risk. Standing resources up and tearing them down to test a change costs money, and a mistake touches a live account.
• Onboarding friction. A new contributor can't run the tutorial — or reproduce a bug — without first being granted access to your infrastructure.
• The enterprise permission wall. In many organizations developers simply aren't allowed near the cloud environment. Local iteration isn't slow for them; it's impossible.

Application developers reach for local databases, mock servers, and emulators to iterate without touching production — but those conveniences never really existed the same way for infrastructure. That was true until emulators became first class in Atmos.

The Solution​

An emulator is a new Atmos component kind. You declare it in a stack and drive it with the new atmos emulator command:

atmos emulator up aws -s local              # start a local AWS emulator
atmos terraform apply s3-bucket -s local    # apply real Terraform against it — no AWS account
atmos emulator down aws -s local            # stop it (state is kept by default)

Atmos wires the emulator into the rest of the system automatically:

• No credentials. Atmos binds a local identity to the emulator and points both in-process cloud calls and the Terraform provider at the emulator endpoint — so the same stacks that target real AWS run unmodified against the emulator.
• The same stacks everywhere. Because the emulator is bound through Atmos identity and provider generation, your component code doesn't change between local and real cloud — laptop and CI run the identical configuration.
• Persistent by default. State survives down/up; atmos emulator reset wipes it, and --ephemeral opts out per run.

You can apply, destroy, and re-apply against a local cloud in seconds, without touching an account or spending money — and without waiting on anyone to grant you access.

Supported Emulators​

Built-in drivers cover the major clouds and the backing services your stacks lean on. The driver field on the component selects the image and target:

The defaults are deliberately the free, open-source options (floci/aws, openbao) — reach for localstack/aws or vault only when you specifically need them. See the emulator component reference for the full matrix, ports, and per-driver details.

What Emulators Are — and Aren't​

Emulators are built for the happy path — the common control-plane API surface your stacks actually exercise. That's where they shine, and for most local development and onboarding it's all you need. But it's worth being clear about what they are not:

• They're not bug-for-bug clones of the real clouds. Edge cases, eventual-consistency quirks, and the long tail of services and IAM nuances won't all be reproduced.
• They're not a substitute for a real pre-prod environment. Validate against a real account before production — emulators raise your confidence locally; they don't replace staging.
• Fidelity varies by service. The more exotic the resource, the more likely you'll hit an unimplemented corner.

The point isn't 100% fidelity — it's being able to iterate quickly, for free, without cloud access, on the work you do every day.

Try It: the Advanced Quick Start​

The advanced quick start now deploys a real event-driven AWS backend — a KMS key, an encrypted S3 bucket, a DynamoDB table, an SNS topic, an SQS queue, and an SSM Parameter Store config — entirely on your laptop, start to finish, with no AWS account and no credentials.

Persistence and Reset​

Emulators persist their state by default. Atmos bind-mounts a per-instance host directory under the XDG cache ($XDG_CACHE_HOME/atmos/emulator/<instance>) onto each emulator's data directory, so resources, images, clusters, and secrets all survive a restart:

atmos emulator up registry -s local      # start the registry
# ... push images ...
atmos emulator down registry -s local    # stop it — state is kept
atmos emulator up registry -s local      # back up — your images are still there

Use reset for a clean slate, or --ephemeral for a throwaway instance that never persists:

atmos emulator reset registry -s local --force
atmos emulator up registry -s local --ephemeral

How to Use It​

• atmos emulator up <component> -s <stack> to start an emulator, then run your normal atmos terraform … commands against it.
• atmos emulator ps, logs, and exec to inspect a running emulator (it outlives the atmos process and is rediscovered by label — no local state files).
• atmos emulator reset <component> -s <stack> to wipe persisted state.
• --ephemeral (or ephemeral: true on the component) for a throwaway instance.

See the emulator component reference and the atmos emulator command docs for details.

What's New​

• atmos emulator list renders every emulator across your stacks in a clean table — a status dot, the image, and the container ID — so you can see what's running at a glance. Scope it to a single stack with --stack, or omit it to list everything. See the atmos emulator list reference.
• Ready-to-run examples. Two new examples let you try emulators without assembling a stack yourself: examples/emulator-aws brings up a local AWS environment, and examples/emulator-k8s brings up a local Kubernetes (k3s) cluster and deploys into it.

What Changed​

Two pieces landed together:

• Planfile storage that works in GitHub Actions. The github/artifacts store talks to the GitHub Actions Artifacts API directly — including the runtime download path, so a planfile uploaded by a plan job can be consumed by a separate deploy job in the same run. (S3 and local stores work too.)
• Automatic, configurable drift verification on deploy. When planfile storage is configured and you run atmos terraform deploy --ci, Atmos downloads the stored plan, generates a fresh plan against current state, compares them with a JSON-structural plan-diff, and:
  • fail (default under CI): blocks the deploy on drift,
  • warn: logs the drift but proceeds,
  • off: skips verification entirely.
• A defined answer for "no stored plan found." verify covers the case where a stored plan exists but differs. A companion required boolean covers whether a stored plan must exist to verify against — previously a silent fresh apply. It defaults to tracking verify strictness, so a fail-by-default CI deploy now fails loudly instead of quietly applying something unverified. That means a green deploy actually proves verification ran — no log-scraping required.

Configure it once:

components:
  terraform:
    planfiles:
      verify: fail        # drift: stored plan exists but differs (fail | warn | off)
      required: true      # must a reviewed stored plan exist? (defaults to tracking `verify`)
      priority: [github]
      stores:
        github:
          type: github/artifacts

Override per run with --verify-plan / --verify-plan=false (CLI beats config beats the CI default). And because CI is auto-detected (CI / GITHUB_ACTIONS), the --ci flag is optional in a real pipeline — atmos terraform deploy mycomponent -s prod behaves natively and exits non-zero on drift or a missing plan, so your workflow asserts via exit codes instead of grepping logs.

Why This Matters​

The gap between "the plan you reviewed" and "what actually gets applied" is where infrastructure surprises live.

Reconcile, don't replay​

By default deploy doesn't replay the stored planfile. It re-plans, checks the fresh plan against the one you reviewed, and applies the fresh plan only if they match.

Why not just apply the stored plan directly? A saved plan is brittle. It goes stale the moment the state changes — which, between a PR and its merge, it usually has. And while Terraform bakes the assumed role into the plan, the base credentials that authenticate (and assume that role) come from the apply environment, not the plan — so a plan built on the PR can fail to apply on merge. Re-planning at apply time uses the current state and the apply-time credentials; the diff still proves nothing changed since review.

Want byte-for-byte replay anyway? Use deploy --from-plan (or apply --planfile).

Why a naive diff doesn't work​

A planfile is a frozen snapshot — but the plan it represents never really is. Between review and apply the details shift: values "known after apply," computed fields, hashes, ordering, timestamps. You adjust course as you go without changing what you set out to do. A byte-for-byte comparison can't tell the difference — it flags every shift as drift, so a plan that's still doing exactly what you reviewed gets rejected. Terraform's own saved-plan apply is stricter still: any movement in state lineage invalidates the snapshot outright, even when the substance hasn't changed.

That's the real-world problem: rigid checks make a plan go invalid long before it goes wrong. Useful verification needs wiggle room — tolerate the benign shifts, catch the real ones.

Atmos's verification is semantic, not naive. It parses both plans to JSON, normalizes the noise (sorted keys, masked secrets, computed-hash attributes, data-source reads), and compares what matters. So it flags a resource added, removed, or substantively changed — while letting the incidental variation slide. That's what makes plan-then-deploy practical.

Verification lives on deploy, not apply, by construction: deploy runs a discrete plan step as part of the command, capturing a fresh plan to diff the stored one against. apply doesn't capture that separate planfile — it applies a plan you pass, or plans-and-applies in one step like terraform apply — so it stays a thin, predictable wrapper.

How to Use It​

Inside GitHub Actions, the github/artifacts store needs the runner's runtime credentials (ACTIONS_RUNTIME_TOKEN / ACTIONS_RESULTS_URL), which GitHub withholds from run: steps. Surface them once with the in-repo github-runtime action:

steps:
  - uses: cloudposse/atmos/actions/github-runtime@v1
    with:
      mode: env
  - run: atmos terraform plan mycomponent -s prod --ci    # uploads the planfile
  - run: atmos terraform deploy mycomponent -s prod --ci   # downloads, verifies, applies

See Planfile Storage, Planfile drift verification, and atmos terraform deploy.

Get Involved​

Planfile storage is evolving — try it in your pipelines and tell us how the fail / warn / off semantics fit your workflow. Open an issue or discussion on GitHub.

The Problem​

Calling an external endpoint from a workflow used to mean a shell step running curl:

steps:
  - type: shell
    command: |
      curl -sf -X POST "https://ci.example.com/hook" \
        -H "Authorization: Bearer $TOKEN" \
        -d '{"status":"deployed"}'

That works until it doesn't: curl isn't guaranteed to be on the box (especially on Windows), quoting and templating the payload is fiddly, and you get no first-class handling of timeouts or transient failures. Retrying a flaky 5xx meant hand-rolling a bash loop.

The Solution​

The http step makes HTTP a first-class citizen:

workflows:
  notify:
    steps:
      - name: trigger
        type: http
        url: "https://ci.example.com/hook/{{ .env.JOB_ID }}"
        method: POST
        query:
          ref: "{{ .env.GIT_SHA }}"
        headers:
          Authorization: "Bearer {{ .env.TOKEN }}"
          Content-Type: application/json
        body: '{"status":"deployed"}'
        expect:
          status: [200, 201, 202, 204]
          response:
            - /"status"\s*:\s*"deployed"/
        timeout: 30s
        retry:
          max_attempts: 5
          backoff_strategy: exponential
          initial_delay: 1s
          max_delay: 30s

      - name: report
        type: info
        content: "Endpoint returned HTTP {{ .steps.trigger.metadata.status_code }}"

Everything templates, including the URL, headers, query params, and body — so you can thread values from earlier steps or the environment straight into the request.

Sending Parameters​

You asked for full parameter support, and it's all here:

• Verb — method: accepts GET (default), POST, PUT, PATCH, DELETE, HEAD, and OPTIONS.
• Query-string parameters — query: is a key-value map appended to the URL.
• POST parameters — use body: for a raw payload, or form: for a key-value map. form is sent as application/x-www-form-urlencoded by default, or as a JSON object when you set a JSON Content-Type:

steps:
  - name: notify-slack
    type: http
    url: "{{ .env.SLACK_WEBHOOK_URL }}"
    method: POST
    headers:
      Content-Type: application/json
    form:
      text: "Deployment complete"

Timeouts and Retries That Compose​

timeout is the per-attempt deadline. retry is the same retry block you already use on shell and atmos steps — and the http step is HTTP-aware about what's worth retrying:

• Retried by default: transport/network errors, 5xx, and 429 Too Many Requests.
• Fail fast: other 4xx responses (a 404 won't burn through five attempts).
• Your call: retry.conditions regexes (matched against "<status> <body>") let you retry additional cases, and expect.status / expect.response define exactly what counts as success.

This makes the step a natural fit for polling, too — GET a health endpoint and retry until the body matches:

steps:
  - name: health
    type: http
    url: "{{ .env.HEALTH_URL }}"
    expect:
      status: [200]
      response:
        - /"status"\s*:\s*"(ok|healthy)"/
    retry:
      max_attempts: 10
      backoff_strategy: constant
      initial_delay: 2s

Using the Response​

The response body becomes the step's value, and useful details land in metadata:

• {{ .steps.<name>.value }} — the response body
• {{ .steps.<name>.metadata.status_code }} — the numeric status code
• {{ .steps.<name>.metadata.status }} — the status text (e.g., 200 OK)
• {{ .steps.<name>.metadata.response_headers }} — response headers

Because it's a regular step type, http works in custom commands exactly as it does in workflows.

Get Involved​

See the workflow step types and custom commands docs for the full reference, and the examples/http-webhooks example to try it out. Questions or ideas? Join us in the Cloud Posse community Slack.

The Problem​

Workflows are where teams encode the operational knowledge that should not live in someone's shell history: run the checks, build the thing, deploy the dependencies, then summarize what happened.

Until now, those steps were sequential. That was easy to reason about, but it meant a workflow with four independent checks took the sum of all four runtimes. The usual workaround was to drop into shell scripts, background jobs, wait, temp files, and hand-rolled log prefixes. That works until it doesn't:

• Output from concurrent commands interleaves into unreadable logs.
• Failure behavior is implicit and different in every script.
• Dependency relationships are hidden in shell control flow.
• Local workflows and CI matrices drift apart.

Infrastructure automation should not force you to choose between "simple but slow" and "fast but fragile."

What's New​

Atmos now supports two new workflow control step types:

• parallel runs sibling steps concurrently.
• matrix expands literal axes and schedules the generated child steps.

Both support:

• needs dependencies between sibling steps.
• max_concurrency to bound parallelism.
• Failure modes: wait_all, fail_fast, and best_effort.
• Output modes: grouped, prefixed, and none.
• Parent-owned summaries with success, failed, skipped, and canceled counts.

This is built into the workflow engine, so the orchestration rules are visible in the workflow file instead of buried in shell glue.

Parallel Checks​

Run independent checks together, then run a dependent summary step only after both prerequisites succeed:

workflows:
  checks:
    steps:
      - name: checks
        type: parallel
        max_concurrency: 4
        fail:
          mode: wait_all
        output:
          mode: grouped
          order: completion
          show_summary: true
          prefix: "{{ .step.name }}"
        steps:
          - name: lint
            type: shell
            command: make lint

          - name: test
            type: shell
            command: make test

          - name: summarize
            type: shell
            needs: [lint, test]
            command: ./scripts/summary.sh

The workflow is still declarative: summarize says what it needs, not how to poll for it. Atmos schedules everything else.

Matrix Fan-Out​

Use matrix when the same step should run across combinations:

workflows:
  test-matrix:
    steps:
      - name: test-matrix
        type: matrix
        max_concurrency: 3
        output:
          mode: grouped
          order: definition
        matrix:
          os: [linux, darwin]
          go: ["1.22", "1.23"]
        steps:
          - name: test
            type: shell
            command: make test OS={{ .matrix.os }} GO_VERSION={{ .matrix.go }}

That gives you CI-style fan-out without requiring the workflow to become a GitHub Actions-only construct. The same workflow can run locally, in CI, or inside a larger operational runbook.

Output That Stays Readable​

Concurrent output is only useful if humans can read it. The control step owns child output rendering:

• grouped captures child stdout/stderr and prints labeled blocks.
• prefixed streams live output with complete-line prefixes.
• none suppresses terminal output while still capturing metadata.

For live logs:

output:
  mode: prefixed
  prefix: "{{ .step.name }}"

Example output:

[lint] checking formatting
[test] running unit tests
[lint] passed
[test] passed
[checks] summary: 2 succeeded, 0 failed, 0 skipped, 0 canceled

The summary uses the same Atmos UI formatter as other command output, so success, warning, and failure states are immediately visible.

Explicit Failure Semantics​

Parallel work needs a clear answer to "what happens when one branch fails?"

fail:
  mode: wait_all        # wait_all | fail_fast | best_effort
  max_failures: 2       # 0 means unlimited

• wait_all lets independent ready/running branches continue, skips dependents of failed children, and fails the parent after schedulable work settles.
• fail_fast cancels pending and running siblings once the failure threshold is reached.
• best_effort records failures and skips dependents, but lets the parent succeed unless the control step itself is invalid.

That makes failure behavior reviewable. Operators can choose fast feedback for checks, complete collection for reports, or best-effort fan-out where partial success is still useful.

Guardrails for v1​

The first version intentionally allows only non-interactive child steps inside concurrent groups:

• shell
• atmos
• sleep

Interactive prompts, terminal-owning renderers, file editors, pagers, spinners, environment-mutating steps, and exec are kept outside concurrent groups for now. That boundary is deliberate: concurrent workflows should not start by letting multiple children fight over the same terminal.

You can still use rich UI steps before or after a parallel or matrix control step to frame the workflow, show tables, render markdown, or summarize the result.

Why This Matters​

Parallel and matrix workflow steps make Atmos workflows feel like real orchestration instead of a sequential macro runner.

• Local runbooks get faster without becoming bash concurrency puzzles.
• CI and local automation can share the same workflow definition.
• Dependency relationships are visible as needs, not hidden in scripts.
• Output remains readable by default.
• Failure behavior is part of the contract.
• Matrix fan-out is available anywhere Atmos runs, not only inside a CI provider.

This is especially useful for validation workflows, multi-component smoke tests, cross-platform checks, reporting jobs, and any operational task where several independent branches can run safely at the same time.

Try It​

This PR includes a runnable example:

cd examples/parallel-steps

atmos workflow checks -f parallel
atmos workflow prefixed -f parallel
atmos workflow matrix -f parallel

Start with validation and reporting workflows first. They usually have the safest fan-out shape: independent checks, obvious dependencies, and low risk if one branch fails.

For the full field reference, see the parallel and matrix step type documentation.

Get Involved​

Try the new control steps on real workflows and tell us where the v1 guardrails feel too strict or exactly right. We're especially interested in feedback on output modes, failure semantics, and which additional non-interactive step types should be allowed inside concurrent groups next.

The Problem​

Long-running workflows — a multi-stack terraform apply, a build pipeline, a vendoring sweep — often outlast your attention. You kick one off, switch to another window, and forget about it. The existing alert step rings the terminal bell, but a bell doesn't tell you what happened, and it's easy to miss.

People have worked around this by shelling out to say on macOS, but that breaks the moment a teammate runs the same workflow on Linux or in CI, where say doesn't exist.

The Solution​

A new say step speaks its content aloud and works across platforms:

workflows:
  deploy:
    steps:
      - name: apply
        type: atmos
        command: terraform apply vpc

      - name: notify
        type: say
        content: "Deployment to {{ .steps.env.value }} is complete"

Under the hood it detects an available speech engine per OS — macOS say, Linux spd-say/espeak/espeak-ng, and Windows PowerShell's System.Speech — so the same workflow runs unchanged on any machine.

Pick a voice, font-family style​

Voice names are platform-specific, so voice is an ordered list — just like a CSS font-family stack. The first voice actually installed on the host wins; if none match, the engine's default is used:

      - name: notify
        type: say
        content: "Build finished"
        voice: [Samantha, Microsoft Zira, en-us]   # macOS, Windows, Linux
        rate: normal                                # slow | normal | fast

That single list resolves to Samantha on macOS, Zira on Windows, and en-us (espeak) on Linux — no per-OS branching required.

Graceful degradation you control​

say only makes sense on an interactive workstation, so it never fails a workflow and never hangs CI. The print field decides what happens when speech is (or isn't) available:

• fallback (default) — speak when possible; otherwise print the message as a Markdown blockquote so the information is never lost.
• always — always print the blockquote and also speak when possible.
• never — speak when possible; otherwise stay silent.

In CI, or on any host with no speech engine, say automatically prints instead of speaking — so you can leave say steps in workflows that run both locally and in pipelines.

Try It​

A new examples/say-something/ example demonstrates voices, rates, print policies, and composing say into a build pipeline:

cd examples/say-something

atmos workflow notify -f say        # speak a completion message
atmos workflow voices -f say        # cross-platform voice stack
atmos workflow print-modes -f say   # the three print policies
atmos workflow pipeline -f say      # announce each build milestone

The cross-platform plumbing lives in a reusable pkg/say package, mirroring the existing browser-opening abstraction, so other parts of Atmos can adopt audible notifications too.

Get Involved​

Add a say step to the end of your slowest workflows and let Atmos tell you when it's done. Feedback and ideas are welcome on GitHub.

What's Included​

The media kit gives contributors, partners, and community teams a single place to find approved Atmos brand assets:

• Logo downloads for the Atmos mark and wordmark, including light and dark variants.
• Powered by Atmos badges for projects that want to show they run on Atmos.
• Brand colors sourced from the official Atmos logo artwork, plus separate animated accent colors for the web treatment.
• Usage guidelines for sizing, clear space, backgrounds, and preserving the original logo proportions.
• Product facts and links for consistent references to Atmos, Cloud Posse, GitHub, and the community.

Why This Matters​

Atmos shows up in documentation sites, internal developer portals, integration pages, conference decks, and open source READMEs. Without a canonical source, teams either copied assets from the website or recreated them by hand.

The media kit makes those references easier to keep consistent. Use the provided files directly, keep the canonical green logo palette for brand-forward placements, and reserve the animated accent colors for the web treatment.

Get the Assets​

Visit the Atmos Media Kit to browse the assets or download the complete ZIP.

What Changed​

You can now add a human-readable description to any component's metadata section:

components:
  terraform:
    vpc-prod:
      metadata:
        component: vpc
        description: "Production VPC with public and private subnets"
      vars:
        environment: prod

The Atmos manifest JSON schema was updated to allow the new field, so editors with schema support get auto-completion and validation for metadata.description.

Why This Matters​

Stacks often define many components that point at the same Terraform root module with different configurations. A short description makes it obvious at a glance what each one is for, without forcing readers to reverse-engineer intent from variables. It keeps documentation co-located with the configuration it describes.

How to Use It​

Add description under any component's metadata:

components:
  terraform:
    vpc-isolated:
      metadata:
        component: vpc
        description: "Isolated VPC without an internet gateway"
      vars:
        vpc_cidr: "10.1.0.0/16"

The field is purely informational and additive — existing stacks are unaffected. See the component metadata reference for details.

The Problem​

Scanner hooks already render a findings summary to the terminal, the job step summary, and the Atmos Pro run page. But the two richest GitHub surfaces were missing:

• Inline annotations — findings pinned to the exact file and line on the PR diff, where reviewers actually look.
• Code Scanning alerts — tracked findings in the Security tab with an open → fixed lifecycle across runs.

The findings were right there in the parsed SARIF; they just had nowhere to go.

The Solution​

Three independent CI reporting outputs, all under ci: and gated by the ci.enabled master switch:

ci:
  enabled: true
  summary: true        # markdown report in the job step summary  (default: on)
  annotations: true    # inline ::error/::warning on the PR diff   (default: on)
  results: true        # upload SARIF to GitHub Code Scanning      (default: off)

• ci.annotations turns each finding into a GitHub ::error/::warning annotation anchored at its file and line. This is the non-Code-Scanning path — it needs no GitHub Advanced Security, so it works on any repo.
• ci.results uploads the raw SARIF to Code Scanning. Atmos derives the analysis category from the scan target automatically, so a terraform plan across many components tracks each as its own analysis instead of overwriting.

Both are implemented as native CI provider capabilities (extending the same provider interface that already powers job summaries, check runs, and PR comments), not by shelling out to a third-party action. Everything is best-effort: a reporting failure never fails your hook or your plan, and outside CI it all no-ops.

Because both outputs can attach line-level feedback to a pull request, enable both only when you want both the lightweight Actions annotation and the tracked Code Scanning alert. If duplicate comments on the same lines are noisy for your team, enable only one of ci.annotations or ci.results.

Built-in and custom tools​

The three SARIF scanners — checkov, trivy, kics — participate automatically. Any custom tool does too, just by declaring format: sarif:

hooks:
  tfsec:
    events: [after-terraform-plan]
    kind: command
    command: tfsec
    args: ["--format", "sarif", "--out", "$ATMOS_OUTPUT_FILE", "$ATMOS_COMPONENT_PATH"]
    format: sarif

Permissions​

permissions:
  contents: read
  security-events: write   # only needed for ci.results (SARIF upload)

Annotations and the summary need no special permissions and no paid add-on — they work on any repo. ci.results uploads to Code Scanning, which needs security-events: write and, on private repos, GitHub Advanced Security — a paid add-on that GitHub licenses per active committer. Code Scanning is free on public repos. That's exactly why annotations default on and ci.results defaults off — everyone gets inline feedback for free, and only GHAS subscribers opt into the Security-tab integration.

How to Use It​

See CI Reporting in the hooks documentation for the full reference.

Get Involved​

Want findings routed somewhere else — GitLab security dashboards, threaded PR review comments? Open an issue or join us in the Atmos community.