GitHub - aws/aws-emulator: AWS Emulator is a local emulator of the AWS APIs.
Key Points
- 1AWS Emulator is a local development tool that allows developers to test software against emulated AWS APIs without requiring an AWS account or incurring service fees.
- 2The software can be operated as a standalone local process, embedded directly into test binaries, or managed via AI coding agents to facilitate seamless integration into development workflows.
- 3While the project tracks fidelity scores and provides a framework for testing, it is strictly intended for development and CI purposes rather than production workloads or security testing.
AWS Emulator is a local, open-source tool designed to simulate AWS API endpoints, enabling developers to test software in local, development, or CI environments without requiring an active AWS account or incurring service costs. The architecture is built as a Rust-based workspace that utilizes Smithy models to drive wire protocols and service declarations, providing a high-fidelity local replacement for AWS cloud services.
Core Methodology and Technical Architecture
The emulator operates through a modular workspace structure where each supported AWS service exists as an individual Rust crate under theservices/ directory. The technical implementation relies on the following components:- Smithy Integration: Each service directory contains a
smithy-model/subdirectory containing a JSON-based Smithy model. This model serves as the source of truth for the service's API, which is utilized by abuild.rsscript to programmatically generate the corresponding service declaration, ensuring consistent request routing and protocol handling. - Request Routing and State Management: Within each service crate, the
service.rsfile manages request routing and overrides for unsupported or non-compliant behaviors. In-memory state is maintained bystate.rs, while individual API operations are mapped to dedicated files within theops/directory. - Execution Modes:
- Local Process: The emulator acts as a standalone server, mounting all services on a single endpoint (default
127.0.0.1:9297). Interaction occurs by updating environment variables to redirect AWS SDK/CLI traffic from official AWS endpoints to the local emulator. - Embedded Mode: Through the
aws-emulator-embeddedcrate, developers can compile the emulator directly into test binaries. This creates an isolated, in-process instance per test, bypassing external network dependencies by injecting the emulator's HTTP client directly into the SDK client.
- Local Process: The emulator acts as a standalone server, mounting all services on a single endpoint (default
Operational Fidelity and Extensibility
The project tracks service fidelity through theissues/ directory, which categorizes API coverage into things-that-do-not-work and things-that-now-work. This allows users to assess if their specific workloads are compatible with the current emulator state. Because the project utilizes an automated maintenance model driven by AI agents, it does not accept external pull requests, ensuring consistent adherence to the upstream AWS API definitions.Telemetry and Security
The emulator includes a telemetry system designed for minimal data collection—specifically excluding request payloads, credentials, or personal information. Telemetry is enabled by default but can be disabled globally via the~/.aws/emulator/config.toml file, per-process via the --telemetry off CLI flag, or programmatically in embedded mode using the Telemetry::Off configuration option. The documentation explicitly warns that the emulator is intended solely for development and testing, and should not be deployed in production environments or used as a security boundary.