supraj.dev

Cloud · Explainer

What is AWS Emulator?Think of a flight simulator.

AWS released a program that pretends to be AWS on your own computer. Here is what it is, and what it isn't.

Supraj Maripeddi · · 9 min read

Cover: a laptop or CI box containing AWS Emulator, with SDK and CLI calls going to it and a faded real AWS cloud outside that is never touched.
Start hereYou should know what an API call is. No AWS account needed.
Leave knowingWhat AWS Emulator is, how a request travels through it, and its limits.
Keep in mindIt's for building and testing. It is not for production.

AWS announced AWS Emulator on 11 November 2026. The short version: it is a program that answers AWS API calls on your own machine, so you can test your AWS code without touching the real cloud. [1]

This is the explanation for someone who has never used it. I'll use one picture all the way through: a flight simulator. Everything about AWS Emulator here comes from AWS's announcement, documentation and README. I haven't run the emulator myself, and the hands-on chapter says so again where it matters.

01 / The simulator

What is AWS Emulator?

A pilot doesn't learn to land by crashing a real plane. A pilot sits in a simulator. The controls are the real controls. But no fuel is burned, and a crash costs nothing.

AWS Emulator is that simulator for AWS. AWS describes it as 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. [2]

It is a local program that serves an AWS API endpoint, and it has no graphical interface. After you start it, you set environment variables to point the AWS CLI or an AWS SDK at its address. Then you run your code as usual. [2]

Figure 1 / Cockpit, simulator, plane

Tap a layer to see its job.

AWS Emulator: the simulator. It runs on your machine or in your CI job, answers the calls it supports, keeps resources in memory, and returns 501 for operations it hasn't implemented.

My simplified map, not an AWS diagram. The emulator sits between your code and the real cloud, and your requests go to it instead of to AWS. [2]
In the flight simulator
The controls are real. The plane, the fuel and the sky are not.
In the system
The SDK and CLI calls are real. The AWS account and the AWS resources are not involved.

02 / Why it matters

Why does it matter?

There are four reasons, and they are the same four reasons a pilot uses a simulator.

  • Speed. Your SDK and CLI calls go to the emulator and return in milliseconds, with no deployment. [1]
  • Cost. There is no additional service fee. You pay only for AWS resources when you deploy on AWS. [2]
  • Coding agents. AWS gives its own example. A coding agent creates a DynamoDB table, tests against it offline, and fixes its code before deploying. [1] A mistake in the simulator costs nothing.
  • CI. You can run integration tests in your pipeline with no AWS account and no AWS resources. [2]

There is one more thing that makes this practical. Each copy you start gets its own port, keys and in-memory state. So agents, test suites and CI jobs never see each other's resources. [1] Every pilot gets their own simulator.

In the flight simulator
Practise as often as you like. Nobody pays for fuel, and nobody else is in your cockpit.
In the system
Test as often as you like. No bill, and your tests don't share state with other jobs.

03 / One request

How does one request travel through it?

Three ideas explain most of how it works.

  • It speaks the same language. The services are generated from the API models that AWS publishes, the same models behind the AWS SDKs. So the emulator accepts the calls your code already sends. [1]
  • It aims to answer the same way. For supported operations it returns the same result as AWS for a valid call, and the same error for an invalid one. AWS says the behaviour is filled in and verified release by release. [1]
  • It tells you when it doesn't know. If it hasn't implemented an operation yet, it returns HTTP 501 with the error code NotImplemented, and a test that calls it fails right away. [3]

Now follow one call from your code, step by step.

Figure 2 / From call to answer

Follow one request.

How a request travels through AWS Emulator Your code or the AWS CLI sends a request to AWS Emulator on your machine, at address 127.0.0.1 port 9297. The emulator answers, keeping resources in an in-memory state. For an operation it has not implemented, it answers 501. Real AWS sits outside, faded, and is never called. Your machine or CI job Your code or the AWS CLI AWS Emulator 127.0.0.1:9297 In-memory state gone when it stops call answer stored 501 Real AWS never called
  1. 1 · SendYour code or the AWS CLI sends the usual call to the emulator's address, signed with keys the emulator made when it started.
  2. 2 · Check the keysBy default the emulator requires a signed request, as AWS does. Real credentials left in your shell are rejected.
  3. 3 · AnswerIf it supports the operation, it replies as AWS would, with a result or the same error, and keeps resources in memory.
  4. 4 · Not modelled yetIf it hasn't implemented the operation, it replies 501 NotImplemented, so the test fails right away.
  5. 5 · StopPress Ctrl+C. Everything held in memory is deleted, along with the files it wrote.
