AWS has released AWS Emulator, a free local copy of the AWS APIs. You run it
on your own machine, point the AWS CLI or an SDK at it, and your code creates
buckets, tables and functions without an AWS account, without a bill, and
without anything leaving your laptop.
I wanted to answer one question: can I test AWS code entirely in containers, locally and in CI, with no AWS account at
all? Short answer: yes, after four gotchas. Here's what I built and what I
learned.
What AWS Emulator is (and isn't)
- A local server for the AWS APIs. It listens on one HTTPS port (
127.0.0.1:9297by default) and answers the same API calls AWS does. - No console. There's no web UI. You use the AWS CLI and SDKs, exactly as you would against AWS.
- Unchanged tools. You switch your tools over with environment variables, not code changes.
- Throwaway by design. Everything lives in memory, so restarting gives you a clean slate. That's great for tests.
- One fake account,
000000000000. Runaws sts get-caller-identity; if you see that account, you're talking to the emulator and not to AWS.
What I built
A deliberately small project:
github.com/sadebare/aws-emulator-docker
- A Python script (plain boto3) that creates an S3 bucket, uploads a file, lists the bucket and reads the file back
- Two containers: the emulator and the script, started together by Docker Compose
- A GitHub Actions workflow that runs the whole thing on every push
The important part is what the script doesn't contain: anything about the
emulator. It's ordinary boto3. Environment variables decide whether it talks
to the emulator or to real AWS.
Running it is one command:
docker compose up --build app-1 | Talking to: https://127.0.0.1:9297 app-1 | Created bucket my-local-bucket app-1 | Uploaded /app/sample.txt -> s3://my-local-bucket/uploads/sample.txt app-1 | Read back s3://my-local-bucket/uploads/sample.txt: app-1 | Hello from my laptop. This file went to S3 without ever leaving my machine. The four gotchas
1. "CERTIFICATE_VERIFY_FAILED"
My very first aws s3 ls failed. The emulator serves HTTPS with a self-signed
certificate that it creates on every start, and saves to
~/.aws/emulator/9297/ca.pem. Point the CLI and SDKs at it:
export AWS_CA_BUNDLE=~/.aws/emulator/9297/ca.pem Don't reach for --no-verify-ssl. It switches off a security check, and the
request still fails because of gotcha 2.
2. Your real AWS keys don't work
The emulator generates a new access key and secret key on every start and
rejects everything else, including your real keys. It writes them to
~/.aws/emulator/9297/emulator_credentials, so you point your tools at that
file and unset any real keys in the shell:
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 When the emulator runs in Docker, mount ~/.aws/emulator into the container
so those files land on your machine.
3. Containers can't call it by name
In Docker Compose, the natural move is to call the emulator by its service
name, https://emulator:9297. That fails:
hostname 'emulator' doesn't match either of 'localhost', '127.0.0.1', '0:0:0:0:0:0:0:1' The certificate is only valid for localhost and 127.0.0.1. The fix is a
single line: make the app container share the emulator's network, so
127.0.0.1 inside the app is the emulator.
app: build: ./app network_mode: "service:emulator" A health check on the emulator, plus depends_on: condition: service_healthy,
makes sure the script only starts once the emulator is ready.
4. File permissions on the shared volume
The emulator saves its keys and certificate so that only its own user (ID 1000)
can read them, and the app container reads them from a shared volume. Two
changes made that work:
- the app container runs as
USER 1000 - the emulator's Dockerfile creates
~/.aws/emulatorowned by user 1000
Without the second change, Docker creates the volume owned by root and the
emulator can't write its files at all.
Running it in CI: no AWS account, no secrets
Because everything is containers, CI is just the same command:
- uses: actions/checkout@v4 - run: docker compose up --build --abort-on-container-exit --exit-code-from app The job passes only if the script succeeds. There are no access keys in
GitHub secrets and no test account to clean up, and the emulator disappears
when the job ends. For me, that's the strongest reason to use it.
What surprised me when I pushed further
I also tried more than S3. Some of it worked better than I expected; some of
it didn't work at all.
- S3 events trigger Lambda. Uploading a file invoked a Lambda function within about a second.
- IAM permissions were enforced. The docs say the emulator doesn't evaluate IAM policies the way AWS does, and warn against using it to test security. Even so, when my Lambda role allowed reading only one S3 folder, reading another failed with
AccessDenied. - Lambda's Python is RustPython, not CPython.
sys.versiongives it away. My log-parsing code was roughly 40 times slower than on standard Python, so don't use the emulator for performance testing. - Container services are early.
docker pushto the emulator's ECR registry fails. ECS checks your setup like real AWS (networking, execution role, ECR permissions) but couldn't run real programs in my tests. Lambda functions packaged as container images can be created but not invoked.
Should you use it?
Yes, for:
- testing code that calls AWS APIs: S3, DynamoDB, SQS, Lambda with Python or Node.js
- CI pipelines where you don't want AWS credentials anywhere
- learning AWS without the fear of a surprise bill
Not yet, for:
- performance testing
- running real container workloads on ECS
- security testing (use real AWS for that)
And LocalStack? It's more mature, has a web UI and runs real containers.
But since March 2026 its free tier needs an account and an auth token, and
reportedly isn't for commercial use. AWS Emulator is free, made by AWS, and
very new, so it's improving fast. For my use case, testing AWS code in Docker
and CI with zero credentials, I'm using AWS Emulator.
The full project, with the Compose file, Dockerfiles and CI workflow, is on
GitHub: sadebare/aws-emulator-docker.
Clone it, run docker compose up --build, and you've got AWS on your laptop in about a minute.

