{"slug": "test-your-applications-against-aws-locally-with-aws-emulator", "title": "Test your applications against AWS locally with AWS Emulator", "summary": "AWS released AWS Emulator, a local emulator that lets developers run AWS CLI, AWS SDKs, and coding agents against AWS APIs over a local HTTPS endpoint at 127.0.0.1:9297 without deploying to the cloud. The emulator is written in Rust, is installed from an RPM or Debian package on Linux and runs in Docker on macOS and Windows, generates its own credentials and certificate in ~/.aws/emulator/9297/, and carries no additional service fee beyond AWS resources used on deployment. AWS said the emulator supports the APIs of services that have an API model in the AWS API models repository, so requests and returned errors match the shape of AWS.", "body_md": "## [AWS News Blog](https://aws.amazon.com/blogs/aws/)\n\n# Test your applications against AWS locally with AWS Emulator\n\n|  | \n\nToday 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)](https://aws.amazon.com/cli/), the [AWS SDKs](https://aws.amazon.com/developer/tools/), 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.\n\n**How it works**\n\n         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.\n\nFrom there, your existing tests, CLI scripts, and coding agents keep working the way they already do. A unit test that creates an [Amazon DynamoDB](https://aws.amazon.com/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.\n\nThe 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.\n\nIf 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.\n\n**Let’s try it out**\n\n         To get started, I installed the package on [Amazon Linux 2023](https://aws.amazon.com/linux/amazon-linux-2023/). The package adds the `aws-emulator` command to `/usr/bin/`, so it’s on the path.\n\n```\nPKG=https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest\nsudo dnf install -y $PKG/aws-emulator-x86_64.rpm\n\naws-emulator -v\n```\n\nOn 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.\n\nI 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.\n\n```\naws-emulator\n```\n\nIn 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.\n\n```\nexport AWS_ENDPOINT_URL=https://127.0.0.1:9297\nexport AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials\nexport AWS_CONFIG_FILE=~/.aws/emulator/9297/config\nexport AWS_EC2_METADATA_DISABLED=true\nexport AWS_DISABLE_HOST_PREFIX_INJECTION=true\nexport AWS_REGION=us-east-1\nexport AWS_DEFAULT_REGION=us-east-1\nunset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE\n```\n\nThe 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`.\n\n```\ncurl --cacert ~/.aws/emulator/9297/ca.pem https://127.0.0.1:9297/__admin/health\n\naws sts get-caller-identity\n```\n\nThen I created a bucket, copied in a small object, and listed it.\n\n``` bash\n$ aws s3 mb s3://local-getting-started\nmake_bucket: local-getting-started\n\n$ echo \"hello from the emulator\" > hello.txt\n\n$ aws s3 cp hello.txt s3://local-getting-started/\nupload: ./hello.txt to s3://local-getting-started/hello.txt\n\n$ aws s3 ls s3://local-getting-started/\n```\n\nWith the AWS CLI pointed at my laptop, I had the same commands I already use and a local endpoint that answered them.\n\nNext I wanted to see it the way I actually work now, so with the emulator still running I opened [Kiro](https://kiro.dev/) 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.\n\n```\nkiro> Using the local AWS Emulator (the environment variables\n      are already set in this shell), create a DynamoDB table\n      \"kiro-demo\" with a string key \"id\", put an item\n      {id: \"item-1\", msg: \"hello from kiro\"}, then read it\n      back with get-item.\n\n$ aws dynamodb create-table --table-name kiro-demo \\\n    --attribute-definitions AttributeName=id,AttributeType=S \\\n    --key-schema AttributeName=id,KeyType=HASH \\\n    --billing-mode PAY_PER_REQUEST\n\n$ aws dynamodb put-item --table-name kiro-demo \\\n    --item '{\"id\": {\"S\": \"item-1\"}, \"msg\": {\"S\": \"hello from kiro\"}}'\n\n$ aws dynamodb get-item --table-name kiro-demo --key '{\"id\": {\"S\": \"item-1\"}}'\n```\n\nTo 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.\n\n**Using the emulator in process**\n\n         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](https://aws.amazon.com/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](https://aws.amazon.com/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.\n\n```\nuse aws_emulator_embedded::{AwsEmulatorEmbedded, EmbeddedOptions};\nuse aws_sdk_dynamodb::types::{\n    AttributeDefinition, AttributeValue, BillingMode, KeySchemaElement, KeyType,\n    ScalarAttributeType,\n};\n\n#[tokio::test]\nasync fn put_then_get_returns_the_item() {\n    let emulator = AwsEmulatorEmbedded::new(EmbeddedOptions::default());\n    let config = aws_config::defaults(aws_config::BehaviorVersion::latest())\n        .http_client(emulator.http_client())\n        .region(aws_config::Region::new(\"us-east-1\"))\n        .credentials_provider(emulator.aws_credentials_provider())\n        .load()\n        .await;\n    let ddb = aws_sdk_dynamodb::Client::new(&config);\n\n    ddb.create_table()\n        .table_name(\"emulator-demo-table\")\n        .attribute_definitions(\n            AttributeDefinition::builder()\n                .attribute_name(\"id\").attribute_type(ScalarAttributeType::S)\n                .build().unwrap())\n        .key_schema(\n            KeySchemaElement::builder()\n                .attribute_name(\"id\").key_type(KeyType::Hash)\n                .build().unwrap())\n        .billing_mode(BillingMode::PayPerRequest)\n        .send().await.unwrap();\n\n    ddb.put_item()\n        .table_name(\"emulator-demo-table\")\n        .item(\"id\", AttributeValue::S(\"item-1\".into()))\n        .item(\"msg\", AttributeValue::S(\"hi\".into()))\n        .send().await.unwrap();\n\n    let got = ddb.get_item()\n        .table_name(\"emulator-demo-table\")\n        .key(\"id\", AttributeValue::S(\"item-1\".into()))\n        .send().await.unwrap();\n    assert_eq!(got.item().unwrap().get(\"msg\").unwrap().as_s().unwrap(), \"hi\");\n}\n```\n\nWhen it runs as a local process, the emulator requires every request to be signed with Signature Version 4 (SigV4), the same way AWS does, and it exposes a `/__admin/health` endpoint on the same port so a script or a container can wait until it is ready before running tests. By default it also sends anonymous usage and error data, and you can turn it off.\n\n**How we measure fidelity**\n\n         An emulator is only useful if a test that passes against it would also pass against AWS, so we measure that directly with fidelity tests. A fidelity test is a short program that uses an AWS SDK to run a workflow, such as storing an object and then reading and deleting it, and asserts how AWS behaves. We verify each fidelity test against real AWS. A fidelity test passes only if the emulator matches AWS on the response to every call, including the status code, the body, and the exact error code and message, and on the resources and data that the workflow creates.\n\nWith each release, we publish how many fidelity tests pass for each service, as k of n. For example, 40 of 50 means that 40 of the service’s 50 fidelity tests pass. The set of fidelity tests is public in the aws-emulator-evaluation-suite repository on GitHub, including the ones that don’t pass yet, so you can see what we verified and run the fidelity tests yourself. Read a score as a snapshot of a product that’s improving. When we add fidelity tests, a score can go down even while the emulator gets better.\n\nIf the emulator doesn’t implement an operation yet, it returns HTTP 501 (Not Implemented), so your tests fail right away. If the emulator acts differently from AWS, you can tell us by opening an issue in the AWS Emulator repository on GitHub.\n\n**How the emulator is built**\n\n         AWS Emulator is built and maintained by agents from the AWS API models using [Amazon Bedrock AgentCore](https://aws.amazon.com/bedrock/agentcore/) Runtime Instances, [AWS CodePipeline](https://aws.amazon.com/codepipeline/), and [AWS CodeCommit](https://aws.amazon.com/codecommit/), so it stays current with AWS as those models change.\n\nOne group of agents looks for gaps, both by comparing emulator responses against real AWS and by statically comparing the emulator’s code against the published Smithy models, and files an issue for each gap it finds. Another group picks up an issue, writes tests, implements the behavior, and reviews the change for correctness, performance, and security. When the change is ready, it is pushed to a source repository, and that push triggers an AWS CodePipeline run that runs the fidelity tests before the change is published to the public GitHub repository.\n\n**How we keep it secure**\n\n         Because the code is written by agents, an independent security agent reviews changes adversarially, both while the fix is being made and again in the release pipeline as a final check before anything ships.\n\nSecurity of your own use remains a shared responsibility. We build the emulator to run safely on your machine: it listens only on your own computer by default and rejects requests that aren’t signed with its own keys. You decide where it runs, what data you put in it, and how you test before production. Don’t use the emulator to test whether your application is secure. It doesn’t evaluate [AWS Identity and Access Management (IAM)](https://aws.amazon.com/iam/) policies and resource-based policies the way AWS does, so a request that AWS denies might succeed in the emulator. Keep real credentials out of the environment of your test jobs, and test your security settings and your whole application on AWS before you go to production.\n\n**Now available**\n\n         AWS Emulator is generally available today. It has no additional service fee. You pay only for AWS resources when you deploy on AWS. You can install it from RPM or Debian packages on Linux, run it in Docker on macOS and Windows, or build from source, and it works with the AWS SDKs and the AWS CLI once you set environment variables. At launch, it has some limits. It doesn’t evaluate IAM policies the way AWS does, and each emulator acts as a single account, with no cross-account or cross-Region behavior. How closely it matches AWS varies by service and feature. To see how well the emulator covers the services that you use, check the fidelity scores in the AWS Emulator documentation.\n\nIf you want to check regional availability, visit the [AWS Capabilities by Region](https://builder.aws.com/capabilities/?trk=f11c83db-08fa-4852-aa10-20185beeaef6&sc_channel=el) page in AWS Builder Center. If you want to call APIs, search documentation, find regional availability, and check troubleshooting about this new feature, try using the [AWS MCP Server](https://docs.aws.amazon.com/agent-toolkit/latest/userguide/getting-started-aws-mcp-server.html) and [plugins](https://docs.aws.amazon.com/agent-toolkit/latest/userguide/plugins.html) with your preferred AI tool.\n\nTo get started, see the AWS Emulator documentation.", "url": "https://wpnews.pro/news/test-your-applications-against-aws-locally-with-aws-emulator", "canonical_source": "https://aws.amazon.com/blogs/aws/test-your-applications-against-aws-locally-with-aws-emulator/", "published_at": "2026-11-11 19:00:44+00:00", "updated_at": "2026-11-11 19:23:02.813636+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": ["AWS", "AWS Emulator", "AWS CLI", "AWS SDKs", "Amazon DynamoDB", "Amazon Linux 2023", "Kiro", "Claude Code"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/test-your-applications-against-aws-locally-with-aws-emulator", "markdown": "https://wpnews.pro/news/test-your-applications-against-aws-locally-with-aws-emulator.md", "text": "https://wpnews.pro/news/test-your-applications-against-aws-locally-with-aws-emulator.txt", "jsonld": "https://wpnews.pro/news/test-your-applications-against-aws-locally-with-aws-emulator.jsonld"}}