AWS Builder Center
AWS Emulator: Testing AWS Applications Locally Without an Account

AWS Emulator: Testing AWS Applications Locally Without an Account

A complete beginner-friendly guide to AWS Emulator, the new free tool that lets you test AWS API calls on your own machine without an AWS account, covering installation, setup, limitations, and real-world use cases for students and developers.

Cybersecurity Student | Pentester | AWS Cloud Learner
Imagine you are learning AWS. You want to test a simple Python script that creates an S3 bucket and uploads a file. To do this, you need an AWS account, a credit card, and you need to worry about the Free Tier limits. If you make a mistake, you might get a bill.
This is the problem that AWS Emulator solves.
In November 2026, AWS released a free tool called AWS Emulator. It lets you run a local version of AWS on your own computer. You can test your code, create resources, and see how things work without ever touching the real AWS cloud .
This article will explain what AWS Emulator is, how it works, how to install it, and why it is a game-changer for students and developers. We will keep it simple and practical so you can start using it today.

What is AWS Emulator?

AWS Emulator is a small program that runs on your computer. It acts like a fake AWS server. When your code makes an AWS API call (like "create a DynamoDB table"), it goes to the emulator instead of the real AWS cloud .
The emulator creates the resource in your computer's memory. You can list the resource, read it, and delete it. But when you stop the emulator, everything disappears. Nothing is saved to the real AWS .
Key facts about AWS Emulator:
  • It is free. There is no additional service fee. You only pay if you deploy to real AWS later .
  • No AWS account is needed. You can use it without signing up for AWS .
  • It is open source. The code is on GitHub under a public domain license .
  • It is written in Rust. This makes it fast and lightweight on your laptop .
  • AI agents wrote the code. This is a fascinating detail. AWS says no human engineer wrote or reviewed the code. AI agents designed and built the entire emulator .

How Does AWS Emulator Work?

The emulator works by listening on a local web address. When you start it, it runs on  https://127.0.0.1:9297  (or another port if you choose) .
You do not need to change your code. You only need to change environment variables so that the AWS SDK knows to send requests to your local machine instead of the real AWS .
Here is the basic flow:
  1. You start the emulator on your computer.
  1. You set environment variables like  AWS_ENDPOINT_URL  to point to the emulator.
  1. You run your Python, Node.js, or Java code as usual.
  1. The AWS SDK sends the API call to the emulator.
  1. The emulator processes the call and returns a response.
  1. Your code sees the response and continues.
The emulator also creates its own fake credentials. When you run  aws sts get-caller-identity , it returns a fake account ID  000000000000  and a user called  emulator  . This confirms you are connected to the emulator and not the real AWS.

How to Install AWS Emulator

The installation process is different for Linux, macOS, and Windows.

On Linux (Ubuntu, Debian, Amazon Linux)

You can install the emulator directly from a package file.
bash
# For Debian or Ubuntu
sudo dpkg -i aws-emulator-x86_64.deb

# For Amazon Linux or RHEL
sudo rpm -i aws-emulator-x86_64.rpm
After installation, you can start it by running:
bash
aws-emulator -p 9297

On macOS and Windows

AWS does not provide a ready-made installer for macOS and Windows. You need to use Docker.
Here is the Dockerfile you can use :
dockerfile
FROM public.ecr.aws/amazonlinux/amazonlinux:2023-minimal

ADD https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-x86_64.rpm /tmp/aws-emulator.rpm

RUN rpm -i /tmp/aws-emulator.rpm && rm /tmp/aws-emulator.rpm \
&& mkdir -p /home/emulator && chown 1000 /home/emulator

USER 1000
ENV HOME=/home/emulator
EXPOSE 9297
ENTRYPOINT ["aws-emulator", "-b", "0.0.0.0"]
Build the Docker image:
bash
docker build -t aws-emulator .
Run the container:
bash
docker run --rm --memory=2g --memory-swap=2g \
-p "127.0.0.1:9297:9297" \
-v "$HOME/.aws/emulator:/home/emulator/.aws/emulator" \
aws-emulator -p 9297
Important: Bind the Docker port to  127.0.0.1  only. Do not expose it to your entire network. This keeps the emulator safe on your machine .

How to Connect Your Code to AWS Emulator

After starting the emulator, you need to tell your AWS SDK to use it.

Environment Variables

Set these variables in your terminal :
bash
# Remove any real AWS credentials first
unset AWS_ACCESS_KEY_ID
unset AWS_SECRET_ACCESS_KEY
unset AWS_SESSION_TOKEN
unset AWS_PROFILE

# Point to the emulator
export AWS_ENDPOINT_URL="https://127.0.0.1:9297"
export AWS_SHARED_CREDENTIALS_FILE="$HOME/.aws/emulator/9297/emulator_credentials"
export AWS_CONFIG_FILE="$HOME/.aws/emulator/9297/config"
export AWS_CA_BUNDLE="$HOME/.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"
Why each variable matters:
Variable
Purpose
 AWS_ENDPOINT_URL 
Sends all API calls to the local emulator
 AWS_SHARED_CREDENTIALS_FILE 
Uses the emulator's fake credentials
 AWS_CONFIG_FILE 
Uses the emulator's configuration file
 AWS_CA_BUNDLE 
Trusts the emulator's HTTPS certificate
 AWS_EC2_METADATA_DISABLED 
Stops the SDK from looking for real EC2 credentials
 AWS_DISABLE_HOST_PREFIX_INJECTION 
Prevents the SDK from changing the endpoint URL
 AWS_REGION 
Sets a default region (the emulator accepts any region)

Verify the Connection

