AWS Emulator Hands-On: Test S3, Lambda and DynamoDB Locally With a Coding Agent
On 11 November AWS shipped AWS Emulator, a local copy of the AWS APIs that you run on your own machine. The pitch is aimed squarely at coding agents: let the agent build and test against something that behaves like AWS,
On 11 November AWS shipped AWS Emulator, a local copy of the AWS APIs that you run on your own machine. The pitch is aimed squarely at coding agents: let the agent build and test against something that behaves like AWS, with no account, no credentials and no bill. Swami Sivasubramanian's launch post passed 1,700 likes on X, and the Hacker News thread went past 960 points in under two days.
LocalStack and moto already cover local AWS testing, so I wanted to know three things. Does it start fast enough to be part of a test loop? Can a coding agent actually ship something against it without me helping? And where does it stop looking like AWS? So I ran it in Docker on a Linux box, had an agent build a small S3 β Lambda β DynamoDB service three times from scratch, and then went looking for the edges myself.
What AWS Emulator is (from the repo and docs)
AWS Emulator (github.com/aws/aws-emulator, docs) is a single Rust binary, aws-emulator, that serves AWS service APIs over HTTPS on 127.0.0.1:9297. A few facts worth knowing up front:
-
It's free and open. The code is CC0 1.0 (public domain), except the
vendor/framework crates, which are Apache 2.0. The repository doesn't take pull requests; you file issues instead. - It runs three ways. On Linux you install an RPM or Debian package. On macOS and Windows you build a Docker image from a short Dockerfile that installs that same package (AWS doesn't publish a prebuilt image). For Rust tests there's an embedded mode that runs in-process.
- Coverage comes from AWS's own API models. The repo has 437 service crates, one per API model. Each release publishes fidelity scores. The v1.0.338 scores I downloaded cover 355 services with 43,548 scored tests, and 26,001 of them (59.7%) pass.
-
Agents built it. AWS's own write-up says autonomous agents wrote every line, with agent teams writing fidelity tests against real AWS, filing issues and fixing them. You can see this in the repo:
issues/things-that-do-not-work/held 6,936 files on the day I tested, andissues/things-that-now-work/held 13,224. -
There's an agent skill.
aws agent-toolkit add-skill --skill-name aws-emulatorinstalls a skill that teaches an agent how to install, start, connect and troubleshoot the emulator. -
Telemetry is on by default. The docs list exactly what's collected (operation counts, error categories, SDK names and versions; no payloads, resource names or credentials). You turn it off with
--telemetry offorEMULATOR_TELEMETRY=off. I ran with it off the whole time.
My setup
I tested version 1.0.338 (released 12 Nov) on a Debian 13 box with 8 vCPUs and 15 GiB of RAM. The coding agent was OpenCode 1.19 with OpenCode Zen's free deepseek-v4.1-flash-free model. I didn't use Cursor or Claude Code, and I didn't use real AWS credentials at any point.
Docker needed some work first. The Debian mirror returned HTTP 500, so I installed Docker 27.3.1 from the static binaries. The box also has no iptables, so the Docker daemon ran without its bridge network and every container used host networking. That meant I couldn't test the documented -p 127.0.0.1:9297:9297 port publishing. I bound the emulator to loopback inside the container instead, which has the same effect on a single host.
I built the image from the Dockerfile in the docs, then started it like this:
# Dockerfile from the docs: amazonlinux:2023-minimal + the aws-emulator RPM
docker build -t aws-emulator . # 30.0 s, image is 1.27 GB
mkdir -p ~/.aws/emulator/9297
docker run -d --rm --name aws-emulator --network host \
--user "$(id -u):$(id -g)" --memory=2g --memory-swap=2g \
--cap-drop ALL --security-opt no-new-privileges --read-only \
-e HOME="$HOME" -e EMULATOR_TELEMETRY=off \
-v "$HOME/.aws/emulator/9297:$HOME/.aws/emulator/9297" \
--entrypoint aws-emulator aws-emulator -b 127.0.0.1 -p 9297
When it starts, the emulator writes a fresh access key, an SDK config file and a self-signed CA into ~/.aws/emulator/9297/. Requests must be SigV4-signed with that run's key. Pointing the AWS CLI or boto3 at it takes only environment variables, with no code changes:
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE
export AWS_ENDPOINT_URL=https://127.0.0.1:9297
export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials
export AWS_CONFIG_FILE=~/.aws/emulator/9297/config
export AWS_CA_BUNDLE=~/.aws/emulator/9297/ca.pem
export AWS_EC2_METADATA_DISABLED=true
export AWS_DISABLE_HOST_PREFIX_INJECTION=true
export AWS_REGION=us-east-1
aws sts get-caller-identity # Account "000000000000", Arn ".../user/emulator"
Keep 127.0.0.1 in the endpoint rather than localhost. With an IP address, the SDKs put the S3 bucket name in the path, which is the only style the emulator accepts.
Start-up numbers
These are wall-clock times on the box. The full logs are in my lab notes.
-
Image build: 30.0 s with the base image already pulled, and 28.7 s with
--no-cache, which re-downloads the 171.6 MB RPM. -
Cold start (from
docker runto the first HTTP 200 on/__admin/health): 272 ms to 1,007 ms across 10 starts, with a median of 375 ms. Three of the ten went over 500 ms, and the slowest was the very first one. - Idle memory: 175.6 MiB.
-
Installing the skill: 0.69 s. It installed for every agent it found:
~/.agents/skills(OpenCode, Codex, Gemini CLI and others),~/.claude/skillsand~/.cursor/skills.
A sub-second start changes how you use it. You can start a clean emulator for every test run instead of sharing a long-lived one, and since state lives only in memory, a restart is also your reset.
The agent test: upload-and-index, three times from scratch
I gave OpenCode one prompt and nothing else. Build a python3.12 Lambda that reads an object from S3, counts its lines and words, and writes an index item to a DynamoDB table. Give it a least-privilege IAM role and an idempotent deploy.py. Write a pytest suite that uploads three files, invokes the function for each, and checks the DynamoDB items. Use the aws-emulator skill. The only hints were about my box: the image was already built, and Docker needed --network host. Each run started with no emulator running and an empty folder.
All three runs ended with passing tests:
- Run 1: 168.9 s, 27 tool calls, 3 tests passed
- Run 2: 280.3 s, 39 tool calls, 2 tests passed (one test covers all three files, including an empty one and one with Unicode)
- Run 3: 187.2 s, 20 tool calls, 2 tests passed (plus an idempotency test that deploys twice)
The median was 3 min 7 s. Afterwards I re-ran each suite myself against a fresh emulator, and all three passed again in 5β11 seconds.
The skill made a visible difference to how the agent worked. In every run, it loaded the skill first and read the container and connect references. It started the emulator with telemetry off, and checked that sts get-caller-identity returned account 000000000000 before writing any code. All three runs also added a guard to deploy.py that refuses to run unless the endpoint is loopback and the account is the emulator's. I didn't ask for that. It comes from the skill's "keep real credentials out" rules, and it's exactly the guard I'd want in a repo where an agent has a shell.
This is the handler from run 1:
import os
import boto3
TABLE_NAME = os.environ.get("DOC_INDEX_TABLE", "doc-index")
def handler(event, context):
bucket, key = event["bucket"], event["key"]
s3 = boto3.client("s3")
body = s3.get_object(Bucket=bucket, Key=key)["Body"].read()
text = body.decode("utf-8")
item = {"pk": key, "bytes": len(body),
"lines": len(text.splitlines()), "words": len(text.split())}
boto3.resource("dynamodb").Table(TABLE_NAME).put_item(Item=item)
return item
The most useful part was where the agents got stuck, because each time the emulator was behaving like AWS:
-
CreateFunctionrejectedAWS_REGIONandAWS_DEFAULT_REGIONas reserved environment variables (runs 1 and 2). - Calling
UpdateFunctionCodeand thenUpdateFunctionConfigurationback to back returnedResourceConflictException(runs 1 and 2). So did invoking a function that was stillPending(run 3). Each agent fixed it by waiting for the update to finish or by retrying. - Inside the function, S3 and DynamoDB calls returned
AccessDenieduntil the execution role had a policy that allowed them (seen in runs 2 and 3).
Every one of those is a bug you'd otherwise find on your first real deploy. Finding them locally, in a three-minute agent run, is the whole value of the tool.
Things I checked myself
I started a second emulator on port 9300 and ran a set of probes against it:
-
DynamoDB tables are created asynchronously, as on AWS. A
PutItemright afterCreateTablereturnedResourceNotFoundExceptionwhile the table was stillCREATING. -
S3 β Lambda notification works. With an
s3:ObjectCreated:*notification on the bucket, aPutObjectinvoked the function, and the DynamoDB item appeared 515 ms later. -
DynamoDB passed everything I tried: a GSI query,
TransactWriteItems, a conditional put that correctly failed withConditionalCheckFailedException, StreamsGetRecordsand TTL. - The S3 basics passed too: multipart upload, a presigned GET fetched with plain HTTPS, and versioning.
-
Lambda behaved like Lambda: a 2-second timeout produced
Sandbox.Timedoutat 2.00 s,LogType=Tailreturned START/END/REPORT lines, and when the role allowed it,/aws/lambda/<fn>appeared in CloudWatch Logs. -
Speed (boto3, 8 threads, same box): 1,000 S3 puts of 10 KiB each took 1.44 s (693 requests/s), and 5,000 DynamoDB
PutItemcalls took 5.18 s (964 requests/s). A Python Lambda invoke took 97β199 ms per round trip, with a median of 117 ms. A Node.js invoke took about 8 ms once warm.
Python Lambdas don't run on CPython
Out of curiosity, I deployed a function that returns sys.version. The answer was 3.14.0.alpha ... [RustPython 0.6.0 with rustc 1.99.1]. The container doesn't have a Python binary at all. The python3.12 runtime is RustPython, a Python interpreter written in Rust and built into the emulator. The boto3 your function imports is a shim that talks to the emulator in-process. The Node.js runtime isn't real Node either: process.versions contains only {"node":"22.0.0"}, and process.pid is undefined.
For the kind of code I tested, plain handlers that call AWS through the SDK, this was invisible: all three agent builds passed. But it's a real parity gap for anything that depends on CPython internals. import sqlite3 fails with No module named '_sqlite3', even though real python3.12 Lambdas include it. I'd expect any C-extension wheel you vendor into the zip to fail as well, though I didn't test that directly. Pure-Python packages in the zip imported fine.
Gaps I hit, compared with real AWS
-
S3 has hard size caps. The 1,001st object in a bucket failed with
ValidationException: the bucket ... already holds the maximum of 1000 objects this emulator keeps per bucket. A singlePutObjectof 8 MiB worked, but 16 MiB and above returned413 Content Too Large. The source code also sets caps of 64 MiB of data per bucket, and 10,000 objects and 128 MiB across all buckets. The comments say these exist to bound memory and are "NOT a fidelity claim". They're fine for unit-sized tests, but a pagination test over 5,000 keys or a large-file upload test will fail for reasons that have nothing to do with your code. - IAM is only half enforced. Identity policies on a Lambda role are evaluated, which is how the agents found their missing permissions. But a new IAM user with no policies at all could still list buckets with its own access key. The docs say plainly that it doesn't evaluate IAM and resource policies the way AWS does and shouldn't be used for security testing. Believe them.
- The fidelity scores are uneven. Counting tests that involve only one service: S3 passes 82.7% (1,014 of 1,226), DynamoDB 71.0%, IAM 71.4% and Lambda 50.1% (395 of 788). The docs say it matches AWS most closely for control-plane APIs.
-
One account, one Region. Everything runs as account
000000000000, and resources aren't kept separate by Region. To test several Regions you run one emulator per Region. -
Some requests never reach it. S3 Control requests always put the account ID in the host name, so they never reach the emulator. Operations that use host prefixes need
AWS_DISABLE_HOST_PREFIX_INJECTION=true(or the equivalent setting in your SDK).
Two things looked like gaps but aren't. S3 Select returned MethodNotAllowed, but AWS stopped offering S3 Select to new customers in 2024. And DynamoDB's ItemCount stayed at 0 after 5,000 writes, but AWS only refreshes it about every six hours.
What I couldn't test
- The native Debian/RPM install (I only ran it in Docker), embedded Rust mode, macOS, Windows and arm64.
- Docker's default bridge networking with
-p 127.0.0.1:9297:9297, because my box has no iptables. - CloudFormation, CDK or Terraform, container-image Lambdas, calling a function URL, multi-Region setups and long-running use.
- What telemetry actually sends. It was off throughout, so I only have the docs' description.
- Cursor or Claude Code as the agent. I used OpenCode with a free model.
Verdict
For the job it's built for, letting an agent build and test AWS code locally, it works today. A free model plus the skill went from an empty folder to a passing S3 β Lambda β DynamoDB test suite three times out of three, with no help from me, in about three minutes each. The errors the agents tripped over were real AWS behaviours, caught before any deploy. And with a median start of 375 ms and 175 MiB of memory at idle, starting a fresh emulator for every test run is realistic.
I'd add it to a repo's test loop today, with two rules. Keep test data small: fewer than 1,000 objects per bucket, and single uploads of 8 MiB or less. And don't treat a passing IAM test as proof of anything. Before I'd trust it for Python Lambdas with native dependencies, I'd want CPython instead of RustPython, or at least a clear compatibility list.
If you want to reproduce this, here's the minimum:
aws agent-toolkit add-skill --skill-name aws-emulator --region us-east-1
# then ask your agent: "Install AWS Emulator in Docker with telemetry off,
# point boto3 at it, and build + test <your service> against it."
All numbers come from my own runs on 13 Nov 2026 (IST) with AWS Emulator 1.0.338. The emulator ships several releases a day, so the gaps above may already be smaller by the time you read this.
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes β full credit and traffic to the original publisher.