Bulbul · Telephony · Proposal

Where should outbound routing live?

Numbers, trunks, and connections after the self-serve launch: why the per-number trunk field should retire, the model I propose we land on, and a migration that cannot burn the house down.

60-second primer

How an outbound call leaves our platform

Five hops and one word of jargon carry this whole deck.

The agent names a trunk when it asks LiveKit to dial; the trunk is what tells LiveKit where the call goes next.

SIP trunk: not a cable, a config object in LiveKit. It says which host to dial into (Kamailio, or a carrier directly) and with which credentials. Every outbound call must name one.
Kamailio is our own SIP routing layer, in the path of most calls: it picks the carrier route and carries per-tenant identity. The dashed shortcut is the “direct” shape we come back to on slide 5.

Where we are

Today, every phone number carries its own trunk ID

A hand-typed field, copied onto each number when it is registered. It was the right bridge during migration, and it is now the weakest link in the chain.

Why it existed: the field was deliberate backward compatibility, a bridge to carry pre-existing numbers into the new model until trunks could be consolidated. The consolidation was always the plan; connections shipping to prod is what finally makes it possible.

Why now

Connections make the trunk field removable, almost

We just shipped SIP connections: a first-class object describing a carrier relationship. That should make the hand-typed trunk field on numbers redundant. Working on exactly that this week convinced me the removal has to be sequenced carefully.

Today the backend prefers a connection’s trunk in exactly one narrow case (an active, direct-to-LiveKit connection that has a trunk recorded). Every other case silently falls back to the number’s own trunk.
And nothing writes a trunk onto a connection yet, so that narrow case never fires: every call still routes by the number’s field.
Relaxing the field before the backend catches up means a number can be saved with no working route, and it fails silently, later, at call time, potentially breaking other callers via the shared pool.

The destination is right: nobody should type trunk IDs once a connection owns routing. The UI just must not get there before the backend does. So the real question is: what is the destination, precisely?

Proposal

The connection owns routing. The number owns identity.

Every number resolves its route through one of three explicit shapes, and “no route” becomes a visible state instead of an empty string.

Decision 1 · platform-routed connections

One trunk per connection, or one shared bridge?

For connections that route through our Kamailio stack, LiveKit needs a trunk pointing at it. The hidden cost of doing that per connection: Kamailio only accepts callers it can authenticate, so every auto-created trunk also needs an auto-created credential pair (“subscriber”) on the Kamailio side, generated, stored, rotated, and cleaned up in sync.

A · Trunk + credentials per connection

N trunks, N credential pairs

Per-tenant revocation and rate limiting at the SIP layer
Auth username itself identifies the tenant
Two systems to keep in sync on every create/delete
Password lifecycle (generate, store, rotate) × every connection
More moving parts in the self-serve path

Recommended

B · One shared bridge trunk per environment

1 trunk, 1 credential pair, set up once in Terraform

No per-connection provisioning dance at all
Tenant identity via the account header we already ship (TEL-160)
Consolidation goal achieved where it matters
Shared credential: revoking it affects everyone
Per-tenant SIP-layer limits need Kamailio-side rules instead

Decision 2 · direct carriers

Do direct-to-LiveKit carriers ever move behind Kamailio?

A few carriers (the Maqsam-style setups) peer with LiveKit Cloud directly today. Full consolidation would eventually put everything behind our own stack.

A · Everything behind Kamailio, eventually

One routing plane

Single place for routing logic, observability, control
Real migration project: carrier coordination, IP allowlists re-pointed
All media hops through our stack (latency, capacity, geography)
Domain cleanup held hostage to carrier timelines

Recommended

B · Permanent hybrid

Two supported shapes, both first-class

All the domain cleanup, none of the carrier migrations
Direct peering stays for carriers that integrate best with LiveKit
Consolidation “per routing boundary”, not literally one trunk
Two code paths to maintain (already true today)

Design point · there is no secret backup path

The old trunks are not a fallback, and we should not pretend they are

A tempting design is “if the connection is down, quietly fall back to the number’s old trunk”. But the legacy trunks point at Kamailio too, and the carrier routing they ride on is exactly the config that connections now own. The old trunk is the same road with an older signpost, not an independent route.

Pre-cutover (trunk value present): the number’s field decides which trunk LiveKit uses, and the call still rides the connection-managed Kamailio config. So disabling or deprovisioning a connection while legacy numbers still ride its config would break them silently: we add an explicit guard against exactly that.
Post-cutover (trunk value null): the connection’s route plan decides. Connection down means the call fails visibly, which is honest, because there is genuinely nothing else it could do.
Cutover = null one column. Rollback = restore one value. The nullable column is the migration state; no new state machine, and the schema cannot disagree with itself.

This also makes onboarding safe by construction: linking a number to a new connection changes nothing about routing. Only the deliberate cutover step does, and only after the connection is verified.

The plan

Six steps, two of which touch live routing

Step 1 Typed routing + guardrails Resolution returns an explicit route plan (direct / platform / legacy / no-route); empty trunks filtered out of the shared pool; unlink and deprovision guards. Legacy behavior reproduced bit for bit. No routing change

Step 2 Trunk-optional UI, gated The register and edit forms relax the trunk field only when the linked connection actually owns routing. No routing change

Step 3 Connections own their trunk from day one Direct connections store their outbound trunk at creation, required by the schema for outbound use. Connections are days old, so the few existing rows get recreated under the strict model; no backfill machinery. No routing change

Step 4 Platform bridge One shared trunk and one credential in Terraform, proven on the lab and canary. Each platform connection then switches with a test call. Hot · per connection

Step 5 Retire per-number trunks Snapshot all values, then per cohort: null the column, test call, monitor. Null means fail closed; rollback is restoring one value. Hot · per number

Step 6 Cleanup UI stops asking for trunks on connection-routed numbers, server-side validation mirrors the same rule, shared contracts updated. Connection-less numbers keep the legacy field until that population is gone. No routing change

Safety property: only steps 4 and 5 change live routing, and both are per-connection or per-number, verified with real test calls, monitored, and instantly reversible. There is no flag day and no deadline pressure.

This week

What lands Monday, and what we’re asking

Monday’s release carries the wizard UX improvements (in-wizard number registration, port + address validation, ping-exempt toggle) plus steps 1 and 2, all routing-neutral by construction.
The “trunk optional” affordance ships behind a narrow gate keyed on connection data: it stays dormant until step 3 lands, so there is no window where the UI promises routing the backend cannot deliver.

Asks

Bless the target model: connection owns routing, number owns identity.
Confirm the two recommendations, shared bridge trunk (D1-B) and permanent hybrid (D2-B), plus the design point: no silent fallback, fail closed after explicit cutover.
Green-light steps 1–3 as the immediate track; steps 4 and 5 each get their own go/no-go on lab and canary results.