Supabase Self-Hosted Moves to Envoy: Breaking-Change Prep

Self-hosted Supabase is scheduled to swap its default API gateway from Kong to Envoy the week of August 9, 2026 — a breaking change announced in the July 17 entry on Supabase’s changelog. Scope first, because the headline causes needless panic: if you run on hosted Supabase Cloud, you need to do nothing. This change applies to self-hosted deployments only.

For self-hosters, the change is real but manageable. Envoy has already shipped as an optional override via docker-compose.envoy.yml for the last several releases; the announced change flips it to the default, and Kong inverts into the optional override. Two specific setups break at cutover: relying on Kong’s built-in :8443 HTTPS listener, and running a customized kong.yml with custom routes, plugins, or ACLs.

This guide covers exactly who is affected, why Supabase is making the move (the forcing function is Kong’s own licensing decisions, not anything Supabase broke), what Envoy’s hardened defaults buy you, and a concrete prep checklist you can run before the cutover window. We run Supabase in production for client work — on the hosted platform, which is precisely why we have nothing to change — and that scope distinction is the first thing worth internalizing.

The announcement itself is compact. On July 17, 2026, Supabase’s changelog published an entry titled “Envoy becomes the default API gateway (breaking change)” for self-hosted deployments. The substance: the week of August 9, 2026, the default API gateway in the self-hosted Docker stack changes from Kong to Envoy. Envoy is not new to the stack — it has shipped as an optional override via docker-compose.envoy.yml for the last several releases. What changes is the polarity: Envoy moves into the base compose file, and Kong becomes the opt-in override.

The mechanics of the swap are designed for continuity where possible. Per the changelog, the gateway service gets a new neutral name in the compose file while keeping the old Kong hostname as a backward-compatible network alias, the gateway HTTP port variable defaults through the existing Kong port setting so current .env files keep working, and the old Envoy override file becomes a no-op shim for one release cycle before removal so existing override users don’t break mid-flight.

Two properties of the announcement matter for planning. First, the date: week of August 9 is the only granularity Supabase has published — no specific day exists, so a prudent operator treats Friday, August 7 as the last safe pre-cutover checkpoint. Second, the reversibility: Kong remains available as an override, which converts this from a forced migration into a scheduled default change with an escape hatch.

The affected population is narrower than the “breaking change” label suggests. You are in scope if you run self-hosted Supabase from the ./docker directory and pull updates from master. Deployments that are pinned to a specific commit or maintained as a fork that doesn’t sync upstream are not force-migrated — the cutover only reaches you when you next pull the updated compose files. That makes the timing partially yours to control: pinning is a legitimate deferral strategy, not just an accident of setup.

Within that in-scope group, the degree of impact splits again. A stock self-hosted deployment — default kong.yml, a reverse proxy already terminating TLS in front of the stack — should pull the update and keep working, with requests now flowing through Envoy. The setups that need real work are the ones that leaned on Kong specifics: the built-in HTTPS listener, custom gateway config, or tooling that addresses the gateway container by its old name. Section 05 breaks those down.

And to close the scope loop from the other side: teams building on hosted Supabase — the setup we walk through in our complete Supabase + Next.js guide — inherit whatever gateway the managed platform runs, invisibly. That is rather the point of managed hosting, and this episode is a clean illustration of the operational delta between the two modes.

The interesting question isn’t that Supabase is swapping gateways — it’s why now. The answer sits mostly on Kong Inc.’s side of the fence, and it’s worth being precise about attribution: the licensing decisions below are Kong’s, documented in Kong-ecosystem sources, not Supabase claims.

Two moves define the situation. First, Kong’s OSS-only images are effectively frozen at kong:3.9.1 — per Kong’s own breaking-changes documentation and third-party migration guides, subsequent 3.9.x releases have been security and nginx backports only, with no feature cadence. Second, starting with Gateway 3.10, Kong removed free (unlicensed) mode: running the kong/kong-gateway 3.10+ image without a valid license behaves like an expired Enterprise license rather than a full free OSS build. To stay on a genuinely free Kong, operators must pin the OSS-only kong:3.9.1 image — a line that is no longer advancing.

Industry commentary around Kong’s ecosystem attributes the OSS slowdown to the company’s commercial pivot toward Konnect, its paid managed control plane — a reading that is plausible but worth labeling as commentary rather than vendor-confirmed fact. What is confirmed, in Supabase’s own framing, is the consequence: shipping a frozen gateway line to thousands of self-hosted deployments carries growing security and compliance risk, and Supabase chose to move its default off that line rather than ride it down. For a platform whose self-hosted story is a core differentiator against closed alternatives — see how Supabase stacks up against Firebase — keeping that stack on actively maintained components is strategic hygiene, not churn.

The trend this fits is bigger than one vendor swap. When a commercial open-source company narrows its free tier, the projects downstream don’t argue — they re-platform, and they tend to re-platform onto neutrally governed infrastructure. Envoy, a CNCF-graduated project, is exactly the kind of destination that pattern predicts. We’d expect more OSS platforms still shipping Kong’s frozen line to make similar moves over the next year.

Envoy is not an obscure pick. It’s a high-performance C++ layer-7 proxy originally built at Lyft, graduated within the CNCF, and widely deployed as the data plane underneath Kubernetes service meshes. Where Kong’s foundation is Lua/LuaJIT scripting on top of OpenResty and Nginx, Envoy is driven by declarative, dynamic configuration — in Supabase’s self-hosted stack, the routing, filters, and access control live as versioned YAML, with no plugin runtime to manage.

