groundy
Agents & Frameworks

AWS Emulator: What Agent Tool Tests Can Run Locally

AWS Emulator server mode supports local boto3 agent tests via HTTPS, but fidelity varies by release. Embedded mode suits Rust, while Moto and LocalStack cover other layers.

Published 5 references
A skeptical green resin dinosaur with blocky scales and a yellow collar extends its forked tail through an ivory partition. One prong enters a yellow ring; the other remains unconnected. Hard shadows fall across the warm ivory ground.
On this page10 sections

AWS Emulator’s server mode exposes HTTPS on 127.0.0.1:9297, making it a credible candidate for boto3 agent-tool CI tests that cross process boundaries, according to AWS’s emulator repository. That endpoint does not establish parity with AWS. The tests that can run locally are the ones whose services and operations are covered adequately by the release you pin; the README does not enumerate the supported services, and its fidelity scores live on a separate releases page.

For a Python agent, the practical deployment choice is therefore server mode. Embedded mode provides one isolated emulator instance per test, but AWS scopes it to Rust tests. Two adoption details deserve attention before the first CI run: telemetry is enabled by default, and the source build needs at least 100 GB of free disk for target/, per AWS’s README. That build requirement applies to building from source and to embedded mode; most server users install a prebuilt package instead.

What AWS commits to, and what it does not

AWS’s documentation index lists AWS Emulator with the description “Test your code against the AWS APIs locally with no AWS account.” That confirms it is an AWS-published offering, rather than an unofficial project using AWS branding. It does not confirm any particular level of API compatibility.

The repository README describes local testing on a development machine, development server, or in CI without calling AWS or holding an AWS account. It says there is no additional service fee for the emulator; you pay for AWS resources when you deploy on AWS. The same document excludes production workloads and security testing from its intended scope.

For agent development, that scope can still cover useful work:

  • Checking that a tool constructs the SDK requests your agent expects.
  • Exercising agent-to-tool-to-SDK wiring across separate processes through a local endpoint.
  • Running isolated Rust tests without configuring an endpoint, certificate, or environment variables.
  • Reproducing a supported AWS interaction without spending test-loop money on a sandbox account.

What remains unknown is more consequential: which services the current release implements, how faithfully each operation behaves, and whether the responses your tools depend on match AWS. A green emulator suite can validate your integration against a selected emulator release. It cannot, by itself, validate that integration against AWS.

The repo-sourced adoption checklist

Every commitment in this table comes from AWS’s README, not an independent compatibility test.

Decision itemRepository commitmentPractical consequence
Server endpointHTTPS on 127.0.0.1:9297, with a self-signed certificatePlan endpoint and certificate handling for the SDK and agent processes.
SDK connectionPoint the CLI or an SDK at the running emulator using environment variablesFits boto3 and cross-process agent tests; exact variable wiring should be checked against the README version you adopt.
Embedded executionRust dev-dependency, in-process, one isolated instance per testUseful test isolation without endpoint configuration, but not a Python embedding option.
Build requirementsRust and Cargo, a C compiler such as GCC or clang, a multi-core machine, and at least 100 GB free for target/Budget CI disk and caching before choosing embedded mode.
Source-build platformsLinux x86_64 and aarch64; Windows and macOS are routed through DockerDo not assume a native source build on a developer’s non-Linux machine.
TelemetryEnabled by default; four documented opt-out mechanismsMake telemetry handling an explicit CI and tool-distribution decision.
LicenseCC0-1.0, except vendor/, which is Apache-2.0Review both license terms when redistributing source or vendored material.
Compatibility trackingPer-release fidelity scores and in-repo ledgers of working and non-working behaviorPin a release and inspect its evidence rather than treating “AWS Emulator” as a stable compatibility target.
ContributionsPull requests are not acceptedA bug report is the available route; do not plan around submitting a parity fix directly.

The README also supplies a vendor-doc-sourced setup path for AI coding agents: aws agent-toolkit add-skill --skill-name aws-emulator --region us-east-1, requiring AWS CLI version 2.35.0 or later. That is a setup aid for a coding agent, not evidence that your runtime agent’s AWS tools are covered.

