Skip to content

AWS Emulator: Free Local AWS for Testing With the CLI, SDKs and Coding Agents

AWS Emulator runs AWS APIs locally with no account or fee. How to install it, point the AWS CLI and SDKs at it, use it with coding agents, and its IAM limits.

MGMCSA Guru Team November 15, 2026 8 min read
A laptop projects a miniature cloud of storage, database and queue blocks inside a glowing dome while small robot agents adjust them

AWS released AWS Emulator on November 11, 2026: a local program that serves the same AWS APIs over an HTTPS endpoint on your own machine. The AWS CLI, the AWS SDKs and coding agents such as Kiro or Claude Code talk to it with the calls they’d send to AWS, and the requests never reach a Region. You don’t need an AWS account, AWS charges no service fee for it, and the source is on GitHub under the CC0 1.0 Universal public domain dedication.

The pitch is a faster test loop. AWS’s What’s New post says SDK and CLI calls “come back in milliseconds”, so a test suite or an agent can create a DynamoDB table, write to it and fix its code before anything is deployed. AWS also says the emulator was built, and is maintained, by agents. The limits weigh as much as the speed: AWS Emulator doesn’t evaluate IAM policies, acts as a single account, and AWS says not to use it for production or security testing.

How AWS Emulator works

AWS Emulator is a local server with no graphical interface. When it starts, it generates its own credentials, a config file and a certificate, writes them to ~/.aws/emulator/9297/, and serves HTTPS on 127.0.0.1:9297, so only your own computer can reach it by default.

You then point your tools at it with environment variables. Your application code doesn’t change:

  1. The AWS SDK or CLI reads AWS_ENDPOINT_URL and sends requests to https://127.0.0.1:9297 instead of AWS.
  2. The emulator checks that each request is signed with Signature Version 4 using its own keys. Its generated access key IDs start with EMULATOR, and it rejects requests signed with any other keys.
  3. It handles the call against in-memory state and returns a response with the same shape as AWS, because it’s built from the AWS API models the SDKs use.
  4. If an operation isn’t implemented yet, it returns HTTP 501 Not Implemented, so a test fails right away instead of passing on a fake result.

Each copy you start gets its own port, keys and in-memory state. Parallel agents, test suites and CI jobs therefore don’t see each other’s resources. State lasts until you stop the emulator. Every copy uses one account, 000000000000, and the emulator doesn’t depend on an AWS Region.

The emulator is written in Rust. GeekWire reports that it’s built from more than 400 API models covering more than 200 AWS services; AWS’s own blog post says it supports the APIs of services that have a model in the AWS API models repository.

Install and start it

On Linux, AWS ships RPM and Debian packages. The AWS News Blog walkthrough installs it on Amazon Linux 2023 like this:

PKG=https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest
sudo dnf install -y $PKG/aws-emulator-x86_64.rpm

aws-emulator -v

The package puts aws-emulator in /usr/bin/. Start it in its own terminal:

aws-emulator

On macOS and Windows you build a container from the short Dockerfile in the AWS Emulator documentation and run it in Docker. AWS doesn’t publish a ready-made image. Building from source is supported on Linux (x86_64 and aarch64), but the README asks for at least 100 GB of free disk for target/ and a multi-core machine, so most people should use the package or the container.

Point the AWS CLI and SDKs at it

In a second terminal, set the variables from the AWS blog post. The unset line matters: it removes anything that could supply real AWS credentials to the same shell.

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_EC2_METADATA_DISABLED=true
export AWS_DISABLE_HOST_PREFIX_INJECTION=true
export AWS_REGION=us-east-1
export AWS_DEFAULT_REGION=us-east-1
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE

Then confirm the shell talks to the emulator and not to your account. The health endpoint is on the same port, which also lets a CI script wait until the emulator is ready:

curl --cacert ~/.aws/emulator/9297/ca.pem https://127.0.0.1:9297/__admin/health
aws sts get-caller-identity

aws sts get-caller-identity should show account 000000000000. If it shows your real account ID, the variables didn’t apply in that shell, and anything you create next goes to AWS. From there, the blog’s examples are ordinary commands such as aws s3 mb s3://local-getting-started and aws dynamodb create-table.

Some SDKs need an extra setting to trust the emulator’s certificate; AWS gives a trust store for the AWS SDK for Java as an example. The emulator generates new keys each time it starts, so scripts should read the credentials file from ~/.aws/emulator/9297/ rather than copy keys.

Using it with coding agents

AWS aims the emulator at agents that check their work by running code and reading the result. In the News Blog post, Kiro creates a DynamoDB table, puts an item and reads it back, all against the local endpoint in a shell where the variables are already set.

The README also lists an agent skill. With AWS CLI 2.35.0 or later, you install it and then ask your agent to set up the emulator:

aws agent-toolkit add-skill --skill-name aws-emulator --region us-east-1

For Rust test suites there’s an embedded mode. You add the aws-emulator-embedded crate to [dev-dependencies] and wire the emulator’s HTTP client into the SDK client, with no endpoint URL, certificate or environment variables. Each embedded instance keeps its own state, so tests can run in parallel. The README warns that embedded mode compiles the emulator’s service crates into your test binary, so the first build costs about as much as building from source; it suggests caching target/ in CI and pinning a release commit.

