Test AWS code with Claude Code using the AWS Emulator skill
Published · Last updated
Short answer
AWS Emulator is a local emulator of the AWS APIs, made by AWS. Its README says to install the aws-emulator skill with AWS CLI 2.35.0 or later, then ask your coding agent to set up the emulator. No AWS account needed.
Version read. This page quotes the repository at tag v1.0.322 (commit 7753983), published 2026-11-11 00:32 UTC. It was the latest release on the releases page when we checked on 2026-11-12. The repo ships several releases a day (five between 2026-11-10 07:55 and 2026-11-11 00:32 UTC), so a newer tag may exist by the time you read this. Every README link below points at that tag.

What AWS Emulator is
The README's first lines, quoted:
"AWS Emulator is a local emulator of the AWS APIs. You use it to test your software without calling AWS, on your own machine, on a development server, or in continuous integration (CI). You don't need an AWS account. Your requests go to the emulator, not to AWS." (README)
"The emulator is a local program that serves an AWS API endpoint. It has no graphical interface. After you start the emulator, you set environment variables to point the AWS CLI or an AWS SDK at its endpoint. Then you run your code as usual." (README)
For Claude Code this means the agent runs your tests against emulated resources, which the README contrasts with AWS resources: "So you work with emulated resources instead of AWS resources." The repository is in the aws GitHub organization and is licensed CC0 1.0, except the vendor/ folder, which is Apache 2.0 (README).
What it emulates
The README does not list services by name. It describes the layout instead: "The workspace has one crate per AWS service" (README), with each service under services/service-<name>/ holding its Smithy model, its in-memory state and "one file per operation" (repository layout).
At tag v1.0.322 the services folder has 436 folders named service-<name>, plus one named common. We counted them through the GitHub API on 2026-11-12. Each service folder has an OPERATIONS.md that lists the operations generated from that service's model. To check whether a service you use is there, open the services folder at the tag and search for its name.
Present is not the same as complete. The README sends you to the fidelity scores for how closely each service matches AWS. The numbers for this tag are in the limits section below.
Setup paths the README lists
| Mode | What the README says | Lines |
|---|---|---|
| AI coding agent | Install the aws-emulator skill with AWS CLI 2.35.0 or later, then ask the agent to set up the emulator. | L13-L19 |
| Server mode, Linux | Install the RPM or Debian package and run aws-emulator. | L23 |
| Server mode, Windows and macOS | Run the emulator in a container built from a short Dockerfile on the AWS User Guide page. | L24 |
| Embedded mode, Rust tests | Add the emulator as a dev-dependency. It runs in-process, one isolated instance per test. | L28-L30 |
| Build from source | Linux x86_64 and aarch64 only. Needs Rust, a C compiler, a multi-core machine and 100 GB of free disk. | L38-L56 |
The Linux packages, the Dockerfile and the environment variable names live on the AWS Emulator User Guide, which the README links. They are not in the repository. The v1.0.322 release has one file attached, scores.json.gz, and no package or container image. So there is no image tag or digest we could pin from the repo, and this page does not copy setup steps from the User Guide.
Install the skill for Claude Code
The README's agent quick start, quoted: "Install the aws-emulator skill, then ask your agent to set up the emulator. This needs the AWS CLI version 2.35.0 or later." (README)
aws agent-toolkit add-skill --skill-name aws-emulator --region us-east-1(README). The skill comes through the AWS CLI, not npm, so there is no npm package to pin. The README shows no version option for the skill, so the command installs whatever version AWS serves that day. The repository itself contains no SKILL.md: a GitHub code search of the repo on 2026-11-12 found none, and the only file that mentions agent-toolkit is the README. The README links Getting started with an AI coding agent for the rest.
How Claude Code finds the skill
The repository does not say where aws agent-toolkit add-skill writes the skill. Claude Code's skills docs say where it looks:
- Personal:
~/.claude/skills/<skill-name>/SKILL.md, for "All your projects on this machine". - Project:
.claude/skills/<skill-name>/SKILL.md, for "Sessions in this repository". Commit it so your team gets it too.
After the install, check that an aws-emulator folder with a SKILL.md sits in one of those places. Then run /skills in a Claude Code session to see it listed. The same docs say "Claude uses skills when relevant, or you can invoke one directly with /skill-name" (code.claude.com). The docs add that "The directory name also invokes the skill", so a folder named aws-emulator gives /aws-emulator. If the skill is not in one of the folders above, Claude Code does not load it.
How it works once it runs
- A source build serves "HTTPS on
127.0.0.1:9297(self-signed certificate)" (README). - The router has a readiness check,
GET /__admin/health, on the same port. Its options include-pfor the port,-a on|offfor SigV4 request authentication ("default on") and--idle-timeout 900to "exit after 900 seconds without an API call" (router README). - You point the AWS CLI or an SDK at it with environment variables (README). The README links Pointing your AWS SDK at AWS Emulator for the names.
- In embedded mode there is "no endpoint URL, certificate, or environment variable to set". Your Rust test hands the emulator's HTTP client to the SDK client (README). The embedded README adds that each emulator keeps its own state: "Every client from one emulator shares its state; two emulators never do."
Once the skill loads, a plain first request to Claude Code is to start the emulator, run your existing test suite against it and list every call that failed.
Limits the README states
- Not for production or security tests. "AWS Emulator is for building and testing. Don't use it for production workloads or to test security." (README)
- Gaps are tracked as files. "APIs and behaviors that don't work yet are under
issues/things-that-do-not-work/, and ones that have since been fixed move toissues/things-that-now-work/" (README). At v1.0.322 we counted 6,545 files in things-that-do-not-work and 12,709 in things-that-now-work. - Source builds are Linux only and large. Building from source "is supported on Linux (x86_64 and aarch64)"; on Windows and macOS, use Docker. You need "At least 100 GB of free disk for
target/" and a multi-core machine (README). Embedded mode compiles the emulator into your test binary, so the same cost applies (README). - Telemetry is on by default. The README says the records never include "what's in your requests or responses, your code, your credentials, or personal data" (README). To turn it off, start with
aws-emulator --telemetry off, setEMULATOR_TELEMETRY=off, or addenabled = falseunder[telemetry]in~/.aws/emulator/config.toml(README). - No pull requests. "This repository does not take PRs." Report gaps in GitHub Issues with the service, operation, SDK and version, the request and how the response differed from AWS (README).
The fidelity scores for v1.0.322
The README says: "To see how closely each service matches AWS, check the fidelity scores published with each release" (README). For v1.0.322 that is scores.json.gz, scored at 2026-11-11 00:09 UTC against commit 7753983. It lists 42,937 test units, each with an outcome. We counted them:
| Kind | Pass | Fail | Skipped | Total |
|---|---|---|---|---|
| behavioral | 20,364 | 11,958 | 80 | 32,402 |
| wire | 3,879 | 6,656 | 0 | 10,535 |
| All units | 24,243 | 18,614 | 80 | 42,937 |
The README does not say how to turn these units into one score per service, so we do not print one. Read the table as a sign that many calls still differ from AWS, and check the services your code uses before you trust a green test run.
What we ran and what we did not
We did not install or run AWS Emulator for this page. The v1.0.322 release attaches no package or image, so a hands-on run from the repo alone means a source build with 100 GB of free disk. The skill install needs the AWS CLI talking to AWS in us-east-1, and the README does not say what account or credentials that takes. Everything above is quoted from the repository files, the release, and Claude Code's docs.
How this page was checked
On 2026-11-12 we read the README, core/router/README.md, core/embedded/README.md and the folder listings at tag v1.0.322 through the GitHub API, and downloaded the release's scores file. Every README quote links to its line at that tag. The GitHub API lists the repository owner as the aws organization. Claude Code skill locations come from code.claude.com, checked the same day. For another vendor's skill set for Claude Code, see Chrome's Modern Web Guidance agent skills for Claude Code.
FAQ
Can Claude Code test AWS code without an AWS account?
The README says you use AWS Emulator "to test your software without calling AWS" and "You don't need an AWS account." Your requests go to the emulator, not to AWS (README). Claude Code runs your tests against it like any other local endpoint.
How do I install the AWS Emulator skill?
The README gives one command, aws agent-toolkit add-skill --skill-name aws-emulator --region us-east-1, and says it needs the AWS CLI version 2.35.0 or later (README). Then ask your agent to set up the emulator.
Which AWS services does it emulate?
The README does not list them by name. It says the workspace has "one crate per AWS service" (README). At tag v1.0.322 the services folder holds 436 service folders. Look for yours there, and read its OPERATIONS.md.
Can I use it for security testing?
No. The README says: "Don't use it for production workloads or to test security" (README).
Does AWS Emulator send telemetry?
Yes, by default. The README says "Telemetry is on by default" and that its records never include your requests, responses, code, credentials or personal data. Turn it off with --telemetry off, EMULATOR_TELEMETRY=off or the config file (README).
Does it cost anything?
The README says "AWS Emulator has no additional service fee. You pay only for AWS resources when you deploy on AWS" (README).
Sources
All checked 2026-11-12.
- AWS Emulator README at v1.0.322: https://github.com/
aws/ aws-emulator/ blob/ v1.0.322/ README.md - Release v1.0.322, published 2026-11-11 00:32 UTC: https://github.com/
aws/ aws-emulator/ releases/ tag/ v1.0.322 - Fidelity scores file for v1.0.322: https://github.com/
aws/ aws-emulator/ releases/ download/ v1.0.322/ scores.json.gz - Router README at v1.0.322: https://github.com/
aws/ aws-emulator/ blob/ v1.0.322/ core/ router/ README.md - Embedded mode README at v1.0.322: https://github.com/
aws/ aws-emulator/ blob/ v1.0.322/ core/ embedded/ README.md - Services folder at v1.0.322: https://github.com/
aws/ aws-emulator/ tree/ v1.0.322/ services - Tracked gaps at v1.0.322: https://github.com/
aws/ aws-emulator/ tree/ v1.0.322/ issues/ things-that-do-not-work - Claude Code skills docs: https://code.claude.com/
docs/ en/ skills