Have you ever tried building an app on AWS, only to get frustrated by how long it takes to deploy your code just to test a small change? Not to mention the worry of accidentally racking up an unexpected cloud bill!
AWS has just released something that changes the game: the AWS Emulator. It is a brand-new, completely free tool that lets you run and test your AWS applications directly on your own computer. The coolest part? Every single line of code for this emulator was written by autonomous AI agents.
Here is everything you need to know about what it is, why it’s awesome, and a hands-on guide on how you can start using it today.
Think of AWS Emulator as a "mini-AWS" that lives entirely on your laptop. When you write code that needs to talk to AWS services (like saving a file to an S3 bucket or reading a database in DynamoDB), you usually have to send that request over the internet to the actual AWS cloud.
With the emulator, your code talks to your local machine instead. It mimics how real AWS behaves, returning the exact same successful results and error messages you would get in the cloud.
It works by using a clever trick. When you run AWS tools (like the Command Line Interface or SDKs), they are programmed to send requests to AWS servers. The emulator starts up a local HTTPS endpoint on your computer. All you have to do is change a single setting (an environment variable) to point your tools to that local endpoint instead of the internet. Your code doesn't know the difference—it thinks it's talking to the real AWS!
If you want to test AWS services without spending a dime or connecting to the internet, let's get our hands dirty. In this tutorial, we will install the emulator, configure our tools, and run a simple test: creating a local Amazon S3 bucket, up a file, and listing its contents.
The emulator runs as a lightweight local server on your machine. How you install it depends on your operating system.
🐧 For Linux (Ubuntu/Debian)
Linux runs the emulator natively without needing any container software. You can download and install the package with two simple commands:
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
(Note: If you are using a Red Hat/CentOS based system, AWS provides an .rpm package you can install using dnf.)
To start it, just type:
aws-emulator
🍎 For macOS & 🪟 Windows
Because the emulator is natively built for Linux, macOS and Windows users will run it using Docker.
To get set up, you will build a simple Docker image. For the exact setup steps and configuration commands, check out the Official AWS Emulator Docker Guide.
Once you start the container following the link above, the emulator will quickly generate its own local credentials and configuration file securely on your machine.
By default, when you type a command like aws s3 ls, the AWS CLI tries to connect to the real cloud over the internet. We need to tell it to look at our local emulator instead.
Open a new terminal window (leave the emulator running in the first one) and set your environment variables to point to the local server:
On Linux/macOS:
export AWS_CONFIG_FILE=~/.aws/emulator/9297/config
export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials
On Windows (PowerShell):
$env:AWS_CONFIG_FILE="$env:USERPROFILE\.aws\emulator\9297\config"
$env:AWS_SHARED_CREDENTIALS_FILE="$env:USERPROFILE\.aws\emulator\9297\emulator_credentials"
Your system is now officially sandboxed! Your CLI doesn't know the difference, but it is now talking directly to your laptop.
Let's test it out by acting like we are using Amazon S3.
1. Create a Bucket
We will create a bucket called my-local-test-bucket. Type this into your terminal:
aws s3api create-bucket --bucket my-local-test-bucket
The emulator will instantly return a success message, exactly like the real AWS would.
2. Create and Upload a File
Let's create a quick text file on your computer and upload it to our new local bucket.
echo "Hello from the emulator!" > hello.txt
aws s3 cp hello.txt s3://my-local-test-bucket/
You should see a message saying upload: ./hello.txt to s3://my-local-test-bucket/hello.txt.
3. List the Objects in Your Bucket
Finally, let's ask our local S3 bucket what it has inside it:
aws s3 ls s3://my-local-test-bucket/
It will print out the details of hello.txt.
4. Cleaning Up
When you are done, simply go back to the terminal where the emulator is running and press Ctrl+C. Because the emulator stores everything in your computer's memory, the moment you shut it down, your my-local-test-bucket and its contents vanish cleanly. No lingering files, and definitely no surprise billing charges!
This simple S3 test just scratches the surface. You can use the AWS Emulator to test complex architectures, wire up DynamoDB tables, use SQS queues, and safely run AI coding agents.
If you want to master local cloud testing, here are the best resources to explore next: