Skip to main content
skill CX Codex

aws-emulator — Claude Code skill: what it does, how to install

aws-emulator manages a local AWS service emulator and tests whether your project or operations work on Claude Code.

Apache-2.0 366 installs ★ 3,536 updated 2026-11-20

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add aws/agent-toolkit-for-aws --skill aws-emulator -a claude-code
Open on GitHub

What aws-emulator does

The skill installs, starts, and troubleshoots the local AWS emulator serving requests over HTTPS on port 9297, fixing TLS and request-signing errors. It runs natively on Linux via RPM or Debian packages, while macOS and Windows require a Docker container built from that package. Rust tests can also embed it directly in-process.

Before running anything, the agent checks for aws-emulator, the AWS CLI version or project SDK, Docker status, and port availability. The setup requires a Rust toolchain with Cargo, a C compiler, and the AWS SDK for Rust in embedded mode, or Docker on macOS and Windows.

What it helps with

  • install and start the local AWS emulator
  • configure the AWS CLI and SDKs to use the emulator
  • fix TLS and request-signing errors
  • check if the app works on the emulator

Example prompts for the agent

  • Install and start aws-emulator for the project
  • Point the AWS CLI at the local aws-emulator instance
  • Check if aws-emulator supports this AWS operation

How to install aws-emulator

1Skills CLI (Vercel)

npx skills add aws/agent-toolkit-for-aws --skill aws-emulator -a claude-code

2Manually: put the files in place

~/.claude/skills/aws-emulator/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/aws-emulator/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about aws-emulator

How to install aws-emulator in Claude Code?

Run npx skills add aws/agent-toolkit-for-aws --skill aws-emulator -a claude-code followed by ~/.claude/skills/aws-emulator/SKILL.md.

What does aws-emulator do?

It serves local AWS service APIs over HTTPS and checks whether projects or specific operations run correctly on the build.

What is needed to run aws-emulator?

Native Linux support, Docker for macOS and Windows, or a Rust toolchain with Cargo and a C compiler for embedded mode.

Source text

SKILL.md · Apache-2.0
---
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: "2"
---

# 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) |
| report a problem, a difference from AWS or a missing operation, or ask for a change to the emulator | [references/troubleshooting.md](references/troubleshooting.md), section "Reporting issues" |
| 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)
(Linux package, "Upgrade") and [references/container.md](references/container.md)): when the user asked
to install, set up or upgrade it, go ahead, but still confirm once before the first `sudo`
command; otherwise ask once first, because the upgrade may need `sudo` and restarting a running
emulator clears its state. An upgrade is: stop the emulator, run the
`LTS/latest/` install command again (it replaces the older version), check `aws-emulator -v`, and
start it again; in Docker, rebuild with `docker build --pull --no-cache`. When the latest release cannot be determined
(no release, no access), say so, give the upgrade command anyway, and go on.

## Rules

- When the user asks how to install, start, connect or fix the emulator, do it in their
  environment, verify it (health check, `aws sts get-caller-identity` shows `000000000000`), then
  report what you ran. Only explain without acting when they ask for an explanation. Write only
  to `~/.aws/emulator/`, `<app>/.aws-emulator/`, `mktemp -d` directories, the image and the
  container; ask before `sudo`, shell-profile edits, repo or test-script edits, or any other write.
- Start the emulator in the background (`nohup … &` with a per-port log for the package,
  `docker run -d` in Docker) and wait on the health check; a foreground emulator blocks the shell.
  When you start it, tell the user that telemetry is on and how to turn it off (see Security);
  in CI jobs and agent sandboxes, start it with telemetry off.
- Never commit the per-run `config`, `emulator_credentials` or `ca.pem`; they change every start.
- A `NotImplemented` answer (HTTP 501, which SDKs do not retry) is a coverage gap in the
  installed build, not a misconfiguration. Say so and offer the compatibility check for the app or that operation.
- For a compatibility question, run the check and present its verdict as its Rules say
  ([references/compatibility-check.md](references/compatibility-check.md)); never answer from
  memory or from this file.
- The check is strict: when the evidence is unclear, the item is UNVERIFIED and the answer WILL
  NOT WORK. Strictness applies to evidence, not to inventing items: record only what the app
  actually relies on.
- After the verdict, add **one** sentence for each UNVERIFIED assumption item that touches a
  limit below, explaining that limit. Leave the verdict itself unchanged.
- The AWS MCP server is recommended for AWS API calls to real AWS (sandboxed, IAM-authenticated,
  audit-logged), but it is not required. It cannot reach an emulator on this machine, so calls to
  the emulator go through the local AWS CLI or SDK with the connect variables set.

## Security

- Keep the emulator on loopback: the default bind is `127.0.0.1`; change `-b` only inside a
  container, and publish a container's port on `127.0.0.1` only, never on all interfaces.
