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-embedded as a dev‑dependency.
  • Create an AwsEmulatorEmbedded instance 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-emulator skill 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) and issues/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 Assign field, 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 using sccache) 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.toml with [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 jobs on 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