AWS Emulator release – official local AWS API emulator
TL;DR
AWS released an official, open‑source emulator of the AWS APIs that runs locally, integrates with the AWS CLI/SDKs, and can be embedded in Rust tests. It aims to simplify development and CI testing by removing the need for real AWS credentials or network calls, though it is not intended for production or security‑critical testing.
What the AWS Emulator Is
The AWS Emulator is a local program that implements the public AWS API surface. It starts an HTTPS endpoint (default 127.0.0.1:9297) that mimics AWS services, allowing any AWS CLI command or SDK call to be redirected to the emulator via environment variables or an in‑process HTTP client.
- No AWS account is required.
- No additional service fees are charged; you only pay for real AWS resources when you later deploy.
- The emulator is not a production‑grade service and should not be used for security testing (IAM policies, KMS keys, cross‑account or cross‑region calls are not fully enforced).
How to Run It – Three Modes
1. Server mode (CLI & any SDK)
- Linux – install the RPM or Debian package and run
aws-emulator. - Windows/macOS – run the Docker image built from the short Dockerfile provided in the repo.
- Point your SDK/CLI at the emulator by setting the usual AWS endpoint environment variables (e.g.,
AWS_ENDPOINT_URL).
2. Embedded mode (Rust tests)
- Add
aws-emulator-embeddedas a dev‑dependency. - Create an
AwsEmulatorEmbeddedinstance and pass its HTTP client directly to the SDK. - Each test gets an isolated emulator instance; no external endpoint or certificate is needed.
3. AI‑agent assisted setup
- Install the
aws-emulatorskill for an AI coding agent (aws agent-toolkit add-skill --skill-name aws-emulator). - The agent can automatically start and configure the emulator, requiring AWS CLI v2.35.0+.
Fidelity and Known Gaps
- Each release publishes fidelity scores that quantify how closely each service matches real AWS behavior.
- Open issues are organized under
issues/things-that-do-not-work/(missing features) andissues/things-that-now-work/(fixed gaps). - Community comments note that the emulator currently lacks:
- Quick state reset (you must restart the process).
- Full support for IAM policy evaluation, KMS key policies, and cross‑account/region semantics.
- Certain service‑specific features (e.g., Step Functions
Assignfield, full Lambda runtime support).
- The project’s README warns that it is not a drop‑in replacement for tools like Moto when tests need rapid state resets.
Building From Source – What It Costs
- Prerequisites: Rust toolchain, C compiler, ≥ 100 GB free disk for the
target/directory, and a multi‑core machine. - A full debug build compiles a separate crate for every AWS service, resulting in a large binary and long initial compile time.
- Incremental builds are fast; caching
target/(or usingsccache) is recommended for CI. - The repository layout reflects a workspace with one crate per service, a router binary, and an embedded façade.
Telemetry – Opt‑Out Options
Telemetry is enabled by default to collect minimal usage data (no request/response payloads, credentials, or personal data). You can disable it via:
- Command‑line flag:
aws-emulator --telemetry off - Environment variable:
EMULATOR_TELEMETRY=off - Config file
~/.aws/emulator/config.tomlwith[telemetry] enabled = false - Embedded API:
EmbeddedOptions::default().telemetry(Telemetry::Off)
Community Reception (Hacker News Highlights)
- Positive – Several commenters praised the potential value for agentic development and as a free alternative to LocalStack.
- Skepticism – Concerns were raised about long‑term maintenance, the massive build footprint, and whether the project is a serious product or a proof‑of‑concept.
- Comparisons – Users compared it to Floci, MiniStack, Fakecloud, and Moto, noting both overlapping functionality and gaps (e.g., state reset, full IAM simulation).
- Technical observations – Building requires > 100 GB disk and can be memory‑intensive; a comment mentioned needing to lower
jobson a 32 GB RAM machine.
When to Use the Emulator
- Unit and integration testing where you need deterministic API responses without incurring AWS costs.
- CI pipelines that run on isolated runners and cannot rely on external credentials.
- Local development of CDK, Terraform, or CloudFormation templates that only need API surface validation.
When Not to Use It
- Security‑critical testing (IAM policies, KMS, bucket policies) – the emulator does not enforce these controls.
- Performance or scalability testing – the emulator runs locally and cannot emulate AWS’s massive infrastructure.
- Tests that require rapid state resets – you must restart the emulator process to clear state.
How to Contribute
- Report fidelity gaps via GitHub Issues, providing service name, operation, SDK version, request, and observed deviation.
- The repository does not accept pull requests; contributions are limited to issue reporting.
- The code is released under CC0‑1.0 (public domain) except for the
vendor/directory, which is Apache‑2.0.
Bottom Line
AWS’s open‑source emulator provides a powerful, officially supported way to run AWS‑compatible code offline, lowering cost and friction for developers. While it still has notable gaps—especially around security semantics and state management—it represents a significant step toward tighter integration of AI‑driven tooling and cloud‑native development workflows.
Sources
Related
- Project
- Dispatch
- Project
- Dispatch
- Project