What Is AWS Emulator and How Do You Install It? Test AWS Apps Locally with Claude Code and Codex (Tested on 1.0.322)

AWS Emulator is AWS's official local emulator of its service APIs, generally available since November 11, 2026 (US time). It has no additional service fee, its source is open, it needs no AWS account, and it covers more than 200 services. We tested version 1.0.322 on Debian 13. This guide covers the install commands, pointing the AWS CLI at the local endpoint to create an S3 bucket and a DynamoDB table, the errors we hit, and how to let Claude Code, Codex and Cursor write and test code against the emulator.

12 分钟阅读
What Is AWS Emulator and How Do You Install It? Test AWS Apps Locally with Claude Code and Codex (Tested on 1.0.322)

AWS Emulator is AWS's official local emulator of AWS. It serves an HTTPS endpoint on your own machine, and the AWS CLI, the AWS SDKs and coding agents call it with the same APIs they use in the cloud. You need no AWS account, and nothing it creates is a real cloud resource. According to the AWS News Blog, it became generally available (GA) on November 11, 2026 (US time), which was around 2:00 a.m. on November 12 in Beijing time.

On November 13, 2026 (Beijing time, UTC+8) we installed AWS Emulator 1.0.322, the version on the LTS channel at the time, on a Debian 13 x86_64 machine. With AWS CLI 2.40.1 we created an S3 bucket, a DynamoDB table, an SQS queue and a Lambda function. Then we had Claude Code 2.1.319 and Codex CLI 0.167.0 each write code and run tests against the emulator. Every command, timing and output below comes from that run.

Create API Key →

The short answer

QuestionAnswer
What is AWS Emulator?AWS's official local emulator of the AWS APIs, written in Rust, with no graphical interface. According to AWS, it is built from more than 400 API models and covers more than 200 AWS services.
Is there a service fee? Do I need an AWS account?According to AWS, there is no additional service fee and no AWS account is needed. The source is on GitHub under the CC0 public-domain dedication.
How do I install it?On Linux, install the RPM or Debian package. On macOS and Windows, build an image from the Dockerfile in the official docs (AWS does not publish a ready-made image). Rust projects can also use embedded mode.
How do I use it?Run aws-emulator. It listens on https://127.0.0.1:9297 by default. Set a few environment variables so the AWS CLI and SDKs point at it; your application code stays the same.
What did our test show?Download plus install took about 6 seconds, and the health check returned ok about 0.3 seconds after start. S3, DynamoDB, SQS and Lambda all worked. Claude Code finished the same "S3 + DynamoDB + pytest" task in about 32 seconds and Codex in about 81 seconds, with 2 passed on both.
The one thing to watchIt does not evaluate IAM policies the way AWS does, and it emulates a single account in a single Region. Test permissions and security on real AWS before production.

What AWS Emulator is

According to the AWS News Blog, AWS Emulator generates its own credentials, a config file and a certificate when it starts, and writes them to ~/.aws/emulator/9297/. Once your SDK's environment variables point there, requests go to your machine instead of AWS. It is built from the same API models the AWS SDKs use, so the data and errors you get back have the same shape as in the cloud.

The main use case is coding agents. According to @AWSNewsroom, every line of AWS Emulator's code was written by autonomous AI agents running on Amazon Bedrock AgentCore, with hundreds of agents organized into three teams that write tests, implement features and review changes. According to AWS's Swami Sivasubramanian in his guest post on All Things Distributed, the agents first write "fidelity tests" and make them pass against real AWS, then build the emulator until it passes the same tests. AWS CTO @Werner says it was written and tested entirely by agents and gives you a high-fidelity test environment for more than 200 AWS services.

The launch drew a lot of attention. By X's public metrics, as of early November 13 (Beijing time), the @AWSNewsroom launch post had about 111,000 views, 705 likes and 206 reposts, and the @awsdevelopers launch post had about 78,000 views, 1,203 likes and 758 bookmarks. The aws/aws-emulator GitHub repository had about 4,400 stars at the same time.

Timeline

