CLI Coming Soon
    Back to catalog

    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.

    Abstract cover: a grid of small grey tiles inside a dark frame, a few marked in orange, wired to one local client box

    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

    Ways to run AWS Emulator, from the README
    ModeWhat the README saysLines
    AI coding agentInstall 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, LinuxInstall the RPM or Debian package and run aws-emulator.L23
    Server mode, Windows and macOSRun the emulator in a container built from a short Dockerfile on the AWS User Guide page.L24
    Embedded mode, Rust testsAdd the emulator as a dev-dependency. It runs in-process, one isolated instance per test.L28-L30
    Build from sourceLinux x86_64 and aarch64 only. Needs Rust, a C compiler, a multi-core machine and 100 GB of free disk.L38-L56
    Source: README at v1.0.322, checked 2026-11-12.

    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 -p for the port, -a on|off for SigV4 request authentication ("default on") and --idle-timeout 900 to "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 to issues/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, set EMULATOR_TELEMETRY=off, or add enabled = false under [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:

    Fidelity test units in scores.json for v1.0.322, by kind and outcome
    KindPassFailSkippedTotal
    behavioral20,36411,9588032,402
    wire3,8796,656010,535
    All units24,24318,6148042,937
    Our count of the "outcome" and "kind" fields in scores.json from the v1.0.322 release, downloaded 2026-11-12. Each unit also names the services it covers, so you can filter the file for yours.

    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.

    Related guides