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, 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.