AWS Emulator: Deploy Your Terraform Infrastructure Locally, Without an AWS Account
- Published on
- Authors

- Name
- Sylvain BRUAS
- @sylvain_bruas
There is a friction everyone knows when building infrastructure on AWS: to check that a terraform apply goes through, you need an account, credentials, a remote state backend, and you have to accept seeing (and paying for) real resources appear. For a static site like this rΓ©sumΓ© site β an Amazon Simple Storage Service (S3) bucket, an Amazon CloudFront distribution, a handful of policies β that is a lot of ceremony just to validate that the code holds up.
AWS Emulator addresses exactly this need: a single command, aws-emulator, that exposes AWS service APIs over HTTPS on 127.0.0.1:9297. The AWS Command Line Interface (AWS CLI), the SDKs and β what matters here β the Terraform provider work unmodified once they are pointed at the emulator. No AWS account, no bill, a fully local state. This article walks through the end-to-end setup on this project, with the real commands and, above all, the limits I ran into along the way.
The Problem: Validating Infrastructure Without Deploying It for Real
The site's infrastructure is plain Terraform, split into two modules:
- an S3 module: the hosting bucket, public access blocking, static website configuration and versioning;
- a CloudFront module: the distribution, an Origin Access Control, two cache policies (HTML and static assets), and a CloudFront Function that redirects
/to/fr/at the edge.
The provider.tf points to a remote S3 backend with locking on Amazon DynamoDB, and an AWS Certificate Manager (ACM) provider in us-east-1 for the certificate. In other words, nothing runs without a properly configured, real AWS account. For a simple check like "is my plan consistent and does my apply pass", that is disproportionate. The emulator lets you replay exactly that cycle locally.
What AWS Emulator Brings
The idea is to substitute the real AWS APIs, at the network endpoint level, with a local server that speaks the same protocol (SigV4, same request and response shapes). Concretely:
- One command, one port.
aws-emulatorlistens on127.0.0.1:9297and serves the APIs over HTTPS with a certificate regenerated at each startup. - Native on Linux, containerized elsewhere. The emulator runs natively only on Linux. On macOS and Windows, you run it in a container built from the Linux package.
- Emulator credentials. At each startup, it writes a disposable key/secret pair (access keys start with
EMULATOR) and aca.pem. All requests run in account000000000000. - In-memory state. Everything disappears when the process stops: no persistence, no cleanup to do.
- Tooling compatibility. The AWS CLI, the SDKs and the
hashicorp/awsTerraform provider work without patching: you only need to redirect the endpoint and supply the emulator credentials.
Step-by-Step Setup
1. The Emulator in a Container (via Colima)
On macOS there is no native binary: you build an image from the RPM package of the latest release, then run the container on the loopback interface only, with telemetry disabled.
FROM public.ecr.aws/amazonlinux/amazonlinux:2023-minimal
ARG TARGETARCH
RUN case "$TARGETARCH" in arm64) a=aarch64 ;; amd64) a=x86_64 ;; *) exit 1 ;; esac \
&& curl -fsSLo /tmp/aws-emulator.rpm \
"https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-$a.rpm" \
&& rpm -i /tmp/aws-emulator.rpm && rm /tmp/aws-emulator.rpm \
&& mkdir -p /home/emulator && chown 1000 /home/emulator
USER 1000
ENV HOME=/home/emulator
ENV PATH=/opt/aws-emulator/bin:$PATH
EXPOSE 9297
ENTRYPOINT ["aws-emulator", "-b", "0.0.0.0"]
One detail that costs a first error: the legacy Docker builder (the one in Colima without buildx) does not set TARGETARCH automatically β that is a BuildKit feature. You therefore have to pass the architecture explicitly:
docker build --build-arg TARGETARCH=arm64 -t aws-emulator ~/.aws/emulator-build
Then start the container, published only on 127.0.0.1, and wait for the health check rather than an arbitrary sleep:
mkdir -p ~/.aws/emulator/9297
docker run -d --rm --name aws-emulator \
--network aws-emulator \
--cap-drop ALL --security-opt no-new-privileges --read-only \
-p 127.0.0.1:9297:9297 \
-e EMULATOR_TELEMETRY=off \
-v "$HOME/.aws/emulator/9297:/home/emulator/.aws/emulator/9297" \
aws-emulator
for i in $(seq 30); do
curl -sf --cacert ~/.aws/emulator/9297/ca.pem \
https://127.0.0.1:9297/__admin/health && break
sleep 1
done
Check that you are really hitting the emulator and not real AWS β the account must be 000000000000:
( . ~/.aws/emulator/9297.env && aws sts get-caller-identity )
# {
# "Account": "000000000000",
# "Arn": "arn:aws:iam::000000000000:user/emulator"
# }
2. Redirect Terraform to the Emulator Without Touching the Versioned Code
The Terraform code must not be modified: we rely on the *_override.tf file mechanism, which merges with existing blocks. Three local, uncommitted files are enough.
Local backend (backend_override.tf) β we replace the S3/DynamoDB backend with a local state file, so Terraform does not try to reach real AWS:
terraform {
backend "local" {
path = "emulator.tfstate"
}
}
Redirected provider (provider_override.tf) β we point each service to the emulator, with the disposable credentials and the skip_* flags that avoid validation calls to AWS:
provider "aws" {
region = "us-east-1"
access_key = "EMULATOR...." # read from emulator_credentials
secret_key = "...."
custom_ca_bundle = "/Users/sbruas/.aws/emulator/9297/ca.pem"
skip_credentials_validation = true
skip_metadata_api_check = true
skip_region_validation = true
skip_requesting_account_id = true
endpoints {
s3 = "https://127.0.0.1:9297"
cloudfront = "https://127.0.0.1:9297"
acm = "https://127.0.0.1:9297"
sts = "https://127.0.0.1:9297"
iam = "https://127.0.0.1:9297"
}
}
The aliased us_east_1 provider (for ACM/CloudFront) gets the same treatment. Finally, an emulator.auto.tfvars file supplies the required bucket_name variable.
3. init, plan, apply
Everything happens in a subshell that sources the emulator's environment file, so that no real credentials leak:
cd infrastructure
( . ~/.aws/emulator/9297.env && terraform init -reconfigure )
( . ~/.aws/emulator/9297.env && terraform plan -out=emulator.tfplan )
( . ~/.aws/emulator/9297.env && terraform apply -auto-approve emulator.tfplan )
Result:
Apply complete! Resources: 10 added, 0 changed, 0 destroyed.
Outputs:
bucket_arn = "arn:aws:s3:::sylvain-bruas-cv-website"
cloudfront_distribution_url = "127.0.0.1:33947"
distribution_id = "E1MJV490Q2CKJ1"
And we verify on the emulator side that the resources really exist, rather than relying on Terraform's exit code alone:
( . ~/.aws/emulator/9297.env && aws s3api list-buckets --query 'Buckets[].Name' )
( . ~/.aws/emulator/9297.env && aws cloudfront list-distributions \
--query 'DistributionList.Items[].{Id:Id,Status:Status}' --output table )
The sylvain-bruas-cv-website bucket and the E1MJV490Q2CKJ1 distribution (status Deployed) are both there. In a few minutes, the full plan β apply β verification cycle runs locally, with no AWS account and without spending a cent.
Limits and Points of Attention
This is the most important part. The emulator is excellent for validating a flow, but it reproduces the APIs, not the full behavior of AWS. Several limits are by design and cannot be worked around.
The 1,000-Object Bucket Cap Is Not Configurable
While uploading the site build (aws s3 sync out/), the upload stopped dead:
An error occurred (ValidationException) when calling the PutObject operation:
the bucket "sylvain-bruas-cv-website" already holds the maximum of 1000 objects
this emulator keeps per bucket; delete an object before writing "robots.txt"
Out of 1,543 local files, only 1,000 were accepted. The natural question is: can this cap be raised?
Answer: no. After reviewing all of the emulator's options, this 1,000-objects-per-bucket cap is hard-coded in the build and exposed through no setting:
- no command-line option (
aws-emulator -honly offers the port-p, the bind address-b, signatures-a, telemetry-tand--idle-timeout); - no dedicated environment variable;
- no configuration file:
~/.aws/emulator/config.tomlonly handles telemetry, and the per-runconfigfile is reserved for the SDKs.
It is a limit of the same family as the other by-design constraints: in-memory state only, a single account and a single region per emulator, no resource policy evaluation. The only way to "free" space is to delete existing objects from the bucket. In practice, for a large site, you test the deployment flow on a subset (for example by excluding a heavy images folder) rather than aiming for an exhaustive upload. This cap is specific to the emulator: a real S3 bucket has no limit on the number of objects.
Resource Policies Are Not Evaluated
The aws_s3_bucket_policy with its AWS:SourceArn condition is indeed created, but its access restriction is not actually enforced. The emulator never rejects a request signed with its own keys: it is not designed to test AWS Identity and Access Management (IAM), bucket policies, AWS Key Management Service (KMS) key policies or cross-account access. Validating authorization logic remains a job for a real account (or a static policy analysis tool).
CloudFront + OAC: You Test the Structure, Not the Behavior
This is the concrete corollary of the two previous limits, and a question that comes up quickly: can I, locally, serve the bucket's files through CloudFront to check that the Origin Access Control (OAC) is correctly in place? The answer is no, for two reasons that add up:
- No CloudFront data plane. The emulator implements the control-plane APIs (
CreateDistribution,GetDistribution,ListDistributions), which is enough for Terraform to create the distribution and retrieve aDomainNameand anId. But there is no edge/CDN that actually serves content: the returnedDomainName(here127.0.0.1:33947) is only an API value, and nothing listens on it to fetch an object from S3, apply the cache policies or run the/ β /fr/CloudFront Function. Acurlon that domain does not return the site's page. - No resource policy evaluation. OAC relies entirely on authorization: the bucket policy only grants
s3:GetObjectif thePrincipalis the CloudFront service andAWS:SourceArnmatches the distribution's ARN. Since the emulator never evaluates these policies, it cannot tell you whether OAC "lets through" aGETvia CloudFront, nor whether it "blocks" a directGETon S3.
What the emulator does confirm is that the configuration is structurally correct: the distribution exists, the OAC is created (signing_behavior = "always", signing_protocol = "sigv4") and attached to the origin, and the bucket policy is in place with the right Principal, the right Action and the right SourceArn condition. That is already useful to catch typos and miswired ARNs. The runtime behavior, however, can only be verified against a real account. The reference test, to run on a real environment (staging):
#!/usr/bin/env bash
# verify-oac.sh β run against a REAL AWS account, not the emulator.
set -euo pipefail
DISTRIBUTION_ID="${1:?usage: verify-oac.sh <distribution-id> <bucket> <key>}"
BUCKET="${2:?missing bucket}"
KEY="${3:-index.html}"
REGION="${AWS_REGION:-eu-west-1}"
DOMAIN=$(aws cloudfront get-distribution --id "$DISTRIBUTION_ID" \
--query 'Distribution.DomainName' --output text)
echo "== 1. Via CloudFront (must return 200) =="
curl -s -o /dev/null -w " https://%{url_effective} -> %{http_code}\n" \
"https://$DOMAIN/$KEY"
echo "== 2. Direct S3 access (must return 403 thanks to OAC) =="
curl -s -o /dev/null -w " https://%{url_effective} -> %{http_code}\n" \
"https://$BUCKET.s3.$REGION.amazonaws.com/$KEY"
echo
echo "OAC OK if: step 1 = 200 AND step 2 = 403."
echo "If step 2 returns 200, the bucket is directly accessible: OAC protects nothing."
Upstream of the deployment, a static analysis completes the picture: re-read that the bucket policy opens nothing other than CloudFront, and that the public_access_block is active with no residual public ACL.
State Is In-Memory, and There Is Only One Account / Region
When the container stops (docker stop aws-emulator), everything disappears: no persistence, no reset route β you restart the process to start clean. Likewise, the emulator accepts any region but does not partition resources by region or by account: to test several regions, you run one emulator per region, each on its own port.
Coverage Per Build, and the TLS Trap
An unimplemented operation returns NotImplemented (HTTP 501): this is a coverage gap in the installed build, not a configuration error. Finally, because the container rewrites the ca.pem path to an internal path, you must keep AWS_CA_BUNDLE pointed at the host-side ca.pem β and never disable TLS verification.
Rebuild the Emulator? Yes, but Not to Bypass a Limit
The emulator is open source (aws/aws-emulator repository, written in Rust): you can clone it and build it with cargo build. That makes sense to contribute, fix a behavior discrepancy, or use it in embedded mode in Rust tests (per-test state, no endpoint or certificate). On the other hand, rebuilding a patched version just to raise the 1,000-object cap is discouraged: you would drift away from the official build, its security fixes and its guaranteed compatibility scope. To faithfully test a large number of objects, you need a real S3 bucket, not a homemade build.
Best Practices
- Isolate the overrides. Put all emulator-specific configuration in uncommitted
*_override.tf/*.auto.tfvarsfiles, to never touch the production Terraform code. - Always the latest release. Do not pin an emulator version: fixes and new coverage only land in the latest release. Rebuild the image with
--no-cacheto refresh it. - Loopback only. Publish the port on
127.0.0.1exclusively, never on0.0.0.0on the host side. Keep real AWS credentials out of any shell that talks to the emulator (the.envfile does theunset). - Wait for the health check. Loop on
GET /__admin/healthbefore the first call, not a fixedsleep. - Verify the resource, not the exit code. An
applythat ends without error proves nothing: listing the created resources through the API confirms the result. - Test a subset when volume exceeds the limits. Faced with the 1,000-object cap, target what really validates the flow rather than a full upload.
Comparison: AWS Emulator vs Floci
AWS Emulator is not alone in this space. Among recent alternatives, Floci targets the same need β a local cloud to develop and test without a real account β but with a noticeably different scope and set of design choices. Comparing them helps frame when each is relevant.
What Both Tools Offer
The common ground is clear: a local endpoint that speaks the AWS protocol, disposable credentials, ephemeral state, and the promise of "no account, no bill, no blast radius". Both explicitly target development and continuous integration loops, and both lend themselves to infrastructure-as-code dry runs (OpenTofu, AWS CloudFormation) against localhost before touching a real account.
The Differences That Matter
- Cloud scope. AWS Emulator focuses on AWS. Floci is multicloud: it offers separate emulators for AWS, Azure, GCP and OCI, each on its own port, usable in isolation or in parallel. If your stack goes beyond AWS, that is an argument.
- Advertised coverage breadth. Floci highlights around 135 AWS services and presents itself as a drop-in replacement for LocalStack (same SDK endpoint override, same CLI options). AWS Emulator does not advertise a service count: its coverage is assessed per build, operation by operation, through a compatibility check.
- "Real engines" approach. Floci claims to run some services on real engines β AWS Lambda in real Docker containers, Amazon Relational Database Service (RDS) on real PostgreSQL/MySQL, Amazon ElastiCache on Redis β whereas AWS Emulator remains a reimplementation of the APIs (and, as we saw, does not run the Lambda triggers of the Amazon Cognito flow, for example).
- Startup and footprint. Floci advertises a startup time of around 24 ms and a very low memory footprint (GraalVM native image), designed to fit in the edit loop. AWS Emulator also starts quickly, but the first launch on macOS goes through building the container image.
- License and model. Floci presents itself as MIT, with no sign-up, no API key and no paid tier. AWS Emulator is also open source; its telemetry, however, is enabled by default and must be explicitly disabled (
-t off/EMULATOR_TELEMETRY=off), which is done here. - "Agents" positioning. Floci emphasizes use by coding agents (a dedicated skill, rules to paste into
AGENTS.md/CLAUDE.md): giving an agent a cloud "it cannot break". AWS Emulator serves the same sandbox purpose, but without this agent-centered product narrative.
Verification on a Real Machine: What Floci Actually Does Here
To avoid relying on marketing claims, Floci was run in a container (floci/floci image, v2.5.0, via Colima) and put through the same scenario as above: terraform apply of the S3 + CloudFront infrastructure, build upload, then HTTP requests. Three concrete findings stand out, and they contrast with AWS Emulator on this specific case.
-
No 1,000-object cap. Where AWS Emulator refuses anything beyond 1,000 objects per bucket, Floci accepted all 1,543 files of the build without complaint.
-
CloudFront really serves the content. This is the decisive difference for "testing your site". On Floci, the
cloudfront_distribution_urloutput is a real domain name (xxxx.cloudfront.net), and aGET /index.htmlrequest with the matchingHostheader returns the page's actual HTML served from the bucket (HTTP 200, content<html lang="fr">β¦). With AWS Emulator, the same distribution is just an API entry: nothing is served. Floci therefore does let you see the site rendered behind a local CloudFront β AWS Emulator does not. -
But OAC is not "really" enforced, and neither is the CloudFront Function. Two important caveats:
- Direct bucket access (outside CloudFront) also returns 200 instead of the 403 expected with a real OAC. Like AWS Emulator, Floci does not evaluate the bucket policy on the S3 side: the "CloudFront=200 / direct S3=403" OAC test fails on both sides on this point. Serving content is not proof that direct access is locked down.
- The
/ β /fr/CloudFront Function is not executed:GET /directly returns the HTML (with thex-amz-*headers of an S3 object) instead of a301to/fr/.
-
Telemetry: nothing left the machine, backed by network verification. Floci was run behind an
iptablesrule (on the Colima VM side) that blocks and counts any packet from the container to a public IP, with private ranges still allowed. After the full scenario (AWS Security Token Service (STS), creation of the 10 resources, upload of 1,543 objects, many CloudFrontGETs) and an idle period, the blocked-packet counter remained at 0. No attempt to send anything outside was observed: on this version and this scenario, Floci sent no telemetry data. (The evidence is observational β it holds for what was exercised, not an absolute guarantee across all code paths.)
When to Prefer One or the Other
To validate the Terraform structure of a simple AWS infrastructure (S3 + CloudFront) from a macOS workstation with Colima, AWS Emulator does the job without extra dependencies. But to actually display the site behind a local CloudFront β or to exceed the 1,000-object cap β Floci has the clear advantage: it serves the content, AWS Emulator does not. Floci is also relevant if the need widens (several clouds, broader coverage, real engines for Lambda/RDS/Redis, agent integration).
In both cases, the same golden rule remains, and the tests above confirm it: these tools validate the structure and the call mechanics, not the security behavior. Neither proves that an OAC locks down direct access to the bucket, and neither faithfully runs a CloudFront Function. Final validation of OAC and the edge is done against a real account.
Conclusion
AWS Emulator transforms the infrastructure validation loop: you replay plan, apply and resource inspection locally, in a few minutes, with no AWS account and no bill. For a project like this static rΓ©sumΓ© site, it is the fastest way to make sure a Terraform change holds up before pushing it to a real account.
The key is to keep in mind what it is not: a substitute for AWS. State is ephemeral, resource policies are not evaluated, coverage depends on the build, and some limits β like the non-configurable cap of 1,000 objects per bucket β are hard-coded. Think of it as a high-fidelity local test bench: perfect for framing and debugging quickly, but final validation always happens against the real service.

