Overcast is alpha — behaviour and APIs may change between releases. Pin your version and read the changelog before upgrading.

overcast

Migrating from LocalStack

Swap the image line and keep the rest: the compose diff, the endpoint and hostname settings, and where the variable, endpoint and behavioural detail lives.

Overcast is a drop-in replacement for LocalStack: same port, same init-hook layout, LocalStack’s own environment variables honoured directly rather than renamed, and no auth token or plan. Usually the image is the only line that changes:

# Before
services:
  localstack:
    image: localstack/localstack
    ports: ["4566:4566"]
    environment:
      SERVICES: s3,sqs,dynamodb
      DEBUG: 1

# After — the environment block carries over as-is; both variables are honoured
services:
  overcast:
    image: ghcr.io/overcast-sh/overcast:latest
    ports: ["4566:4566"]
    environment:
      DEBUG: 1

The endpoint and the hostname

SettingWhat to do
AWS_ENDPOINT_URLLeave it. Overcast listens on 4566 too
A /_localstack/health healthcheckLeave it. Overcast serves it in LocalStack’s shape
/etc/localstack/init/<stage>.d/ scriptsLeave them. Both init trees are scanned
OVERCAST_HOSTNAMESet it to localhost.overcast.sh if you use virtual-hosted S3 URLs. An existing localhost.localstack.cloud keeps working
LOCALSTACK_AUTH_TOKENDrop it whenever you like. It is recognised, logged once, and gated behind nothing
A LocalStack Testcontainers moduleReplace it — see Testcontainers

Where the detail is

QuestionPage
Which of my environment variables still mean something?LocalStack environment variables
Which /_localstack/ and /_aws/ paths still answer?Endpoints and init hooks
What behaves differently once it is running?Behavioural differences
Item-by-item status for every port, URL, hostname and toolLocalStack compatibility matrix

Coverage

For current coverage use the Reference index § Services — every emulated service with its operation count — and the per-service pages behind it for operation-level detail. CloudFormation coverage is listed separately under supported resource types. Overcast has no plans, so every service it emulates is in the one build.

Troubleshooting

“Connection refused” on port 4566

docker compose ps
curl http://localhost:4566/_overcast/health

A bucket I just created does not exist

Two candidates: path-style addressing, or the state went with the last container. Storage defaults to memory when no volume is mounted — see Storage and persistence and S3 addressing.

Tests pass with LocalStack but fail here

  1. Check the service page under Reference index § Services — the operation may not be emulated yet.
  2. Re-run with OVERCAST_LOG_LEVEL=debug to see the request and the response.
  3. Inspect stored state at /_overcast/debug/state (needs OVERCAST_DEBUG=true).
  4. If the operation is listed ✅ Supported, open a compatibility issue with a minimal reproduction.