DEV Community

Evan
Evan

Posted on AI-assisted

Trying Out AWS Emulator: A Free, Local Alternative to LocalStack

#aws #infrastructure #testing #tools

One of the great things about building on AWS is the range of tools available to developers. I've used LocalStack for a lot of my application's API testing. It lets me confirm that my code will work in AWS without deploying it, which saves money, time, and frustration when things go wrong.

AWS recently launched a new tool called AWS Emulator, which got me thinking: why use LocalStack if AWS Emulator is free? I made the switch today to try it out, and so far I love it. Creating and managing S3 buckets, pushing messages to SQS queues, and setting up batch jobs all happen in a simulated, low-risk environment. That makes it much easier for developers like me to experiment with services we might not try in a real AWS account because of cost or security restrictions.

Building the Docker Image

I already use Docker, so running the emulator in a container was easy. The Dockerfile is short:

FROM public.ecr.aws/amazonlinux/amazonlinux:2023-minimal
ADD https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-aarch64.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
Enter fullscreen mode Exit fullscreen mode

Note on architecture: Make sure the RPM matches the architecture of the machine you're running on. On ARM (for example, Apple Silicon Macs), use the aarch64 RPM shown above. On x86, swap in the x86_64 RPM instead.

Build the image:

docker build -t aws-emulator .
Enter fullscreen mode Exit fullscreen mode

Creating the Emulator Directory

Next, create a local directory to mount into the container. The emulator writes its credentials, config, and CA certificate here.

macOS / Linux:

mkdir -p ~/.aws/emulator
Enter fullscreen mode Exit fullscreen mode

Windows (PowerShell):

New-Item -ItemType Directory -Force "$env:USERPROFILE\.aws\emulator"
Enter fullscreen mode Exit fullscreen mode

Running the Container

Now run the container with the new directory mounted.

macOS / Linux:

PORT=9297
docker run --rm --memory=2g --memory-swap=2g -p 127.0.0.1:$PORT:$PORT \
  -e HOME="$HOME" -v "$HOME/.aws/emulator:$HOME/.aws/emulator" \
  aws-emulator -p $PORT
Enter fullscreen mode Exit fullscreen mode

Windows (PowerShell):

$port = 9297
docker run --rm --memory=2g --memory-swap=2g -p "127.0.0.1:${port}:${port}" `
  -v "$env:USERPROFILE\.aws\emulator:/home/emulator/.aws/emulator" `
  aws-emulator -p $port
Enter fullscreen mode Exit fullscreen mode

Pointing the AWS CLI at the Emulator

Open a new terminal and set the following environment variables so the AWS CLI and SDKs talk to the emulator instead of real AWS.

macOS / Linux:

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
Enter fullscreen mode Exit fullscreen mode

Windows (PowerShell):

$env:AWS_ENDPOINT_URL = "https://127.0.0.1:9297"
$env:AWS_SHARED_CREDENTIALS_FILE = "$env:USERPROFILE\.aws\emulator\9297\emulator_credentials"
$env:AWS_CONFIG_FILE = "$env:USERPROFILE\.aws\emulator\9297\config"
$env:AWS_CA_BUNDLE = "$env:USERPROFILE\.aws\emulator\9297\ca.pem"
$env:AWS_EC2_METADATA_DISABLED = "true"
$env:AWS_DISABLE_HOST_PREFIX_INJECTION = "true"
$env:AWS_REGION = "us-east-1"
$env:AWS_DEFAULT_REGION = "us-east-1"
Enter fullscreen mode Exit fullscreen mode

Using It

From here, the AWS CLI works as normal. I can run OpenTofu, run AWS CLI commands, and test my configuration before it ever touches a real account.

This is especially useful with boto3 or other AWS SDKs. I can validate my code before moving to a real AWS account, which makes me much more comfortable trying a service I haven't used before. I know the configuration and code I've written will behave in AWS the way I expect.

Here I'm listing an S3 bucket I created:

$ aws s3 ls
2026-11-12 19:02:05 test-bucket
Enter fullscreen mode Exit fullscreen mode

I can also see the contents of the bucket, which I'd uploaded earlier with aws s3 sync dist/ s3://test-bucket:

$ aws s3 ls s3://test-bucket/
                           PRE __nuxt_content/
                           PRE _nuxt/
                           PRE _studio-app/
                           PRE documents/
                           PRE images/
2026-11-12 19:02:33     131744 og-image.png
2026-11-12 19:02:33        138 robots.txt
2026-11-12 19:02:33       1403 sitemap.xml
Enter fullscreen mode Exit fullscreen mode

Wrapping Up

This is a pretty basic example, but it shows how useful AWS Emulator can be. It's a safe, free sandbox for validating your work before it reaches AWS, and that's valuable for your infrastructure, your software, and even your operations team.

For AWS-specific work, I'd highly recommend AWS Emulator. LocalStack still has its place, especially if you need to emulate tools like Snowflake or Microsoft Azure. But when it comes to value in the AWS world, AWS Emulator is the better option. It will be interesting to see whether LocalStack adapts by offering features AWS Emulator doesn't have yet.

Top comments (0)