# Reference index

Every guide and reference below, grouped by the job you are doing. To get a
container answering the AWS APIs first:

```bash
docker run --rm -p 4566:4566 ghcr.io/overcast-sh/overcast:latest
export AWS_ENDPOINT_URL=http://localhost:4566
aws s3 mb s3://demo
```

Credentials, regions and per-language client setup are in
[Using AWS SDKs and CLI](/docs/sdk-cli/index.md).

## Get running

| Guide | For |
| --- | --- |
| [Install Overcast](/docs/install/index.md) | The one-line installers for macOS, Linux and Windows, the Docker images, and installing by hand |
| [Using AWS SDKs and CLI](/docs/sdk-cli/index.md) | Pointing the AWS CLI, Node.js, Python, Go, Java, .NET, Rust or Terraform at Overcast |
| [CLI reference](/docs/cli/index.md) | Every `overcast` subcommand — background instances, introspection, AWS helpers, mDNS and TLS |
| [Using AWS CDK](/docs/cdk/index.md) | `cdk bootstrap`, `cdk deploy`, which resource types provision for real, and the local-VPC pattern |
| [Testcontainers](/docs/testcontainers/index.md) | Starting Overcast from integration tests |
| [Migrating from LocalStack](/docs/migration-from-localstack/index.md) | Swapping the image and keeping your environment block |
| [LocalStack compatibility matrix](/docs/localstack-compatibility/index.md) | Every port, URL, hostname, container convention and client tool, with its status |

## Build against it

