Supabase self-hosted installs move from Kong to Envoy in August

Supabase self-hosters have a dated migration window: in the week of August 9, 2026, the default API gateway in the Docker setup changes from Kong to Envoy. Supabase calls it a breaking change for teams that depend on Kong's HTTPS listener, custom kong.yml rules, or scripts that target the old gateway service name.

For teams running hosted Supabase, this is background infrastructure news. For operators pulling self-hosted updates from the ./docker directory, it is the kind of change that should be checked before the next upgrade lands.

Supabase changes the default gateway, not the whole stack

The new default service in docker-compose.yml is api-gw, backed by the supabase-envoy container. Supabase says the old kong hostname remains as a network alias for compatibility, and Kong is still available through a docker-compose.kong.yml override.

That matters because this is not an immediate removal of Kong. It is a default-path change. A clean self-hosted setup with no gateway customization should keep working after pulling the updated compose files, but teams with gateway-level assumptions need to choose between migrating those assumptions to Envoy or opting back into Kong for the transition.

Supabase says the former docker-compose.envoy.yml override becomes a no-op shim for one release cycle, then goes away. Operators already using Envoy should remove that override from COMPOSE_FILE after updating, rather than carrying a dead config entry forward.

The breakage risk is concentrated in Kong-specific setups

The highest-risk group is easy to identify. If you expose Kong's built-in :8443 HTTPS listener directly, the new Envoy default will not replace that behavior. Supabase's Envoy default listens on plain HTTP port 8000, so public deployments need TLS terminated by the included Caddy or Nginx reverse-proxy overrides, another upstream proxy, or the Kong override.

Custom Kong configuration is the second risk. Supabase warns that custom kong.yml routes, plugins, and ACLs do not carry over to Envoy and can stop applying if teams assume they migrated automatically. The practical path is either to opt back into Kong with the override or port the rules into Envoy's YAML configuration under volumes/api/envoy/.

The third risk is operational tooling. Commands, dashboards, scripts, and runbooks that reference kong or supabase-kong as a service/container name may need edits. The new service name is api-gw, and the container name is supabase-envoy.

Why Supabase is moving now

Supabase links the change to the state of the open-source Kong line it ships today. Its changelog says the current self-hosted stack uses kong:3.9.1, and that later 3.9.x releases have mainly been security and NGINX backports. Kong's own 3.10 changelog says unlicensed deployments now get a read-only Admin API while proxy data planes keep serving existing traffic, with license-upload and recovery endpoints left writable.

That is enough to explain the direction: Supabase wants a self-hosted gateway it can configure as code, ship with hardened defaults, and align with its newer API key model. The Envoy guide describes opaque sb_publishable_* and sb_secret_* key translation, path normalization, header-smuggling rejection, service-role restrictions for sensitive routes, and a local-only admin interface.

The caveat is that Envoy is not a drop-in copy of Kong. It has a different configuration surface, and the move is safest when treated as a gateway migration instead of a routine Docker update.

What operators should check before August 9

Start with the public edge. If your self-hosted Supabase instance relies on gateway-level HTTPS, decide whether Caddy, Nginx, or another reverse proxy will terminate TLS before the Envoy listener. Do not assume :8443 remains available.

Then check whether you maintain any Kong plugins, custom routes, ACLs, or observability hooks. Those are migration items, not passive compatibility items. Supabase's guide also notes that Envoy's admin /config_dump can expose rendered secrets inside the container, so debug workflows need the same care operators already apply to credentials.

Finally, scan automation for the old service name. Monitoring, restart commands, log collectors, and internal docs that refer to kong may still resolve at the network-hostname layer, but service/container commands should be updated to api-gw or supabase-envoy.

Sources and next milestone

The next milestone is the self-hosted Supabase release planned for the week of August 9, 2026. Supabase has already published the changelog and Envoy gateway guide, while Kong's own changelog explains the licensing behavior that affects unlicensed Admin API writes in the newer Kong Gateway line.

For teams building broader AI and automation stacks on self-hosted infrastructure, LinkLoot's AI workflow automation guide is a useful companion, but the immediate action here is operational: test the gateway path before the default changes.