A fast, free, open-source local cloud service emulator.

Overcast emulates the APIs of popular cloud services so you can develop and test locally without an internet connection, a cloud account, or a bill.

Every change is tested against eight official AWS clients — the AWS CLI, the CDK, and the Go, JavaScript, Python, Java, .NET, and Rust SDKs — via the compatibility suite.

---

Project goals

1. Works with the official AWS CLI — aws s3 mb s3://my-bucket --endpoint-url http://localhost:4566 just works.
2. Works with all official AWS SDK clients — Go, JavaScript/TypeScript, Python, Java, .NET without code changes.
3. Drop-in replacement for LocalStack — same port (4566), LocalStack's own env vars honoured, same path conventions, no auth token. Switching is one image line, and nothing Overcast emulates sits behind a plan; the compatibility matrix is the item-by-item audit.
4. Zero configuration — docker run -p 4566:4566 ghcr.io/overcast-sh/overcast:latest is the full getting-started guide.
5. Fast — sub-50ms startup (~22ms p50, hybrid backend), <15 MiB idle memory, tiny Docker image. CI pipelines should not wait for the emulator.
6. Honest about gaps — unimplemented endpoints return 501 Not Implemented with a clear message and a link to the support matrix. Silent failures are worse than loud ones.
7. Fully open — MIT licensed, no auth tokens, no telemetry, no usage limits, no feature gates. Free forever for every use case including CI/CD.
8. Production-quality internals — race-safe, well-tested, well-documented, easy to contribute to.

---

Caution

Overcast is a local development and CI tool only. Never expose it on a public network, use it as a staging environment, or make production go/no-go decisions based on its behaviour. Details: What Overcast is NOT.

Contents

• Project goals
• Contents
• Quick start
• What Overcast is NOT
• Running with Docker
  • docker run
  • docker compose (recommended for local dev)
• Native binaries
  • Binary variants
  • Installation
  • Commands
  • overcast serve
  • Browser-trusted HTTPS
  • Reaching it by name
• Supported services
• Documentation
• Contributing

---

Quick start

Two images are published to GHCR:

Image	Description	Size
ghcr.io/overcast-sh/overcast	Full image with web management console (ports 4566 + 4567)	~50 MB
ghcr.io/overcast-sh/overcast-slim	Headless — Go binary only, no UI, no SQLite (port 4566)	~20 MB

The slim image leaves out SQLite as well as the UI, so it is memory-only unless you set OVERCAST_STATE=wal — see Storage and persistence.

Overcast is pre-1.0, so every build publishes to the :alpha channel tag and to an exact version tag such as :0.0.1-alpha.25. :latest also moves with every build for now — tracking the newest alpha — and switches to tracking stable releases once the first one ships. Pin the exact version in CI; use :latest or :alpha to track the newest build.

# Full image (with web console on :4567)
docker run --rm -p 4566:4566 -p 4567:4567 ghcr.io/overcast-sh/overcast:latest

# Slim image (CI pipelines, no UI)
docker run --rm -p 4566:4566 ghcr.io/overcast-sh/overcast-slim:latest

Point any AWS SDK or the AWS CLI at it:

export AWS_ENDPOINT_URL=http://localhost:4566
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
export AWS_DEFAULT_REGION=us-east-1

# AWS CLI
aws s3 mb s3://my-bucket
aws sqs create-queue --queue-name my-queue
aws dynamodb list-tables

# No other changes needed — use the SDK exactly as you would against real AWS.

---

What Overcast is NOT

Not for	Why
Staging environments	API parity is not 100%. Differences are documented but exist.
Production traffic	Overcast is not hardened, not monitored, not replicated.
Self-hosted AWS replacement	Not a platform you host for others: no security boundary, no durability guarantees.
Security testing	Credentials are accepted. SigV4 validation is optional, and IAM policies are not enforced as an authorization layer.
Performance / load testing	AWS throttling, quotas, and latency are not emulated.
IAM policy testing	Enforcement is off by default and covers identity policies only (details). A development aid, not a security boundary.
CloudFormation / CDK deploys	CloudFormation emulation supports 130+ resource types. cdk deploy works for stacks using supported types. Coverage is not exhaustive.

Running with Docker

docker run

# Full image with web console
docker run --rm \
  -p 4566:4566 \
  -p 4567:4567 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e OVERCAST_LOG_LEVEL=debug \
  ghcr.io/overcast-sh/overcast:latest