| Guide | For |
| --- | --- |
| [Service reference](/docs/services/index.md) | What each AWS service supports, operation by operation |
| [Networking and host-based addressing](/docs/networking/index.md) | Host-routed endpoints, wildcard DNS, sibling containers, VPC isolation |
| [The inner loop](/docs/local-dev/index.md) | Editing a file and seeing it take effect — `cdk watch`, Lambda and ECS hot reload |
| [Step debugging inside emulated compute](https://github.com/overcast-sh/overcast/blob/main/docs/debugger.md) | Attaching VS Code, a JetBrains IDE or Chrome DevTools to code running inside a Lambda function or ECS task |
| [Debugging in the console](https://github.com/overcast-sh/overcast/blob/main/docs/debugger-console.md) | Breakpoints, stepping, locals and watches in the function page's Code tab, for Node.js functions |
| [HTTPS and HTTP/2](/docs/https/index.md) | Browser-trusted TLS in two commands, in Docker, and by hand |

## Tune and inspect

| Guide | For |
| --- | --- |
| [Configuration](/docs/configuration/index.md) | Where each setting lives, the handful most people change, and every variable with its default |
| [Storage and persistence](/docs/storage/index.md) | Choosing a backend and knowing what survives a restart |
| [Performance](/docs/performance/index.md) | Startup and memory expectations, storage tuning, and where "feels slow" time goes |
| [Debug endpoints](/docs/debug-endpoints/index.md) | Health, metrics, state dump, request traces, pprof |
| [Troubleshooting](/docs/troubleshooting/index.md) | A symptom, and where its answer lives |

---

## Runtime emulation tiers

`GET /_overcast/health`, `overcast services` and the web console report a tier
per running service. It answers "how much of this service is wired up", and is a
different axis from the coverage tier in the index below — see
[Service reference § Coverage tiers](/docs/services/index.md#coverage-tiers) for
that one and for the per-operation status tokens.

| Tier        | Meaning                                                                                                                                                                           |
| --- | --- |
| **Full** | P1+P2 operations implemented. Real SDK clients can use it end-to-end. |
| **Partial** | P1 operations implemented. Basic workflows work. |
| **Inert** | Full CRUD works — resources are created and stored — but no side-effects or enforcement occur. For example, IAM stores users, roles, and policies but never enforces permissions. |
| **Stub** | Registered so discovery works: at most a hardcoded, stateless answer to the service's describe call; every other operation returns `501 Not Implemented`. |

---

## Services

Shorter overview: the [service reference index](/docs/services/index.md).

<!-- BEGIN overcast:service-index -->

| Service          | Doc                                                 | Ops | Coverage tier                 |
| --- | --- | --- | --- |
| S3 | [s3.md](/docs/services/s3/index.md) | 53 | Comprehensive / broad support |
| SQS | [sqs.md](/docs/services/sqs/index.md) | 21 | Comprehensive / broad support |
| DynamoDB | [dynamodb.md](/docs/services/dynamodb/index.md) | 28 | Comprehensive / broad support |
| Lambda | [lambda.md](/docs/services/lambda/index.md) | 62 | Comprehensive / broad support |
| API Gateway | [apigateway.md](/docs/services/apigateway/index.md) | 104 | Comprehensive / broad support |
| AppSync | [appsync.md](/docs/services/appsync/index.md) | 81 | Comprehensive / broad support |
| CloudFront | [cloudfront.md](/docs/services/cloudfront/index.md) | 88 | Comprehensive / broad support |
| Cognito | [cognito.md](/docs/services/cognito/index.md) | 70 | Comprehensive / broad support |
| EC2 / VPC | [ec2.md](/docs/services/ec2/index.md) | 79 | Comprehensive / broad support |
| SNS | [sns.md](/docs/services/sns/index.md) | 30 | Comprehensive / broad support |
| Step Functions | [stepfunctions.md](/docs/services/stepfunctions/index.md) | 37 | Comprehensive / broad support |
| IAM | [iam.md](/docs/services/iam/index.md) | 74 | Core CRUD + common workflows |
| ECS | [ecs.md](/docs/services/ecs/index.md) | 48 | Core CRUD + common workflows |
| ECR | [ecr.md](/docs/services/ecr/index.md) | 25 | Core CRUD + common workflows |
| KMS | [kms.md](/docs/services/kms/index.md) | 34 | Core CRUD + common workflows |
| Kinesis | [kinesis.md](/docs/services/kinesis/index.md) | 23 | Core CRUD + common workflows |
| EventBridge | [eventbridge.md](/docs/services/eventbridge/index.md) | 31 | Core CRUD + common workflows |
| Scheduler | [scheduler.md](/docs/services/scheduler/index.md) | 12 | Core CRUD + common workflows |
| CloudFormation | [cloudformation.md](/docs/services/cloudformation/index.md) | 53 | Core CRUD + common workflows |
| RDS | [rds.md](/docs/services/rds/index.md) | 34 | Core CRUD + common workflows |
| ElastiCache | [elasticache.md](/docs/services/elasticache/index.md) | 24 | Core CRUD + common workflows |
| EFS | [efs.md](/docs/services/efs/index.md) | 31 | Core CRUD + common workflows |
| S3 Tables | [s3tables.md](/docs/services/s3tables/index.md) | 49 | Core CRUD + common workflows |
| AppConfig | [appconfig.md](/docs/services/appconfig/index.md) | 20 | Core CRUD + common workflows |
| AppConfigData | [appconfigdata.md](/docs/services/appconfigdata/index.md) | 2 | Core CRUD + common workflows |
| Secrets Manager | [secretsmanager.md](/docs/services/secretsmanager/index.md) | 22 | Core CRUD + common workflows |
| SSM | [ssm.md](/docs/services/ssm/index.md) | 18 | Core CRUD + common workflows |
| CloudWatch Logs | [cloudwatch-logs.md](/docs/services/cloudwatch-logs/index.md) | 26 | Core CRUD + common workflows |
| SES | [ses.md](/docs/services/ses/index.md) | 45 | Core CRUD + common workflows |
| STS | [sts.md](/docs/services/sts/index.md) | 11 | Core CRUD + common workflows |
| Route 53 | [route53.md](/docs/services/route53/index.md) | 25 | Core CRUD + common workflows |
| Auto Scaling | [autoscaling.md](/docs/services/autoscaling/index.md) | 25 | Core CRUD + common workflows |
| Pipes | [pipes.md](/docs/services/pipes/index.md) | 8 | Minimal / targeted support |
| WAF v2 | [waf.md](/docs/services/waf/index.md) | 7 | Minimal / targeted support |
| Shield | [shield.md](/docs/services/shield/index.md) | 8 | Minimal / targeted support |
| ACM | [acm.md](/docs/services/acm/index.md) | 11 | Minimal / targeted support |
| Athena | [athena.md](/docs/services/athena/index.md) | 12 | Minimal / targeted support |
| Bedrock | [bedrock.md](/docs/services/bedrock/index.md) | 2 | Minimal / targeted support |
| CloudWatch | [cloudwatch.md](/docs/services/cloudwatch/index.md) | 17 | Minimal / targeted support |
| DynamoDB Streams | [dynamodbstreams.md](/docs/services/dynamodbstreams/index.md) | 4 | Minimal / targeted support |
| Firehose | [firehose.md](/docs/services/firehose/index.md) | 9 | Minimal / targeted support |
| Glue | [glue.md](/docs/services/glue/index.md) | 26 | Minimal / targeted support |
| OpenSearch | [opensearch.md](/docs/services/opensearch/index.md) | 8 | Minimal / targeted support |
| AppRegistry | [appregistry.md](/docs/services/appregistry/index.md) | 22 | IaC/discovery-oriented stub |
| Backup | [backup.md](/docs/services/backup/index.md) | 18 | IaC/discovery-oriented stub |
| CloudTrail | [cloudtrail.md](/docs/services/cloudtrail/index.md) | 12 | IaC/discovery-oriented stub |
| EKS | [eks.md](/docs/services/eks/index.md) | 49 | IaC/discovery-oriented stub |
| ELBv2 | [elb.md](/docs/services/elb/index.md) | 22 | IaC/discovery-oriented stub |
| MSK | [msk.md](/docs/services/msk/index.md) | 30 | IaC/discovery-oriented stub |
| Organizations | [organizations.md](/docs/services/organizations/index.md) | 15 | IaC/discovery-oriented stub |
| Transfer Family | [transfer.md](/docs/services/transfer/index.md) | 13 | IaC/discovery-oriented stub |

<!-- END overcast:service-index -->

Want to add support for a new AWS service? See
[CONTRIBUTING.md § How to add a service](https://github.com/overcast-sh/overcast/blob/main/CONTRIBUTING.md#how-to-add-a-service)
in the repository.

---

## Event pipelines

| Pipeline                          | Status       |
| --- | --- |
| SNS → SQS subscription | ✅ Supported |
| SQS → Lambda event source mapping | ✅ Supported |
| DynamoDB Streams → SQS (Pipes) | ✅ Supported |
| DynamoDB Streams → Lambda (ESM) | ✅ Supported |

---

## Web management console

The full image (`ghcr.io/overcast-sh/overcast`) serves a web management console
on **http://localhost:4567** — in-process, from the same binary, so there is no
second server to start and the AWS API on 4566 never depends on it. Set
`OVERCAST_UI_PORT` (or `--ui-port`) to move it; `0` disables it. A tour with
screenshots is at [overcast.sh/console](https://overcast.sh/console/).

| Feature | What it does |
| --- | --- |
| Dashboard | Service cards with live status and emulation tier |
| Per-service UI | S3 browser, SQS message inspector, DynamoDB item editor, Lambda test/invoke, and more |
| Live activity feed | Every API call as it happens — operation, resource, status code, latency |
| Request traces | Full bodies, headers, log lines and internal hops for any call, searchable. Needs `OVERCAST_DEBUG=true` |
| Inbox | Everything Overcast would have sent: SES mail, SNS email subscriptions and Cognito verification mail via the built-in SMTP server on `:1025`, plus SNS SMS and HTTP webhook deliveries — searchable, headers and bodies included, with no third-party mail catcher |
| Topology map | Cross-service resource relationships |
| Real-time updates | Server-sent events push changes as they happen |

If the console stops responding to clicks while many Lambdas run or transfers are
in flight, you are hitting the browser's 6-connection HTTP/1.1 limit — the live
feed and progress streams hold the sockets. Serving the console over HTTPS
unlocks HTTP/2 and fixes it: see [HTTPS and HTTP/2](/docs/https/index.md).

> [!TIP]
> Request traces are the console's strongest debugging tool and the one thing it
> cannot show by default. Start the daemon with `OVERCAST_DEBUG=true` and every
> call gets a full trace — see [Debug endpoints](/docs/debug-endpoints/index.md).