# emulator

The `emulator` step type starts, stops, or resets a local cloud [emulator](/stacks/components/emulator) component from a workflow, custom command, or lifecycle hook. It is the declarative way to bracket an operation with a sandbox — most commonly a [`kind: step` hook](/stacks/hooks) on the `before.terraform.test` / `after.terraform.test` events that brings the emulator up before Terraform tests and tears it down after. No shelling out to `atmos emulator`.

```yaml
steps:
  - name: start-sandbox
    type: emulator
    component: aws        # the emulator component to operate on
    action: up            # up | down | reset (default: up)
```

The most common use is on the `terraform test` lifecycle so apply-backed tests run against a local sandbox with no cloud account:

```yaml
hooks:
  start-emulator:
    kind: step
    type: emulator
    events: [before.terraform.test]
    with: { component: aws, action: up }
  stop-emulator:
    kind: step
    type: emulator
    events: [after.terraform.test]
    when: always          # tear down even if a test fails
    with: { component: aws, action: down }
```

## Fields

- **`component`** — Required. The name of the emulator component to operate on (e.g. `aws`). Supports Go templates.
- **`action`** — Lifecycle action: `up` (start or reuse the sandbox), `down` (stop and remove it), or `reset` (stop and wipe persisted state, non-interactively). Defaults to `up`.
- **`ephemeral`** — When `true` with `action: up`, runs the emulator without persistence for this invocation, overriding the component's `ephemeral:` config. Defaults to `false`.
- **`stack`** — The stack the emulator belongs to. As a lifecycle hook this defaults to the component's stack, so it is rarely set explicitly.

## See also

- [Emulator components](/stacks/components/emulator)
- [Manage lifecycle events with hooks](/stacks/hooks)
- [Job summaries](/ci/job-summaries) — `atmos terraform test` writes a pass/fail step summary in CI.