Reference
Reference index
Runtime emulation tiers, the full service index with per-service coverage, supported event pipelines, and what the web management console shows.
Every guide and reference below, grouped by the job you are doing. To get a container answering the AWS APIs first:
docker run --rm -p 4566:4566 ghcr.io/overcast-sh/overcast:latest
export AWS_ENDPOINT_URL=http://localhost:4566
aws s3 mb s3://demoCredentials, regions and per-language client setup are in Using AWS SDKs and CLI.
Get running
| Guide | For |
|---|---|
| Install Overcast | The one-line installers for macOS, Linux and Windows, the Docker images, and installing by hand |
| Using AWS SDKs and CLI | Pointing the AWS CLI, Node.js, Python, Go, Java, .NET, Rust or Terraform at Overcast |
| CLI reference | Every overcast subcommand — background instances, introspection, AWS helpers, mDNS and TLS |
| Using AWS CDK | cdk bootstrap, cdk deploy, which resource types provision for real, and the local-VPC pattern |
| Testcontainers | Starting Overcast from integration tests |
| Migrating from LocalStack | Swapping the image and keeping your environment block |
| LocalStack compatibility matrix | Every port, URL, hostname, container convention and client tool, with its status |
Build against it
| Guide | For |
|---|---|
| Service reference | What each AWS service supports, operation by operation |
| Networking and host-based addressing | Host-routed endpoints, wildcard DNS, sibling containers, VPC isolation |
| The inner loop | Editing a file and seeing it take effect — cdk watch, Lambda and ECS hot reload |
| Step debugging inside emulated compute | Attaching VS Code, a JetBrains IDE or Chrome DevTools to code running inside a Lambda function or ECS task |
| Debugging in the console | Breakpoints, stepping, locals and watches in the function page’s Code tab, for Node.js functions |
| HTTPS and HTTP/2 | Browser-trusted TLS in two commands, in Docker, and by hand |
Tune and inspect
| Guide | For |
|---|---|
| Configuration | Where each setting lives, the handful most people change, and every variable with its default |
| Storage and persistence | Choosing a backend and knowing what survives a restart |
| Performance | Startup and memory expectations, storage tuning, and where “feels slow” time goes |
| Debug endpoints | Health, metrics, state dump, request traces, pprof |
| Troubleshooting | 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 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.
| Service | Doc | Ops | Coverage tier |
|---|---|---|---|
| S3 | S3 — Simple Storage Service | 53 | Comprehensive / broad support |
| SQS | SQS — Simple Queue Service | 21 | Comprehensive / broad support |
| DynamoDB | DynamoDB — Amazon DynamoDB | 28 | Comprehensive / broad support |
| Lambda | Lambda — AWS Lambda | 62 | Comprehensive / broad support |
| API Gateway | API Gateway — Amazon API Gateway | 104 | Comprehensive / broad support |
| AppSync | AppSync — AWS AppSync | 81 | Comprehensive / broad support |
| CloudFront | CloudFront — Amazon CloudFront | 88 | Comprehensive / broad support |
| Cognito | Cognito — Amazon Cognito User Pools | 70 | Comprehensive / broad support |
| EC2 / VPC | EC2 — Elastic Compute Cloud | 79 | Comprehensive / broad support |
| SNS | SNS — Simple Notification Service | 30 | Comprehensive / broad support |
| Step Functions | Step Functions — AWS Step Functions | 37 | Comprehensive / broad support |
| IAM | IAM — Identity and Access Management | 74 | Core CRUD + common workflows |
| ECS | ECS — Elastic Container Service | 48 | Core CRUD + common workflows |
| ECR | ECR — Elastic Container Registry | 25 | Core CRUD + common workflows |
| KMS | KMS — Key Management Service | 34 | Core CRUD + common workflows |
| Kinesis | Kinesis — Amazon Kinesis Data Streams | 23 | Core CRUD + common workflows |
| EventBridge | EventBridge — Amazon EventBridge | 31 | Core CRUD + common workflows |
| Scheduler | Scheduler — Amazon EventBridge Scheduler | 12 | Core CRUD + common workflows |
| CloudFormation | CloudFormation — AWS CloudFormation | 53 | Core CRUD + common workflows |
| RDS | RDS — Relational Database Service | 34 | Core CRUD + common workflows |
| ElastiCache | ElastiCache — Managed In-Memory Cache | 24 | Core CRUD + common workflows |
| EFS | EFS — Amazon Elastic File System | 31 | Core CRUD + common workflows |
| S3 Tables | S3 Tables — Amazon S3 Tables | 49 | Core CRUD + common workflows |
| AppConfig | AppConfig — AWS AppConfig | 20 | Core CRUD + common workflows |
| AppConfigData | AppConfigData — AWS AppConfig Data Plane | 2 | Core CRUD + common workflows |
| Secrets Manager | Secrets Manager — AWS Secrets Manager | 22 | Core CRUD + common workflows |
| SSM | SSM Parameter Store — AWS Systems Manager | 18 | Core CRUD + common workflows |
| CloudWatch Logs | CloudWatch Logs — Amazon CloudWatch Logs | 26 | Core CRUD + common workflows |
| SES | SES — Simple Email Service | 45 | Core CRUD + common workflows |
| STS | STS — Security Token Service | 11 | Core CRUD + common workflows |
| Route 53 | Route 53 — Amazon Route 53 | 25 | Core CRUD + common workflows |
| Auto Scaling | Auto Scaling — AWS Auto Scaling | 25 | Core CRUD + common workflows |
| Pipes | Pipes — Amazon EventBridge Pipes | 8 | Minimal / targeted support |
| WAF v2 | WAF — AWS WAF v2 | 7 | Minimal / targeted support |
| Shield | Shield — AWS Shield | 8 | Minimal / targeted support |
| ACM | ACM — AWS Certificate Manager | 11 | Minimal / targeted support |
| Athena | Athena — Amazon Athena | 12 | Minimal / targeted support |
| Bedrock | Bedrock — Amazon Bedrock Runtime | 2 | Minimal / targeted support |
| CloudWatch | CloudWatch — Amazon CloudWatch | 17 | Minimal / targeted support |
| DynamoDB Streams | DynamoDB Streams — Amazon DynamoDB Streams | 4 | Minimal / targeted support |
| Firehose | Firehose — Amazon Data Firehose | 9 | Minimal / targeted support |
| Glue | Glue — AWS Glue Data Catalog | 26 | Minimal / targeted support |
| OpenSearch | OpenSearch — Amazon OpenSearch Service | 8 | Minimal / targeted support |
| AppRegistry | AppRegistry — Service Catalog AppRegistry | 22 | IaC/discovery-oriented stub |
| Backup | Backup — AWS Backup | 18 | IaC/discovery-oriented stub |
| CloudTrail | CloudTrail — AWS CloudTrail | 12 | IaC/discovery-oriented stub |
| EKS | EKS — Amazon Elastic Kubernetes Service | 49 | IaC/discovery-oriented stub |
| ELBv2 | ELBv2 — Elastic Load Balancing v2 (ALB/NLB) | 22 | IaC/discovery-oriented stub |
| MSK | MSK — Managed Streaming for Kafka | 30 | IaC/discovery-oriented stub |
| Organizations | Organizations — AWS Organizations | 15 | IaC/discovery-oriented stub |
| Transfer Family | Transfer Family — AWS Transfer Family | 13 | IaC/discovery-oriented stub |
Want to add support for a new AWS service? See 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.
| 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.
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.