Atmos Emulator

DevOps & Security

atmos-emulator

Atmos Emulator is an Agent Skill for devops & security published in the cloudposse/atmos repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Atmos emulator components: local AWS/GCP/Azure/Kubernetes/Vault/OpenBao/registry emulators, components.emulator, !emulator, identities, persistence, health checks, and emulator commands

View on GitHub ↗

QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

Open your project in Codex.
Copy and paste the prompt below.
Review files and risks before approving any action.

Prompt to paste

Inspect the Agent Skill at https://github.com/cloudposse/atmos/blob/HEAD/agent-skills/skills/atmos-emulator/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/atmos-emulator, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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 running emulators
`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.

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.