Server mode fits boto3 agents; embedded mode is a Rust choice

The important architectural distinction is whether the AWS call must cross a process boundary.

An agent runner, tool server, and SDK client often run as separate processes or containers. Server mode gives them an actual HTTPS endpoint, and the README’s environment-variable path supports SDKs including boto3. This lets a test exercise the request path between those components rather than replacing the boto3 call inside the Python process. The self-signed certificate is part of the test setup, not a detail to discover after CI fails.

Embedded mode removes that transport setup. The test wires the emulator’s HTTP client directly into the SDK client, with one isolated instance per test. That is attractive for Rust test binaries where isolation matters more than reproducing a multi-process deployment. It does not provide the same path for a boto3-based agent.

The build budget may decide the Rust question before test design does. AWS requires a Rust toolchain, Cargo, a C compiler, and at least 100 GB of free disk for target/ according to the README, which explains that the workspace has one crate per AWS service and grows as services are added. Its repo-sourced CI guidance is to:

  1. Reuse one CARGO_TARGET_DIR across projects.
  2. Cache target/ or use sccache.
  3. Pin the emulator to a release commit so it is not rebuilt on every change.

These are build-cost controls, not compatibility guarantees. A cache can make the emulator cheaper to run; it cannot make an unsupported operation behave like AWS.

Telemetry is on by default

The README’s telemetry section says the emulator collects and reports usage data to AWS and that telemetry is enabled by default. It also states that records never include request or response contents, code, credentials, or personal data, and are not shared with third parties. Those are project statements about telemetry behavior; no independent audit is cited.

For CI hygiene, the safe operational distinction is straightforward: the README excludes test payloads and credentials from telemetry records, but usage data still leaves the machine unless you disable collection.

The four repo-sourced controls operate at different scopes:

  • --telemetry off, or the short form -t, disables it per process.
  • EMULATOR_TELEMETRY=off controls it per shell. The accepted true values are on, true, and 1; false values are off, false, and 0. Any other value turns telemetry off with a warning.
  • Setting enabled = false under [telemetry] in the emulator’s config.toml disables it per machine.
  • Telemetry::Off disables it through embedded-mode options.

There is an additional obligation for tool builders. If you embed the emulator in a test framework or another tool that users run, AWS instructs you to tell those users about telemetry, provide a way to turn it off, or ship with it disabled. A wrapper that silently inherits the default would make an outbound-data decision on the user’s behalf.

Fidelity is the product

An emulator’s endpoint, license, and startup model are easy to checklist. Compatibility is the part that determines whether a test result means anything.

AWS directs users to fidelity scores published with each release. It also maintains issues/things-that-do-not-work/ and issues/things-that-now-work/ ledgers, according to the repository. This is a useful admission of how the project should be evaluated: compatibility is per service, per operation, and per release, rather than a property conferred by the AWS name.

The repository does not accept pull requests. It asks for useful bug reports identifying the service, operation, SDK and version, request, and how the response differed from real AWS. That reporting format also provides a good model for an internal compatibility failure: preserve the exact request and observed difference so the failure can be reproduced rather than reduced to “the emulator behaves strangely.”

Before trusting an agent-tool suite locally, I would pin a release, inspect its fidelity scores and ledgers, and map the agent’s actual tool operations to that evidence. For behavior where a mismatch would invalidate an important deployment decision, retain a real-AWS contract check. That is a verification recommendation, not a claim that the emulator has already failed such a check.

The limitation here is substantial. The README does not list which services the current release implements; per-release fidelity scores live on a separate releases page, which this article does not review. No independent usage evidence for the emulator is cited here, and maintenance cadence is likewise unestablished.

Where Moto and LocalStack still fit

The choice is not simply “official emulator versus unofficial emulator.” The three approaches exercise different layers of an agent system.

