Key details

  1. Envoy is now the default API gateway for self-hosted Supabase.
  2. The Compose service is `api-gw` and the container is `supabase-envoy`; `kong` remains a network alias.
  3. Kong is opt-in through a Compose override rather than the default.
  4. The Envoy default exposes HTTP on port 8000 and does not include Kong’s 8443 HTTPS listener.
  5. Customized `kong.yml` settings do not automatically migrate.
  6. Supabase recommends Envoy long term because the OSS Kong line it previously shipped is effectively frozen.

What builders should take away

  1. Before pulling the latest self-hosted stack, search automation and runbooks for `kong`, `supabase-kong`, port 8443 and custom `kong.yml` references.
  2. If Kong currently terminates TLS, add an explicit reverse-proxy path before switching rather than assuming the new default preserves HTTPS behavior.
  3. For custom routes or plugins, either pin/override Kong as a temporary compatibility layer or port rules into Envoy and test them before rollout.
  4. Treat the retained `kong` network alias as a migration aid, not a guarantee that Kong-specific operational commands or plugins still work.
  5. Pin the self-hosted checkout if you need more migration time; do not rely on pulling `master` without reviewing breaking-change notes.

What changed

Supabase has made Envoy the default API gateway in its self-hosted Docker stack, replacing Kong in the base `docker-compose.yml`. The gateway service is now `api-gw` using the `supabase-envoy` container, while `kong` remains as a network alias for compatibility. Kong is still available as an explicit override. The new default listens on plain HTTP only, so users relying on Kong’s built-in HTTPS listener on port 8443 need a reverse proxy or must opt back into Kong.

Why it matters

This is a breaking infrastructure-default change for operators who customize the self-hosted stack. A stock checkout can move with little work, but Kong-specific routes, plugins, ACLs and service-name automation do not automatically translate to Envoy. Supabase’s rationale also signals a longer-term maintenance boundary: it says the free Kong OSS line it shipped is effectively frozen, while Envoy becomes the path for current key handling and hardened gateway defaults.

The default container and service identity changed

The base self-hosted Compose stack now runs Envoy as the `api-gw` service in the `supabase-envoy` container. Supabase preserves `kong` as a network alias to reduce breakage inside the Docker network, but commands and scripts that refer to the old service or container name directly can fail.

Built-in Kong TLS does not carry over

The default Envoy gateway listens on HTTP port 8000 and does not reproduce Kong’s direct HTTPS listener on 8443. Operators who terminated TLS at Kong need to add the supplied Caddy or Nginx overrides, place another reverse proxy in front, or keep Kong during migration.

Custom Kong configuration is the main compatibility trap

A customized `kong.yml` is not translated into Envoy configuration. Custom routes, plugins and access rules can therefore silently stop applying after pulling the new base stack. Supabase recommends either opting back into Kong temporarily or porting configuration into the versioned Envoy YAML under `volumes/api/envoy/`.

Supabase is using the switch to align newer authentication and hardening

Supabase says the Envoy configuration natively translates the newer opaque publishable and secret API keys into internal credentials and ships with stricter path normalization, header-smuggling rejection, proxy-aware client-IP handling and a locked-down admin interface. The migration is therefore both a compatibility event and a security/maintenance direction change.

What to watch next

  • When Supabase removes the one-release-cycle Envoy override shim.
  • Whether additional Kong-specific compatibility helpers are added or removed.
  • How quickly Kong override support is narrowed as Supabase standardizes on Envoy.
  • Further gateway features that depend on the new opaque API-key model.

Still unclear

  • The breaking impact is concentrated on customized self-hosted deployments; hosted Supabase and CLI local development are not affected.
  • Supabase still offers Kong as a transition override, but its long-term support horizon is not stated as a fixed removal date.

Sources

Direct reading behind this dossier.

2 sources
Envoy API Gateway
Supabase official documentation

Current documentation confirming Envoy as the default self-hosted gateway and describing its service identity and architecture.