Time (Beijing time)Event
November 111.0.322 released (aws-emulator -v shows a release date of 2026.11.10)
November 12, about 02:00The AWS News Blog, Werner and the official AWS accounts announce GA
November 13, 00:16The LTS/latest package we downloaded was still 1.0.322; v1.0.336 appeared on GitHub Releases at the same time

AWS Emulator ships releases very often, and the official skill says to always use the latest one, so your version number will probably be newer than ours.

Install AWS Emulator

The official docs offer four paths (see Getting started): let an AI coding agent install it for you, the Linux package, Docker, or Rust embedded mode.

Linux: RPM or Debian package

bash
# Debian / Ubuntu (x86_64)
curl -fsSLo aws-emulator.deb https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_amd64.deb
sudo apt-get install -y ./aws-emulator.deb

# Amazon Linux / Fedora / RHEL (x86_64)
sudo dnf install -y https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-x86_64.rpm

# Check the version
aws-emulator -v

On ARM machines, use aws-emulator_arm64.deb or aws-emulator-aarch64.rpm instead. The package installs into /opt/aws-emulator/ and puts the aws-emulator command in /usr/bin/.

Our output:

text
Version: 1.0.322
Release date: 2026.11.10
Commit: 7753983c6e495ec3612695b1336bf4936fc7b7fd

The deb package is about 171 MB. The download took 1.7 seconds, and download plus apt-get install took about 6 seconds in total. The docs also describe a GPG check: each package has a .sig file next to it, and after importing https://downloads.aws.com/keys/gpg/current.asc the fingerprint should be 98BC F336 A3BE 53B7 34E9 67C5 2E5B F49B D940 F624. We followed those steps and got Good signature from "SSM Publishing <ssm-publishing@amazon.com>".

macOS / Windows: build it from the Dockerfile

According to the Docker guide, AWS does not publish a prebuilt image; you build one from this Dockerfile. On Apple silicon, replace x86_64.rpm with aarch64.rpm:

dockerfile
FROM public.ecr.aws/amazonlinux/amazonlinux:2023-minimal
ADD https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-x86_64.rpm /tmp/aws-emulator.rpm
RUN 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
EXPOSE 9297
ENTRYPOINT ["aws-emulator", "-b", "0.0.0.0"]
bash
docker build -t aws-emulator .
mkdir -p ~/.aws/emulator
PORT=9297
docker run --rm --memory=2g --memory-swap=2g -p 127.0.0.1:$PORT:$PORT \
  -e HOME="$HOME" -v "$HOME/.aws/emulator:$HOME/.aws/emulator" \
  aws-emulator -p $PORT

Publish the port as -p 127.0.0.1:9297:9297, not -p 9297:9297; the short form opens the emulator to every machine on your network. Our test machine has no Docker, so we compiled the Docker path from the official docs and did not run it.

Start it and point the AWS CLI at it

In the first terminal, start the emulator (-t off turns off the anonymous telemetry that is on by default):

bash
aws-emulator -t off

The log is in JSON lines. One line gives the endpoint, config and certificate paths:

text
"endpoint_url":"https://127.0.0.1:9297","health_check_url":"https://127.0.0.1:9297/__admin/health","config_file":"/home/box/.aws/emulator/9297/config","ca_file":"/home/box/.aws/emulator/9297/ca.pem"

In a second terminal, set the environment variables. This set comes from the AWS News Blog; the last line clears any real AWS credentials:

bash
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

First confirm you are talking to the emulator:

bash
curl --cacert ~/.aws/emulator/9297/ca.pem https://127.0.0.1:9297/__admin/health
aws sts get-caller-identity

In our run the health check returned ok about 0.27 seconds after start. get-caller-identity returned the emulator's fixed account 000000000000 with the ARN arn:aws:iam::000000000000:user/emulator. If you see that account, your requests are not going to real AWS. The idle emulator used about 283 MB of resident memory.

Test run: S3, DynamoDB, SQS, Lambda

bash
aws s3 mb s3://aicodewith-emu-demo
echo "hello from the emulator" > hello.txt
aws s3 cp hello.txt s3://aicodewith-emu-demo/
aws s3 ls s3://aicodewith-emu-demo/

