feat: self-hosted backend URL override in Developer Settings

[Rahulsharma0810]

Problem

Self-hosting the Omi backend is documented and supported, but the iOS app hardcodes api.omi.me — making it impossible to use a self-hosted backend without maintaining a full fork of the app.

This was raised in #842 and closed citing "e2e authentication" as the blocker. That reasoning is incomplete:

• Firebase mismatch is already solved by LOCAL_DEVELOPMENT=true in the backend (endpoints.py) — self-hosters can enable this flag
• The real blocker is Flutter's dart:io using BoringSSL (its own TLS stack), which ignores iOS's system certificate store. Even with a custom CA installed and trusted in iOS Settings, the app rejects it with CERTIFICATE_VERIFY_FAILED. The only fix is using a domain you control — which requires changing the hardcoded URL

Solution

Add a Self-Hosted Backend section to Developer Settings with a URL text field. The infrastructure was already 90% in place:

// env.dart — already existed, just never exposed in UI
static String? _apiBaseUrlOverride;
static void overrideApiBaseUrl(String url) { ... }
static String? get apiBaseUrl => _apiBaseUrlOverride ?? _instance.apiBaseUrl;

This PR simply wires a UI to that existing method.

Changes

• app/lib/backend/preferences.dart — add customBackendUrl getter/setter (1 key in SharedPreferences)
• app/lib/main.dart — restore saved URL via Env.overrideApiBaseUrl() on launch, before any network calls
• app/lib/pages/settings/developer.dart — new "Self-Hosted Backend" section with text field, save, and clear

Behaviour

1. User enters https://my-backend.example.com in Developer Settings → Self-Hosted Backend
2. Taps Save Backend URL — persisted to SharedPreferences, snackbar prompts restart
3. On next launch: main.dart restores the URL before any network call
4. All API and WebSocket calls go to the custom backend
5. Clear field + save → reverts to default api.omi.me

A note in the UI tells users their backend needs LOCAL_DEVELOPMENT=true for Firebase token bypass.

Who needs this

