AWS Emulator Puts AWS on Your Laptop. Keep Your IAM Tests Off It.
AWS released AWS Emulator on November 11, a free local server that answers AWS API calls on 127.0.0.1 with per-run keys and fresh certificates.
Testing code that talks to AWS has always meant picking a bad option. Hit a real account and you pay for it, wait on deployments, and occasionally leave a public bucket lying around. Mock the SDK and your tests pass against something that behaves nothing like S3. Third-party emulators filled the gap for years, with their own coverage holes.
On November 11, AWS released its own. AWS Emulator is a local server that answers AWS API calls from the CLI, the SDKs, and coding agents, with no AWS account and no internet connection. It's free, written in Rust, and built from the same API models the SDKs use. I installed release 1.0.385 on Linux to see what it does by default, and where it shouldn't be trusted.
What AWS Emulator Is and How It Runs
AWS ships it as RPM and Debian packages. There's no prebuilt Docker image. For macOS and Windows, the docs give a short Dockerfile that installs the Linux package. On my machine:
Version: 1.0.385
Release date: 2026.11.14
Commit: 813af480bf7f16d5418b64e4f5644a74a7da11c5
Started as an ordinary user with no options, it wrote a startup line in JSON with its endpoint, health check URL, and file paths, then waited on one port:
LISTEN 0 128 127.0.0.1:9297 0.0.0.0:* users:(("aws-emulator",pid=2243,fd=9))
AWS's announcement describes how it's made: the emulator is "built and maintained by agents from the AWS API models," with one group of agents finding gaps against real AWS and another implementing fixes, and "an independent security agent" reviewing changes. The package description repeats that it's "built by autonomous team of agents constantly improving AWS Emulator to behave more like real AWS." Keep that in mind later. This is software that changes quickly, and its documentation can fall behind it.
The Defaults Are Careful
| Default | What I saw |
|---|---|
| Listens on | 127.0.0.1:9297 only |
| Protocol | HTTPS, with a new certificate each start |
| Authentication | On. Requests must be signed with this run's keys |
| Credentials | New key pair each start, written to ~/.aws/emulator/9297/ |
| File permissions | drwx------ for the folder, -rw------- for all four files |
| Account | One account, 000000000000 |
| Telemetry | On by default |
| Cleanup | Credential files deleted when it stops |
An unsigned request got a 404 with UnknownService, because the emulator works out which service you're calling from the signature. Its health route answered ok. When I stopped it, the per-port folder was left empty, as the docs say.
It also warns when you loosen things. With --auth off:
request authentication is off: the emulator accepts any request, signed or not; start it with -a on to require signatures
And with -b 0.0.0.0:
the emulator listens on 0.0.0.0, not loopback: other machines that can reach port 9302 can call it; bind 127.0.0.1 (-b 127.0.0.1) unless that is intended
The Docker instructions need -b 0.0.0.0 inside the container so Docker can forward the port, and then publish it only on the host's loopback with -p 127.0.0.1:9297:9297. Copy that exactly. Leave out 127.0.0.1: and the emulator is reachable from your network.
We recommend reading The World now is Serverless and Container based to continue reading our selection of content. Local emulators exist because so much code now runs on managed services, and that piece covers how we got here.
The World now is Serverless and Container based Serverless and containers have become the default way to run modern software, reshaping infrastructure decisions for developers and ops teams. SudoSecurity · Santhdium
Telemetry Is On Until You Turn It Off
On a normal start, the emulator printed this to stderr:
This emulator collects usage and error telemetry: enabled (on by default; opt out any time); disable with EMULATOR_TELEMETRY=off or [telemetry] enabled = false in /home/dev/.aws/emulator/config.toml
AWS's telemetry page says it never sends request contents, resource names, credentials, or code, and lists what it does send: per-operation call counts and outcomes, SDK names and versions, OS and CPU type, whether it runs in a container or CI, and "which AI coding assistant drives the emulator, if any." A random installation ID ties runs together, kept with a queue of unsent data in ~/.aws/emulator/telemetry/.
If that's more than you want leaving a CI runner, set EMULATOR_TELEMETRY=off or pass --telemetry off. The docs say turning it off also deletes the installation ID and the queue.
Pointing Code at It
The emulator writes an AWS config file and a credentials file for each run. Point the SDK at those and it signs requests with the emulator's keys. My test, using boto3:
# Point boto3 at a local AWS Emulator and check what it allows.
import boto3, botocore, json
s = boto3.Session() # reads AWS_CONFIG_FILE and AWS_SHARED_CREDENTIALS_FILE
print("account:", s.client("sts").get_caller_identity()["Account"])
s3 = s.client("s3")
s3.create_bucket(Bucket="demo")
s3.put_object(Bucket="demo", Key="hello.txt", Body=b"hi")
print("s3 object:", s3.get_object(Bucket="demo", Key="hello.txt")["Body"].read())
# An IAM user whose only policy denies everything.
iam = s.client("iam")
iam.create_user(UserName="locked")
iam.put_user_policy(
UserName="locked", PolicyName="deny-all",
PolicyDocument=json.dumps({"Version": "2012-10-17", "Statement": [
{"Effect": "Deny", "Action": "*", "Resource": "*"}]}),
)
key = iam.create_access_key(UserName="locked")["AccessKey"]
locked = boto3.Session(aws_access_key_id=key["AccessKeyId"],
aws_secret_access_key=key["SecretAccessKey"]).client("s3")
try:
locked.get_object(Bucket="demo", Key="hello.txt")
print("deny-all user: allowed")
except botocore.exceptions.ClientError as e:
print("deny-all user:", e.response["Error"]["Code"])
Run with AWS_CONFIG_FILE and AWS_SHARED_CREDENTIALS_FILE pointing at ~/.aws/emulator/9297/:
account: 000000000000
s3 object: b'hi'
deny-all user: AccessDenied
Seeing 000000000000 is the check that matters most. The security docs put the risk plainly: "If AWS_ENDPOINT_URL isn't set, your code calls AWS with whatever credentials it finds." AWS's own walkthrough unsets AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN and AWS_PROFILE before running anything. Do the same in the script that runs your tests, not in your shell profile, and have the tests fail if the account ID isn't all zeros.
Don't Test Your Security Here
AWS is direct about this. The security page opens with a warning: "Don't use AWS Emulator to test whether your application is secure. Passing tests in the emulator don't show that your permissions are correct or safe." It lists IAM policies, bucket policies, KMS key policies, and cross-account access as things not to test, and says: "The emulator never denies a request signed with its own key. It doesn't check AWS KMS key policies or Amazon S3 bucket policies." The launch post is softer: it says the emulator doesn't evaluate IAM and resource-based policies "the way AWS does, so a request that AWS denies might succeed in the emulator."
So I tested a bucket policy. I gave an IAM user s3:*, then added a bucket policy denying s3:GetObject to everyone:
# Does the emulator enforce an S3 bucket policy that denies reads?
import boto3, botocore, json
s = boto3.Session()
s3, iam = s.client("s3"), s.client("iam")
s3.create_bucket(Bucket="private")
s3.put_object(Bucket="private", Key="secret.txt", Body=b"payroll")
iam.create_user(UserName="reader")
iam.put_user_policy(
UserName="reader", PolicyName="allow-s3",
PolicyDocument=json.dumps({"Version": "2012-10-17", "Statement": [
{"Effect": "Allow", "Action": "s3:*", "Resource": "*"}]}),
)
s3.put_bucket_policy(Bucket="private", Policy=json.dumps({
"Version": "2012-10-17", "Statement": [{
"Effect": "Deny", "Principal": "*", "Action": "s3:GetObject",
"Resource": "arn:aws:s3:::private/*"}]}))
key = iam.create_access_key(UserName="reader")["AccessKey"]
reader = boto3.Session(aws_access_key_id=key["AccessKeyId"],
aws_secret_access_key=key["SecretAccessKey"]).client("s3")
try:
print("reader, bucket policy denies GetObject:",
reader.get_object(Bucket="private", Key="secret.txt")["Body"].read())
except botocore.exceptions.ClientError as e:
print("reader, bucket policy denies GetObject:", e.response["Error"]["Code"])
reader, bucket policy denies GetObject: AccessDenied
Two follow-up runs against the same emulator:
| Request | Result |
|---|---|
reader, with the bucket policy |
AccessDenied: "with an explicit deny in a resource-based policy" |
reader, after deleting the bucket policy |
Read succeeded |
| The emulator's own key, with the bucket policy put back | AccessDenied |
So on 1.0.385 the emulator did enforce a bucket policy, including against its own key, which the security page says it never denies. That isn't a reason to start trusting it. It's the opposite. The user guide and the binary disagree, and the binary is rebuilt by agents as AWS's models change. Whatever it does today about a given policy, you have no stable contract for it. A deny that works in the emulator tells you nothing about whether your real policy is right.
Two more warnings from the security page are worth repeating:
- Function code isn't sandboxed. "When the emulator runs code for you, such as function code, it doesn't isolate that code from your machine. The code runs with your user's permissions and can read and change your files." A Lambda function in the emulator is a program on your laptop.
- Some resources get their own ports. Resources such as databases can get "an endpoint of their own on another port of
127.0.0.1," and those ports "don't check request signatures." On a shared machine, other users can reach them.
We recommend reading What is Docker? Containers, Images, and Why Every Developer Needs to Know This to continue reading our selection of content. The emulator's only path to macOS and Windows is a container you build yourself, and that piece covers how images and port publishing work.
What is Docker? Containers, Images, and Why Every Developer Needs to Know This Docker packages your app and its dependencies into a container that runs the same everywhere. How containers and images work, and Docker in production. SudoSecurity · Santhdium
Where It Fits
| Use it for | Don't use it for |
|---|---|
| Unit and integration tests of AWS API calls | Testing IAM, bucket, or KMS policies |
| CI jobs that shouldn't touch an account | Anything holding real data or real credentials |
| Letting a coding agent iterate without a deployment | Running code you haven't read |
| Checking request shapes and error codes | Proving your app is safe to ship |
The emulator returns HTTP 501 for operations it doesn't implement yet, so a test hits a clear failure instead of a fake success. AWS publishes per-service "fidelity tests" in a public repository, scored as how many of each service's tests match real AWS. Check the scores for the services you use before relying on it.
For CI, add --idle-timeout so a forgotten emulator stops on its own, and --telemetry off if your runner shouldn't phone home.
What This Doesn't Cover
I tested the Debian package, release 1.0.385, on x86_64 Linux, run as a normal user, with no network access for the emulator. I tested STS, S3, and IAM only. I didn't test the Docker build, the embedded Rust mode, Lambda, DynamoDB, or the fidelity test suite. The policy results are from one release, and the next one may differ. That's the point of the section above.
I also didn't check the emulator's license. The announcement says the source is on GitHub, and the package includes third-party notices.
The Actual Point
AWS Emulator gets the dangerous defaults right: loopback only, signed requests, keys that die with the process, files only your user can read. Use it to speed up tests that make AWS calls.
Don't let it near the questions that matter most. Who can read this bucket, and whether this role is too broad, still need real AWS. And make every test script check for account 000000000000 before it runs, so a missing variable can't send your test suite to production.
The boto3 scripts are original code using boto3 1.44.3's documented client API, run on November 16, 2026 against AWS Emulator 1.0.385 installed from AWS's Debian package. The version output, listening socket, warnings, telemetry notice, and results are reproduced from those runs, and the follow-up table summarizes two further runs against the same emulator. Quotes are from AWS's launch post and the AWS Emulator user guide pages on security, telemetry, and the command reference.
$ tail -f /forums
Discussion
Comments live on the community forums — sign in there to reply.