AWS has introduced AWS Emulator, a local testing environment that runs on developer machines and accepts requests through a local HTTPS endpoint identical to the AWS APIs used in production. The tool integrates with the AWS Command Line Interface, AWS SDKs, and AI coding agents without requiring any additional fees—developers pay only when deploying actual resources to AWS. The emulator's source code is available on GitHub, with installation via RPM or Debian packages on Linux, or Docker containers on macOS and Windows.
How it works
After installation and startup, users point their tools at the local endpoint. The emulator generates its own credentials, configuration file, and certificate, storing them in ~/.aws/emulator/9297/. Setting environment variables redirects the AWS SDK to the local machine instead of AWS, while application code remains unchanged.
Existing tests, CLI scripts, and coding agents continue functioning as normal. A unit test that creates an Amazon DynamoDB table, inserts an item, and retrieves it runs locally without deployment. AI coding agents can create resources, verify results, and iterate without waiting for regional deployments.
Built in Rust for minimal CPU and memory overhead on laptops, the emulator supports APIs for AWS services that have models in the AWS API models repository on GitHub. Since it uses the same models as the AWS SDKs, requests and error responses match AWS behavior exactly.
Getting started
Installation on Amazon Linux 2023 adds the aws-emulator command to /usr/bin/:
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, users build a Docker image from the provided Dockerfile and run the emulator in a container. AWS does not publish a pre-built image.
Starting the emulator with aws-emulator serves HTTPS on 127.0.0.1:9297, accessible only from the local machine. It logs output as JSON lines showing the address, config file, and certificate file location.
aws-emulator
In a separate terminal, environment variables redirect the AWS CLI to the emulator:
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_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 fresh keys on each startup with access key IDs beginning with EMULATOR, preventing confusion with real AWS credentials. It rejects requests signed with any other keys. The emulator operates as a single account with ID 000000000000.
Verification of connectivity to the emulator:
curl --cacert ~/.aws/emulator/9297/ca.pem https://127.0.0.1:9297/__admin/health aws sts get-caller-identity
Basic S3 operations demonstrate standard AWS CLI functionality against the local endpoint:
$ 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/
The same CLI commands work against the local endpoint as they do against AWS. AI coding agents like Kiro can create DynamoDB tables, write items, and read them back entirely against the emulator:
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 integrate with existing test suites, users start the emulator, set the same environment variables in the test script, and run tests normally.
Embedded mode for testing
Running the emulator as a local process provides an HTTPS endpoint for the AWS CLI and SDKs via environment variables. Some SDKs require additional configuration to trust the emulator certificate, such as a trust store for the AWS SDK for Java. For testing, AWS Emulator offers embedded mode, where the emulator instantiates directly inside the test process and connects through the SDK's HTTP client rather than over the network. Each embedded instance maintains separate state, so tests do not share buckets, tables, or queues, and many can run in parallel. Embedded mode is currently available for the AWS SDK for Rust.
Add the aws-emulator-embedded crate from GitHub to the [dev-dependencies] section of Cargo.toml. This example creates a DynamoDB table, writes an item, and reads it back entirely in-process:
use aws_emulator_embedded::{AwsEmulatorEmbedded, EmbeddedOptions};
use aws_sdk_dynamodb::types::{
AttributeDefinition, AttributeValue, BillingMode, KeySchemaElement, KeyType,
ScalarAttributeType,
};
#[tokio::test]
async fn put_then_get_returns_the_item() {
let emulator = AwsEmulatorEmbedded::new(EmbeddedOptions::default());
let config = aws_config::defaults(aws_config::BehaviorVersion::latest())
.http_client(emulator.http_client())
.region(aws_config::Region::new("us-east-1"))
.credentials_provider(emulator.aws_credentials_provider())
.load()
.await;
let ddb = aws_sdk_dynamodb::Client::new(&config);
ddb.create_table()
.table_name("emulator-demo-table")
.attribute_definitions(
AttributeDefinition::builder()
.attribute_name("id").attribute_type(ScalarAttributeType::S)
.build().unwrap())
.key_schema(
KeySchemaElement::builder()
.attribute_name("id").key_type(KeyType::Hash)
.build().unwrap())
.billing_mode(BillingMode::PayPerRequest)
.send().await.unwrap();
ddb.put_item()
.table_name("emulator-demo-table")
.item("id", AttributeValue::S("item-1".into()))
.item("msg", AttributeValue::S("hi".into()))
.send().await.unwrap();
let got = ddb.get_item()
.table_name("emulator-demo-table")
.key("id", AttributeValue::S("item-1".into()))
.send().await.unwrap();
assert_eq!(got.item().unwrap().get("msg").unwrap().as_s().unwrap(), "hi");
}
When running as a local process, the emulator requires all requests to be signed with Signature Version 4 (SigV4), matching AWS requirements. It exposes a /__admin/health endpoint on the same port, allowing scripts or containers to wait for readiness before running tests. By default, the emulator sends anonymous usage and error data, which can be disabled.
Measuring fidelity
An emulator provides value only if tests passing against it would also pass on AWS. Fidelity tests measure this directly—short programs using an AWS SDK to run workflows like storing and retrieving objects, then asserting AWS behavior. Each fidelity test is verified against real AWS. A test passes only when the emulator matches AWS on every response detail: status code, body, error code, error message, and resources and data created by the workflow.
With each release, AWS publishes fidelity test pass rates for each service as k of n. For example, 40 of 50 means 40 of 50 fidelity tests pass for that service. The fidelity test suite is public in the aws-emulator-evaluation-suite repository on GitHub, including tests not yet passing, so users can verify what was tested and run fidelity tests themselves. A score represents a snapshot of an improving product; adding new fidelity tests can lower a score even as the emulator improves.
If the emulator has not implemented an operation, it returns HTTP 501 (Not Implemented), causing tests to fail immediately. When the emulator behaves differently from AWS, users can report issues in the AWS Emulator repository on GitHub.
How the emulator is built
AWS Emulator is built and maintained by agents using the AWS API models, Amazon Bedrock AgentCore Runtime Instances, AWS CodePipeline, and AWS CodeCommit, keeping it current as those models evolve.
One group of agents identifies gaps by comparing emulator responses against real AWS and statically comparing emulator code against published Smithy models, filing issues for each gap. Another group picks up issues, writes tests, implements behavior, and reviews changes for correctness, performance, and security. When ready, changes are pushed to a source repository, triggering an AWS CodePipeline run that executes fidelity tests before publishing to the public GitHub repository.
Security considerations
Because agent-written code requires independent review, a security agent reviews changes adversarially both during development and in the release pipeline as a final check before shipping.
Security of user deployments remains a shared responsibility. The emulator is designed to run safely on local machines: it listens only on the local computer by default and rejects unsigned requests. Users control where it runs, what data enters it, and testing before production. The emulator should not be used to test application security. It does not evaluate AWS Identity and Access Management (IAM) policies and resource-based policies the way AWS does, so requests AWS would deny might succeed in the emulator. Keep real credentials out of test job environments, and test security settings and the full application on AWS before production deployment.
Availability and limitations
AWS Emulator is generally available today with no additional service fee—users pay only for AWS resources deployed to AWS. Installation is available via RPM or Debian packages on Linux, Docker on macOS and Windows, or from source. It works with AWS SDKs and the AWS CLI after setting environment variables.
At launch, the emulator has certain limitations. It does not evaluate IAM policies the way AWS does, and each emulator instance acts as a single account with no cross-account or cross-Region behavior. Coverage varies by service and feature. Users should check fidelity scores in the AWS Emulator documentation to see how well the emulator covers their services.
For regional availability information, users can visit the AWS Capabilities by Region page in AWS Builder Center. The AWS MCP Server and plugins work with preferred AI tools for calling APIs, searching documentation, finding regional availability, and troubleshooting. Detailed setup instructions are available in the AWS Emulator documentation.