# With persistent data: mounting a volume at /data is the whole of it
docker run --rm \
  -p 4566:4566 \
  -p 4567:4567 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.overcast:/data \
  ghcr.io/overcast-sh/overcast:latest

# Slim image (no web console) — no Docker socket needed for the services that
# start no containers (S3, SQS, DynamoDB, SNS, ...)
docker run --rm \
  -p 4566:4566 \
  ghcr.io/overcast-sh/overcast-slim:latest

Which backend a run gets, what survives a restart, and why a volume does nothing on the slim image are in Storage and persistence.

docker compose (recommended for local dev)

# docker-compose.yml
services:
  overcast:
    image: ghcr.io/overcast-sh/overcast:latest
    ports:
      - "4566:4566"
      - "4567:4567"
    environment:
      OVERCAST_LOG_LEVEL: debug
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock # required for Lambda, ECS, RDS, EC2
      - overcast-data:/data # persistence; see docs/storage.md
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:4566/_overcast/health"]
      interval: 5s
      timeout: 3s
      retries: 5

volumes:
  overcast-data:

docker compose up

Testcontainers

Integration tests start Overcast per-test through the Testcontainers module for Go: three lines to a running emulator and an endpoint to point an SDK client at. Testcontainers has the module, the pinned-image advice and the other-language plans.

Note

Docker socket and container-based services

Lambda, ECS, RDS, and EC2 launch sibling containers on the host's Docker daemon. This requires bind-mounting the Docker socket (/var/run/docker.sock). If the socket is not mounted, these services degrade gracefully — metadata operations (create, describe, list, delete) still work, but Lambda invocations return mock responses and ECS/RDS containers won't start.

Services that don't need the Docker socket (S3, SQS, DynamoDB, SNS, CloudWatch Logs, SES, Secrets Manager, KMS, SSM, STS, IAM, etc.) work without it.

CI environments where socket mounting is restricted can use a Docker-in-Docker (DinD) sidecar instead. Set LAMBDA_DOCKER_SOCKET (and optionally ECS_DOCKER_SOCKET / RDS_DOCKER_SOCKET) to a tcp:// endpoint:

services:
  dind:
    image: docker:dind
    privileged: true
    environment:
      DOCKER_TLS_CERTDIR: "" # disable TLS for simplicity
  overcast:
    image: ghcr.io/overcast-sh/overcast:latest
    ports:
      - "4566:4566"
    environment:
      LAMBDA_DOCKER_SOCKET: tcp://dind:2375
    depends_on:
      - dind

---

Native binaries

Download pre-built binaries from the GitHub releases page. No runtime dependencies — a single static binary is all you need.

Binary variants

Two binaries are published for every release:

Binary	Platforms	Description
overcast	Linux amd64/arm64, macOS amd64/arm64, Windows amd64	Full binary — emulator + embedded web console + Go BFF. All subcommands available.
overcastd	Linux amd64/arm64, macOS amd64/arm64, Windows amd64	Slim binary — emulator only, no web console. Smaller footprint for CI and servers.

Both binaries share the same overcast serve entrypoint and respond identically to AWS SDK clients. The only difference is that overcastd returns 404 for web console requests.

Installation

macOS / Linux:

curl -fsSL https://overcast.sh/install.sh | sh

Windows (PowerShell):

irm https://overcast.sh/install.ps1 | iex

The installer detects your OS and CPU, verifies the download against the release's SHA256SUMS, installs to a per-user directory (~/.local/bin, %LOCALAPPDATA%\Programs\overcast\bin) and never uses sudo. Add --slim (or set OVERCAST_INSTALL_FLAVOR=slim) for overcastd, --version <tag> to pin a release. Every flag, the environment variables for irm | iex, and installing by hand are in docs/install.md; the scripts themselves are in install/.

Build from source:

git clone https://github.com/overcast-sh/overcast.git && cd overcast
# Full binary (builds web console first)
cd web && pnpm install --frozen-lockfile && pnpm run build && cd ..
go build -trimpath -o overcast ./cmd/overcast

# Slim binary (no Node.js needed) — this is exactly how the released overcastd
# binaries are built. Drop `,nosqlite` to keep SQLite (and with it the hybrid
# and persistent backends) in your own build.
go build -trimpath -tags slim,nosqlite -o overcastd ./cmd/overcast

Commands

All subcommands are available in both overcast and overcastd (the web console is absent in the slim binary). Run overcast --help or overcast <command> --help for the full flag reference, or see the CLI reference for every command's flags, defaults, and examples in one place.

