cloudposse 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.
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-allworkflow 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-secretsfor local secret workflows.