
AWS has released AWS Emulator, a local emulator that runs on your own machine and answers AWS API calls the way the cloud does. The AWS CLI, the AWS SDKs and coding agents talk to it over a local HTTPS endpoint, so your application code stays the same. It is written in Rust, built from the official AWS API models, and has no service fee. For teams that test against a shared dev account or run integration tests that create real resources, it can make tests faster, cheaper and safer. This post covers how to set it up, how to use it in CI, and where it falls short.
What it is and how fidelity is measured
Because it is generated from AWS API models, the emulator can expose the API of any service that has a published model. Coverage still varies a lot by service. AWS measures it with fidelity tests: each test runs a real SDK workflow, and it only passes if the emulator matches real AWS on every response, including status codes, bodies, error codes and error messages. Results are published per service as a score like 40 of 50, and the test suite is public in the aws-emulator-evaluation-suite repository. Operations that are not implemented return HTTP 501, so tests fail loudly instead of passing on a fake response. Scores can drop when new tests are added, so look at the scores for the services you use, not at a headline number.
Installing and starting it
On Linux, AWS provides RPM and Debian packages. On Amazon Linux 2023, or another dnf-based distribution:
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
aws-emulator
On macOS and Windows, you build a container image from the Dockerfile in the documentation. AWS does not publish a ready-made image. You can also build the emulator from source on GitHub.
Once started, it listens on HTTPS at 127.0.0.1:9297, so only the local machine can reach it. On first run it creates credentials, a config file and a certificate under ~/.aws/emulator/9297/. It writes JSON-line logs and has a health endpoint at /__admin/health.
Pointing the CLI and SDKs at it
You redirect clients with environment variables. Unsetting your normal credentials is the important step, because it stops a test from reaching a real account by mistake:
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
The emulator uses account 000000000000 and generates new keys each time it starts. Those keys begin with EMULATOR, and it rejects requests signed with any other key. Some SDKs, the Java SDK among them, need an extra setting to trust the emulator’s certificate.
For Rust projects, the aws-emulator-embedded crate runs the emulator inside the test process. Each instance has its own state, so tests can run in parallel without fighting over the same bucket, table or queue.
Using it in CI
AWS does not publish a CI recipe, but the pieces fit a standard pipeline:
- Install the package in the build image, or build the container.
- Start
aws-emulatorin the background. - Poll
/__admin/healthuntil it responds before running tests. - Export the variables above in the test step.
- Keep real AWS credentials out of that job completely, so a misconfigured test cannot create or delete real resources.
By default the emulator sends anonymous usage and error data to AWS. You can turn this off. Check the documentation for the setting if your policies require it.
What it does not cover
| Limitation | What it means for you |
|---|---|
| No real IAM or resource policy evaluation | A call AWS would deny can succeed locally. Test permissions in a real account. |
| Single account, no cross-Region behaviour | Cross-account roles and multi-Region replication need real AWS. |
| Fidelity varies by service | Check per-service scores before relying on it. |
| Not a security testing tool | Do not treat passing tests as proof that access controls work. |
A sensible approach is to run most unit and integration tests against the emulator, then keep a smaller set of tests against a real, locked-down AWS account. Those cover IAM, networking and the service features the emulator scores poorly on.
How TechProvidence can help
We design AWS environments and the CI/CD pipelines that deploy to them, including test stages that keep production credentials out of reach. If you want local AWS testing added to your pipeline, a separate account for permission tests, or a review of your existing AWS setup, contact us.
Source: AWS News Blog


