Skip to main content

Using Emulators

Atmos natively supports emulator components — stack-scoped, long-running containers that stand in for a cloud API (AWS, GCP, Azure), Kubernetes, or a backing service (Vault/OpenBao, 1Password Connect, an OCI/Terraform registry) during local development and testing. You declare them with the same stack-based configuration used for Terraform, Helmfile, Packer, and Ansible, and operate them with the atmos emulator command group — letting the rest of your stack run offline, with no cloud account.

Experimental

An emulator is built on the same lifecycle as the container component: the container outlives the atmos process and is discovered by labels derived from the canonical component instance address, so atmos emulator ps, logs, exec, and down reattach to the already-running container — there are no local state files.

Stack Configuration​

Emulator components are declared under components.emulator with first-class sections (driver, cloud, region, container, …) as siblings of metadata — NOT nested under vars. The required driver selects the image and target:

components:
  emulator:
    aws:
      driver: floci/aws          # selects the image and target (aws)
      region: us-east-2
      container:                 # optional container overrides (same schema as container components)
        ports:
          - host: 4566
            container: 4566

Inheritance (metadata.inherits), catalogs, mixins, and deep-merge work exactly like other component kinds — define an abstract base emulator with shared defaults and inherit it.

For the complete configuration reference — every driver and target, the !emulator function, health checks, persistence, and full examples — see Emulator Components.

Lifecycle​

atmos emulator up aws -s dev          # start (or reuse) the emulator for a stack
atmos emulator ps -s dev              # list running emulators in the stack
atmos emulator logs aws -s dev        # stream the emulator's logs
atmos emulator exec aws -s dev -- aws s3 ls   # run a command inside the emulator container
atmos emulator down aws -s dev        # stop + remove the container (persisted state is kept)
atmos emulator reset aws -s dev --force       # stop and wipe the emulator's persisted state

Each instance is named and labeled from its canonical address <stack>/emulator/<component>, so lifecycle commands discover it by label.

Try It​

Explore a complete, working example that provisions an S3 bucket against a local AWS emulator — no AWS account or credentials required.

emulator-awsView full example
atmos emulator aws lifecycle
00:00.0 / 00:00.0

Notes

This example provisions an S3 bucket against a local AWS sandbox — no AWS account or credentials required. The sandbox is an Atmos emulator component: a container declared in the normal local stack that Atmos starts and stops for you. By default it runs Floci, a free, MIT-licensed AWS emulator and a drop-in replacement for LocalStack Community Edition (which was EOL'd in March 2026).

The emulator is declared once in the local stack (components.emulator.aws, driver floci/aws) and a single aws/emulator identity in atmos.yaml binds every Terraform component to the local/aws instance. The provider-config contributor injects the AWS provider settings (dummy credentials, path-style S3, skip-flags) automatically, so there is no providers.tf and no endpoint configuration to maintain, and no hand-rolled docker-compose.yml.

Usage

Start the sandbox, apply, then tear everything down (a container runtime — Docker or Podman — is the only prerequisite):

atmos emulator up aws -s local         # start the shared local sandbox
atmos terraform apply demo -s dev     # provision the S3 bucket against the emulator
atmos terraform output demo -s dev    # inspect outputs

atmos terraform destroy demo -s dev   # remove the resources
atmos emulator down aws -s local      # stop and remove the sandbox container

atmos emulator list inventories every configured emulator instance, including local/aws when it has not been started; atmos emulator ps shows the running subset. The INSTANCE column is the value an aws/emulator identity targets. Add -s local to scope either command. For raw container-runtime diagnostics, including stale containers from other projects, use --runtime.

Other lifecycle verbs include atmos emulator logs aws -s local.

The atmos test custom command runs the full apply/destroy lifecycle across the dev, staging, and prod stacks.

Browse all files