# atmos emulator

Develop and test against local substitutes for cloud APIs, Kubernetes, and services such as Vault.
Atmos manages these emulators as components in your stacks, giving your workflows local endpoints to
use during development.

> ⚠️ Experimental

**Configure Container Runtimes**

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

Configuration Reference[Read more](/stacks/components/emulator#container-runtime)

## Usage

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

The `emulator` command also has the alias `emu`.

## Subcommands

## Container Runtime

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.

Emulators run inside a container runtime. Atmos selects the runtime via the global
`container.runtime.provider` configuration and the `ATMOS_CONTAINER_RUNTIME`
environment variable; `auto` (or an omitted provider) detects Docker, then Podman.
There is no per-command
runtime flag.

```shell
# 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):

```yaml
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](/stacks/components/emulator).

## Examples

```shell
# 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

- [Atmos Components](/components) — Learn about Atmos components
- [Emulator Components](/stacks/components/emulator) — Configure emulator components in stack manifests