Whole picture
My own drawing, built from AWS's documentation. [4] [2] The default address is 127.0.0.1 on port 9297, and the signature rule applies when it runs as a local process. [4] The five steps are my split of how the docs describe it.

How close is "the same answer"? AWS measures it with fidelity tests. A fidelity test is a short program that uses an AWS SDK to run a workflow against an AWS service and checks how AWS behaves. A fidelity score is how many of those tests the emulator passes for a service, such as 40 of 50. AWS publishes the scores with each release. [3]

The docs say the emulator matches AWS most closely for control plane APIs, the ones that create, describe, update, delete and list resources. Fidelity for data plane APIs, and support for infrastructure as code tools like CloudFormation, Terraform and the AWS CDK, varies by service. [3] Check the score for the services you use before you rely on it.

In the flight simulator
Pull the lever and the plane responds. A manoeuvre the simulator hasn't modelled yet stops the exercise at once.
In the system
Make a call and the emulator answers. An unsupported call returns 501.

04 / Hands-on run

What does a short hands-on run look like?

These steps come from AWS's own documentation. They were not run for this article, so check the docs if anything differs on your machine. [5] [4]

Step 1: install and start it. On Linux, AWS provides RPM and Debian packages. For example, on a Debian-based x86_64 machine: [5]

curl -fsSLo aws-emulator.deb https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_amd64.deb
sudo apt-get install -y ./aws-emulator.deb
aws-emulator -v

Then start it. It keeps running in that terminal.

aws-emulator

By default it serves HTTPS on 127.0.0.1:9297, so only your own machine can reach it. [5] On macOS and Windows you run it in Docker instead, from an image you build with a short Dockerfile from the AWS docs. AWS doesn't publish a prebuilt image. [6]

Step 2: point your tools at it. In a second terminal, set these variables. They tell the AWS CLI and SDKs where the emulator is and which keys to use. When the emulator starts, it generates fresh keys and writes them under ~/.aws/emulator/9297/. [4]

export AWS_ENDPOINT_URL=https://127.0.0.1:9297
export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials
export AWS_CONFIG_FILE=~/.aws/emulator/9297/config
export AWS_CA_BUNDLE=~/.aws/emulator/9297/ca.pem
export AWS_EC2_METADATA_DISABLED=true
export AWS_DISABLE_HOST_PREFIX_INJECTION=true
export AWS_REGION=us-east-1
export AWS_DEFAULT_REGION=us-east-1
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE

The last line matters. If real credentials stay in your shell, your tools sign requests with them and the emulator rejects the requests. [4]

Step 3: check you are in the simulator, not the real plane.

aws sts get-caller-identity

The docs say the emulator uses one account, 000000000000. If you see your own account ID instead, your requests are going to AWS. Stop and check your variables. [4]

Step 4: build something. Create a bucket and list it, using AWS's own example: [2]

aws s3api create-bucket --bucket amzn-s3-demo-bucket
aws s3api list-buckets --query 'Buckets[].Name'

Now try a mistake on purpose. DynamoDB table names must be at least 3 characters, so this call should fail the way it fails on AWS: [2]

aws dynamodb create-table --table-name ab \
    --attribute-definitions AttributeName=id,AttributeType=S \
    --key-schema AttributeName=id,KeyType=HASH \
    --billing-mode PAY_PER_REQUEST

The docs show a ValidationException saying the table name must have length greater than or equal to 3. [2] That is the point of the tool: your code meets the same errors it would meet in the real cloud, and nothing was deployed.

Step 5: stop it. Press Ctrl+C in the emulator terminal. It deletes its files and all emulated resources, because it keeps resources only in memory. [5] To run several at once, give each its own port with aws-emulator -p <port> and use that port in the variables above. [5]

One warning from the docs. If AWS_ENDPOINT_URL isn't set in the shell that runs your tests, your code calls real AWS with whatever credentials it finds. Set the variables in the same script that runs your tests, and keep real credentials out of your test jobs. [4]

In the flight simulator
Check the screen says "simulator" before you fly. Then crash all you like.
In the system
Check get-caller-identity shows the emulator's account before you test.

05 / What it can't do

What does it not do?