aws dynamodb create-table --table-name notes \
  --attribute-definitions AttributeName=id,AttributeType=S \
  --key-schema AttributeName=id,KeyType=HASH --billing-mode PAY_PER_REQUEST
aws dynamodb wait table-exists --table-name notes
aws dynamodb put-item --table-name notes --item '{"id":{"S":"n1"},"msg":{"S":"hello"}}'
aws dynamodb get-item --table-name notes --key '{"id":{"S":"n1"}}'
OperationResultTime per command
s3 mb / s3 cp / s3 lsmake_bucket: aicodewith-emu-demo, 24 bytes uploaded, hello.txt listedabout 0.55–0.6 s
dynamodb create-tableStatus CREATINGabout 0.5 s
put-item right after creating the tableResourceNotFoundException: Requested resource not foundabout 0.5 s
put-item / get-item after wait table-existsWrite succeeded; read back {"id":"n1","msg":"hello"}about 0.5 s
sqs create-queue / send-message / receive-messageReceived the message body "hi"about 0.5 s
lambda create-function (Python 3.13) + invokeStatusCode: 200; the function returned {"ok": true, "echo": {"a": 1}}about 0.6 s

Most of the roughly 0.5 seconds per command is the AWS CLI's own startup; the emulator itself answers quickly.

Two behaviors are worth knowing, and both match real AWS:

  • A new DynamoDB table cannot be written to right away. After creation its status is CREATING, and an immediate put-item fails with ResourceNotFoundException. Run aws dynamodb wait table-exists, or use a waiter in code, before you write. This is where agent-written tests trip most often.
  • Lambda checks the role's trust policy. Our first attempt used a role with an empty Statement and failed with The role defined for the function cannot be assumed by Lambda. After we added sts:AssumeRole for lambda.amazonaws.com to the trust policy, the function was created.

Let Claude Code, Codex and Cursor work against the emulator

Option 1: install the official aws-emulator skill

According to the AI coding agent guide, AWS CLI 2.35.0 or later can install the official skill with one command. After that you can simply tell your agent "Install AWS Emulator and point my project at it":

bash
aws agent-toolkit add-skill --skill-name aws-emulator --region us-east-1

The command installs the skill for every agent it detects on your machine and needs no AWS account. With AWS CLI 2.40.1 each run took about 0.6 seconds, and it wrote to the directory of each agent it found:

  • Claude Code: ~/.claude/skills/aws-emulator/
  • Codex: ~/.agents/skills/aws-emulator/
  • Cursor: ~/.cursor/skills/aws-emulator/

Note: do not run this command in a shell where AWS_ENDPOINT_URL is set. Our first attempt ran in a terminal already pointed at the emulator and failed with UnknownService ... GetLatestSkillVersion, because the skill download request also went to the emulator. A clean terminal fixed it.

The skill contains only documents, no scripts: install steps for Linux, Docker and Rust embedded mode, how to connect each SDK, an error table, and a "will my project work on the emulator" compatibility check. For how skills work in general, see How to use Agent Skills.

Option 2: set the environment variables and hand the agent a task

The agents in Claude Code, Codex and Cursor all run commands in a terminal, so the simplest approach is to set the variables from the previous section in the terminal where you start the agent. The aws commands and boto3 tests the agent runs then go to the emulator automatically, and even if the agent gets something wrong, it cannot touch a real account. Cursor's terminal reads the same variables; in this test we only installed the skill for Cursor and did not run a task in it.

We gave Claude Code and Codex the same task. The project was an empty Python repository with boto3 1.44.1 and pytest 9.2.0 preinstalled in .venv:

text
The shell already points the AWS CLI and SDKs at a local AWS Emulator (AWS_ENDPOINT_URL=https://127.0.0.1:9297); never use a real AWS account.
1. Write notes.py with save_note(bucket, table, note_id, text): put the text in S3 at notes/<note_id>.txt and put an item {id, s3_key} in the DynamoDB table; and get_note(bucket, table, note_id) that returns the text by reading the item and then the S3 object.
2. Write tests/test_notes.py with pytest: create a uniquely named bucket and table (string key "id", PAY_PER_REQUEST, wait until the table exists) against the emulator, then test save/get round trip and that get_note of a missing id raises KeyError.
3. Run .venv/bin/pytest -q until it passes, then verify with the aws CLI that the object and item exist. Finish with a 3-line summary.
ClientModelWall-clock timeResult
Claude Code 2.1.319 (claude -p)claude-opus-5-5about 32.3 s, 5 turnsWrote notes.py and tests/test_notes.py, 2 passed; confirmed the object notes/n1.txt and its item with the aws CLI
Codex CLI 0.167.0 (codex exec)gpt-6.1-solabout 80.9 sWrote notes.py and tests/test_notes.py and added a pytest.ini; 2 passed in 3.36s, then confirmed the object and item with a script

Both agents used get_waiter("table_exists") on their own and avoided the "write right after create" trap. Afterwards we reran .venv/bin/pytest -q ourselves in the Claude Code directory and got 2 passed in 3.24s again, and aws s3 ls showed the notes-test-* buckets that both runs created. Read the agent's own summary, but trust your own rerun.

We ran both non-interactively: Claude Code with --permission-mode bypassPermissions and Codex with --dangerously-bypass-approvals-and-sandbox. That is only appropriate for a throwaway test directory. In a real repository, use hooks to block dangerous commands; see Claude Code / Codex / Cursor Agent Hooks setup. To drive Claude Code and Codex from one interface, see T3 Code with Claude Code and Codex.

Connect Claude Code and Codex to an AICodeWith API Key

In the tests above, both clients used an AICodeWith API Key. If you would rather not sign in with an official subscription, write the global config for each CLI.

For Claude Code, write ~/.claude/settings.json (full guide: Claude Code third-party API setup):

json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.aicodewith.ai",
    "ANTHROPIC_AUTH_TOKEN": "your AICodeWith API Key"
  }
}

For Codex, write ~/.codex/config.toml (download and install: Codex download; field reference: Codex config.toml guide):

toml
model_provider = "aicodewith"
model = "gpt-6.1-sol"

[model_providers.aicodewith]
name = "aicodewith"
base_url = "https://api.aicodewith.ai/chatgpt/v1"
wire_api = "responses"
experimental_bearer_token = "your AICodeWith API Key"

Check each one on its own first: claude -p "Reply with exactly: pong" and codex exec --skip-git-repo-check "Reply with exactly: pong". Both returned pong in our run, in about 4.3 seconds for Claude Code and 4.8 seconds for Codex.

Keep the two sets of credentials apart. The AICodeWith Key is only for the agent to call the model. On the AWS side, the emulator uses temporary keys starting with EMULATOR... that it generates at each start; they have nothing to do with your model Key.

Create API Key →

Put it in CI

According to the docs, the emulator keeps state only in memory, and /__admin/health exists so scripts and containers can wait until it is ready. Here is a GitHub Actions example; the install and start commands are the ones we ran on Debian above:

yaml
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install and start AWS Emulator
        run: |
          curl -fsSLo aws-emulator.deb https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_amd64.deb
          sudo apt-get install -y ./aws-emulator.deb
          aws-emulator -t off &
          until curl -sf --cacert ~/.aws/emulator/9297/ca.pem https://127.0.0.1:9297/__admin/health; do sleep 0.2; done
      - name: Run tests against the emulator
        run: |
          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 AWS_DISABLE_HOST_PREFIX_INJECTION=true
          export AWS_REGION=us-east-1 AWS_DEFAULT_REGION=us-east-1
          pytest -q

Keep real AWS credentials out of the environment of CI jobs, as AWS also recommends.

Limits: what it cannot do

According to the AWS News Blog and the fidelity docs:

  • No IAM policy evaluation. A request that AWS would deny can succeed in the emulator, so do not use it to test security.
  • One account, one Region. There is no cross-account or cross-Region behavior.
  • Operations that are not implemented yet return HTTP 501 (`NotImplemented`). Your test fails right away instead of passing silently.
  • Fidelity varies by service. Control-plane APIs (create, describe, delete resources) match AWS most closely; data-plane APIs and IaC tools such as CloudFormation, Terraform and the CDK vary more by service. Per-service fidelity scores for each release are published on GitHub Releases, and the tests are public in the aws-emulator-evaluation-suite repository.
  • A restart wipes everything. When we stopped and restarted it, the earlier buckets and tables were gone, and the Access Key in emulator_credentials changed from EMULATORC3... to EMULATOR1D.... Reread the credentials file after every restart.