OptionArchitectural fitWhere it remains a candidateEvidence constraint
AWS Emulator server modeLocal HTTPS endpoint for an SDK, including cross-process testsboto3 agent tools where endpoint wiring and process boundaries matterCoverage and fidelity must be checked against a pinned release; no independent usage evidence is cited.
AWS Emulator embedded modeIn-process Rust tests with one isolated instance per testRust suites that can accommodate the source-build and caching requirementsNot scoped to Python tests by the README.
MotoPatches boto3 calls in the Python processPython-only tests where no separate process, container, or HTTP behavior needs exercisingArchitectural description comes from a single third-party comparison.
LocalStackSingle-container AWS service environment with a broader workflow catalogMulti-service, infrastructure-as-code, shared-state, and failure-injection workflowsProduct breadth is vendor-reported; plan and authentication requirements need checking for your use case.

A March 2026 third-party comparison describes Moto as patching boto3 in-process, without Docker or a network round-trip. Its decisive limitation is that it cannot test AWS calls arriving from another process, container, or service, and it does not exercise the HTTP layer for Terraform or CDK validation. If your agent and tool run in one Python process and transport behavior is outside the test’s purpose, Moto remains a plausible lightweight choice. If the tool server runs separately, that architectural limit changes the recommendation rather than merely qualifying it.

LocalStack occupies a different layer. Its archived community repository describes a single container supporting services including Lambda, S3, DynamoDB, Kinesis, SQS, and SNS, with Pro adding APIs and features. Development is being consolidated into a unified image. The archived notice also says a free Hobby plan for non-commercial use retains the same capabilities as the archived project; commercial teams should not assume that plan applies to them.

LocalStack’s product page lists capabilities beyond API responses: Cloud Pods for state sharing, fault and delay injection, ephemeral environments, Stack Insights, extensions, and integrations with tools including Testcontainers, CDK, Terraform, Pulumi, and GitHub Actions. If your agent tests need shared environment state, infrastructure provisioning, or simulated failures, those are concrete reasons to evaluate LocalStack that AWS’s README does not claim to match.

The same third-party article reports that LocalStack moved images behind authentication on March 23, 2026, breaking tokenless CI pulls. LocalStack’s own pages do not state that requirement, so treat the report as uncorroborated here and verify the pull path for your image and plan. The article’s broader “LocalStack is gone” framing is not supported by LocalStack’s archived-repository notice.

A decision path for agent-tool CI

For a boto3 agent whose tools run across process boundaries, I would trial AWS Emulator server mode, with telemetry explicitly disabled, a pinned release commit, and a written inventory of every service operation the tools call. The trial should compare the release’s fidelity evidence against that inventory before the suite becomes a merge gate.

For Rust tests, embedded mode is the cleaner isolation model when the build disk and caching costs are acceptable. For same-process Python mocks where HTTP transport is irrelevant, Moto remains architecturally sufficient based on a single third-party comparison, though its current documentation still needs checking. For container-based multi-service environments, infrastructure-as-code workflows, shared state, or fault injection, LocalStack addresses requirements the emulator README does not claim to cover.

The durable adoption rule is to record four things beside the CI configuration: the emulator release, the operations relied upon, the fidelity evidence for those operations, and the telemetry setting. Without those records, “the agent tools pass locally” hides the compatibility assumption that matters most.

Frequently Asked Questions

Is telemetry enabled by default in AWS Emulator?

The README’s telemetry section says the emulator collects and reports usage data to AWS and that telemetry is enabled by default. It also states that records never include request or response contents, code, credentials, or personal data, and are not shared with third parties.

What is the local endpoint for AWS Emulator server mode?

AWS Emulator’s server mode exposes HTTPS on 127.0.0.1:9297, making it a credible candidate for boto3 agent-tool CI tests that cross process boundaries, according to AWS’s emulator repository.

References

Follow the links in the article for context. The supporting material is collected here for further reading.

  1. AWS's emulator repositorygithub.comAccessed
  2. AWS's documentation indexdocs.aws.amazon.comAccessed
  3. March 2026 third-party comparisondev.toAccessed
  4. LocalStack archived community repositorygithub.comAccessed
  5. LocalStack's product pagelocalstack.cloudAccessed

Join the discussion

Share a useful perspective or ask a question about this article.

Discussion guidelinesComments privacy