Command	Description
overcast serve	Start the AWS service emulator
overcast start / stop / restart	Run serve as a named background instance (native or --docker)
overcast status	Check a running daemon is reachable (version, state backend)
overcast wait	Block until a daemon reports healthy (CI-friendly)
overcast logs	Tail a background instance's output
overcast services	List enabled services and their emulation tiers
overcast reset	Wipe emulated state, all or one service
overcast network	Report Docker networks that have drifted from your configuration, and rebuild them
overcast config	Show the daemon's effective configuration (needs OVERCAST_DEBUG=true)
overcast env	Print AWS environment exports for pointing tools at Overcast
overcast aws	Run the host AWS CLI against Overcast, environment scrubbed first
overcast import cognito-users	Import Cognito users from real AWS into Overcast
overcast bridge	Publish .local domains via mDNS and start a port-80 reverse proxy
overcast https	One-shot browser-trusted HTTPS setup (CA + trust store + certificate)
overcast trust	Manage the local trust store for self-signed TLS certificates

overcast serve

Starts the emulator on port 4566. All emulator configuration is environment variables — the environment variable reference has every one:

overcast serve

OVERCAST_PORT=4566 OVERCAST_STATE=hybrid OVERCAST_LOG_LEVEL=debug   overcast serve

The web console (full binary only) is served on port 4567 and loads lazily on first request. --ui-port 0 disables it. Storage is the other place the two binaries differ — the released overcastd is built without SQLite; see Builds without SQLite.

Browser-trusted HTTPS

Serving the API and console over TLS unlocks browser HTTP/2, which keeps the console responsive under load:

overcast https enable            # once per machine; approve the OS prompt
OVERCAST_TLS=auto overcast serve # → https://localhost.overcast.sh:4567

Docker, WSL, bringing your own certificate, and installing the CA by hand are all in docs/https.md. The lower-level overcast trust subcommands are there too.

Reaching it by name

overcast bridge publishes overcast.local and overcast-app.local over mDNS and proxies port 80 by Host header, so .local names work with no hosts-file edits and no port numbers. Flags and the per-platform mDNS/port-80 setup are in the CLI reference.

---

Supported services

Overcast currently registers 51 AWS services. Coverage ranges from broad service emulation to minimal discovery/IaC stubs; check the per-service docs for exact endpoint support.

ACM, API Gateway, AppConfig, AppConfigData, AppRegistry, AppSync, Athena, Auto Scaling, Backup, Bedrock, CloudFormation, CloudFront, CloudTrail, CloudWatch, CloudWatch Logs, Cognito, DynamoDB, DynamoDB Streams, EC2 / VPC, ECR, ECS, EFS, EKS, ElastiCache, ELBv2, EventBridge, Firehose, Glue, IAM, Kinesis, KMS, Lambda, MSK, OpenSearch, Organizations, Pipes, RDS, Route 53, S3, S3 Tables, Scheduler, Secrets Manager, SES, Shield, SNS, SQS, SSM, Step Functions, STS, Transfer Family, WAF v2.

Some services require Docker socket access for full runtime behaviour:

• Lambda, ECS, RDS, EC2/VPC, and ElastiCache can launch sibling containers.
• Without Docker, their metadata/control-plane APIs still work where possible, but runtime execution falls back to metadata-only or stub behaviour.

IAM is implemented for local development and CloudFormation/CDK compatibility, but IAM policies are not enforced as an authorization layer.

See the service emulation reference for per-endpoint coverage tables, or browse the generated summary in STATUS.md.

---

Documentation

The reference index routes every guide by the job you are doing — getting running, building against it, tuning and inspecting it. Four of them answer most first questions:

• Using AWS SDKs and CLI — pointing the CLI, or any SDK, at Overcast
• Service reference — what each service supports, operation by operation
• Configuration — where each setting lives, and every variable with its default
• Troubleshooting — a symptom, and where its answer lives

---

Contributing

See CONTRIBUTING.md for coding standards, workflow, and how to build from source.

Disclaimer

Overcast is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by Amazon Web Services. "AWS" and all AWS service names are trademarks of Amazon.com, Inc. or its affiliates, used here solely to describe compatibility.

Overcast is a work in progress, provided as-is and on a best-effort basis, without warranty of any kind, under the MIT License. It aims for high fidelity on the most-used AWS API surface, but it is not a perfect replica: there are compatibility gaps we know about (documented in the per-service support matrices) and inevitably some we haven't found yet. Fidelity improves all the time — and discrepancy reports are what drive that work. If you find behaviour that differs from real AWS, please open a compatibility issue.