• Privacy-focused users who don't want voice data on Omi's servers
• Users who exceeded transcription minute limits and want to self-host
• Enterprise deployments (the original motivation in An ability to change link and add a self-hosted backend inside of an app #842)
• Developers testing against local backends without rebuilding the app on every change

What this is NOT

This does not remove or weaken any existing auth. It only lets users redirect API calls to a backend they control. The backend is still responsible for its own auth decisions.

Closes #842

[greptile-apps]

Greptile Summary

This PR adds a self-hosted backend URL override to Developer Settings, wiring a new customBackendUrl SharedPreferences key into an existing Env.overrideApiBaseUrl() hook. The core plumbing is sound, but two runtime defects need addressing before merge.

• TestFlight staging override silently wins: In main.dart the custom backend block runs first, then the TestFlight staging detection block runs unconditionally after — meaning any TestFlight user with testFlightUseStagingApi=true will have their custom URL silently replaced by the staging URL, making the feature non-functional for that combination.
• Clear button breaks live API calls: The "✕" clear icon calls Env.overrideApiBaseUrl(''), setting _apiBaseUrlOverride to an empty string. Because Env.apiBaseUrl uses ?? (not a null/empty check), the override takes effect immediately and all API requests in the current session will construct against '' until a restart — the opposite of the stated "restart required" behavior.

Confidence Score: 4/5

Not safe to merge as-is — two P1 defects can break API calls or silently ignore the user's custom URL.

Two P1 issues remain: TestFlight staging always overwrites a custom backend URL, and the clear button immediately corrupts the live Env state with an empty-string override. Both are straightforward to fix but affect core functionality of the feature being added.

app/lib/main.dart (TestFlight ordering) and app/lib/pages/settings/developer.dart (clear button Env call)

Important Files Changed

Filename	Overview
app/lib/main.dart	Adds custom backend URL restoration at startup, but the ordering lets TestFlight staging always override the custom URL when both are configured.
app/lib/pages/settings/developer.dart	New Self-Hosted Backend UI section with save/clear logic; clear button incorrectly calls Env.overrideApiBaseUrl('') which breaks live sessions; all new user-facing strings are hardcoded (l10n missing).
app/lib/backend/preferences.dart	Adds customBackendUrl getter/setter correctly, but placed in the Auth section instead of Developer Settings section.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[App Launch: _init] --> B[SharedPreferencesUtil.init]
    B --> C{customBackendUrl not empty?}
    C -- Yes --> D[Env.overrideApiBaseUrl customBackend]
    C -- No --> E{F.env == prod?}
    D --> E
    E -- Yes --> F{isTestFlight?}
    E -- No --> Z[App Ready]
    F -- No --> Z
    F -- Yes --> G[Env.isTestFlight = true]
    G --> H{testFlightUseStagingApi?}
    H -- No --> Z
    H -- Yes --> I[Env.overrideApiBaseUrl stagingUrl]
    I --> Z
    style I fill:#c0392b,color:#fff
    style D fill:#27ae60,color:#fff

Loading

Comments Outside Diff (1)

1. app/lib/main.dart, line 154-178 (link)

   TestFlight staging silently overrides custom backend URL

   The custom backend block runs first (lines 155–159), then the TestFlight staging block runs unconditionally after it (lines 162–178). For a TestFlight user who has testFlightUseStagingApi=true and has also set a custom backend URL, the staging URL always wins and the user-configured URL is silently discarded. The feature the PR adds is completely non-functional for that combination.

   The fix is to skip the TestFlight staging override when a custom backend URL has already been applied:

     // Self-hosted backend URL — must be after SharedPreferencesUtil.init()
     final customBackend = SharedPreferencesUtil().customBackendUrl;
     if (customBackend.isNotEmpty) {
       Env.overrideApiBaseUrl(customBackend);
       debugPrint('Self-hosted backend: using $customBackend');
     }
   
     // TestFlight environment detection — must be after SharedPreferencesUtil.init()
     // Skip TestFlight staging override if a custom backend has been set.
     if (F.env == Environment.prod && customBackend.isEmpty) {
       final isTestFlight = await EnvironmentDetector.isTestFlight();
       if (isTestFlight) {
         Env.isTestFlight = true;
         if (SharedPreferencesUtil().testFlightUseStagingApi) {
           ...
         }
       }
     }

_{Reviews (1): Last reviewed commit: "feat: add self-hosted backend URL overri..." | Re-trigger Greptile}

[greptile-apps]

Clear button sets URL to empty string, breaking live API calls

Env.overrideApiBaseUrl('') sets _apiBaseUrlOverride = ''. Because Env.apiBaseUrl uses _apiBaseUrlOverride ?? _instance.apiBaseUrl, an empty string is non-null and passes the ?? check, so all API calls from this point forward will construct requests against '' and fail immediately — before the required restart.

The snackbar already communicates that a restart is needed, so the live Env.overrideApiBaseUrl call on clear is not just redundant but actively harmful. Remove it:

Suggested change

	onPressed: () {
	_backendUrlController.clear();
	SharedPreferencesUtil().customBackendUrl = '';
	Env.overrideApiBaseUrl('');
	setState(() {});
	AppSnackbar.showSnackbar('Backend URL cleared — restart app to apply');
	},
	onPressed: () {
	_backendUrlController.clear();
	SharedPreferencesUtil().customBackendUrl = '';
	setState(() {});
	AppSnackbar.showSnackbar('Backend URL cleared — restart app to apply');
	},

[greptile-apps]

Hardcoded user-facing strings must use l10n

All user-visible strings in this section are hardcoded English. The codebase rule requires context.l10n.keyName for every user-facing string — there are at least 8 violations in this block:

• 'Self-Hosted Backend' (section header)
• 'Backend URL' (row title)
• 'https://your-backend.example.com' (hint text)
• 'Save Backend URL' (button label)
• 'Note: your backend must have LOCAL_DEVELOPMENT=true…'
• 'Backend URL cleared — restart app to apply'
• 'URL must start with http:// or https://'
• 'Restored default backend — restart app to apply' / 'Backend URL saved — restart app to apply'

Add the corresponding keys to app/lib/l10n/app_en.arb and provide translations for all 33 non-English locales per the project's localization policy.

Context Used: Flutter localization - all user-facing strings mus... (source)

[greptile-apps]

customBackendUrl placed in the Auth section

This getter/setter was added inside the //------------------------ Auth ------------------------------------// block, but it belongs with the other developer settings under //---------------------- Developer Settings ---------------------------------// (around line 116). Moving it keeps the file's organization coherent and avoids confusion for future readers who look for dev-only preferences in the Auth block.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[Rahulsharma0810]

All Greptile-flagged issues have been addressed across commits 2 and 3. For clarity:

P1 — Env.overrideApiBaseUrl('') on clear/save (commit 27e583): Removed both calls. Changes now only write to SharedPreferencesUtil and take effect on restart as stated in the UI. No live session state is mutated.

P1 — TestFlight staging overrides custom URL (commit 27e583): Fixed by guarding the TestFlight block with && customBackend.isEmpty so user-configured backend always takes priority.

P2 — Hardcoded strings (commit 451de1): All 9 user-facing strings now use context.l10n keys. Corresponding entries added to app_en.arb.

P2 — customBackendUrl in Auth section (commit 451de1): Moved to the Developer Settings section in preferences.dart.

Greptile's inline comments appear to be cached from earlier commits — the flagged code no longer exists in the current HEAD.