- Never disable TLS verification globally or for AWS endpoints, and never suggest
  `--no-verify-ssl` or `verify=False`. Trust this run's `~/.aws/emulator/<port>/ca.pem`, through
  the config file, `AWS_CA_BUNDLE` (always in Docker) or the SDK's own setting.
- Keep real AWS credentials out of every command or job that calls the emulator (the env file
  in [references/connect.md](references/connect.md) does this):
  `unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE` plus the
  web-identity and container-credential variables (full list in
  [references/connect.md](references/connect.md)), then check that
  `aws sts get-caller-identity` shows `000000000000`.
- Use `-a off` only for local test runs, reachable only on `127.0.0.1` (in Docker: port
  published on `127.0.0.1`); never on a shared or CI host that others can reach.
- Telemetry is on by default; turn it off with `-t off` or `EMULATOR_TELEMETRY=off` (Docker:
  `-e EMULATOR_TELEMETRY=off`). When you start the emulator, tell the user it is on and how to
  turn it off. In CI jobs and agent sandboxes, start it with `-t off` (Docker:
  `-e EMULATOR_TELEMETRY=off`) by default. For what telemetry sends, point to the
  [AWS Emulator user guide](https://docs.aws.amazon.com/emulator/latest/userguide/).
- Never use production data or send production traffic to the emulator.
- Before sharing logs, requests or responses, remove or mask secrets (keys, tokens, signatures)
  and personal data.

## Limits by design

These hold for every build. They are not a coverage list.

- **Open source.** The source is in [aws/aws-emulator](https://github.com/aws/aws-emulator); see
  its LICENSE file for the license.
- **State is in memory only.** Everything is gone when the process exits. There is no reset
  operation: restart the process for a clean state.
- **Not for production.** No durability or security guarantees; do not send production traffic
  or data to it.
- **One account.** Every request runs in account `000000000000`, signed with keys vended for that
  run (`emulator_credentials`).
- **One Region and one account per emulator.** The emulator accepts any Region and account ID
  but does not keep resources separate by either, so calls across Regions or accounts are not
  supported. To test several Regions, run one emulator per Region, each on its own port.
  Behavior is checked against AWS in `us-west-2` only.
- **Not a security test target.** Signatures are checked (not in embedded mode), and the emulator
  never denies a request signed with its own keys. Do not use it to test IAM policies,
  permissions boundaries, resource-based policies (such as bucket policies), AWS KMS key
  policies, or access across accounts or Regions.
- **Code it runs is not isolated.** Function code the emulator runs for you runs on the user's
  machine without isolation.
- **Coverage is per build.** Whether a specific operation or behavior works on the installed
  build is answered by the compatibility check, not by this list.

© aws · Apache-2.0 · aws/agent-toolkit-for-aws

Similar skills

All skills for Cloud: AWS, Azure, GCP →

From the same set159

The whole set →
contextual-offers-for-startups contextual-offers-for-startups is a Claude Code skill that may add one relevant AWS Activate offer after another AWS Startup Advisor skill finishes. It leaves technical advice unchanged. CX Codex +1 566installs operate-on-aws operate-on-aws investigates live AWS incidents, diagnoses root causes, and checks pull request risks using AWS DevOps Agent. Built for startup teams without a dedicated SRE. CX Codex +1 540installs migrating-hive-tables-to-s3-tables The migrating-hive-tables-to-s3-tables skill guides an agent when migrating Glue Hive Parquet tables into Amazon S3 Tables as managed Iceberg. It runs during data catalog migration and table sync tasks. CX Codex +1 495installs querying-aws-athena querying-aws-athena — a skill for Claude Code and Cursor that runs SQL queries on Amazon Athena query history via the query_executions system table. CX Codex +1 454installs setting-up-workspaces-applications setting-up-workspaces-applications is a Claude Code skill that provisions Amazon WorkSpaces Applications for an AI agent or people. It handles requests to create a desktop environment, try a sample, or enable agent access. CX Codex +1 245installs bedrock-migration-assessment bedrock-migration-assessment is a Claude Code skill that evaluates moving LLM workloads to Amazon Bedrock. Scans projects for OpenAI, Anthropic, Gemini, or OpenRouter calls. CX Codex +1 167installs aws-startup-advisor aws-startup-advisor recommends lean AWS architectures tailored to startup stage, runway, and credits. Scaffolds Terraform and handles migrations from Azure, GCP, or Heroku to AWS and Bedrock. ★ 3,536repo stars aws-data-analytics aws-data-analytics — a Claude Code plugin with 17 skills covering data engineering on AWS. It kicks in for S3 Tables, AWS Glue, Athena, Redshift, MSK, MWAA and OpenSearch. ★ 3,536repo stars

Project sponsors

Companies that keep this analytics open