Atmos Emulators

Use this skill for local emulators managed by Atmos. Emulators are stack-scoped, persistent containers that stand in for cloud APIs, Kubernetes, Vault/OpenBao, or OCI registries during local development and testing.

Related Skills

Need	Load
Container component lifecycle	atmos-container
YAML `!emulator` references	atmos-yaml-functions
Secrets backed by Vault/OpenBao/SOPS/cloud stores	atmos-secrets
Workflow `emulator` and `wait` steps	atmos-workflows

Component Shape

Define emulators under components.emulator:

components:
  emulator:
    aws:
      driver: localstack/aws
      region: us-east-1
      ephemeral: false
      container:
        healthcheck:
          test: ["CMD", "awslocal", "s3", "ls"]

Supported driver families include AWS, GCP, Azure, Kubernetes (k3s), Vault/OpenBao, and registry emulators. Check the local docs for exact driver names before generating config for a specific driver.

A nonempty container.ports list replaces the driver's defaults. When adding ingress ports to k3s, also include container: 6443 (TCP, the default protocol). Atmos rejects an override missing this API port before startup. Omit host for an automatically assigned host port, or pin it explicitly.

Commands

Command	Purpose
`atmos emulator up <name> -s <stack>`	Start an emulator
`atmos emulator down <name> -s <stack>`	Stop and remove an emulator
`atmos emulator reset <name> -s <stack>`	Stop and wipe persisted state
`atmos emulator ps -s <stack>`	List configured emulators that are running
`atmos emulator list -s <stack>`	List configured emulators and status
`atmos emulator logs <name> -s <stack>`	Show emulator logs
`atmos emulator exec <name> -s <stack> -- <cmd>`	Run a command in the emulator container

Use --dry-run to preview.

list and ps are configuration-scoped: emulator components declared in the current Atmos project are the inventory, and the container runtime only supplies their status. Use --runtime on either command only when diagnosing raw labeled containers outside the current project configuration. Lifecycle commands prompt for a stack on an interactive TTY when -s is omitted.

YAML Integration

Use !emulator to resolve connection details from stack config instead of hardcoding localhost ports. This keeps components portable across stacks, CI, and local developer machines.

Guidance

Use emulators for local integration tests and agent workflows that need cloud-like APIs without cloud credentials.
Keep emulator state persistent only when tests or development workflows benefit from it.
Prefer wait/wait-all workflow steps or health checks before running dependent commands.
Use local registry emulators when testing container build/push flows.
Use Vault/OpenBao emulators together with atmos-secrets for local secret workflows.

SKILL.md