[Feature]: Support multiple connection routes with automatic fallback and manual pinning

[harryisfish]

Before submitting

• I searched existing issues and found the related [Feature]: Ordered fallback endpoints for a saved environment (e.g. LAN primary, Tailscale secondary) #5233.
• I am describing a concrete use case.

Area

packages/client-runtime connection handling, with settings UI support on web, desktop, and mobile.

Problem

I use the same T3 Code computer from different networks:

• At home, the LAN endpoint is the fastest option.
• Away from home, the LAN endpoint is unreachable.
• T3 Connect / Relay works from almost anywhere, but can be slow for bandwidth-heavy sessions.
• I also have an FRP HTTPS endpoint, but using it at home unnecessarily consumes my home's upload bandwidth.

A saved environment currently supports only one connection endpoint. Pairing the same computer through another URL replaces the existing connection because the catalog is keyed by environmentId.

As a result, I have to edit the saved URL manually whenever my network changes.

This is closely related to #5233, but the desired behavior also includes T3 Connect / Relay and a manual route lock.

Proposed behavior

Allow one logical environment to store multiple connection routes, for example:

• Home LAN
• Tailscale
• FRP
• T3 Connect Relay

The environment must remain a single environment with one environmentId. Routes are alternative transports for that environment, not separate environments.

The client should provide two modes:

Automatic mode

• Store an ordered route preference.
• Try the last successful route first, then fall back through the remaining routes.
• On connection or reconnect, advance to the next route after transient network failures, timeouts, endpoint-unavailable errors, or transport failures.
• Do not fall back after authentication, permission, configuration, or environment-identity errors.
• Confirm that every endpoint resolves to the expected environmentId before using it.
• Remember the route that eventually succeeds and prefer it on the next connection.
• Preserve the existing environment, threads, projections, and cached state while changing only the transport route.
• Avoid parallel racing; serial attempts with bounded per-route timeouts are sufficient.

Manual mode

• Let the user pin one specific route.
• Use only the pinned route.
• Do not silently switch to another route when the pinned route is unavailable.
• Make it easy to return to automatic mode.

Route management

On web, desktop, and mobile, users should be able to:

• Add, edit, remove, label, and reorder routes.
• Add direct HTTP/HTTPS endpoints such as LAN, Tailscale, and FRP.
• Add the linked T3 Connect / Relay route for the same environment.
• See which route is currently active and why another route was selected.
• Switch between automatic mode and a pinned route without creating duplicate environments.

Relay authentication and its existing Cloudflare Tunnel data path should remain unchanged. Relay should be another selectable route for the same environment.

Acceptance criteria

• A user can save LAN, FRP, and T3 Connect routes under one environment.
• Automatic mode works when moving between home and public networks without editing the environment URL.
• Manual mode remains stable and never changes routes unexpectedly.
• Existing single-endpoint environments migrate to a one-route configuration.
• Reconnecting after a route change does not create duplicate environments or lose thread state.
• The feature works consistently on web, desktop, and mobile.

[juliusmarminge]

Triage

This is a real enhancement, not a duplicate of #5233, and it is not already in the product.

#5233 did not ship

#5233 was converted to Ideas discussion #6860 on 2026-08-15. GitHub records that as completed. There is no linked PR and no comments. #6860 is still open with no replies.

main still stores one endpoint per environment:

• BearerConnectionProfile is a single httpBaseUrl / wsBaseUrl pair (packages/client-runtime/src/connection/catalog.ts)
• The catalog is keyed by environmentId; register() replaces the existing entry (registry.ts)
• Pairing derives connectionId as bearer:${environmentId} and overwrites (onboarding.ts)
• EnvironmentSupervisor retries that one target with backoff capped at 16s; it does not walk candidates (supervisor.ts)
• Advertised endpoints are pairing-time hints only (docs/internals/remote.md)

So the single-endpoint pain described here is still accurate.

Related work (none implements this issue)

• [Feature]: Ordered fallback endpoints for a saved environment (e.g. LAN primary, Tailscale secondary) #6860 — converted [Feature]: Ordered fallback endpoints for a saved environment (e.g. LAN primary, Tailscale secondary) #5233; same LAN + Tailscale request, no T3 Connect pin, no comments
• feat(connection): support multiple routes per environment #7921 — closed unmerged. Desktop-only persist + manual route pick (relay/SSH). No automatic fallback; mobile UI out of scope. Closed as too large, not merged
• feat: T3 Connect environments switch to local connections automatically #5463 (open) — T3 Connect may promote to advertised LAN/Tailscale and fall back to relay. That is not a user-managed route list, has no pin, and does not cover FRP/LAN as saved alternatives
• fix(desktop): separate LAN and Tailscale pairing endpoints #9882 (merged), fix(desktop,web): advertise all usable network interfaces as selectable endpoints #5165, feat(desktop): choose the network interface used for LAN pairing URLs #10838 — pairing advertisement / interface choice, not saved multi-route reconnect

Scope

One environment, many labeled routes (LAN, Tailscale, FRP, T3 Connect), automatic ordered fallback (last success first; no fallback on auth/permission/identity errors; confirm environmentId), plus a pin that never silently switches. Needs catalog migration, supervisor candidate walk, and Settings UI on web, desktop, and mobile.

Next step

Keep this issue open as the tracking request. Product should choose among: the full catalog described here, landing #5463 first (T3 Connect users only), or leaving it on the Ideas track. Do not close this as a duplicate of #5233.