Skip to main content

atmos emulator

Use these commands to manage emulator components: stack-scoped, long-running containers that stand in for a cloud API (AWS, GCP, Azure), Kubernetes, or a backing service (Vault) during local development and testing.

An emulator container outlives the atmos process and is discovered by labels derived from the canonical component instance address, so subsequent commands (ps, logs, exec, down) reattach to the already-running container.

Experimental
Configure Container Runtimes

Learn how to select and configure the container runtime (Docker or Podman) that Atmos uses to run emulators.

atmos emulator --help

Usage​

atmos emulator <subcommand> <component> --stack <stack> [flags]

The emulator command also has the alias emu.

Subcommands​

Container Runtime​

Emulators run inside a container runtime. Atmos selects the runtime via the global container.runtime.provider configuration and the ATMOS_CONTAINER_RUNTIME environment variable; Docker and Podman are auto-detected. There is no per-command runtime flag.

# Force Podman for emulator commands
ATMOS_CONTAINER_RUNTIME=podman atmos emulator up aws --stack=plat-ue2-dev

Configuration​

Emulator components are declared in your stacks under components.emulator. Each emulator selects a driver (for example, floci/aws for a local AWS sandbox):

components:
  emulator:
    aws:
      driver: floci/aws
      region: "{{ .vars.region }}"

With the configuration above, atmos emulator up aws --stack=plat-ue2-dev starts the local AWS sandbox for the plat-ue2-dev stack.

For the full list of drivers and how to configure each emulator type (AWS, GCP, Azure, Kubernetes, Vault/OpenBao, and registry), see Emulator Components.

Examples​

# Start (or reuse) the aws emulator in the plat-ue2-dev stack
atmos emulator up aws --stack=plat-ue2-dev

# List running emulators in the stack
atmos emulator ps aws --stack=plat-ue2-dev

# Stream the emulator's logs
atmos emulator logs aws --stack=plat-ue2-dev

# Run a command inside the emulator container
atmos emulator exec aws --stack=plat-ue2-dev -- aws s3 ls

# Stop and remove the emulator container
atmos emulator down aws --stack=plat-ue2-dev

See Also​