The security posture of Supabase’s shipped Envoy config is the substantive upgrade, and the self-hosted Envoy docs spell it out. Path normalization is on (normalize_path: true, merge_slashes: true), closing the classic path-confusion route around prefix-based access rules. URL-encoded-slash tricks are rejected outright (path_with_escaped_slashes_action: REJECT_REQUEST), as are headers containing underscores (headers_with_underscores_action: REJECT_REQUEST) — the underscore-versus-hyphen normalization gap being a known header-smuggling vector. Client-IP handling treats Envoy as an edge proxy (use_remote_address: true), stripping untrusted proxy headers and using the peer connection as the authoritative client address.

One more motivation deserves mention because it explains the long-term direction: the changelog notes the Envoy configuration has first-class support for Supabase’s newer API-key scheme, translating publishable and secret keys into internal JWTs at the gateway. The pattern across all of this is convergence — the self-hosted stack aligning with the direction of the wider Supabase platform rather than maintaining a parallel, divergent gateway path. Section 07 shows that alignment was the stated rationale months before the changelog entry existed.

Strip away the “breaking change” framing and the concrete breakage list is short. Two setups fail at cutover; a third degrades quietly later.

1. The :8443 HTTPS listener disappears

If you rely on Kong’s built-in :8443 HTTPS listener directly — no reverse proxy in front of the stack — Envoy’s default does not expose port 8443. The default gateway listens on plain HTTP only. The recommended fix is to put Caddy or Nginx in front for TLS termination; Supabase ships compose overrides for both, and its self-hosted proxy/HTTPS docs cover the setup. If neither works for your environment, opting back into Kong preserves the listener. Frankly, terminating TLS at a dedicated reverse proxy is the better architecture regardless — the cutover just forces the decision.

2. Customized kong.yml files stop applying

Any customized kong.yml — custom routes, plugins, ACLs — does not carry over to Envoy. Once the default flips, those customizations stop applying, and nothing errors to tell you: the stack comes up, requests flow, and your custom access rules are simply no longer in the request path. This is the dangerous one, because the failure mode is silent permissiveness rather than loud downtime. If you have ever edited kong.yml, audit what’s in it before the cutover week, and either port the rules to the Envoy config or plan to run the Kong override.

3. Gateway-name references drift

Scripts and tooling that reference the gateway by its old service or container name keep partially working — the changelog notes the old Kong hostname survives as a network alias — but compose-level commands aimed at the renamed service need updating. Not a day-one outage; a slow accumulation of confusing failures if ignored.

The table below turns the changelog’s one-line notice into an operator runbook. Find your row, do the action column before the cutover week, and know your fallback. Most deployments match more than one row — work through all that apply.

Two checklist-adjacent notes. First, the best rehearsal available today is the existing Envoy override: enabling docker-compose.envoy.yml in a staging copy of your stack switches you to Envoy now — the docs confirm enabling the override disables the default Kong gateway — so you can validate your app’s full request surface against Envoy weeks before the default flips. Second, if you opt back into Kong, treat it as a transition aid with a shelf life, not a destination: the override tracks the frozen OSS 3.9.x line, which is the very problem the migration exists to solve.

The gateway question wasn’t decided in private. In a Supabase GitHub Discussion opened November 30, 2025 (#40929), a HAProxy maintainer proposed HAProxy as an alternative gateway to Kong for self-hosted Supabase. The exchange that followed is the clearest public window into the team’s reasoning — months before the changelog entry existed.

That reply — from Supabase maintainer Aantti, naming Envoy as the team’s primary consideration — carries two useful disclosures. First, it confirms that Supabase Cloud already runs Envoy internally: the self-hosted default change is explicitly an alignment move, bringing the open stack closer to what the managed platform runs. Second, it shows how the team handles gateway pluralism: rather than adopting HAProxy into core, the maintainer proposed a community-maintained alternative-proxy repository, modeled on the existing community Traefik project. The architecture stays opinionated at the center with an escape valve at the edge.

Looking forward, that managed-parity logic is the tell for where self-hosted Supabase goes next. When the hosted platform and the self-hosted stack share a gateway, gateway-level features — the new API-key translation is the first visible example — can ship to both without a compatibility fork. Self-hosters should expect the payoff of this migration to arrive as faster feature parity, and should weigh that against the comfort of staying on the Kong override longer than necessary.

The decision tree is short, and for most readers it terminates at “do nothing.” Here’s the honest split by situation.

Our own position illustrates the scope point: we run Supabase as the data backbone for client production systems — CRM-integrated apps like the one in our Zoho-to-Supabase sync agent tutorial — on the hosted platform, and this cutover costs us zero maintenance windows. That is the trade self-hosting makes explicit: you gain control of the stack and inherit its migrations. Neither answer is wrong, but teams should price gateway-level churn like this into the self-hosting decision, not just server costs.

For teams whose Supabase deployment underpins operational systems — CRM sync, customer portals, internal dashboards — a gateway change is exactly the kind of infrastructure event worth handling deliberately rather than discovering in production. That operational layer is where we spend most of our client time: our CRM automation practice builds on Supabase-backed stacks daily, and our web development team handles precisely this class of migration-window planning for production apps.