If you run self-hosted Supabase, the week of August 9, 2026 brings the biggest infrastructure change to the stack in years: Envoy replaces Kong as the default API gateway in the official Docker Compose setup. Supabase announced the change in its July 17 changelog entry, and it lands as a breaking change for a specific subset of deployments — anyone using Kong's built-in HTTPS listener, a customized kong.yml, or scripts that reference the gateway by service name.
If you've already read our API gateway configuration guide for Kong and Envoy, you know Envoy has been available as an opt-in override for several releases. What changes now is the polarity: Envoy moves into the base docker-compose.yml, and Kong becomes the opt-in. This post covers exactly what changes, how to tell whether you're affected, and the migration steps to take before you pull the new compose files.
What Exactly Is Changing
The gateway sits in front of everything in a self-hosted Supabase deployment — REST, Auth, Storage, Realtime, Studio. Every request passes through it, so a gateway swap touches every deployment even when it doesn't break anything. Here's the delta:
| Before (Kong default) | After (Envoy default) | |
|---|---|---|
| Compose service name | kong | api-gw |
| Container name | supabase-kong | supabase-envoy |
| HTTP port | 8000 (KONG_HTTP_PORT) | 8000 (API_GW_HTTP_PORT, old var still works) |
| HTTPS listener on 8443 | Built in | Removed — HTTP only |
| Custom routing config | kong.yml | Envoy YAML under volumes/api/envoy/ |
| Kong availability | Default | Opt-in via docker-compose.kong.yml |
Two backward-compatibility shims soften the landing:
- The new
api-gwservice keepskongas a network alias, so other containers resolvinghttp://kong:8000internally keep working. docker-compose.envoy.yml— the old opt-in override — becomes a no-op shim for one release cycle, then disappears. If you opted into Envoy early, remove it from yourCOMPOSE_FILEvariable after updating.
Supabase Cloud projects and local CLI development are unaffected. This applies exclusively to self-hosted Docker deployments.
Are You Affected? A Quick Checklist
Run through these four questions against your deployment. If you answer no to all of them, the upgrade should be uneventful.
1. Do you terminate TLS on Kong's port 8443?
This is the one that takes deployments offline. The Envoy default listens on plain HTTP port 8000 only — there is no 8443 listener. If your DNS points clients directly at https://yourdomain:8443, that endpoint stops existing after the upgrade. You'll need to terminate TLS in front of the gateway instead, using the shipped docker-compose.caddy.yml or docker-compose.nginx.yml overrides — or your own proxy, as covered in our reverse proxy setup guide.
Frankly, terminating TLS at a dedicated proxy was already the right architecture. Kong's built-in listener was convenient for quick setups, but it coupled certificate management to the gateway container. If this change forces you to move TLS out front, you end up in a better place.
2. Have you customized kong.yml?
Custom routes, rate-limiting plugins, IP restrictions, modified auth rules — none of it carries over. Envoy's configuration is a different language entirely. You'll need to re-express your customizations in Envoy YAML under volumes/api/envoy/, following the official Envoy gateway guide. Budget real time for this: Envoy's routing model (listeners, filter chains, clusters) is more verbose than Kong's declarative services-and-routes format, though it's also more precise.
3. Do scripts or monitoring reference the gateway by name?
The network alias covers container-to-container DNS, but it does not cover Compose-level tooling. docker compose logs kong, docker compose restart kong, health checks that grep for supabase-kong — these all break because the service is now api-gw and the container is supabase-envoy. Grep your deployment scripts, cron jobs, and alerting rules for both names before you upgrade. Our service health monitoring guide covers how to structure these checks so a rename doesn't take your alerting down with it.
4. Did you already opt into Envoy via the override?
You're nearly done — the default is catching up to you. Just remove docker-compose.envoy.yml from your COMPOSE_FILE after updating, since the shim is temporary.
Why Supabase Is Making This Change
This isn't churn for its own sake. Kong's open-source line has effectively stalled — frozen at version 3.9.1 — while the project's commercial focus moved elsewhere. Building the default self-hosted stack on a gateway that's no longer advancing is a long-term liability, particularly for security patches on the single most exposed component of the deployment.
Envoy also fits how self-hosters actually operate. Routing, filters, and access control live in versioned YAML that diffs cleanly in git — genuine config-as-code, which matters if you manage your stack through CI/CD pipelines or infrastructure-as-code. And it aligns the self-hosted stack with the direction of the broader Supabase platform, which reduces the odds of self-hosting becoming a second-class citizen — a fear the community voices regularly, and one of the recurring themes in what's missing from self-hosted Supabase.
The honest trade-off: Envoy's learning curve is steeper. Kong's kong.yml was approachable; Envoy's configuration is powerful but famously verbose. For the majority who never touch the gateway config, this doesn't matter. For the minority who customize it heavily, the migration is real work.
Staying on Kong (and Why That's a Deferral, Not a Fix)
Kong isn't being removed — it's becoming opt-in. If the timing is bad, opt back in:
sh run.sh config add kong sh run.sh recreate
This adds the docker-compose.kong.yml override and restores the previous behavior, including the 8443 listener and your existing kong.yml.
But be clear-eyed about what this buys you: time, not a solution. You'd be pinning your most internet-exposed component to a gateway whose open-source releases have stopped. That's an acceptable short-term position while you plan a proper migration window; it's a poor permanent one. Treat opting into Kong the way you'd treat pinning a deprecated Postgres version — a scheduled item on your maintenance calendar, not a resolved ticket. The same discipline applies here as with upgrading self-hosted Supabase generally: deferred upgrades compound.
How Supascale Deployments Handle This
Supascale-managed deployments were never exposed to the sharpest edge of this change. TLS termination has always happened at the proxy layer Supascale provisions — custom domains ship with automatic SSL certificates — so no Supascale deployment depends on Kong's 8443 listener. The gateway behind it can swap from Kong to Envoy without your domain, certificates, or client configuration changing.
For the rename issue, Supascale's service monitoring tracks the stack's services as the stack defines them, so gateway health checks follow the upgrade rather than breaking on a container name change. And because Supascale deployments are built from the official compose definitions, you take this transition as part of a managed upgrade rather than hand-editing COMPOSE_FILE on a production box over SSH.
What Supascale doesn't do — and honesty matters here — is auto-migrate a hand-customized kong.yml. Nothing does. If you've written custom gateway rules, translating them to Envoy is engineering work you'll need to schedule regardless of tooling. What you can do is stop customizing the gateway for problems that belong elsewhere: rate limiting and access control are often better handled at the reverse proxy or network security layer, which survives gateway swaps untouched.
Key Takeaways
2026 has been an unusually active year for self-hosted Supabase breaking changes — the June 2026 changes and the October Data API grants change bracket this one. The Envoy migration is the most infrastructural of the three, but also the most manageable if you prepare:
- Check TLS first. If anything points at port 8443, set up Caddy, Nginx, or another proxy in front before you upgrade.
- Audit for the names
kongandsupabase-kongin scripts, monitoring, and tooling — the network alias won't save Compose commands. - Inventory
kong.ymlcustomizations and either translate them to Envoy YAML or consciously opt back into Kong with a sunset date. - Early Envoy adopters: drop
docker-compose.envoy.ymlfromCOMPOSE_FILEonce you're on the new release.
The direction is sound — an actively developed, config-as-code gateway is the right default for the most exposed component in your stack. The cost is a migration weekend for the minority who customized Kong. Schedule it; don't let the upgrade schedule it for you.