A simulator is not the sky. These are the limits AWS lists.

  • State disappears. The emulator keeps all resources in memory and deletes them when it stops. A restart also gives your tests a clean state. [2]
  • Some operations return 501. Unsupported operations return 501 Not Implemented. Coverage differs by service, so check the fidelity scores. [1] [3]
  • It is not a security test. It doesn't evaluate IAM policies and resource-based policies the way AWS does. Don't use it to test security. [2]
  • One Region and one account. It accepts any Region and account ID but doesn't keep resources separate by them. Use one of each per emulator. [2]
  • Not for production, load or long runs. AWS says it is for building and testing, and hasn't tested it for long-running use or load testing. [2]
  • It isn't real AWS. AWS checks its behaviour against the real service in one Region, so differences can exist. Test on real AWS before production. [2] [3]
  • It runs natively only on Linux. On macOS and Windows you use Docker. [7]
In the flight simulator
Hours in the simulator don't replace a check flight in the real plane.
In the system
Passing tests on the emulator don't replace testing on real AWS before production.

06 / When to use it

When should you use it?

Use it when:

  • You want fast, free, repeatable tests for code that calls AWS.
  • You run CI and don't want an AWS account in the pipeline.
  • A coding agent should try its code safely before anything reaches the cloud.
  • You want each developer, test suite or job to have its own isolated state.

Don't use it as your only test. To see whether your own project is expected to work, check the fidelity tests and scores for the operations you call. AWS also offers an aws-emulator skill for coding agents that does this check for you. [8]

Community tools in this space already existed. LocalStack describes itself, in its README, as a framework to develop and test AWS applications locally. [9] Moto describes itself as a library that lets tests mock out AWS services. [10] They are separate projects with their own terms, so read their own pages for licence, pricing and status before you choose. This article doesn't compare them with AWS Emulator.

The tool is new. AWS publishes the source under CC0 1.0 Universal, except the vendor/ directory, which is under Apache License 2.0. [7] Treat the fidelity report as your guide to what works today.

In the flight simulator
Use it to practise often and safely. Then fly the real plane with a check.
In the system
Use it for fast, safe tests. Then run the same checks on real AWS.

Keep these names

A small glossary

AWS Emulator
A local emulator of the AWS APIs that you use to test software without calling AWS. [2]
Endpoint
The address your tools send requests to. For the emulator it is https://127.0.0.1:9297 by default. [4]
AWS SDK and AWS CLI
The libraries and the command-line tool you use to call AWS. You point them at the emulator with environment variables. [2]
SigV4
Signature Version 4, the way AWS signs API requests. The emulator requires it by default when it runs as a local process. [4]
501 Not Implemented
What the emulator returns, with the error code NotImplemented, for an operation it hasn't implemented yet. [3]
Fidelity test
A short program that uses an AWS SDK to run a workflow against an AWS service and checks how AWS behaves. [3]
Fidelity score
For each service, the number of fidelity tests the emulator passes out of the total, such as 40 of 50. [3]
Control plane
The APIs that create, read or describe, update, delete and list resources, such as creating an S3 bucket. [3]
Data plane
A service's primary function, such as getting and putting objects in an S3 bucket. [3]
In-memory state
The resources the emulator keeps in memory. They are deleted when it stops. [2]

Check the concept

Can you explain it back?

1. Do you need an AWS account to run AWS Emulator?

No. Your requests go to the emulator, not to AWS, and there is no additional service fee.

2. What happens if you call an operation the emulator hasn't implemented?

It returns HTTP 501 with the error code NotImplemented, so a test that calls it fails right away.

3. Two CI jobs each start an emulator. Do they see each other's resources?

No. Each copy gets its own port, keys and in-memory state.

4. What happens to your resources when you stop the emulator?

They are deleted, because the emulator keeps them only in memory.

5. Is passing tests on the emulator enough to ship?

No. It is for building and testing, and its behaviour can differ from AWS. Test on real AWS before production.

Continue the thread

Now look at testing and access.

The emulator helps you test earlier. These articles cover the pipeline it runs in and the access rules it doesn't check: what CI/CD and environments are and least-privilege IAM with an agent.

Read further

Sources

AWS Emulator references use AWS's announcement, user guide and README. Sources accessed 18 November 2026.

  1. AWS: AWS Emulator is now available (11 November 2026).
  2. AWS Emulator User Guide: What is AWS Emulator?
  3. AWS Emulator User Guide: Fidelity in AWS Emulator.
  4. AWS Emulator User Guide: Pointing your AWS SDK at AWS Emulator.
  5. AWS Emulator User Guide: Getting started on Linux.
  6. AWS Emulator User Guide: Getting started with Docker.
  7. AWS Emulator User Guide: Setting up AWS Emulator. Also the project README on GitHub.
  8. AWS Emulator User Guide: Checking whether your project works with AWS Emulator.
  9. LocalStack: project README.
  10. Moto: project README.

Written with AI assistance. Technical sources are listed above.