Fidelity, telemetry and other limits

AWS Emulator limits at launch (AWS docs, November 2026)

IAM IAM and resource-based policies aren't evaluated; denied requests might succeed
Accounts and Regions Single account 000000000000; no cross-account or cross-Region behavior
Coverage Varies by service and feature; unsupported operations return HTTP 501
Use Building and testing only; not for production workloads or security testing
Telemetry On by default; turn off with --telemetry off, EMULATOR_TELEMETRY=off or config.toml

AWS measures fidelity with tests that run a workflow through an SDK and compare every response, status code, body and error message with real AWS. Each release publishes a k-of-n score per service, such as 40 of 50, and the test set is public in the aws-emulator-evaluation-suite repository. AWS notes that a score can go down when new tests are added even while the emulator improves. Known gaps live in the repo’s issues/things-that-do-not-work/ folder. GeekWire also quotes an IDC analyst saying it doesn’t yet simulate throttling, outages or regional feature differences.

To turn telemetry off for one run:

aws-emulator --telemetry off

The README says telemetry records never include request or response content, code, credentials or personal data.

Before you wire AWS Emulator into tests or an agent

  • aws sts get-caller-identity returns 000000000000 in the shell your tests or agent use
  • Real AWS keys and AWS_PROFILE are unset in that environment
  • The fidelity score for each service you depend on is checked on the releases page
  • Tests treat HTTP 501 as an unsupported operation, not as an application bug
  • IAM, resource policies and cross-account access are tested on AWS before production
  • Telemetry is turned off if your policy requires it

Built and maintained by agents

AWS says the emulator is built and maintained by agents running on Amazon Bedrock AgentCore. One group finds gaps by comparing responses with real AWS and with the published Smithy models, and files issues. Another writes tests, implements the fix and reviews it. An independent security agent reviews changes adversarially, and an AWS CodePipeline run executes the fidelity tests before each change reaches the public GitHub repository. GeekWire quotes Matt Goldberg, the senior principal engineer behind the project: “Our team hasn’t written or reviewed any of the code.” The repository doesn’t take pull requests; you report gaps as GitHub issues.

The agent pipeline is why releases come so fast. The aws/aws-emulator repo shipped several releases on November 14 alone, up to v1.0.385, and had about 8,100 stars on November 15. Pin a version in CI so a mid-week release doesn’t change results under you.

Should you use it?

AWS Emulator fits local and CI testing of AWS SDK code, especially loops driven by an agent: it’s free, needs no account, and isolates each run. GeekWire notes that LocalStack, the best-known alternative, put its free version behind an account requirement this year and limited it to noncommercial use, while AWS released this one under CC0. Check the fidelity score for your services first, keep real credentials out of the test environment, and keep IAM and security testing on AWS. For agent setups that already run tests on their own, see our Playwright MCP testing guide for Claude Code and the Claude Code power user guide.

Frequently asked questions

What is AWS Emulator?

AWS Emulator is a free, open-source local program from AWS that serves AWS APIs over an HTTPS endpoint on your machine, by default 127.0.0.1:9297. The AWS CLI, AWS SDKs and coding agents use it with their normal calls after you set environment variables. It needs no AWS account and keeps resource state in memory.

Is AWS Emulator free?

Yes. AWS says it has no additional service fee, and you pay only for AWS resources when you deploy to AWS. The source is published on GitHub under the CC0 1.0 Universal public domain dedication.

How do I point the AWS CLI at AWS Emulator?

Start aws-emulator, then set AWS_ENDPOINT_URL to https://127.0.0.1:9297 and point AWS_SHARED_CREDENTIALS_FILE and AWS_CONFIG_FILE at the files it writes in ~/.aws/emulator/9297/. Unset any real AWS credential variables. aws sts get-caller-identity should then return account 000000000000.

Can I use AWS Emulator to test IAM permissions?

No. AWS says the emulator doesn't evaluate IAM policies or resource-based policies the way AWS does, so a request AWS would deny might succeed locally. AWS says not to use it for security testing and to test security settings on AWS before production.

Does AWS Emulator run on Windows and macOS?

Yes, in Docker. AWS ships RPM and Debian packages for Linux, and on macOS and Windows you build a container from the short Dockerfile in the documentation. AWS doesn't publish a ready-made image.

Sources & further reading

Official vendor documentation referenced while writing this guide.

MG

MCSA Guru Team

IT & Systems Administration

We are working IT pros and system administrators who spend our days in Windows Server, Microsoft 365, and the wider Microsoft stack. MCSA Guru is where we write down the fixes and walkthroughs we wish we had found the first time.

MCSA Guru provides independent, educational IT guidance. Microsoft, Windows, Windows Server, Microsoft 365, Exchange, and Microsoft Teams are trademarks of Microsoft Corporation; Docker is a trademark of Docker, Inc. MCSA Guru is not affiliated with or endorsed by Microsoft or Docker. Always test changes in a safe environment before applying them in production.

Related guides

Fixing something right now?

Jump straight into the guide library or search for the exact error or task you are dealing with.