# AWS Emulator (service host)

Create an instance:
curl -s -X POST https://aws.emulators.dev/_emulate/instances
# Hosted deployments create instances lazily when the returned URL is first used. The instance URL is a capability: anyone who has it can read and modify the instance, so save the returned URLs. Never store real secrets in an emulator.
# The server generates an unguessable name. An optional {"instance":"<prefix>"} body adds a readable prefix.

Then use the returned providerBaseUrl / controlBaseUrl. Example below uses a sample instance.
# AWS Emulator

Stateful AWS emulator for S3, SQS, IAM, and STS using AWS SDK-compatible request flows.

Provider base URL: https://aws.your-instance.emulators.dev
Control base URL: https://aws.your-instance.emulators.dev/_emulate

Supported surfaces:
- S3-compatible API: partial at /
- SQS Query API: partial at /
- IAM Query API: partial at /iam
- STS Query API: partial at /sts
- Inspector UI: supported at /_inspector

Control endpoints:
- https://aws.your-instance.emulators.dev/_emulate/manifest
- https://aws.your-instance.emulators.dev/_emulate/coverage
- https://aws.your-instance.emulators.dev/_emulate/connections
- https://aws.your-instance.emulators.dev/_emulate/state
- https://aws.your-instance.emulators.dev/_emulate/ledger
- https://aws.your-instance.emulators.dev/_emulate/faults
- POST https://aws.your-instance.emulators.dev/_emulate/credentials
- POST https://aws.your-instance.emulators.dev/_emulate/seed
- POST https://aws.your-instance.emulators.dev/_emulate/reset

Fault injection:
Arm a one-shot provider failure with a glob pathPattern, then inspect /ledger for faulted: true.
curl -s -X POST https://aws.your-instance.emulators.dev/_emulate/faults \
  -H "content-type: application/json" \
  -d '{"match":{"method":"GET","pathPattern":"/v1/*"},"response":{"status":503,"body":{"error":"temporary"}}}'

Connect:

## AWS SDK v3 S3Client (TypeScript)
import { S3Client } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  endpoint: "https://aws.your-instance.emulators.dev",
  region: "us-east-1",
  forcePathStyle: true,
  credentials: {
    accessKeyId: "<client_id>",
    secretAccessKey: "<client_secret>",
  },
});

## AWS SDK v3 SQSClient (TypeScript)
import { SQSClient } from "@aws-sdk/client-sqs";

const sqs = new SQSClient({
  endpoint: "https://aws.your-instance.emulators.dev",
  region: "us-east-1",
  credentials: {
    accessKeyId: "<client_id>",
    secretAccessKey: "<client_secret>",
  },
});

## AWS endpoint and credentials (env)
AWS_ENDPOINT_URL=https://aws.your-instance.emulators.dev
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=<client_id>
AWS_SECRET_ACCESS_KEY=<client_secret>

## curl
curl -s https://aws.your-instance.emulators.dev/

## Base URL (env)
AWS_BASE_URL=https://aws.your-instance.emulators.dev

## Create a credential
curl -s -X POST https://aws.your-instance.emulators.dev/_emulate/credentials \
  -H "content-type: application/json" \
  -d '{"type":"provider-specific"}'

## Inspect requests
curl -s https://aws.your-instance.emulators.dev/_emulate/ledger