Website: https://xsavikx.github.io/aws-emulator-docker/
This project publishes a multi-architecture container image of the AWS Emulator, a local emulator of the AWS APIs. You can run the image immediately. You do not build it first.
AWS does not publish a prebuilt image. The official guide tells you to build one yourself. This project builds that image, tests it, signs it, and publishes it for you. A scheduled workflow checks for a new upstream release every hour. After a new upstream release, the workflow usually publishes a new image in about one to two hours.
A blog post about docker run, Compose, GitHub Actions and known problems:
Running AWS Emulator in Docker, on any arch, in CI
This is an unofficial community project. It is not affiliated with or endorsed by Amazon Web Services.
mkdir -p ~/.aws/emulator
docker run --rm -p 127.0.0.1:9297:9297 --user "$(id -u):$(id -g)" \
-e HOME="$HOME" -v "$HOME/.aws/emulator:$HOME/.aws/emulator" ghcr.io/xsavikx/aws-emulatorIn a second terminal:
export AWS_ENDPOINT_URL=https://127.0.0.1:9297 AWS_CA_BUNDLE=~/.aws/emulator/9297/ca.pem \
AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials AWS_CONFIG_FILE=~/.aws/emulator/9297/config
aws sts get-caller-identity # "Account": "000000000000"With rootless Docker, use --user 0:0. In CI, use the
Run AWS Emulator action. For
Windows, SDKs and Compose, see Run it step by step.
The AWS guide
tells you to build the image yourself. This project gives you a built image that is also smaller.
The sizes are for linux/amd64, uncompressed:
| Image | Size |
|---|---|
| Built with the Dockerfile from the AWS guide | 1.86 GB |
| This project, Amazon Linux (default) | 1.49 GB |
| This project, Debian | 1.48 GB |
| This project, distroless | 1.39 GB |
The guide's Dockerfile uses ADD for the RPM package. The rm in the next step does not
remove the 180 MB package from the image, because the package stays in the ADD layer.
This project mounts the package only for the install step. Measured on 2026-11-14 with
emulator 1.0.367 (guide) and 1.0.366 (this project).
The guide's image also does not check the package signature and runs no tests. This project checks the AWS signature on each package, tests each image, and signs it. See Supply chain.
GitHub Container Registry:
docker pull ghcr.io/xsavikx/aws-emulatorDocker Hub:
docker pull docker.io/xsavikx/aws-emulatorQuay.io:
docker pull quay.io/xsavikx/aws-emulatorFor the Debian or distroless variant, add the :debian or :distroless tag. All tags and
digests are the same on the three registries.
Platforms: linux/amd64 and linux/arm64. Docker Desktop on macOS (Intel and Apple
silicon) and on Windows (x64 and Arm, WSL 2 backend) runs these Linux images. Docker,
Podman, containerd and Kubernetes on Linux run them natively.
| Tag | Meaning |
|---|---|
latest, lts |
The newest LTS release |
<version>-<yyyymmdd>.<run> |
One build. This tag never moves. |
<version> |
The exact upstream package version, for example 1.0.322.1 |
<emulator-version> |
The emulator version (as aws-emulator --version reports it), for example 1.0.322 |
1.0, 1 |
The newest release in that line |
sha-<commit> |
The build from one commit of this repository |
| Variant | Base image | Tags |
|---|---|---|
| Amazon Linux (default) | public.ecr.aws/amazonlinux/amazonlinux:2023-minimal |
latest, <version>, ... |
| Debian | debian:trixie-slim (Debian 13) |
debian, latest-debian, <version>-debian, 1.0-debian, ... |
| Distroless | gcr.io/distroless/cc-debian13 |
distroless, latest-distroless, <version>-distroless, ... |
Each tag of the default variant has a matching tag with the -debian suffix and a matching
tag with the -distroless suffix. The three variants install the same upstream emulator.
The Amazon Linux variant installs it from the .rpm package. The Debian and distroless
variants install it from the .deb package. The three variants use the same user (UID 1000),
port and health check route. Use the Debian variant if your tooling expects apt and Debian.
The distroless variant contains only glibc, the emulator and a small static health check
program in Go. It has no shell, no package manager and no curl, so security scanners
report very few findings. You cannot docker exec a shell into it. Its Docker HEALTHCHECK
runs the Go program. The other two variants run a shell script with curl. The entry point
of the distroless variant is /opt/aws-emulator/bin/aws-emulator -b 0.0.0.0. The other two
variants use aws-emulator -b 0.0.0.0.
The version tags move when the image is rebuilt (for example for a base image fix). For reproducible builds, pin a build tag or a digest. Each build is listed in the releases.
-
Create the working directory before the first start:
mkdir -p ~/.aws/emulator -
Start the emulator (macOS and Linux). With rootless Docker, use
--user 0:0instead of--user "$(id -u):$(id -g)". Otherwise the start fails withPermission denied (os error 13).PORT=9297 docker run --rm --memory=2g --memory-swap=2g -p 127.0.0.1:$PORT:$PORT \ --user "$(id -u):$(id -g)" \ -e HOME="$HOME" -v "$HOME/.aws/emulator:$HOME/.aws/emulator" \ ghcr.io/xsavikx/aws-emulator -p $PORT
Windows PowerShell:
New-Item -ItemType Directory -Force "$env:USERPROFILE\.aws\emulator" $port = 9297 docker run --rm --memory=2g --memory-swap=2g -p "127.0.0.1:${port}:${port}" ` -v "$env:USERPROFILE\.aws\emulator:/home/emulator/.aws/emulator" ` ghcr.io/xsavikx/aws-emulator -p $port
-
Point the AWS CLI or an SDK at it:
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_DEFAULT_REGION=us-east-1 unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE aws sts get-caller-identity # Account: 000000000000
Node.js needs
NODE_EXTRA_CA_CERTS, Rust and .NET needSSL_CERT_FILE, and Java needs thetruststore.p12file. See the SDK guide. -
Stop it with Ctrl+C or
docker stop. The emulator removes its runtime files from~/.aws/emulator/<port>/. All state is in memory and goes away.
See compose.yaml.
mkdir -p ~/.aws/emulator
UID_GID="$(id -u):$(id -g)" docker compose up
# With rootless Docker:
UID_GID=0:0 docker compose up-
examples/has integration tests in Python (pytest), TypeScript (Vitest), Java (JUnit 5), Go (go test), C# (xUnit) and Rust (cargo test). They cover STS, S3, DynamoDB, SQS, SNS to SQS and Secrets Manager. CI runs them on amd64 and arm64 every day and after each image release. -
The Run AWS Emulator GitHub Action (source) starts the emulator in your own workflow and sets the SDK environment:
- uses: xSAVIKx/run-aws-emulator@v1 - run: aws sts get-caller-identity
- Bind address. The image starts
aws-emulator -b 0.0.0.0, so Docker can forward the port. Always publish the port on127.0.0.1. A plain-p 9297:9297exposes the emulator to your whole network. - Same port on both sides. The emulator writes its files to
~/.aws/emulator/<port>/. If you change the port, change it in all three places: the host side of-p, the container side of-p, and the emulator-pargument. Do not use-p 0. - TLS. The emulator serves HTTPS with a self-signed certificate that it creates at each
start (
ca.pem). Your client must trust that file. - Memory. Give the container 2 GiB. If it goes over the limit, Docker stops it with exit code 137 and you lose all emulated resources.
- Telemetry. The upstream emulator sends anonymous usage telemetry by default. This image
does not change that. To turn it off, add
-e EMULATOR_TELEMETRY=off. A variable in your own shell does not reach the container. - Health check. The image has a Docker
HEALTHCHECKthat calls/__admin/health. If you use a port other than 9297, also set-e EMULATOR_HEALTHCHECK_PORT=<port>. - User. The image runs as UID 1000. On Linux with rootful Docker, add
--user "$(id -u):$(id -g)"so the files in~/.aws/emulatorbelong to you. With rootless Docker, use--user 0:0instead: container root maps to your host user. Without it, or with your own UID, the emulator stops withPermission denied (os error 13). With Podman, use--userns=keep-id. - Other containers. The emulator certificate names only
localhost,127.0.0.1and::1. A client in another container that callshttps://aws-emulator:9297fails TLS validation. Run the client in the network namespace of the emulator instead (docker run --network container:<emulator> ...withhttps://127.0.0.1:<port>). - Use
127.0.0.1, notlocalhost. With a host name, some SDKs use virtual-hosted S3 addresses such asbucket.localhost. These addresses do not resolve. The AWS SDK for JavaScript v3 is an example of such an SDK. - No Windows containers. The emulator runs only on Linux. On Windows, use Linux containers (Docker Desktop with WSL 2).
Every published image has:
- Open Container Initiative labels and index annotations (
org.opencontainers.image.*), includingversion,revision,created,source,licenses,base.nameandbase.digest. - An SBOM and SLSA provenance (
mode=max) attestation from BuildKit. - A keyless cosign signature.
- A GitHub artifact attestation (GHCR).
The build downloads a pinned upstream version (from versions.json). It checks the SHA-256
digest of each package. It checks the RPM or DEB package signature with the AWS package
signing key:
- Signer:
SSM Publishing <ssm-publishing@amazon.com> - Fingerprint:
98BC F336 A3BE 53B7 34E9 67C5 2E5B F49B D940 F624 - Source: https://downloads.aws.com/keys/gpg/current.asc, stored in
keys/
Each base image is pinned by digest.
Verify a signature (cosign v3 or later; v2 reports "no signatures found"):
cosign verify ghcr.io/xsavikx/aws-emulator:latest \
--certificate-identity 'https://github.com/xSAVIKx/aws-emulator-docker/.github/workflows/release.yml@refs/heads/main' \
--certificate-oidc-issuer https://token.actions.githubusercontent.comWithout a local cosign installation, run cosign as a container:
docker run --rm ghcr.io/sigstore/cosign/cosign:v3.1.4 verify ghcr.io/xsavikx/aws-emulator:latest \
--certificate-identity 'https://github.com/xSAVIKx/aws-emulator-docker/.github/workflows/release.yml@refs/heads/main' \
--certificate-oidc-issuer https://token.actions.githubusercontent.comVerify the GitHub attestation:
gh attestation verify oci://ghcr.io/xsavikx/aws-emulator:latest --owner xSAVIKx --format jsonThe AWS signature on the package tells you that the emulator binary comes from AWS. The cosign signature and the attestations tell you that the image comes from the release workflow of this repository, from a known commit. These checks do not tell you that the emulator code is free of defects. This project does not review or change the upstream code. Use the emulator for local and CI tests only. Do not give it real AWS credentials or production data.
For a local test, build for the platform of your host and load the image into Docker
with --load:
docker buildx build --load -t aws-emulator:dev .
docker buildx build --load -f Dockerfile.debian -t aws-emulator:dev-debian .
docker buildx build --load -f Dockerfile.distroless -t aws-emulator:dev-distroless .
tests/smoke.sh aws-emulator:devA multi-platform build needs --push to a registry. Without --load or --push, the build
keeps the result only in the build cache, and Docker has no local image:
docker buildx build --platform linux/amd64,linux/arm64 --push -t <registry>/aws-emulator:dev .Each Dockerfile downloads the pinned LTS package for each target architecture. The Amazon
Linux variant checks the signature of the .rpm package with rpmkeys. The Debian and
distroless variants check the detached .sig file of the .deb package with gpg.
To build another version, pass --build-arg EMULATOR_VERSION=<version>. Use a version from
versions.json,
or latest. To also check the SHA-256 digests, pass --build-arg RPM_SHA256_AMD64=<sha> and
--build-arg RPM_SHA256_ARM64=<sha>. For the Debian and distroless variants, pass
DEB_SHA256_AMD64 and DEB_SHA256_ARM64 instead.
- The files in this repository: Apache License 2.0. Copyright 2026 Yurii Serhiichuk.
- The AWS Emulator: CC0 1.0 Universal, with code in its
vendor/directory under the Apache License 2.0. See aws/aws-emulator. - The base images
public.ecr.aws/amazonlinux/amazonlinux:2023-minimal,debian:trixie-slimandgcr.io/distroless/cc-debian13: see the licenses of their packages.
Created and maintained by Yurii Serhiichuk (yurii@serhiichuk.dev, serhiichuk.dev, @xSAVIKx). Contributions are welcome. See CONTRIBUTING.md.