Add SPEECH_TO_SPEECH_URL: deploy-pinned direct URL that overrides the LB

When set, the browser connects straight to it (shown read-only in
Settings) and all load-balancer logic — session proxy, queue, metering,
sign-in — is disabled. Also gitignore the local-only deploy_replica.py.

.gitignore

@@ -14,3 +14,8 @@ __pycache__/
 *.pyc
 .venv/
 venv/
+
+# Local-only replica deploy script (never tracked)
+deploy_replica.py
+
+.env

README.md

@@ -88,14 +88,26 @@ button, top-right):
 
 ## Connecting to a backend
 
-The app connects **directly** to a speech-to-speech server's realtime WebSocket —
-no load balancer, no `/session` step. Set the URL in two ways:
-
-- **`LOAD_BALANCER_URL` env** (served via `/api/config`) provides the default URL
-  shown in Settings — handy for the deployed Space.
-- **Settings → Speech-to-speech server URL** lets you override it: paste a full
+Three modes, picked by env (`/api/config` tells the client which one is active):
+
+- **`SPEECH_TO_SPEECH_URL` env** — highest priority. The browser connects
+  **directly** to this realtime WebSocket URL; it's shown read-only in Settings.
+  Setting it disables the load-balancer logic entirely (no `/api/session` proxy,
+  no queue, no metering, no sign-in). Unlike the LB address it is not a secret.
+- **`LOAD_BALANCER_URL` env** — the original flow: the browser POSTs the
+  same-origin `/api/session` proxy, the server forwards to the LB, and the
+  browser dials the per-session compute URL the LB hands back. The LB address
+  never reaches the browser; the Settings URL field is hidden.
+- **Neither** — **Settings → Speech-to-speech server URL**: paste a full
   `connect_url` (`wss://host/v1/realtime?...`) or a bare host like `localhost:8080`
-  (the app adds `/v1/realtime`).
+  (the app adds `/v1/realtime`), and the browser connects to it directly.
+
+| `SPEECH_TO_SPEECH_URL` | `LOAD_BALANCER_URL` | `SPACE_ID` | Connection | URL field | Metering |
+|:---:|:---:|:---:|---|---|---|
+| ✅ | any | any | direct → pinned URL | visible, locked | off |
+| – | ✅ | ✅ | LB proxy | hidden | **on** |
+| – | ✅ | – | LB proxy | hidden | off |
+| – | – | any | direct → user URL | editable | off |
 
 **Settings → Restart** reconnects with the current voice, instructions and URL.
 
@@ -126,8 +138,9 @@ proxy from one container).
 
 ```bash
 pip install -r requirements.txt
-export SERPER_API_KEY=...        # optional; web search is disabled without it
-export LOAD_BALANCER_URL=...     # optional; default s2s server URL (set it in Settings otherwise)
+export SERPER_API_KEY=...          # optional; web search is disabled without it
+export SPEECH_TO_SPEECH_URL=...    # optional; pin a direct s2s server URL (overrides the LB)
+export LOAD_BALANCER_URL=...       # optional; session-proxy flow (set a URL in Settings otherwise)
 uvicorn server:app --reload --port 7860
 # or, matching production: docker build -t s2s . && docker run -p 7860:7860 -e SERPER_API_KEY=... -e LOAD_BALANCER_URL=... s2s
 ```

main.js

@@ -264,16 +264,22 @@ let currentState = "idle";
 let settings = loadSettings();
 
 // ── Connection target ────────────────────────────────────────────────────────
-// Two modes, decided by the deploy via /api/config:
+// Three modes, decided by the deploy via /api/config:
+//   • SPEECH_TO_SPEECH_URL set -> direct mode pinned by the deploy: the browser
+//     connects straight to that URL, shown read-only in Settings. Overrides the
+//     load balancer entirely.
 //   • LOAD_BALANCER_URL set  -> original flow: POST the same-origin /api/session
 //     proxy (the server forwards to the LB; the LB address is never sent here).
-//   • unset (allowDirect)    -> the user sets a speech-to-speech server URL and
+//   • neither (allowDirect)  -> the user sets a speech-to-speech server URL and
 //     the browser connects to it directly (no load balancer, no /session).
 let lbMode = false;
 // Fail open: direct entry is allowed unless /api/config reports an LB URL. This
 // way a missing/unreachable config (e.g. static hosting) leaves the field
 // usable rather than locked.
 let allowDirect = true;
+// Deploy-pinned s2s URL (SPEECH_TO_SPEECH_URL). Non-empty -> locked direct
+// mode: the field displays it read-only and the saved user URL is untouched.
+let pinnedUrl = "";
 
 // ── Tool state ──────────────────────────────────────────────────────────────
 let toolsEnabled = loadTools();
@@ -829,6 +835,8 @@ async function fetchConfig() {
       lbMode = !!json.lb;
       // Lock to LB mode only when the deploy reports a load balancer.
       allowDirect = json.allowDirect ?? !lbMode;
+      // Deploy-pinned direct URL (overrides the LB server-side already).
+      pinnedUrl = (json.s2sUrl || "").trim();
       // The conversation-time limiter rides on the LB being present.
       limiterOn = lbMode;
     }
