cloudposse/atmos/atmos-emulator

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

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

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.