Local Cloud Infrastructure Testing: AWS's Official API Emulator Without the Cloud BillArticle · digest for November 17
Macro shot of a compact hardware server showing local port 9297 and an offline AWS emulation indicator.
Article3 sections≈ 6 min

Local Cloud Infrastructure Testing: AWS's Official API Emulator Without the Cloud Bill

Looking through the aws-emulator repository, one detail jumped out at me immediately — something you rarely see from a cloud giant. Amazon, a company whose business runs on billing every API call and resource, released a local emulator of its own APIs into the public domain under CC0-1.0, complete with 34,127 commits, 8.8k stars, and a remarkably candid issues/things-that-do-not-work/ folder documenting operations that diverge from the real cloud. At the same time, the README is upfront: the project doesn't accept pull requests, and all changes come from inside AWS.

For developers, that raises a direct practical question: how do you run integration tests for a service that stores user media archives in S3 and enqueues jobs in SQS, both locally and in CI, without an AWS account or surprise bills? The emulator intercepts standard SDK requests on a local socket and mimics core services right on your own hardware. Convenience comes with trade-offs, though — and it's worth knowing them before migrating your pipeline.

Why live AWS tests stall and how Smithy-based interception works

Testing cloud integrations against a live AWS account creates constant friction: you have to isolate credentials in CI, clean up leftover resources after failed runs so you don't rack up charges, and live with network latency on every call. For years LocalStack filled that gap, though many of its advanced services and features sit behind a paid Pro license.

aws-emulator takes a different path: all of its code is public domain (only vendor/ directories use Apache License 2.0) and written in Rust on top of official Smithy models. Each service gets its own crate under services/service-<name>/ with a smithy-model/<name>.json schema, a build.rs generator, handlers in ops/, and in-memory state in state.rs. The core/router/ module ties everything together on a single local HTTPS endpoint at 127.0.0.1:9297 with a self-signed certificate. Generating directly from Smithy specs lets the emulator maintain high protocol fidelity for core services with no subscription required.

Server and embedded modes: running S3 and SQS on a local port

The tool ships in two modes — a standalone server for any language and an embedded library for Rust tests. If you write Python, Node.js, Go, or Java, the easiest route is the official Docker container (RPM and DEB packages are also available on Linux).

Let's spin up the local emulator on port 9297 with telemetry disabled so we can test our media upload service completely offline:

docker run -d --name aws-emulator -p 9297:9297 public.ecr.aws/aws-emulator/aws-emulator:latest --telemetry off

The container starts a headless local HTTPS daemon on 127.0.0.1:9297. Placing --telemetry off right after the image name disables usage reporting, and all buckets and queues live in container memory.

Next, let's point the AWS CLI at the local port, set dummy credentials, and create an S3 bucket plus an SQS queue for incoming archives:

export AWS_ENDPOINT_URL=https://127.0.0.1:9297
export AWS_ACCESS_KEY_ID=dummy-test-key
export AWS_SECRET_ACCESS_KEY=dummy-test-secret
export AWS_DEFAULT_REGION=us-east-1

aws s3 mb s3://my-local-bucket --endpoint-url https://127.0.0.1:9297 --no-verify-ssl
aws sqs create-queue --queue-name local-tasks --endpoint-url https://127.0.0.1:9297 --no-verify-ssl

The emulator accepts any non-empty test credentials, so you no longer need real AWS secrets in CI. The --no-verify-ssl flag is required here so the client accepts the local socket's self-signed certificate (alternatively, you can clear AWS_CA_BUNDLE="" in your environment).

Now let's hook up a Python integration test using boto3 that writes processed archive metadata to the local bucket and reads it back:

import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="https://127.0.0.1:9297",
    aws_access_key_id="test",
    aws_secret_access_key="test",
    region_name="us-east-1",
    verify=False,
)

s3.put_object(Bucket="my-local-bucket", Key="data.json", Body=b'{"status":"ok"}')
response = s3.get_object(Bucket="my-local-bucket", Key="data.json")
assert response["Body"].read() == b'{"status":"ok"}'

Your business logic stays identical — only endpoint_url and verify=False change for local TLS. The exact same container step drops cleanly into GitHub Actions. And if you use coding agents (Claude Code, Cursor, or Kiro) with AWS CLI 2.35.0 or newer, you can hand the environment setup to the agent:

aws agent-toolkit add-skill --skill-name aws-emulator --region us-east-1

That command installs the official Agent Toolkit skill so your agent can launch the emulator and route requests automatically while debugging.

Embedded mode for Rust projects works quite differently: you add the emulator as a dev-dependency and start it directly inside your test process:

use aws_emulator_embedded::{AwsEmulatorEmbedded, EmbeddedOptions, Telemetry};

fn main() {
    let emulator = AwsEmulatorEmbedded::new(
        EmbeddedOptions::default().telemetry(Telemetry::Off),
    );
    let _http_client = emulator.http_client();
}

Embedded mode doesn't bind port 9297, need certificates, or touch environment variables: you pass emulator.http_client() into your SDK client and get an isolated emulator instance per parallel test.

The price of convenience: 100 GB builds, telemetry, and emulation limits

For zero AWS bills, the emulator asks for real resources and careful attention. Of the three constraints I'd check before moving CI over, the first is heavy source builds: because every service lives in its own Rust crate, a cold compile via cargo build -p aws-emulator-router or a first cargo test run in embedded mode needs a C compiler, a multi-core CPU, and at least 100 GB of disk space for target/. Day to day, it's far easier to pull the Docker image or binary package, and in Rust CI you'll want to cache target/, share a CARGO_TARGET_DIR, enable sccache, and pin a release commit.

The second catch is default telemetry. The emulator sends anonymized usage metrics to AWS (no request bodies, code, keys, or personal data). If your security policy forbids outbound telemetry, disable it with --telemetry off (-t off), EMULATOR_TELEMETRY=off (or false, 0), Telemetry::Off, or a [telemetry] section with enabled = false in ~/.aws/emulator/config.toml.

Third are fidelity boundaries. The AWS Emulator User Guide explicitly forbids using the tool in production or for security validation such as IAM policies. Before leaning on it for complex workflows, check the fidelity scores in the release notes and browse issues/things-that-do-not-work/.

There's no magic button that replaces the live cloud 100%, but the rules of the game are clear. Fast integration tests for S3, SQS, and SDK contracts belong on a local aws-emulator at 127.0.0.1:9297 with a zero-dollar budget, while a real AWS test account stays reserved for final IAM and permission checks before release. If you want to compare this with a lighter alternative, take a look at our breakdown of the Go-based Kumo emulator and our dev-tools roundup featuring AWS Emulator.

Want a deep diveVotes help us choose what to break down in detail. This material has 0 votes.
Sources · 2