@@ -855,7 +863,7 @@ function connectionTarget() {
   if (!allowDirect) {
     return { sessionUrl: "api/session" };
   }
-  const directUrl = buildDirectWsUrl(settings.directUrl);
+  const directUrl = buildDirectWsUrl(pinnedUrl || settings.directUrl);
   if (!directUrl) {
     throw new Error("Enter a speech-to-speech server URL in Settings.");
   }
@@ -904,10 +912,11 @@ function createResumedAudioContext() {
 }
 
 /** Read the editable settings out of the form. The URL field is only honoured
- *  in direct mode (in LB mode it's locked and server-owned). */
+ *  in free direct mode — in LB mode it's hidden, and when the deploy pins a
+ *  URL it's read-only, so the user's saved URL survives either way. */
 function readSettingsFromForm() {
   return {
-    directUrl: allowDirect ? inputLbUrl.value.trim() : settings.directUrl,
+    directUrl: allowDirect && !pinnedUrl ? inputLbUrl.value.trim() : settings.directUrl,
     voice: inputVoice.value || DEFAULT_VOICE,
     instructions: inputInstructions.value.trim() || DEFAULT_INSTRUCTIONS,
     noiseGate: readGateThreshold(),
@@ -923,10 +932,18 @@ function readGateThreshold() {
 
 /** Adapt the connection field to the mode learned from /api/config. */
 function syncConnectionUi() {
-  if (allowDirect) {
+  if (pinnedUrl) {
+    // Deploy-pinned URL: show it, but locked — the deployment owns it.
+    connField.hidden = false;
+    inputLbUrl.value = pinnedUrl;
+    inputLbUrl.readOnly = true;
+    connHint.classList.remove("error");
+    connHint.textContent = "Speech-to-speech server URL pinned by this deployment.";
+  } else if (allowDirect) {
     // Direct mode: the user sets their own s2s server URL.
     connField.hidden = false;
     inputLbUrl.value = settings.directUrl;
+    inputLbUrl.readOnly = false;
     inputLbUrl.placeholder = "http://localhost:port";
     connHint.classList.remove("error");
     connHint.textContent =
@@ -941,7 +958,7 @@ function syncConnectionUi() {
 /** True when the user must supply a server URL before connecting (direct mode
  *  with nothing set). */
 function missingServerUrl() {
-  return allowDirect && !buildDirectWsUrl(settings.directUrl);
+  return allowDirect && !pinnedUrl && !buildDirectWsUrl(settings.directUrl);
 }
 
 /** Open Settings and point the user at the empty server-URL field. */

server.py

@@ -18,8 +18,12 @@ On the deployed Space the server also meters conversation time by HF login tier
 is off unless BOTH `LOAD_BALANCER_URL` and `SPACE_ID` are set, so it runs only on
 the live Space, never locally (even with the LB exported for testing).
 
+`SPEECH_TO_SPEECH_URL` overrides everything: when set, the LB logic above is
+disabled entirely (no session proxy, no queue, no metering, no sign-in) and the
+browser connects directly to that URL, shown read-only in Settings.
+
 Endpoints:
-  GET  /api/config           -> { search, lb, allowDirect, auth }
+  GET  /api/config           -> { search, lb, allowDirect, s2sUrl, auth }
   GET  /api/me               -> login + tier + remaining budget (LB mode only)
   POST /api/search           -> { results, answer }  Google via Serper.dev
   POST /api/session          -> proxies <LB>/session: a grant, or a queue ticket
@@ -58,6 +62,14 @@ SERPER_KEY = os.environ.get("SERPER_API_KEY", "").strip()
 # When empty, the user may instead set a direct s2s server URL in Settings and the
 # browser connects to it straight (no load balancer).
 LOAD_BALANCER_URL = os.environ.get("LOAD_BALANCER_URL", "").strip()
+# Direct s2s server URL pinned by the deploy. Takes priority over the load
+# balancer: when set, ALL LB logic is disabled (no /api/session proxy, no queue,
+# no limiter, no sign-in) and the browser connects to this URL directly. Unlike
+# the LB address it is NOT a secret — /api/config sends it to the client, which
+# shows it read-only in Settings.
+SPEECH_TO_SPEECH_URL = os.environ.get("SPEECH_TO_SPEECH_URL", "").strip()
+if SPEECH_TO_SPEECH_URL:
+    LOAD_BALANCER_URL = ""
 # HF injects SPACE_ID ("owner/space") into every Space runtime; it's absent
 # locally and on a plain `docker run`. We meter conversation time ONLY on the
 # deployed Space — i.e. when BOTH the LB is configured AND we're on a Space.
@@ -112,6 +124,9 @@ def config():
         "search": bool(SERPER_KEY),
         "lb": bool(LOAD_BALANCER_URL),
         "allowDirect": not LOAD_BALANCER_URL,
+        # Deploy-pinned direct s2s URL (empty when unset). Not a secret: the
+        # browser dials it itself, and Settings shows it locked.
+        "s2sUrl": SPEECH_TO_SPEECH_URL,
         "auth": AUTH_ENABLED,
     }
 

style.css

@@ -1419,6 +1419,15 @@ body.cam-on .footer {
 .field textarea:focus {
   border-color: var(--text-dim);
 }
+/* Deploy-pinned server URL: shown for transparency, not editable. */
+.field input[readonly] {
+  color: var(--text-dim);
+  border-style: dashed;
+  cursor: default;
+}
+.field input[readonly]:focus {
+  border-color: var(--border);
+}
 .field small {
   color: var(--text-faint);
   font-size: 12px;