--- title: "Run AWS Emulator on a remote server for your agents" description: "Run AWS's own AWS Emulator as a service on an exe.dev VM, so Claude Code, Codex and your scripts test S3, DynamoDB, Lambda and Terraform without AWS keys." url: https://exe-staging.dev/deploy/aws-emulator category: "Developer tools" updated: 2026-11-14 --- # Run AWS Emulator on a remote server for your agents A fake AWS that's always up, for agents that shouldn't have real AWS keys. - **Software:** AWS Emulator (https://docs.aws.amazon.com/emulator/latest/userguide/what-is-service.html) - **Source:** https://github.com/aws/aws-emulator - **License:** CC0-1.0 (vendor/ code Apache-2.0) - **Time:** 10 minutes - **Example VM name:** `my-aws-emulator` (yours will differ; on the VM, `hostname` prints it) - **Machine-readable:** https://exe-staging.dev/deploy/aws-emulator/manifest.json ## What you get - AWS Emulator from AWS's package, running as `exedev` on 127.0.0.1:9297, back after a reboot - The emulator's usage telemetry turned off - The AWS CLI, and `~/aws-emulator.env`, which points the CLI and SDKs at the emulator - `aws sts get-caller-identity` answers with the emulator's account, 000000000000 - Claude Code, Codex and Pi using exe.dev's LLM integration, with AWS's aws-emulator skill - A Git project at `~/project` whose AGENTS.md tells agents to use the emulator, never real AWS Running on the VM: - **AWS Emulator**: the aws-emulator Debian package from AWS, run as exedev by a systemd service, port 9297, data in `in memory only; keys and certificate in ~/.aws/emulator/9297` - **AWS CLI v2**: AWS's official installer - **Claude Code, Codex and Pi**: preinstalled; connected to exe.dev's LLM integration, with AWS's aws-emulator skill, data in `~/.claude, ~/.codex` - **Your project**: an AGENTS.md that sends every AWS call to the emulator, data in `~/project` How it is reached: - https://127.0.0.1:9297 (private): the emulator's AWS API, on the VM only; signed with this run's keys - ssh -L 9297:127.0.0.1:9297 my-aws-emulator.exe.xyz (private): the same API on your laptop, through an SSH tunnel ## Deploy with Shelley Open https://exe-staging.dev/new?prompt=Set%20up%20AWS%20Emulator%20on%20this%20VM%20by%20following%20the%20exe.dev%20recipe%20at%20https%3A%2F%2Fexe-staging.dev%2Fdeploy%2Faws-emulator.md%20from%20top%20to%20bottom.%0A%0AThe%20recipe%27s%20example%20VM%20name%20is%20my-aws-emulator.%20This%20VM%27s%20name%20is%20the%20output%20of%20%60hostname%60%3A%20use%20it%20wherever%20the%20recipe%20writes%20my-aws-emulator.%20Skip%20the%20step%20that%20creates%20the%20VM%3B%20you%20are%20on%20it.%0A%0AYou%20are%20done%20when%20all%20of%20these%20are%20true.%20Check%20each%20one%20yourself%3A%0A-%20AWS%20Emulator%20from%20AWS%27s%20package%2C%20running%20as%20%60exedev%60%20on%20127.0.0.1%3A9297%2C%20back%20after%20a%20reboot%0A-%20The%20emulator%27s%20usage%20telemetry%20turned%20off%0A-%20The%20AWS%20CLI%2C%20and%20%60~%2Faws-emulator.env%60%2C%20which%20points%20the%20CLI%20and%20SDKs%20at%20the%20emulator%0A-%20%60aws%20sts%20get-caller-identity%60%20answers%20with%20the%20emulator%27s%20account%2C%20000000000000%0A-%20Claude%20Code%2C%20Codex%20and%20Pi%20using%20exe.dev%27s%20LLM%20integration%2C%20with%20AWS%27s%20aws-emulator%20skill%0A-%20A%20Git%20project%20at%20%60~%2Fproject%60%20whose%20AGENTS.md%20tells%20agents%20to%20use%20the%20emulator%2C%20never%20real%20AWS%0A%0ARun%20the%20VM-side%20commands%20in%20%22Set%20up%20the%20VM%22%20only%3B%20skip%20creating%20the%20VM.%0AIf%20%60exeuntu%20configure%60%20reports%20an%20existing%20user%20config%2C%20leave%20it%20alone.%0AIf%20%60~%2Fproject%60%20or%20its%20AGENTS.md%20already%20exists%2C%20add%20the%20AWS%20section%20to%0Ait%20instead%20of%20replacing%20it.%20Never%20put%20real%20AWS%20credentials%20on%20this%20VM%2C%0Anever%20bind%20the%20emulator%20to%20anything%20but%20127.0.0.1%2C%20never%20run%20it%20with%0A%60--auth%20off%60%2C%20and%20never%20expose%20port%209297%20through%20the%20HTTPS%20proxy.%0AVerify%20with%20the%20checks%20at%20the%20end%20of%20that%20section%3A%20the%20service%20is%0Aactive%2C%20the%20health%20check%20prints%20%60ok%60%2C%20the%20log%20says%20telemetry%20is%0Adisabled%2C%20and%20%60aws%20sts%20get-caller-identity%60%20shows%20account%20000000000000.%20Then%20run%20the%20demo%20in%20%22Try%20it%22%20once%20to%20prove%0AS3%2C%20DynamoDB%20and%20Lambda%20work.%20Skip%20the%20later%20sections%20and%20the%20FAQ.%0AFinish%20by%20telling%20the%20owner%20that%20everything%20in%20the%20emulator%20lives%20in%0Amemory%20and%20is%20gone%20when%20the%20service%20restarts.%0A%0AFinish%20with%20the%20URLs%20I%20should%20open.%0A to create a VM whose agent, Shelley, follows this recipe. From a terminal: ```sh curl -fsSL https://exe-staging.dev/deploy/aws-emulator/prompt.txt | ssh exe.dev new --prompt=/dev/stdin ``` Or follow the steps below by hand. [AWS Emulator](https://github.com/aws/aws-emulator) is AWS's own local emulator of the AWS APIs: S3, DynamoDB, Lambda, SQS, IAM and hundreds more on one HTTPS endpoint, with no AWS account. Run it on an exe.dev VM and your coding agents get an AWS to build against that's always up and holds no real credentials. Claude Code or Codex can create buckets, deploy Lambdas and run `terraform apply` all day, and the worst they can do is break a fake. That's safer than handing an agent your AWS keys. The VM has none, and an AGENTS.md in your project tells every agent to source one file that points the CLI and SDKs at the emulator. Your laptop can use the same emulator through an SSH tunnel. > [!WARNING] > AWS Emulator keeps everything in memory. Restarting the service, a > reboot or an update empties it and makes new keys. It's for building > and testing, not for production data or for testing IAM policies and > other security settings, which it doesn't enforce the way AWS does. ## Set up the VM On your computer, create a VM and connect to it. Pick any free name; if you've already clicked Deploy or have a VM, skip the first command and use its name: ```bash ssh exe.dev new --name=my-aws-emulator ssh my-aws-emulator.exe.xyz ``` On the VM, install AWS Emulator from AWS's Debian package, and the AWS CLI with AWS's installer: ```bash curl -fsSLo /tmp/aws-emulator.deb "https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_$(dpkg --print-architecture).deb" sudo apt-get install -y /tmp/aws-emulator.deb curl -fsSLo /tmp/awscliv2.zip "https://awscli.amazonaws.com/awscli-exe-linux-$(uname -m).zip" (cd /tmp && unzip -qo awscliv2.zip && sudo ./aws/install --update) aws-emulator -v aws --version ``` The emulator sends anonymous usage telemetry to AWS by default. Turn it off for every run on this VM, in the settings file AWS [documents](https://docs.aws.amazon.com/emulator/latest/userguide/telemetry.html): ```bash mkdir -p ~/.aws/emulator printf '[telemetry]\nenabled = false\n' > ~/.aws/emulator/config.toml ``` Run the emulator as a service, as `exedev`. It listens on 127.0.0.1:9297 only, accepts only requests signed with this run's keys, and writes those keys, a config file and its certificate to `~/.aws/emulator/9297/`. The memory cap is AWS's suggestion; the needrestart line stops Ubuntu's package upgrades from restarting it, which would wipe its state: ```bash sudo tee /etc/systemd/system/aws-emulator.service >/dev/null < ~/aws-emulator.env <<'EOF' # Send the AWS CLI and SDKs to AWS Emulator on this VM, never to AWS. 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=$HOME/.aws/emulator/9297/emulator_credentials export AWS_CONFIG_FILE=$HOME/.aws/emulator/9297/config export AWS_CA_BUNDLE=$HOME/.aws/emulator/9297/ca.pem export NODE_EXTRA_CA_CERTS=$HOME/.aws/emulator/9297/ca.pem export AWS_EC2_METADATA_DISABLED=true export AWS_DISABLE_HOST_PREFIX_INJECTION=true export AWS_REGION=us-east-1 export AWS_DEFAULT_REGION=us-east-1 EOF echo 'source ~/aws-emulator.env' >> ~/.bashrc ``` Connect the agents to exe.dev's [LLM integration](/docs/integrations-llm), install AWS's `aws-emulator` skill for them (it explains the emulator's errors and checks whether a project's AWS calls are covered), and make a project whose AGENTS.md says where AWS is: ```bash exeuntu configure claude exeuntu configure codex env -u AWS_ENDPOINT_URL -u AWS_CONFIG_FILE -u AWS_SHARED_CREDENTIALS_FILE -u AWS_CA_BUNDLE \ aws agent-toolkit add-skill --skill-name aws-emulator --region us-east-1 mkdir -p ~/project && cd ~/project && git init -q cat >> AGENTS.md <<'EOF' # AWS on this VM This VM has no AWS account. AWS calls go to AWS Emulator, a local emulator of the AWS APIs, which runs as the systemd service `aws-emulator` on https://127.0.0.1:9297. - Before any `aws`, `terraform`, `cdk`, `sam` or SDK command, run `source ~/aws-emulator.env` in the same shell. - Don't install or start another emulator, and don't change the service. - State lives in memory: `sudo systemctl restart aws-emulator` empties it and makes new keys. Ask before restarting it. - Account 000000000000, Region us-east-1. Use one Region. - An operation that answers 501 NotImplemented is an emulator gap, not a bug in this code. EOF [ -e CLAUDE.md ] || ln -s AGENTS.md CLAUDE.md ``` Check it. The service is active, telemetry is off, the health route says `ok`, and the AWS CLI talks to the emulator's account, `000000000000`, with the user `arn:aws:iam::000000000000:user/emulator`: ```bash source ~/aws-emulator.env systemctl is-active aws-emulator journalctl -u aws-emulator | grep -o 'telemetry: disabled' curl -s --cacert "$AWS_CA_BUNDLE" https://127.0.0.1:9297/__admin/health; echo aws sts get-caller-identity ``` ## Try it: a bucket, a table and a Lambda On the VM, in a shell where you've run `source ~/aws-emulator.env` (new logins do it for you): ```bash aws s3 mb s3://demo-bucket aws dynamodb create-table --table-name demo-table \ --attribute-definitions AttributeName=id,AttributeType=S \ --key-schema AttributeName=id,KeyType=HASH --billing-mode PAY_PER_REQUEST aws dynamodb wait table-exists --table-name demo-table ``` Now a Python Lambda that writes to both. Like AWS, the emulator checks the function's role, so give it a policy: ```bash mkdir -p ~/demo-fn && cd ~/demo-fn cat > app.py <<'EOF' import boto3 s3 = boto3.client("s3") table = boto3.resource("dynamodb").Table("demo-table") def handler(event, context): name = event.get("name", "world") s3.put_object(Bucket="demo-bucket", Key=f"greetings/{name}.txt", Body=f"hello, {name}\n") table.put_item(Item={"id": name, "msg": "greeted"}) return {"greeted": name} EOF rm -f fn.zip && python3 -m zipfile -c fn.zip app.py aws iam create-role --role-name demo-fn --assume-role-policy-document \ '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Service":"lambda.amazonaws.com"},"Action":"sts:AssumeRole"}]}' aws iam put-role-policy --role-name demo-fn --policy-name demo --policy-document \ '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":["s3:PutObject","dynamodb:PutItem"],"Resource":"*"}]}' aws lambda create-function --function-name demo-fn --runtime python3.13 \ --handler app.handler --role arn:aws:iam::000000000000:role/demo-fn --zip-file fileb://fn.zip aws lambda wait function-active-v2 --function-name demo-fn aws lambda invoke --function-name demo-fn --cli-binary-format raw-in-base64-out \ --payload '{"name":"exe.dev"}' /tmp/out.json && cat /tmp/out.json; echo ``` The invoke prints `{"greeted": "exe.dev"}`, and the function's writes are there: ```bash aws s3 cp s3://demo-bucket/greetings/exe.dev.txt - aws dynamodb get-item --table-name demo-table --key '{"id":{"S":"exe.dev"}}' ``` The emulator runs Python and Node.js functions itself, with no Docker. As AWS [warns](https://docs.aws.amazon.com/emulator/latest/userguide/security.html), function code isn't isolated from the VM, so deploy only code you'd run yourself. ## Let the agents build against it Start an agent in the project: ```bash cd ~/project && claude ``` and give it something with AWS in it: > Write todo.py: store todo items in a DynamoDB table named todos (create > it if it's missing) with boto3, and list them. Run it to add "buy milk". It reads AGENTS.md, sources `~/aws-emulator.env`, and creates the table in the emulator. In our test, Claude Code did it in one go. Codex (`codex`) and Pi (`pi`) read the same AGENTS.md. Shelley, exe.dev's agent at `https://my-aws-emulator.shelley.exe.xyz/`, works too if you point it at `~/project`. The skill can also answer "will this repo work on AWS Emulator?": it checks the AWS calls your code makes against AWS's [fidelity tests](https://github.com/aws/aws-emulator-evaluation-suite). ### Terraform Terraform's AWS provider reads the same variables, so a plain provider block targets the emulator. Pin the provider below 6.23: from 6.23, `aws_s3_bucket` reads tags through S3 Control, whose requests can't reach the emulator ([issue #56](https://github.com/aws/aws-emulator/issues/56)). ```hcl terraform { required_providers { aws = { source = "hashicorp/aws", version = "~> 6.0, < 6.23.0" } } } provider "aws" {} resource "aws_s3_bucket" "uploads" { bucket = "tf-demo-uploads" } resource "aws_dynamodb_table" "items" { name = "tf-demo-items" billing_mode = "PAY_PER_REQUEST" hash_key = "id" attribute { name = "id" type = "S" } } ``` We ran `terraform apply` and `destroy` with this (provider 6.22.1, and 5.x) on Terraform 1.17. Install Terraform from [HashiCorp's apt repository](https://developer.hashicorp.com/terraform/install#linux) first. Support for CloudFormation, CDK and SAM varies by service; check the fidelity scores on the [releases page](https://github.com/aws/aws-emulator/releases). ## Use it from your laptop The emulator listens on the VM's 127.0.0.1 only, and its certificate is for `127.0.0.1`. An SSH tunnel keeps both true on your laptop. You need the AWS CLI or an SDK there. On your computer, copy this run's keys and certificate, and open the tunnel (it stays in the background until you close it): ```bash mkdir -p ~/.aws/my-aws-emulator scp 'my-aws-emulator.exe.xyz:.aws/emulator/9297/*' ~/.aws/my-aws-emulator/ ssh -fN -L 9297:127.0.0.1:9297 my-aws-emulator.exe.xyz ``` Then, in the shell that runs your code: ```bash D=~/.aws/my-aws-emulator unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE export AWS_ENDPOINT_URL=https://127.0.0.1:9297 AWS_CONFIG_FILE=$D/config \ AWS_SHARED_CREDENTIALS_FILE=$D/emulator_credentials AWS_CA_BUNDLE=$D/ca.pem \ NODE_EXTRA_CA_CERTS=$D/ca.pem AWS_DISABLE_HOST_PREFIX_INJECTION=true \ AWS_EC2_METADATA_DISABLED=true AWS_REGION=us-east-1 AWS_DEFAULT_REGION=us-east-1 aws sts get-caller-identity aws s3 ls ``` You see the agents' buckets. Each restart of the emulator makes new keys and a new certificate, so run the `scp` again after one. If port 9297 is busy on your laptop, tunnel another local port (`-L 9300:127.0.0.1:9297`) and use it in `AWS_ENDPOINT_URL`. Another exe.dev VM can open the same tunnel with an SSH key of its own that reaches only this VM: on your computer, `cat key.pub | ssh exe.dev ssh-key add --vm=my-aws-emulator` (see [VM-scoped SSH keys](/docs/vm-scoped-ssh-keys)). That key gets a shell on the emulator's VM, which holds nothing but fakes. ## In CI For CI, AWS's advice is an emulator per job, which also gives every run clean state. On exe.dev, where [CI jobs](/deploy/ci) run on fresh copies of a base VM, set up the base VM with the install, the telemetry setting and `~/aws-emulator.env` from [Set up the VM](#set-up-the-vm), without the service. Each job then starts its own: ```bash aws-emulator --idle-timeout 900 > /tmp/aws-emulator.log 2>&1 & source ~/aws-emulator.env for i in $(seq 30); do curl -sf --cacert "$AWS_CA_BUNDLE" https://127.0.0.1:9297/__admin/health && break; sleep 1; done # run your tests here ``` `--idle-timeout` stops it after 15 minutes without a call, in case the job forgets. ## When it's time for real AWS Keep real credentials off this VM; that's the point of it. When code is ready for an actual AWS account, deploy from a different VM with exe.dev's [AWS integration](/docs/integrations-aws-wif): the VM gets short-lived credentials for one IAM role through workload identity federation, with no access keys on disk. [Agent secrets](/deploy/agent-secrets) covers the same idea for other APIs. ## Restarts and starting over - **Clean slate on purpose:** `sudo systemctl restart aws-emulator`. Every resource is gone; `~/aws-emulator.env` keeps working because it names the files the new run writes. - **A reboot or an update** does the same. Keep what you need as code (Terraform, a seed script in `~/project`) and run it again. A Terraform state file from before the restart still lists the old resources; the next `terraform apply` notices they're gone and creates them again. - **The VM itself** keeps the emulator, the CLI, your code and the agents' setup. For a copy of all of it, run `ssh exe.dev cp my-aws-emulator my-aws-emulator-backup` on your computer. ## Update AWS ships releases several times a day, and security fixes only in the latest. Updating restarts the emulator, so its state goes too. On the VM: ```bash curl -fsSLo /tmp/aws-emulator.deb "https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_$(dpkg --print-architecture).deb" sudo apt-get install -y /tmp/aws-emulator.deb sudo systemctl restart aws-emulator aws-emulator -v ``` To hold a version your tests pass on, install a numbered package from [versions.json](https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/versions.json) instead, as AWS's [versioning guide](https://docs.aws.amazon.com/emulator/latest/userguide/versioning.html) shows. ## Troubleshooting - **`AccessDenied: Sign the request with the emulator credentials`.** Something supplied other keys. Run `source ~/aws-emulator.env` in that shell, which unsets `AWS_ACCESS_KEY_ID` and friends. On your laptop, copy the files again after an emulator restart. - **`Could not connect to the endpoint URL`.** The service is down or restarting: `systemctl status aws-emulator` and `journalctl -u aws-emulator -e`. On your laptop, check the tunnel. - **Certificate errors.** The client doesn't read `AWS_CA_BUNDLE`. The env file sets `NODE_EXTRA_CA_CERTS` for Node.js too; Rust and .NET need `SSL_CERT_FILE`, and Java the `truststore.p12` settings from [AWS's guide](https://docs.aws.amazon.com/emulator/latest/userguide/point-sdk-to-emulator.html#point-sdk-ca-java). Use `127.0.0.1`, not `localhost`, in the endpoint, or some SDKs put the bucket name in the host name. - **`ResourceNotFoundException` right after a create.** As on AWS, tables and functions start as `CREATING` or `Pending`; use `aws dynamodb wait table-exists` or `aws lambda wait function-active-v2`. - **`501 NotImplemented`, or a call that behaves unlike AWS.** A gap. Look in the repository's [issues folder](https://github.com/aws/aws-emulator/tree/main/issues) and report it on [GitHub](https://github.com/aws/aws-emulator/issues). Inside a Lambda, the bundled SDK makes only some calls; an error `SdkCallNotMade` names the ones it supports. - **Everything's gone.** The service restarted: `journalctl -u aws-emulator | grep 'starting'` shows when. ## Frequently asked questions ### What is AWS Emulator? AWS's own emulator of the AWS APIs, released as open source (CC0) in September 2026 and on the front page of Hacker News in November. One program serves every service on one HTTPS endpoint. You point the AWS CLI or an SDK at it with environment variables, and your code doesn't change. No AWS account is needed, and it costs nothing. ### Does it keep my buckets and tables after a restart? No. The emulator keeps everything in memory, and AWS says it isn't built for long-running use. A restart of the service, a reboot or an update empties it and makes new keys and a new certificate. What the VM keeps is everything around it: the emulator, your code, your Terraform and seed scripts, and the agents' setup, so getting back to a known state is one `terraform apply` away. ### How is it different from LocalStack? It's written by AWS, generated from AWS's API models, covers every service with a public model (operations it hasn't built yet answer `501 NotImplemented`), and AWS publishes per-service fidelity scores with each release. It runs natively on Linux with no Docker. It's also new: releases come several times a day, and gaps are tracked in the repository's `issues/` folder. ### Can I put it behind exe.dev's HTTPS proxy or make it public? Don't. AWS says not to open its ports to the internet. It serves HTTPS with a certificate for 127.0.0.1 only, Lambda functions run as your user on the VM, and AWS SDKs can't sign in to exe.dev's proxy anyway. Use it on the VM, or through an SSH tunnel, which keeps the address 127.0.0.1 and uses your exe.dev SSH key. ### Does it send data to AWS? Not your requests, responses or resources. By default it sends anonymous usage and error telemetry; this setup turns that off for every run on the VM in `~/.aws/emulator/config.toml`. To turn it back on, delete that file and restart the service. ### What does it cost? The emulator is free and needs no AWS account. You pay for the VM as part of your [exe.dev plan](https://exe.dev/pricing), and agent model usage through the [LLM integration](/docs/integrations-llm) is billed to your exe.dev account. The emulator uses about 160 MiB idle. ## Related - [Give agents API access without giving them the keys](https://exe-staging.dev/deploy/agent-secrets.md): Your agents call your APIs. The keys stay with exe.dev, outside the VM. - [Run Claude Code on a remote server](https://exe-staging.dev/deploy/claude-code.md): A computer for Claude. A breather for your laptop. - [Run Codex on a remote server](https://exe-staging.dev/deploy/codex.md): A computer for Codex. An early night for your laptop. - [Run CI on exe.dev, a fresh VM for every job](https://exe-staging.dev/deploy/ci.md): A warm base VM, a fresh copy per job, deleted when the job ends. - [Dev, Test, Prod: Choose One, Two, or Three](https://exe-staging.dev/deploy/dev-test-prod.md): You can build, test, and deploy on exe.dev. - [VS Code in your browser, with code-server](https://exe-staging.dev/deploy/code-server.md): Your editor in a tab. Your projects right where you left them.