AWS Emulator is the free local emulator for AWS: it runs over 200 AWS services on your machine, without an account or token. AWS launched it on November 11, 2026. The AWS CLI and AWS SDKs connect to it with just a few environment variables, so your code doesn’t change. It’s AWS’s first official answer to the gap that opened in March, when LocalStack started requiring an account and authentication token.
What is AWS Emulator?
AWS Emulator is a local emulator of AWS APIs: a headless process that serves an AWS API endpoint. Requests that would go to AWS go to it instead. You can run it on your laptop, a development server, or in CI.
According to the launch post by Swami Sivasubramanian on Werner Vogels’ blog, it covers over 200 services and is built from over 400 API models. Those models are written in Smithy, the format AWS uses to describe the operations, inputs, outputs, and errors of each service.
You have four ways to run it:
- Linux: an RPM or Debian package, for x86_64 or arm64.
- macOS and Windows: a Docker container you build from a short Dockerfile.
- Tests in Rust: embedded mode, which runs the emulator inside the test process so each test has its own isolated state.
- From your code agent: an
aws-emulatorskill that installs with the AWS CLI.
Is AWS Emulator free?
Yes. There’s no service fee and you only pay for real resources when you deploy to AWS. The code is published under CC0 1.0, a public domain dedication, except the vendor/ directory, which comes with Apache 2.0. It’s an unusually permissive license for an AWS project.
Before adopting it, it’s worth knowing two things:
- Telemetry is enabled by default. The emulator sends anonymous usage and error data. AWS says it doesn’t send your requests, responses, or resource data. Below we explain how to turn it off.
- The repository doesn’t accept pull requests. Bugs and fidelity differences are reported in GitHub Issues.
Is AWS Emulator the free alternative to LocalStack?
For anyone who wants to test without an account, yes: that’s the main difference. On March 23, 2026, LocalStack stopped supporting its Community edition. The localstack/localstack:latest image now requires an account and a LOCALSTACK_AUTH_TOKEN, and commercial use requires a paid plan. LocalStack still offers a free plan for non-commercial use, and the old Community tags still boot without a token, though they no longer receive security updates. The details, and what to check before migrating, are in our guide Floci vs LocalStack.
AWS Emulator doesn’t need an account or token. It generates its own local credentials every time it boots.
That said, migrating isn’t just swapping one image for another. AWS Emulator serves HTTPS on port 9297 with a self-signed certificate, so each SDK has to trust its CA file (you’ll see it in the table below). If your tests assume plain HTTP on a different port, you’ll need to adjust that configuration.
If you search for localstack alternatives in English, this is the news that changes the list: the first option coming from AWS itself.
AWS Emulator, Floci, or MiniStack?
Floci, MiniStack, and other community projects filled LocalStack’s gap this year. Floci positions itself as a free LocalStack replacement, with MIT license and no token. We already covered them: Floci vs LocalStack and MiniStack.
What AWS Emulator brings is its origin: it comes from AWS, is built with AWS’s own API models, and its fidelity tests are verified against real AWS. What you still can’t do is compare coverage service by service, because AWS hasn’t published the list of the 200+ services (we explain why below).
How to install AWS Emulator on Linux?
Install the package for your distribution and architecture.
RPM (x86_64):
sudo dnf install -y https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-x86_64.rpm
RPM (aarch64):
sudo dnf install -y https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-aarch64.rpm
Debian (amd64):
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
Debian (arm64):
curl -fsSLo aws-emulator.deb https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_arm64.deb
sudo apt-get install -y ./aws-emulator.deb
Confirm the installation and start it:
aws-emulator -v
aws-emulator
It listens on 127.0.0.1:9297 and stays in the foreground. Use -p 9300 for another port, or -p 0 to let the operating system pick a free one (you’ll see it in the endpoint_url field in the startup log). To stop it, press Ctrl+C: there’s no stop command.
The documentation also describes an optional GPG verification of the package before installing it.
There’s no cargo install. The repository is a Rust workspace, but the crates aren’t published on crates.io. Building from source only works on Linux and needs at least 100 GB free for target/, a C compiler, and a multi-core machine.
Does AWS Emulator work on Windows or Mac?
Only with Docker: there’s no native package for either. Save this Dockerfile, taken from the official documentation:
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"]
On Apple Silicon or other Arm machines, change aws-emulator-x86_64.rpm to aws-emulator-aarch64.rpm on the ADD line.
Build and run it on macOS:
docker build -t aws-emulator .
mkdir -p ~/.aws/emulator
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
On Windows PowerShell (after the same docker build -t aws-emulator .):
New-Item -ItemType Directory -Force "$env:USERPROFILE\.aws\emulator"
$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
Two details from the documentation that matter:
- Keep the
127.0.0.1:prefix. The short form-p 9297:9297exposes the emulator to your entire network. - The host and container ports must match the value of
-pfor the emulator, because the emulator writes its port to the files it creates. For the same reason,-p 0doesn’t work in a container.
The mounted volume is what lets your SDK read the credentials and certificate that the emulator generates.
How to install AWS Emulator from Claude Code, Cursor, or Kiro?
With a skill for agents. You need AWS CLI 2.35.0 or later (check with aws --version):
aws agent-toolkit add-skill --skill-name aws-emulator --region us-east-1
The command installs the skill in all code agents the AWS CLI finds on your machine; the documentation mentions Kiro, Cursor, and Claude Code as examples. Then ask your agent: “Install AWS Emulator and point my project at it.”
How to connect the AWS CLI and SDKs to the emulator?
Define these environment variables in the terminal where you run your code (macOS and 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
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"
If you changed the port, replace 9297 in all values.
The emulator generates a new access key and secret each time it boots, and they only work for that run. Remove any variable that might provide real AWS credentials, or your SDK could use them instead:
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE
In PowerShell:
Remove-Item Env:AWS_ACCESS_KEY_ID, Env:AWS_SECRET_ACCESS_KEY, Env:AWS_SESSION_TOKEN, Env:AWS_PROFILE -ErrorAction SilentlyContinue
AWS_CA_BUNDLE covers AWS CLI v2, Boto3, and the AWS SDK for Go v2. Other SDKs need their own adjustment:
| SDK | Adjustment |
|---|---|
| JavaScript v3 (Node.js) | NODE_EXTRA_CA_CERTS pointing to ca.pem |
| Java 2.x | JAVA_TOOL_OPTIONS pointing to the emulator’s truststore.p12 |
| Rust | SSL_CERT_FILE pointing to ca.pem |
| .NET | SSL_CERT_FILE pointing to ca.pem |
For Java, the documentation gives this value on macOS and Linux:
export JAVA_TOOL_OPTIONS="-Djavax.net.ssl.trustStore=$HOME/.aws/emulator/9297/truststore.p12 -Djavax.net.ssl.trustStoreType=PKCS12"
Warning: that trust store replaces the JVM’s, so calls to real AWS will fail in that same process unless you add ca.pem to a bundle that also includes your system’s certificates.
Verify it works:
curl --cacert ~/.aws/emulator/9297/ca.pem https://127.0.0.1:9297/__admin/health
aws sts get-caller-identity
Against the emulator, Account returns 000000000000 and the ARN is arn:aws:iam::000000000000:user/emulator.
How to turn off AWS Emulator telemetry?
With any of these three options:
- Flag:
aws-emulator --telemetry off(or-t off). In Docker, put it after the image name. - Environment variable:
EMULATOR_TELEMETRY=off. - Config file: in the
[telemetry]section, setenabled = falsein~/.aws/emulator/config.toml(on Windows,%USERPROFILE%\.aws\emulator\config.toml).
What doesn’t AWS Emulator do?
AWS is straightforward about its limits:
- It’s not for production or security testing. IAM policies and resource-based policies aren’t evaluated the way AWS does them, so a test that passes locally says nothing about your permissions.
- One region and one account per emulator. It accepts any region or account ID, but doesn’t separate resources between them. For multiple regions, run one emulator per region, each on its own port.
- Nothing persists. Resources live in memory and disappear when the emulator stops.
- Not tested for long-running use or load testing. Restart it for a clean slate.
- Fidelity varies by service. It’s only verified in
us-west-2(global services, inus-east-1). The repository maintains a “things-that-do-not-work” folder with behaviors that still don’t match real AWS. - No public list of services. At the time of publishing this note, AWS hadn’t published which 200+ services are covered or numerical fidelity scores. The releases page (latest tag v1.0.322, from November 11) announces scores per release, and earlier releases indicate they’re not available.
The practical divide: use the emulator for the fast development cycle and for CI, and keep a smaller suite against real AWS for anything that depends on IAM, cross-region behavior, or load.
Who wrote AWS Emulator?
Agents wrote it, and AWS says so openly. According to the launch post, agent teams first wrote the fidelity tests (end-to-end scenarios derived from API models) and fixed them until they passed against real AWS. Then they built the emulator until it passed those same tests. Each change goes through a merge gate: several security agents do adversarial reviews, a general reviewer evaluates the change, and deterministic checks prevent agents from touching code they shouldn’t modify. The full commit history and issues opened by agents are public.
It’s an official AWS project, with documentation published on docs.aws.amazon.com. What this says about the work of an engineer when agents write the code is a topic for a separate column.
What about you? Which AWS service would you test in the emulator first before trusting it to your CI?
- LocalStack
- Floci, MiniStack, or another community emulator
- Nothing: I test directly against AWS
- I prefer another option (tell us which)
Comment below or, if this article reached you by email, reply directly to the email: your answer will be published here.