
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.
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:
- You start the emulator on your computer.
- You set environment variables like
AWS_ENDPOINT_URLto point to the emulator.
- You run your Python, Node.js, or Java code as usual.
- The AWS SDK sends the API call to the emulator.
- The emulator processes the call and returns a response.
- 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 Ubuntusudo dpkg -i aws-emulator-x86_64.deb
# For Amazon Linux or RHELsudo rpm -i aws-emulator-x86_64.rpmAfter installation, you can start it by running:
bash
aws-emulator -p 9297On 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 1000ENV HOME=/home/emulatorEXPOSE 9297ENTRYPOINT ["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 9297Important: 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 firstunset AWS_ACCESS_KEY_IDunset AWS_SECRET_ACCESS_KEYunset AWS_SESSION_TOKENunset AWS_PROFILE
# Point to the emulatorexport 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-identityYou 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-bucketUpload a file:
bash
echo "Hello from AWS Emulator" > test.txtaws 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_REQUESTPut 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.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article