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

overcast

Hostnames that resolve for every caller

Set OVERCAST_HOSTNAME to a name your shell and your containers both resolve: the wildcard DNS domain, the offline fallbacks, and what to use in Docker Compose.

Every URL Overcast hands out carries OVERCAST_HOSTNAME when it is set, so that name has to resolve to Overcast for whoever receives the URL. One value works for the host and for containers alike:

OVERCAST_HOSTNAME=localhost.overcast.sh

Every *.localhost.overcast.sh subdomain resolves to 127.0.0.1 through public DNS, so host-routed URLs work with no hosts-file edits and behave the same on Linux, macOS and Windows. localhost.localstack.cloud and localhost.floci.io are recognised out of the box and work the same way, so a setup carried over from either tool keeps working. None of the three sends traffic to the project that owns it — the domain is a DNS lookup and nothing else, and every request goes to Overcast on your machine.

OptionResolvesOfflineWindowsSetup
localhost.overcast.sh (recommended)Every subdomain, via public DNS✗✓One variable
Plain localhost*.localhost on Linux and macOS only✓✗ — only localhost itself is in the hosts fileNone; it is the default
A hosts-file entry, or a local resolver (dnsmasq)Whatever you list, or your own wildcard domain✓✓One line per subdomain, or a resolver to run

Warning

Public wildcard DNS needs internet access, and may be blocked. Routers, corporate networks and DNS filtering software often implement DNS rebinding protection, which stops a public hostname resolving to a loopback address. localhost.overcast.sh resolves to 127.0.0.1, so a filtering network refuses it. nslookup localhost.overcast.sh should answer 127.0.0.1; anything else means your network is filtering it. Fall back to plain localhost (Linux and macOS) or a hosts-file entry (any OS).

Plain localhost on Windows is what breaks CDK’s S3 asset upload — see CDK troubleshooting.

In Docker Compose

Inside a sibling container localhost is that container, so client-facing URLs (SQS queue URLs, SNS unsubscribe links, RDS endpoints) built on localhost point at the wrong process. Give both sides a wildcard-DNS name: it resolves to 127.0.0.1 from the host and is remapped to Overcast inside every container Overcast starts, so one URL works everywhere and host-routed addressing keeps working with it.

services:
  overcast:
    image: ghcr.io/overcast-sh/overcast
    ports:
      - "4566:4566" # AWS API endpoint
      - "4567:4567" # web management console
    environment:
      OVERCAST_HOSTNAME: localhost.overcast.sh

  app:
    build: .
    environment:
      AWS_ENDPOINT_URL: http://localhost.overcast.sh:4566
    depends_on:
      - overcast

CreateFunctionUrlConfig then returns http://a1b2c3….lambda-url.us-east-1.localhost.overcast.sh:4566/, which resolves via public DNS to 127.0.0.1 and routes straight back into this container.

Offline, or behind DNS filtering: use the Compose service name, which Compose already resolves.

services:
  overcast:
    image: ghcr.io/overcast-sh/overcast:latest
    environment:
      OVERCAST_HOSTNAME: overcast # SQS QueueUrl → http://overcast:4566/...
    ports:
      - "4566:4566"

  app:
    build: .
    environment:
      AWS_ENDPOINT_URL: http://overcast:4566
    depends_on:
      - overcast

Warning

A Compose service name resolves only on the Compose network. URLs Overcast hands out then fail from your own shell, from cdk deploy, and from a browser — including the web console’s links. Add the name to your hosts file pointing at 127.0.0.1 if you need both, or prefer the wildcard-DNS option above.

OVERCAST_SPLIT_HORIZON_HOSTS adds hostnames to the set remapped to Overcast inside the containers it starts, on top of the built-in localhost.overcast.sh, localhost.localstack.cloud and localhost.floci.io.