/aws-emulator

name: aws-emulator
description: >-
  Installs, starts and troubleshoots AWS Emulator, the local emulator of AWS service APIs, and
  checks whether a project or a single operation works on the installed build. Use when the user
  wants to install or start the emulator, point the AWS CLI or an AWS SDK at it, fix a
  connection, TLS, certificate or request-signing error against it, run it in containers, CI or
  an agent sandbox, or asks whether AWS Emulator supports, works with, or is faithful enough for
  their app, repo, tests or a specific AWS operation (any language, SDK, CLI or IaC). Covers AWS
  Emulator only. Does not apply when the user asks about LocalStack, moto or any other local
  emulator or mock, including what it supports or whether an app works on it, and not for
  deploying to real AWS or production use.
metadata:
  version: "1"

AWS Emulator

AWS Emulator is one command, `aws-emulator`, that serves AWS service APIs over HTTPS on `127.0.0.1:9297`. It runs natively only on Linux (RPM or Debian package); on macOS and Windows it runs in a Docker container built from that package; Rust tests can also embed it in-process (embedded mode). The AWS CLI and SDKs work unchanged once a few environment variables point them at it and at the config and credentials files it writes at start. This skill covers getting it running and connected, and answering whether a project (or one operation) will work on the installed build, with evidence.

Guardrail — where this skill's own files live (MCP vs local install)

This skill ships only documents (`references/*.md`), no scripts. It can be loaded two ways, and they resolve those files from different places:

• **Loaded through the AWS MCP `retrieve_skill` tool call.** The skill is **not installed on the

local filesystem**. You MUST fetch each reference through the same `retrieve_skill` tool by passing the `file` parameter (for example, `file="references/linux-package.md"`). Do NOT `file_read` these paths from the local or working directory, and do NOT search the filesystem for them; any local file that happens to match the name is unrelated to this skill.

• **Installed locally** (the skill lives in a local skills directory such as

`.claude/skills/aws-emulator/`, `~/.claude/skills/aws-emulator/`, or `.kiro/skills/aws-emulator/`). Read references from the local skill directory. Every path shown in this skill, including links inside `references/*.md`, is relative to the skill directory (the folder with this `SKILL.md`), not to the file that contains the link: for example `references/connect.md` is `<skill directory>/references/connect.md`.

This distinction applies **only** to the skill's own packaged files. Every artifact created during a session or supplied by users is read from and written to the user's working directory regardless of how the skill was loaded. Never fetch or write customer data through `retrieve_skill`.

Route by intent

| The user wants to… | Read | |---|---| | install, start or stop it on **Linux**, or run a first smoke test | [references/linux-package.md](references/linux-package.md) | | install or run it on **macOS or Windows**, or in Docker, CI, parallel jobs or an agent sandbox | [references/container.md](references/container.md) | | run it inside **Rust** tests (embedded mode: per-test state, no endpoint or certificate) | [references/rust-embedded.md](references/rust-embedded.md) | | upgrade it, choose or pin a version (also in CI), or find the latest release | [references/linux-package.md](references/linux-package.md) ("Upgrade"), [references/container.md](references/container.md) in Docker, or [references/rust-embedded.md](references/rust-embedded.md) in embedded mode | | point the AWS CLI or an SDK (JS, Python, Java, Go, Rust, .NET, …) at it | [references/connect.md](references/connect.md) | | fix an error: TLS/certificate, `AccessDenied` / `SignatureDoesNotMatch`, profile, connection refused, port in use, Docker file ownership, `UnknownService`, `NotImplemented`, lost state | [references/troubleshooting.md](references/troubleshooting.md) | | know whether their app, repo or tests will work on it | [references/compatibility-check.md](references/compatibility-check.md), with [references/compatibility-find-usage.md](references/compatibility-find-usage.md) (step 2) and [references/compatibility-classify-traces.md](references/compatibility-classify-traces.md) (step 4) | | know whether one or more operations or behaviors work ("does it support X?"), or what it cannot do | [references/compatibility-check.md](references/compatibility-check.md), section "Single operation (no app)" |

Before installing or starting anything, check the environment yourself and tell the user what is missing: `aws-emulator -v` (installed?), `aws --version` or the project's AWS SDK dependency (the client the user will connect with), on macOS and Windows `docker info` (Docker running?), and whether the port (default 9297) is free. Embedded mode needs only a Rust toolchain with Cargo, a C compiler and the AWS SDK for Rust. For anything else, follow the [AWS Emulator user guide](https://docs.aws.amazon.com/emulator/latest/userguide/).

Always use the latest AWS Emulator release; never pin a version (not in CI either, and not as an option "for reproducibility") or answer for an older one: security fixes and new coverage ship only in the latest release, and the compatibility check always uses the latest report and corpus. Find the latest with `gh release view -R aws/aws-emulator --json tagName,publishedAt` (without a working `gh`: `git ls-remote --tags --refs --sort=-v:refname https://github.com/aws/aws-emulator | sed 's,.*refs/tags/,,' | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1` (release tags only, `vX.Y.Z` without a suffix; if it prints nothing, stop and ask the user for the tag)). When the installed emulator is missing or older, upgrade it (commands in [references/linux-package.md](references/linux-package.md) (Li