AWS Emulator Gives Your Coding Agent a Free Local AWS. Here Is How to Use It Without Trusting It Too Much

AWS just shipped an offline copy of its own APIs, written by agents, so agents can test their code before it touches a real account. It is a fast inner loop. It is not proof.

Coding agents are good at writing code that calls AWS and bad at knowing whether it works.

The reason is boring. To check an S3 upload or an SQS message flow, the agent needs something that behaves like S3 or SQS. Usually that means a real AWS account, real credentials sitting in the agent's environment, real money, and real risk if it gets a delete call wrong. So most agents write the code, guess, and hand you a diff that has never run against anything.

On November 11, AWS released AWS Emulator, a free local stand-in for the AWS APIs that runs offline on your own machine. The launch post on Werner Vogels' blog says it is built from more than 400 API models covering more than 200 AWS services, and it was made for exactly this gap: it "gives coding agents a local copy of AWS to test against" (All Things Distributed).

The twist is who built it. According to AWS, agents wrote all of it.

That makes it two things at once: a useful tool you can install today, and a live example of the workflow AWS wants you to copy. Both are worth understanding before you point an agent at it.

What AWS Emulator actually is

Think of it as a flight simulator for AWS calls. Your code, or your agent's code, sends the same API requests it would send to the real cloud. The emulator answers them locally, the way AWS would, without an account and without a bill. (One thing does leave your machine by default: usage telemetry, covered in the setup steps below.)

The README lists three ways to run it:

Linux: install the RPM or Debian package and run aws-emulator.
Windows and macOS: run it in a container built from a short Dockerfile (AWS's getting-started guide has the file).
From source: cargo build -p aws-emulator-router, then cargo run -p aws-emulator-router, which serves HTTPS on 127.0.0.1:9297 with a self-signed certificate. Plan for at least 100 GB of free disk for the build.

There is also an embedded mode for Rust projects, where the emulator runs inside your test process as a dev-dependency instead of as a separate server.

AWS's News Blog launch post says plainly that it "is generally available today." The license is CC0, a public-domain dedication, with a vendor/ folder under Apache 2.0. No AWS account is needed and the README says there is no additional service fee. AWS is already shipping fixes at a fast clip: the releases page showed a run of v1.0.x builds over November 8 to 11, with v1.0.322 marked latest, and notes like "cognito-idp-getuser-refuses-a-revoked-access-token."

How agents built it, and why that matters to you

The companion post by AWS engineer Matthew Goldberg on About Amazon tells the build story, and it is the most useful part of the launch.

He started with a hunch. If you give an agent the public API models AWS already publishes (machine-readable descriptions of every request and response, written in a format called Smithy) and let it compare its work against the real cloud, can it build a working service? He gave Kiro, AWS's AI coding tool, a simple prompt. A first version of SQS came back in about 15 minutes.

Then came the part that made it a product. Goldberg describes three teams of agents: one writes tests, one finds problems, one fixes them. The tests are "fidelity tests," which is a plain idea with a fancy name. Each test sends a request to real AWS, records what comes back, and then checks that the emulator gives the same answer. AWS says there are tens of thousands of them, and they can be replayed later without calling AWS at all. Any test that fails becomes an issue. Fixes pass through a merge gate (the automated checkpoint code must clear before it lands) that runs build, code review, security and fidelity regression checks.

Swami Sivasubramanian's guest post states the lesson behind it: "the engineer's job is to give them room to work on their own and to build the specs, tests, and merge gates that decide when that work is correct" (All Things Distributed).

Notice what that sentence assumes. The agents only got good once they had something to check their work against. The post says it took four nights of supervision before an agent had a way to check its own results.

That is the real insight here, and it applies far beyond AWS. An agent's code is only as reliable as the thing it can test against. The emulator is AWS handing your agent the same kind of checking environment AWS's own agents needed.

Putting it to work: the lowest-friction setup

Here is the shortest path from zero to an agent that tests its own AWS code.

1. Let the agent install it. AWS ships the emulator as an agent skill (a packaged set of instructions an agent loads for a specific job). With AWS CLI 2.35.0 or later:

aws agent-toolkit add-skill --skill-name aws-emulator --region us-east-1

After that you can ask your agent to set up the emulator for the project, and the skill tells it how.

2. Turn telemetry off. The emulator collects usage data by default. The README says the records never include request or response contents, your code, credentials or personal data, but there is no reason to leave it on in a test environment. Pick one:

aws-emulator --telemetry off          # this process only
export EMULATOR_TELEMETRY=off         # every run in this shell

Or set enabled = false under [telemetry] in ~/.aws/emulator/config.toml.

3. Point your code at it, not at AWS. The README says to set environment variables for the endpoint and links to AWS's guide for pointing SDKs at the emulator. AWS's SDKs and CLI already support a custom endpoint through the AWS_ENDPOINT_URL setting (AWS SDK reference), so in most projects this is one variable in your test config, not a code change. Because the emulator uses a self-signed certificate, expect to tell your client to trust it. AWS's launch post says server mode writes its own credentials, a config file and that certificate to ~/.aws/emulator/9297/, so point your test setup there and keep real credentials out of it.

4. Give the agent a rule it cannot skip. Put a line in your agent instructions file (CLAUDE.md, AGENTS.md or equivalent):

Before proposing any change that calls AWS, run the integration tests against the local AWS Emulator and include the test output in your summary. Never use real AWS credentials in this repo's test runs.

This is the step that changes behavior. Without it, the agent has a simulator and no reason to use it.

What to expect. The first run is where you find out which services your code touches and how well each is covered. Fast, offline test runs for the services that work well. Clear failures where your code is wrong. And now and then a failure where the emulator is wrong, which is the case the next section is about.

The part to be honest about: who grades the simulator?

AWS's agents wrote the emulator. AWS's agents wrote the fidelity tests. AWS's merge gate decides when a fix is good enough. That is a closed loop, and it is fine for what the tool claims to be. It is worth naming anyway, because it shapes how much a green test run means.

Some specifics from AWS's own pages:

Fidelity varies by service. The README says so directly and tracks known gaps in an issues/things-that-do-not-work/ folder, with fixed items moved to issues/things-that-now-work/.
The scores are not where the README says they are. The README says fidelity scores are published with each release. Several November 8 releases carried the note "Scores are not available for this release," and the latest release page showed no scores when checked on November 11. Until they appear, you cannot see at a glance how close any given service is to the real thing.
It is not for security testing. The README is blunt: "Don't use it for production workloads or to test security." AWS's launch post goes further: the emulator does not evaluate IAM policies (AWS's permission rules) or resource-based policies (permission rules attached to a bucket or queue itself) the way AWS does, "so a request that AWS denies might succeed in the emulator." Each emulator also acts as a single account, with no cross-account or cross-Region behavior. That rules out the one thing many teams would most like to check locally, which is whether their permissions block what they should.
You cannot fix it yourself. The repository does not take pull requests. You report bugs and fidelity gaps as GitHub issues and wait for AWS's agents to fix them.