Run this command to confirm you are connected to the emulator:
bash
aws sts get-caller-identity
You should see:
json
{
"Account": "000000000000",
"Arn": "arn:aws:iam::000000000000:user/emulator"
}
If you see your real AWS account ID, stop and check your environment variables. You are still connected to the real AWS .

A Simple Example: S3 and DynamoDB

Let us test the emulator with a simple example.

Create an S3 Bucket

bash
aws s3 mb s3://my-test-bucket
Upload a file:
bash
echo "Hello from AWS Emulator" > test.txt
aws s3 cp test.txt s3://my-test-bucket/
List the bucket contents:
bash
aws s3 ls s3://my-test-bucket/
You will see  test.txt  in the list. This works exactly like real AWS .

Create a DynamoDB Table

bash
aws dynamodb create-table \
--table-name TestTable \
--attribute-definitions AttributeName=id,AttributeType=S \
--key-schema AttributeName=id,KeyType=HASH \
--billing-mode PAY_PER_REQUEST
Put an item:
bash
aws dynamodb put-item \
--table-name TestTable \
--item '{"id": {"S": "1"}, "name": {"S": "Test Item"}}'
Read the item back:
bash
aws dynamodb get-item \
--table-name TestTable \
--key '{"id": {"S": "1"}}'
The emulator returns the item you just created. This is perfect for learning how DynamoDB works .

What Works and What Does Not Work

AWS Emulator is not a perfect copy of AWS. It supports many services, but some features are not implemented. You must know the limitations before you rely on it.

Supported Services (with Fidelity Scores)

AWS publishes "fidelity scores" that show how closely the emulator matches real AWS. Here are some examples from version 1.0.322 :
Service
Tests Passed
Amazon S3
763 / 924
Amazon DynamoDB
661 / 808
Amazon SQS
286 / 304
AWS IAM
359 / 463
AWS Lambda
293 / 616
Amazon EC2
576 / 1,299
A higher score means the emulator behaves more like real AWS for that service.

Key Limitations

1. IAM Policies Are Not Evaluated Correctly
The emulator does not check IAM policies the way AWS does. A request that AWS would deny might succeed in the emulator. Do not use the emulator to test security permissions .
2. One Account, One Region
The emulator acts as a single account ( 000000000000 ) and does not support cross-account or cross-region behavior. If you need to test multiple regions, you must start a separate emulator for each region on a different port .
3. State is Lost When You Stop
All resources are stored in memory. When you stop the emulator, everything is deleted. There is no persistence .
4. Unimplemented APIs Return HTTP 501
If an API is not implemented, the emulator returns HTTP 501 Not Implemented. This makes it easy to see what is missing, but your tests will fail loudly .
5. No Failure Simulation
The emulator does not simulate throttling, outages, or regional service differences. You cannot use it to test how your application handles failures .

Why This Matters for Students

If you are a student learning AWS, AWS Emulator is a huge benefit.
1. No Credit Card Required
You can practice without signing up for AWS. This removes the fear of surprise bills.
2. Fast Feedback Loop
You can test your code in milliseconds instead of waiting for a cloud deployment. This makes learning faster and less frustrating.
3. Safe Environment for Mistakes
You can delete buckets, break tables, and experiment without consequences. The emulator resets when you restart it.
4. Perfect for CI/CD Pipelines
You can run integration tests in GitHub Actions or other CI tools without AWS credentials. This is a valuable skill for DevOps .
5. AI Agent Development
If you are building AI coding agents, the emulator gives the agent a concrete way to test its own code. The agent can create resources, see the results, and fix errors without human intervention .

The AI Connection: Who Wrote This Code?

One of the most interesting facts about AWS Emulator is that AI agents wrote the code.
AWS Senior Principal Engineer Matt Goldberg said that AI agents designed and wrote the entire service. No human engineers wrote or reviewed a single line of code .
The AI agents used the Smithy API models as a blueprint. They compared their results with real AWS services to verify correctness. For example, when asked to recreate Amazon SQS, the AI produced a working replica in 15 minutes .
This is a significant moment in software engineering. It shows that AI can build complex, production-grade infrastructure tools. But it also raises questions about trust and verification. The emulator's public test suite and fidelity scores are important because they provide evidence that the AI-generated code actually works.

Best Practices for Using AWS Emulator

1. Check Fidelity Scores First
Before you rely on the emulator for a specific service, check the fidelity score. If a service has a low score, do not assume it will work perfectly.
2. Always Test Security on Real AWS
The emulator does not check IAM. After you finish building and testing locally, deploy to a real AWS account and verify that your security policies work correctly.
3. Use One Emulator Per Project
If you are working on multiple projects, start a separate emulator for each project on a different port. This prevents resources from interfering with each other.
4. Clean Up Your Environment Variables
After you finish using the emulator, unset the environment variables. Otherwise, your terminal will keep sending requests to the local emulator even when you want to use real AWS.
5. Use Docker for Isolation
On macOS and Windows, Docker provides a clean, isolated environment. Bind the port to  127.0.0.1  only for security.

Final Summary

AWS Emulator is a powerful new tool that makes learning and testing AWS applications faster and safer. It lets you run AWS locally, without an account, without a credit card, and without the fear of unexpected bills.
For students, it is the perfect sandbox. You can practice S3, DynamoDB, SQS, Lambda, and more. You can build CI/CD pipelines without AWS credentials. You can even use it to test AI-generated code.
The limitations are real. IAM is not checked. Regions are not isolated. State is lost when you stop. But for development and learning, the benefits far outweigh the drawbacks.
The future of cloud development is local-first. AWS Emulator is a big step in that direction.
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article