Testing an application that calls AWS APIs often means choosing between hand-written mocks and deploying resources to a real AWS account. Mocks are fast, but they can miss request validation and state changes. Real AWS testing is still necessary, but deploying resources for every small change can slow down the development loop.
AWS Emulator offers another option: run AWS APIs locally and point the AWS CLI or an SDK at them, without creating an AWS account or deploying cloud resources.
In this post, we’ll look at how it works, set it up with Docker, and walk through a small S3 example. We’ll also cover where it fits in CI and what you still need to test on real AWS.
What Is AWS Emulator?
AWS Emulator is a local program that exposes an AWS-compatible API endpoint. Your application sends requests to that endpoint instead of the AWS Cloud.
The basic flow looks like this:
1 | Application / AWS CLI / AWS SDK |
Unlike a mock that returns a response you defined, the emulator maintains resources across requests. For example, a bucket created through the CLI can appear in a later SDK call.
According to the official overview:
- No AWS account is required to download or run it.
- The CLI and SDKs connect to a local endpoint, using credentials generated by the emulator.
- Resources live in memory, so restarting the emulator gives you a clean environment.
- There is no graphical console; you interact through APIs and development tools.
- There is no additional service fee for the emulator. Local compute and CI runner costs still apply, and real AWS resources are billed separately.
One important distinction: having an AWS API model does not mean every operation behaves exactly like AWS. Check the fidelity documentation for the services and workflows your application actually uses.
Choose How to Run It
AWS documents four starting points:
| Option | When it makes sense |
|---|---|
| Linux package | Run a native process on a supported Linux system, using an RPM or Debian package. |
| Docker | Run on Windows or macOS, or use a container-based setup on Linux. |
| AI coding agent | Install the official skill and let a supported agent help configure the emulator. |
| Embedded Rust mode | Run an emulator inside Rust tests, with separate state for each instance. |
We’ll use Docker with Windows PowerShell below. You need Docker running in Linux-container mode and the AWS CLI installed on the host. The Docker guide also provides Linux and macOS commands.
The walkthrough is based on the official documentation; its expected results are illustrative, not a report of a locally executed emulator session.
1. Build the Docker Image
AWS currently does not publish a prebuilt emulator image. Instead, the documented approach is to build a small image that installs its Linux package.
In a separate working directory for this experiment, create a Dockerfile:
1 | FROM public.ecr.aws/amazonlinux/amazonlinux:2023-minimal |
This example targets an x86-64 Docker environment. For an Arm environment, use the aws-emulator-aarch64.rpm package and a matching image architecture, as described in the official guide.
Build the image:
1 | docker build -t aws-emulator . |
The 0.0.0.0 binding is inside the container so Docker can forward requests. It does not mean you should publish the service to your network. We’ll restrict the host binding in the next step.
The package URL selects the latest LTS release. For repeatable team builds, use a specific package version and record the image you tested; see versions and compatibility.
2. Start a Private Local Instance
Create the host directory that will receive the emulator’s generated credentials and certificate:
1 | New-Item -ItemType Directory -Force "$env:USERPROFILE\.aws\emulator" |
Then start the container:
1 | $port = 9297 |
Keep this terminal open. The emulator serves HTTPS on https://127.0.0.1:9297.
A few details matter:
- Publish only on
127.0.0.1. Publishing as9297:9297would expose the port on other host interfaces. - The mounted directory shares connection files, not persistent AWS resources. Resource state still disappears when the process stops.
- Authentication stays enabled. Use the generated credentials, not arbitrary dummy keys or your real AWS credentials.
- Telemetry is disabled for this example. It is enabled by default; AWS explains the collected usage data and opt-out controls in the telemetry guide.
The memory options cap this container at 2 GiB with no swap. If it exceeds that limit, it can stop with exit code 137 and lose its in-memory resources.
Use a private development machine or appropriately isolated CI runner. AWS warns that other users on the same machine can reach local ports; a loopback address is not a security boundary between users.
3. Point the AWS CLI at the Emulator
Open a new PowerShell terminal dedicated to this experiment. The following settings apply to that terminal and the programs it starts, not your whole machine:
1 | $emulatorDir = "$env:USERPROFILE\.aws\emulator\9297" |
Remove inherited credentials and profile selections from this dedicated terminal:
1 | $credentialVariables = @( |
Environment credentials take precedence over a shared credentials file. Leaving real credentials set can cause signing errors because the emulator expects keys from its current run.
AWS_CA_BUNDLE makes the CLI trust the emulator’s generated certificate. Keep certificate verification enabled rather than adding --no-verify-ssl. AWS_EC2_METADATA_DISABLED prevents fallback to instance metadata credentials, and AWS_DISABLE_HOST_PREFIX_INJECTION stops supported clients from changing the local endpoint’s host name.
Keep the IP address 127.0.0.1, rather than substituting localhost: some SDKs otherwise try to put S3 bucket names into the host name.
These settings follow the official SDK connection guide. Explicit endpoint settings in application code or service-specific configuration can take precedence, so check existing client configuration too.
Check the Connection Before Creating Resources
First, check readiness using the generated certificate:
1 | curl.exe --fail --silent --show-error ` |
The documented healthy response is ok.
Then confirm which account the CLI reaches:
1 | aws sts get-caller-identity --query Account --output text |
The expected emulator account ID is:
1 | 000000000000 |
If you see a real account ID, stop before creating anything and correct the endpoint configuration. For automated tests, make this an assertion that fails the job rather than a message someone might overlook.
4. Create an S3 Bucket and Read It Through the SDK
Start with a small workflow rather than assuming your entire application will work immediately.
Create a bucket in the configured us-east-1 Region:
1 | aws s3api create-bucket --bucket emulator-demo-bucket |
On a fresh instance, the expected bucket list is:
1 | [ |
Creating and listing a bucket is also an example in the official overview. It demonstrates state across calls, not full S3 feature compatibility.
To read that same state from Python, install Boto3 in your own test project’s virtual environment:
1 | python -m pip install boto3 |
Run this code from the terminal where you configured the emulator:
1 | import boto3 |
The client uses the environment’s endpoint, credentials, Region, and CA bundle. The assertion checks that the SDK can observe a resource created through a separate CLI request.
In a test suite, create the resources as test fixtures rather than depending on manual CLI setup. Add the operations your application needs incrementally and check their fidelity for the emulator release you use.
When finished, press Ctrl+C in the container terminal and close the dedicated client terminal. Stopping the emulator removes the test resources; closing the client terminal discards its temporary AWS environment settings.
Where It Fits in a CI Pipeline
The useful pattern is one fresh emulator per isolated test job, with deterministic resource setup:
- Install a known emulator version or use a controlled image built from that version.
- Start the instance and wait for its HTTPS health endpoint with a bounded timeout. Fail the job if it never becomes ready.
- Configure the endpoint, generated credentials, certificate, and Region in the environment that actually runs the tests.
- Assert the emulator account ID, create test fixtures, and run integration tests.
- Collect test reports and relevant logs, excluding credential files.
- Stop the instance even when tests fail.
On GitHub Actions, separate run steps do not share shell exports. Keep connection setup and the test command in the same step, or explicitly pass the required settings between steps.
For parallel instances on one host, give each instance a different port and use that port consistently in Docker’s host mapping, container port, emulator option, and client configuration. AWS specifically warns that mapping 9300:9297 while sharing the same connection-file directory can make instances overwrite each other’s files. See the parallel Docker guidance.
This gives you a middle layer in a broader testing strategy:
| Test layer | Main purpose |
|---|---|
| Unit tests and focused mocks | Exercise application logic and deliberately injected failure cases. |
| Emulator integration tests | Exercise supported AWS request workflows, validation, and resource state without deploying to AWS. |
| Tests on real AWS | Verify actual service integration, deployment behavior, permissions, and other cloud-specific assumptions. |
Using It with an AI Coding Agent
AWS also provides an official aws-emulator skill. It helps an agent install the tool, connect SDK clients, troubleshoot configuration, and assess whether a project uses supported workflows.
The agent setup guide requires AWS CLI 2.35.0 or later for skill installation:
1 | aws --version |
You can then ask a supported agent to set up the emulator, or ask:
1 | Will my app in this repo work on AWS Emulator? |
The important part is not just getting an agent to start a local process. It is giving that agent a fast feedback loop while keeping real cloud credentials and production data out of its test environment.
Important Limitations
API Coverage Is Not the Same as Behavioral Fidelity
AWS generates service interfaces from its published API models, but behavior is implemented and verified over time. An operation that is not implemented returns HTTP 501 with NotImplemented.
AWS currently describes control-plane fidelity as stronger than data-plane fidelity. Infrastructure-as-code support also varies by service. Successfully creating an S3 bucket does not establish that object events, a complete application deployment, or every Terraform/CDK workflow will behave as expected.
Before adopting it for a project, list your actual AWS operations, inspect the matching fidelity tests, and check the scores for the release you use. The project compatibility guide explains that process. Compare scores only when they use the same fidelity-test version.
It Does Not Validate Your Security Configuration
AWS explicitly says not to use the emulator to validate IAM permissions, resource policies, KMS key policies, or other security controls. A request accepted locally might be denied on real AWS.
It is not a sandbox for untrusted application code either. See the security guidance, keep authentication enabled, and use only synthetic test data.
State, Regions, and Performance Have Limits
- No durable resource state: restarting clears resources, even when the connection-file directory is mounted.
- No realistic multi-account or multi-Region isolation within one instance: use a single account and Region per instance.
- Not a production or load-testing substitute: local timing does not measure real AWS latency, throughput, or availability.
These boundaries make it useful for short, repeatable test runs rather than a permanent local cloud.
Summary
AWS Emulator adds a practical option between hand-written mocks and deploying every test scenario to AWS. You can create local resources through familiar CLI and SDK calls, run fresh instances for CI jobs, and give coding agents a test environment without a cloud account.
Start with one small workflow, verify that your clients really reach the emulator, and expand only after checking the relevant API fidelity. Keep real AWS tests for the things an emulator cannot prove, especially security and production behavior.