None of this makes the tool bad. It makes it a simulator. Pilots train in simulators constantly, and nobody skips the check ride in a real plane.

A sane way to fit it into an agent workflow

The pattern that holds up is two tiers.

Inner loop, local and free. The agent writes code, runs tests against AWS Emulator, fixes what breaks, and repeats. This is where the emulator earns its keep: hundreds of test runs that cost nothing and never touch a real account or a real credential.

Merge gate, one real check. Before code lands, run a small smoke test (a few quick calls that prove the basics work) against a real, isolated AWS account set up only for testing, with tightly scoped permissions. A handful of calls covering the services you depend on is enough. If the local run was green and the real run is red, you have found a fidelity gap, and AWS wants you to report it.

The second tier is also where you keep one check that nobody selling you the tool wrote. AWS publishes its fidelity tests in a separate evaluation suite, which is a good start for seeing what is covered. Your own smoke test is what tells you whether your code works on your account, with your policies, in your region.

Honest limitations

New and moving fast. It launched November 11 and shipped multiple releases a day just before launch. Expect behavior to change under you; pin a version for CI (continuous integration) runs.
Generally available, but young. AWS calls it GA, and the fidelity scores the README promises were not visible on the latest release. GA here means supported, not finished.
Mac and Windows go through a container you build. Native packages are Linux only, and AWS does not publish a ready-made image.
Source builds are heavy. 100 GB of free disk is a real ask on a laptop.
Telemetry is on until you turn it off.
Agents still need a rule. Installing the emulator does nothing if your agent instructions do not require using it.

The bigger point

The most interesting thing about AWS Emulator is not the emulator. It is the admission inside it. AWS could not get agents to build reliable software until it gave them something to check their work against. Then it built that checking environment, at scale, and handed it to everyone.

Your agents have the same problem on a smaller scale. Install the skill, switch telemetry off, add one line to your agent instructions, and keep one real-cloud test at the merge gate. Then watch how many of your agent's AWS mistakes it now catches on its own, and how many it still does not.

Sources: AWS Emulator repository and README (reviewed at v1.0.322, November 11, 2026) · AWS Emulator releases · All Things Distributed, "AWS Emulator and the engineer's job when agents write the code" · About Amazon, "How autonomous AI agents built AWS Emulator" · AWS News Blog launch post · AWS Emulator evaluation suite · AWS SDKs and Tools reference, service-specific endpoints