Today we’re announcing AWS Emulator, a local emulator for Amazon Web Services (AWS) that you run on your machine. The AWS Command Line Interface (AWS CLI) , the AWS SDKs , and your coding agents speak to it over a local HTTPS endpoint using the same AWS APIs they would use in the cloud, from your laptop. AWS Emulator has no additional service fee.
You pay only for AWS resources when you deploy on AWS. Its source is on GitHub. You install it from an RPM or Debian package on Linux, and on macOS and Windows you run it in Docker.
How it works You install the emulator, start it, and point your tools at the local endpoint. When AWS Emulator starts, it generates its own credentials, a config file, and a certificate, and writes them to ~/. aws/emulator/9297/ .
You set environment variables so the AWS SDK talks to your laptop instead of AWS, and your application code stays unchanged. From there, your existing tests, CLI scripts, and coding agents keep working the way they already do. A unit test that creates an Amazon DynamoDB table, writes an item, and reads it back is the same test, and it runs on your machine without a deployment.
A coding agent can create resources, check the result, and iterate again without waiting on a deployment in a Region. The emulator is implemented in Rust so that it stays light on CPU and memory on a laptop. It supports the APIs of AWS services that have an API model in the AWS API models repository on GitHub, and because it’s built from those models, the same ones the AWS SDKs use, your requests and the errors you get back have the same shape as on AWS.
If you are a developer, especially one working with coding agents such as Kiro or Claude Code, you can use that loop to test AWS interactions of real complexity locally. Let’s try it out To get started, I installed the package on Amazon Linux 2023 . The package adds the aws-emulator command to /usr/bin/ , so it’s on the path.
PKG=https://downloads. aws. com/aws-emulator/packages/aws-emulator/LTS/latest sudo dnf install -y $PKG/aws-emulator-x86_64.
rpm aws-emulator -v On macOS and Windows, you build a Docker image from the short Dockerfile in the documentation and run the emulator in a container. We don’t publish a ready-made image. I started the emulator with aws-emulator .
It serves HTTPS on 127. 0. 0.
1:9297 , so only my own computer can reach it, and it writes its log as JSON lines that show the address, the config file, and the certificate file. aws-emulator In another terminal, I set the environment variables that point the AWS CLI at the emulator, and unset any variables that could supply real AWS credentials. export AWS_ENDPOINT_URL=https://127.
- 1:9297 export AWS_SHARED_CREDENTIALS_FILE=~/.
aws/emulator/9297/emulator_credentials export AWS_CONFIG_FILE=~/. aws/emulator/9297/config 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 unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE The emulator generates new keys each time it starts.
Its access key IDs start with EMULATOR , so you can’t mistake them for real AWS keys, and it rejects requests signed with any other keys. To confirm that my shell was talking to the emulator, I checked the health endpoint and the caller identity. The emulator uses a single account, 000000000000 .
curl --cacert ~/. aws/emulator/9297/ca. pem https://127.
- 1:9297/__admin/health aws sts get-caller-identity Then I created a bucket, copied in a small object, and listed it.
$ aws s3 mb s3://local-getting-started make_bucket: local-getting-started $ echo "hello from the emulator" > hello. txt $ aws s3 cp hello. txt s3://local-getting-started/ upload: .
/hello. txt to s3://local-getting-started/hello. txt $ aws s3 ls s3://local-getting-started/ With the AWS CLI pointed at my laptop, I had the same commands I already use and a local endpoint that answered them.
Next I wanted to see it the way I actually work now, so with the emulator still running I opened Kiro and asked it to create an Amazon DynamoDB table, write an item, and read it back, all against AWS Emulator rather than my AWS account. kiro> Using the local AWS Emulator (the environment variables are already set in this shell), create a DynamoDB table "kiro-demo" with a string key "id", put an item {id: "item-1", msg: "hello from kiro"}, then read it back with get-item.
$ aws dynamodb create-table --table-name kiro-demo \ --attribute-definitions AttributeName=id,AttributeType=S \ --key-schema AttributeName=id,KeyType=HASH \ --billing-mode PAY_PER_REQUEST $ aws dynamodb put-item --table-name kiro-demo \ --item '{"id": {"S": "item-1"}, "msg": {"S": "hello from kiro"}}' $ aws dynamodb get-item --table-name kiro-demo --key '{"id": {"S": "item-1"}}' To use the same setup with an existing test suite, I would start the emulator, set the same environment variables in the script that runs the tests, and run them as usual.
Using the emulator in process Running the emulator as a local process gives you an HTTPS endpoint that works with the AWS CLI and the AWS SDKs through environment variables. Some SDKs need an extra setting to trust the emulator certificate, for example a trust store for the AWS SDK for Java . For tests, there is a second option.
AWS Emulator ships an embedded mode that you instantiate directly inside your test process and wire into the SDK through its HTTP client, rather than talking to a separate server over the network. Each embedded instance keeps its own state, so tests do not share buckets, tables, or queues, and you can run many of them in parallel. Embedded mode is available for the AWS SDK for Rust .
You add the aws-emulator-embedded crate from GitHub to the [dev-dependencies] section of your Cargo. toml file. The following example creates an Amazon DynamoDB table, writes an item, and reads it back, entirely in process.
Originally published at aws.amazon.com