Common errors and fixes

Error / symptomCauseFix
AccessDenied: Sign the request with the emulator credentialsSigned with other keys, for example real AWS keys left in environment variables (we hit this with a fake key)unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE and point AWS_SHARED_CREDENTIALS_FILE at this run's emulator_credentials
ResourceNotFoundException right after creating a DynamoDB tableThe table is still CREATING (we hit this)aws dynamodb wait table-exists, or a waiter in code
UnknownService: could not resolve a target serviceA request not meant for the emulator went to it, for example installing the skill in a terminal with AWS_ENDPOINT_URL set (we hit this)Run it in a terminal without AWS_ENDPOINT_URL
SSL: CERTIFICATE_VERIFY_FAILEDThe client does not trust this run's ca.pemSet AWS_CONFIG_FILE; for Node set NODE_EXTRA_CA_CERTS, for Java use truststore.p12; never turn off certificate checks
sts get-caller-identity shows a real accountThat command ran without AWS_ENDPOINT_URL, so it went to AWSRun it in the terminal or script where the variables are set
Address already in useThe port is takenUse another port, for example aws-emulator -p 9300, and change the port in the variables too
NotImplemented / HTTP 501The installed version does not implement that operation yetUpgrade to the latest release, then check that service's fidelity score on Releases

FAQ

Are AWS Emulator's APIs the same as real AWS?

According to AWS, it is built from the same Smithy API models the AWS SDKs use, so requests and errors have the same shape as on AWS. Whether the behavior matches depends on each service's fidelity score. The DynamoDB CREATING state and the Lambda trust-policy check we ran into both matched AWS.

Can I install it directly on macOS?

No, you use Docker. AWS publishes only Linux packages; on macOS and Windows you build an image from the official Dockerfile.

Can I use it for production or security testing?

No. AWS says it is for building and testing only. It does not evaluate IAM policies and is not for production workloads.

Could the agent accidentally change my real AWS resources?

As long as the terminal where you start the agent has AWS_ENDPOINT_URL set and real credentials unset, requests only go to your machine. The emulator also accepts only requests signed with the EMULATOR... keys it generated. Before you start, run aws sts get-caller-identity once and check that the account is 000000000000.

Which is better here: Claude Code, Codex or Cursor?

All three work: each can install the official skill, and each inherits the environment variables in its terminal. In this test, Claude Code and Codex both completed the same task on the first run. Pick the one you already use.

Create API Key →

Sources

相关文章

What is the UI SDK, and how do you use it? Vercel and shadcn's behavior library for agents, installed and tested in Claude Code / Codex / Cursor (0.1.0-beta.1)

What is the UI SDK, and how do you use it? Vercel and shadcn's behavior library for agents, installed and tested in Claude Code / Codex / Cursor (0.1.0-beta.1)

The UI SDK is Vercel's behavior library for agents, released on 12 November 2026 as 0.1.0-beta.1. Behaviors live in the framework-free @ui-sdk/core package and are rendered by adapters for React, Vue, Svelte, Solid, and Web Components. This guide follows the official docs on what it is, how to install it, and how to add the skill for Claude Code, Codex, and Cursor, and it records the commands, timings, and output from our test machine.

What Is T3 Code and How Do You Install It? Connect Claude Code and Codex, Use a Third-Party API Key, Fix Common Errors (Tested on 0.1.9)

What Is T3 Code and How Do You Install It? Connect Claude Code and Codex, Use a Third-Party API Key, Fix Common Errors (Tested on 0.1.9)

T3 Code is pingdotgg's open-source control surface for coding agents. It ships no model of its own; it drives the Claude Code, Codex, Cursor and other CLIs already on your machine. We tested T3 Code 0.1.9 on Linux. This guide covers the install commands, how to point Claude Code and Codex at an AICodeWith API Key so T3 Code can drive them, a full run of both agents with the t3 thread command, and the errors we hit along the way with their fixes.