llm-switcher 1.3.2 → 1.3.4

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog — LLM Switcher
 
+## Release 1.3.4
+
+- **The dashboard page carries no token:** `/ui` sent `admin.token` in the page, and any program on the machine can load `/ui`. The page now gets the token only from the `#token=` of the private launcher that `switch ui` opens (a file with mode 0600). The tab keeps it in `sessionStorage`, so it does not stay in the browser after the tab closes. A tab opened at `/ui` directly says to use `switch ui`. `switch status` and the gateway start line say the same.
+- **Tests:** The agy shim tests start a real relay and send a real request through it. The request must reach the gateway with the Google token, and a gateway without a valid proof must get nothing. The Update now test waits longer than the page polls, so a failure shows what the page saw.
+
+## Release 1.3.3
+
+- **agy runs behind a relay:** A routed agy no longer gets the gateway port. The shim starts it behind `agy-relay.mjs`, which holds its own loopback port for as long as agy runs. For each connection, the relay asks the gateway for its identity proof on the same socket and sends agy's request only after the proof holds. Before, the shim checked the gateway only at launch, so a gateway that stopped during an agy session left its port free for another program to take, with agy's Google token sent to it. If the proof fails now, agy gets a 502 and the token stays in the relay.
+- **A relay key that no page serves:** The relay accepts only `relayProof`, an HMAC keyed by `gateway.secret`, a random file next to `admin.token`. The gateway makes it at startup and keeps no copy. The dashboard page carries `admin.token`, so a proof keyed by it could be made by any program that loads the page. A gateway older than the relay gets a 502 that says to restart it.
+- **A `.cmd` agy gets its arguments unchanged:** The relay starts a `.cmd` or `.bat` agy through `%SystemRoot%\System32\cmd.exe /e:ON /v:OFF /d /c` with the quoting of the Rust standard library since CVE-2024-24576. `%` cannot expand a variable, and `&` or `|` cannot start a second command. A line break, or a command line over 8191 characters, stops the relay before agy starts, with a hint to pipe the prompt on stdin.
+- **`switch off` and `switch port` leave another instance alone:** They stopped or rewrote the installed service even when it ran the gateway of another port. A second instance (`LLM_SWITCHER_PORT`) then stopped the first one. The service now counts only for the port its definition names. The test suite triggered the same fault and stopped the real gateway of the machine.
+
 ## Release 1.3.2
 
 - **Codex over WebSocket crosses Bifrost:** Codex uses its WebSocket transport by default. The gateway now sends each WebSocket turn to intact `/v1/responses` as one HTTP request with the whole conversation, and sends each event back as one frame. Before, these turns took the convert route. A stream that stops before `response.completed` ends the turn with `response.failed`.

package/README.md

@@ -211,7 +211,8 @@ node "$(npm root -g)/llm-switcher/proxy.mjs"
 
 `switch <command>` works the same on Linux, macOS and Windows. A checkout has its own launchers: `switch` for Linux and macOS, `switch.cmd` for Windows. Platform differences, and the two features that are not available everywhere, are in [📖 `docs/cross-platform.md`](docs/cross-platform.md).
 
-Open the Web Dashboard at: **[http://127.0.0.1:3456/ui](http://127.0.0.1:3456/ui)**
+Open the Web Dashboard with `switch ui`. It opens `http://127.0.0.1:3456/ui` with the access token of
+this install, and the browser tab keeps the token while it stays open.
 
 ---
 
@@ -337,9 +338,18 @@ gateway for its identity proof before it gives agy the variable. If the port doe
 the proof of this install within 3 seconds, the shim removes the variable, prints one line, and agy
 uses its official endpoint.
 
-The shim does this check only when agy starts. If the gateway stops while agy runs (`switch off`, a
-crash, an update), the port is free. Another account on this computer can then take the port and
-receive the token. To close this gap, close agy before you stop the gateway.
+The gateway can also stop while agy runs (`switch off`, a crash, an update). Its port is then free,
+and another program can take it. So a routed agy never talks to the gateway port directly. The shim
+starts agy behind a relay (`agy-relay.mjs`) that holds its own loopback port for as long as agy
+runs. For each connection from agy, the relay asks the gateway for its identity proof on the same
+socket, and sends the request on that socket only after the proof holds. If the proof fails, agy
+gets a 502, and its token stays in the relay.
+
+The relay accepts only a proof keyed by `gateway.secret`, a random key next to `admin.token`. No
+page and no route of the gateway serves this key, and no program can derive it from `admin.token`.
+If the running
+gateway is older than the relay, agy gets a 502 that says to restart it (`switch off`, then
+`switch on`).
 
 ### Blindfold mode (optional)
 
@@ -773,7 +783,7 @@ Because of this split, a provider fingerprint is never a rule in this gateway. I
 ## Security Model
 
 - The gateway binds to `127.0.0.1` only and rejects requests whose `Host` is not a loopback name (DNS-rebinding protection) or whose `Origin` is not the dashboard itself (CSRF protection).
-- The admin API (`/api/*`) requires the `x-llm-switcher-token` header. The gateway creates the token in `admin.token`, next to `config.json`, with mode 0600. The gateway puts this token in the dashboard page, so `http://127.0.0.1:3456/ui` works when you open it directly. The Host and Origin checks keep the page and the token from other sites. The MCP server reads the file. `/v1/*` and `/health` need no token.
+- The admin API (`/api/*`) requires the `x-llm-switcher-token` header. The gateway creates the token in `admin.token`, next to `config.json`, with mode 0600. The dashboard page does not carry this token, because any program on the computer can load the page. `switch ui` opens the dashboard through a private file (mode 0600) that gives the token to the browser tab in the URL fragment, and the page removes it from the address bar. A tab opened at `http://127.0.0.1:3456/ui` without this file shows a message that says to use `switch ui`. The MCP server reads the file. `/v1/*` and `/health` need no token.
 - API keys are never sent to the browser: `/api/status` returns redacted profiles and the dashboard keeps the stored key unless you type a new one. The stored key goes only to the stored `baseURL` and `endpoints` of that profile. A save that changes either one must carry the key again.
 - Every dashboard change carries the config revision that the page loaded. If another tab, the CLI or the MCP server saved in the meantime, the gateway answers 409 and the page reloads instead of overwriting that change.
 - Client credentials such as `x-api-key`, `authorization` or `x-goog-api-key` are **not** forwarded to upstreams. Other `x-*` headers, `traceparent` and `tracestate` pass through. The gateway drops its own control headers (`x-profile`, `x-llm-profile`) and the network identity headers (`x-forwarded-*`, `x-real-ip`).

package/README.vi.md

@@ -213,7 +213,8 @@ node "$(npm root -g)/llm-switcher/proxy.mjs"
 Khác biệt giữa các nền tảng, và hai tính năng không chạy ở mọi nơi, nằm trong
 [📖 `docs/cross-platform.md`](docs/cross-platform.md).
 
-Mở Bảng điều khiển Web Dashboard tại: **[http://127.0.0.1:3456/ui](http://127.0.0.1:3456/ui)**
+Mở Bảng điều khiển Web Dashboard bằng `switch ui`. Lệnh này mở `http://127.0.0.1:3456/ui` kèm token truy
+cập của bản cài này, và tab trình duyệt giữ token trong lúc tab còn mở.
 
 ---
 
@@ -337,9 +338,17 @@ agy gửi token này dạng rõ tới `CLOUD_CODE_URL`. Vì vậy shim `agy` h
 trước khi giao biến này cho agy. Nếu cổng không trả lời đúng bằng chứng của bản cài này trong 3 giây,
 shim gỡ biến, in một dòng thông báo, và agy dùng endpoint chính thức.
 
-Shim chỉ kiểm tra việc này lúc agy khởi động. Nếu gateway dừng trong lúc agy đang chạy (`switch off`,
-crash, cập nhật), cổng bị bỏ trống. Khi đó một tài khoản khác trên máy có thể chiếm cổng và nhận token.
-Để không có khoảng hở này, hãy đóng agy trước khi dừng gateway.
+Gateway cũng có thể dừng trong lúc agy đang chạy (`switch off`, crash, cập nhật). Khi đó cổng của nó
+bỏ trống, và một chương trình khác có thể chiếm cổng. Vì vậy agy đã route không bao giờ nói chuyện
+trực tiếp với cổng gateway. Shim chạy agy sau một relay (`agy-relay.mjs`) giữ cổng loopback riêng
+suốt thời gian agy chạy. Với mỗi kết nối của agy, relay hỏi gateway bằng chứng danh tính trên chính
+socket đó, và chỉ gửi request trên socket ấy khi bằng chứng đúng. Nếu sai, agy nhận 502, và token
+vẫn nằm lại trong relay.
+
+Relay chỉ chấp nhận bằng chứng ký bằng `gateway.secret`, một khóa ngẫu nhiên nằm cạnh `admin.token`.
+Không trang và không route nào của gateway trả về khóa này, và không chương trình nào suy ra được nó từ
+`admin.token`. Nếu gateway đang
+chạy cũ hơn relay, agy nhận 502 kèm hướng dẫn khởi động lại (`switch off`, rồi `switch on`).
 
 ### Chế độ blindfold (tùy chọn)
 
@@ -768,7 +777,7 @@ Nhờ cách chia này, fingerprint của provider không bao giờ là rule tron
 ## Mô hình Bảo mật
 
 - Gateway chỉ lắng nghe `127.0.0.1` và từ chối request có `Host` không phải loopback (chống DNS rebinding) hoặc `Origin` không phải chính dashboard (chống CSRF).
-- Admin API (`/api/*`) bắt buộc header `x-llm-switcher-token`. Gateway tạo token trong file `admin.token`, cạnh `config.json`, với mode 0600. Gateway đặt token này vào trang dashboard, nên mở thẳng `http://127.0.0.1:3456/ui` là dùng được. Lớp kiểm tra Host và Origin ngăn trang web khác đọc trang và token. MCP server đọc token từ file. `/v1/*` và `/health` không cần token.
+- Admin API (`/api/*`) bắt buộc header `x-llm-switcher-token`. Gateway tạo token trong file `admin.token`, cạnh `config.json`, với mode 0600. Trang dashboard không chứa token này, vì chương trình nào trên máy cũng tải được trang. `switch ui` mở dashboard qua một file riêng tư (mode 0600), file này đưa token cho tab trình duyệt qua phần fragment của URL, rồi trang xóa nó khỏi thanh địa chỉ. Tab mở thẳng `http://127.0.0.1:3456/ui` mà không qua file này sẽ hiện thông báo bảo dùng `switch ui`. MCP server đọc token từ file. `/v1/*` và `/health` không cần token.
 - API key không bao giờ gửi xuống trình duyệt: `/api/status` trả profile đã che key, dashboard giữ nguyên key đã lưu nếu bạn không nhập key mới. Key đã lưu chỉ được gửi tới `baseURL` và `endpoints` đã lưu của chính profile đó. Lần lưu nào đổi một trong hai thì phải nhập lại key.
 - Mỗi thay đổi từ dashboard mang theo revision của config mà trang đã tải. Nếu tab khác, CLI hoặc MCP server đã lưu trước đó, gateway trả 409 và trang tải lại thay vì ghi đè thay đổi kia.
 - Credential của client (`x-api-key`, `authorization`, `x-goog-api-key`) **không** được chuyển tiếp lên upstream. Các header `x-*` khác, `traceparent` và `tracestate` được chuyển tiếp. Gateway bỏ header điều khiển của chính nó (`x-profile`, `x-llm-profile`) và header định danh mạng (`x-forwarded-*`, `x-real-ip`).

package/agy-relay-lib.mjs

@@ -0,0 +1,86 @@
+// Pure helpers of agy-relay.mjs, kept apart so tests can import them without starting a relay.
+
+// The switcher writes 127.0.0.1 only. localhost can resolve to ::1, which no proof covers.
+export function gatewayPort(raw) {
+  let u;
+  try { u = new URL(raw); } catch { return 0; }
+  if (u.protocol !== 'http:' || u.hostname !== '127.0.0.1') return 0;
+  const port = Number(u.port);
+  return Number.isInteger(port) && port >= 1 && port <= 65535 ? port : 0;
+}
+
+// One complete HTTP/1.1 answer at the start of `buf`: { status, text, rest }, or null while it is
+// still incomplete. An answer with no length cannot share its socket, so it counts as a failure.
+export function readAnswer(buf) {
+  const end = buf.indexOf('\r\n\r\n');
+  if (end < 0) return null;
+  const lines = buf.subarray(0, end).toString('latin1').split('\r\n');
+  const status = Number(lines[0].split(' ')[1]);
+  const headers = {};
+  for (const line of lines.slice(1)) {
+    const i = line.indexOf(':');
+    if (i > 0) headers[line.slice(0, i).trim().toLowerCase()] = line.slice(i + 1).trim();
+  }
+  const rest = buf.subarray(end + 4);
+  if (/close/i.test(headers.connection || '')) return { status: 0, text: '', rest };
+  if (headers['content-length'] !== undefined) {
+    const n = Number(headers['content-length']);
+    if (!Number.isInteger(n) || n < 0) return { status: 0, text: '', rest };
+    if (rest.length < n) return null;
+    return { status, text: rest.subarray(0, n).toString('utf8'), rest: rest.subarray(n) };
+  }
+  if (/chunked/i.test(headers['transfer-encoding'] || '')) {
+    const parts = [];
+    let off = 0;
+    for (;;) {
+      const lineEnd = rest.indexOf('\r\n', off);
+      if (lineEnd < 0) return null;
+      const size = parseInt(rest.subarray(off, lineEnd).toString('latin1'), 16);
+      if (!Number.isInteger(size) || size < 0) return { status: 0, text: '', rest };
+      if (size === 0) {
+        if (rest.length < lineEnd + 4) return null;
+        return { status, text: Buffer.concat(parts).toString('utf8'), rest: rest.subarray(lineEnd + 4) };
+      }
+      if (rest.length < lineEnd + 2 + size + 2) return null;
+      parts.push(rest.subarray(lineEnd + 2, lineEnd + 2 + size));
+      off = lineEnd + 2 + size + 2;
+    }
+  }
+  return { status: 0, text: '', rest };
+}
+
+// The longest string cmd.exe takes after /c.
+export const CMD_LIMIT = 8191;
+const SAFE = /^[A-Za-z0-9#$*+\-./:?@\\_]$/;
+
+// One argument for a batch file, as the Rust standard library builds it since CVE-2024-24576
+// (make_bat_command_line): `"` becomes `""`, and `%` becomes `%%cd:~,%`, which expands to `%`, so
+// cmd.exe never expands a %name% or %name:x=y% that came from the argument.
+function batArg(arg) {
+  const quote = arg === '' || arg.endsWith('\\') || [...arg].some(c => !SAFE.test(c));
+  let out = quote ? '"' : '';
+  let backslashes = 0;
+  for (const c of arg) {
+    if (c === '\\') {
+      backslashes++;
+    } else {
+      if (c === '"') out += `${'\\'.repeat(backslashes)}"`;
+      else if (c === '%') out += '%%cd:~,';
+      backslashes = 0;
+    }
+    out += c;
+  }
+  if (quote) out += `${'\\'.repeat(backslashes)}"`;
+  return out;
+}
+
+// The cmd.exe arguments that run a .cmd/.bat with `args` unchanged: { args } or { error }.
+export function batCommandLine(script, args) {
+  if (script.includes('"') || script.endsWith('\\')) return { error: `the path of agy (${script}) cannot hold " or end with \\` };
+  for (const a of args) {
+    if (/[\r\n]/.test(a)) return { error: 'an argument holds a line break, which a .cmd or .bat agy cannot receive. Pipe the prompt on stdin instead.' };
+  }
+  const inner = `"${[`"${script.replace(/%/g, '%%cd:~,%')}"`, ...args.map(batArg)].join(' ')}"`;
+  if (inner.length > CMD_LIMIT) return { error: `the command line is longer than ${CMD_LIMIT} characters, the limit of cmd.exe. Pipe the prompt on stdin instead.` };
+  return { args: ['/e:ON', '/v:OFF', '/d', '/c', inner] };
+}

package/agy-relay.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+// Runs agy behind a relay that holds its own loopback port for exactly as long as agy runs.
+//
+// agy sends its Google token in clear text to CLOUD_CODE_URL. The shim checks the gateway once,
+// at launch. A gateway that stops later frees its port, and another program can take it. So agy
+// talks only to this relay: for each connection it asks the gateway for its relay proof on the
+// socket it will use, and sends agy's bytes only after that proof holds.
+//
+// Usage: node agy-relay.mjs <gateway-url> <agy> [args...]
+import net from 'node:net';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { relayProof } from './state.mjs';
+import { gatewayPort, readAnswer, batCommandLine } from './agy-relay-lib.mjs';
+
+// The proof of a live gateway takes milliseconds; a squatter gains nothing from a longer wait.
+const PROOF_MS = 3000;
+const MAX_PROBE_ANSWER = 64 * 1024;
+
+// The gateway on a new socket: { sock } when it proved itself with the relay key (state.mjs),
+// otherwise { old: true } for a gateway built before relayProof, or {} for anything else. Only the
+// first case gets agy's bytes, on this same socket, so no other process can answer them.
+function provenSocket(port) {
+  return new Promise((resolve) => {
+    const nonce = crypto.randomBytes(16).toString('hex');
+    const sock = net.connect(port, '127.0.0.1');
+    let buf = Buffer.alloc(0);
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      sock.off('data', onData);
+      sock.off('error', onFail);
+      sock.off('close', onFail);
+      if (result.sock) return resolve(result);
+      sock.destroy();
+      resolve(result);
+    };
+    const onFail = () => finish({});
+    const onData = (chunk) => {
+      buf = Buffer.concat([buf, chunk]);
+      if (buf.length > MAX_PROBE_ANSWER) return finish({});
+      const answer = readAnswer(buf);
+      if (!answer) return;
+      // Nothing may follow the probe answer: those bytes would reach agy as its own answer.
+      if (answer.status !== 200 || answer.rest.length) return finish({});
+      let body;
+      try { body = JSON.parse(answer.text); } catch { return finish({}); }
+      if (!body || typeof body !== 'object' || Array.isArray(body)) return finish({});
+      if (body.proxy !== 'llm-switcher' || body.port !== port) return finish({});
+      // An absent field, never a falsy one: relayProof '' must still fail the check below.
+      if (!Object.hasOwn(body, 'relayProof')) return finish({ old: true });
+      const expected = relayProof(nonce, { port, pid: body.pid });
+      finish(Boolean(expected) && body.relayProof === expected ? { sock } : {});
+    };
+    const timer = setTimeout(onFail, PROOF_MS);
+    sock.on('data', onData);
+    sock.on('error', onFail);
+    sock.on('close', onFail);
+    sock.write(`GET /health?challenge=${nonce} HTTP/1.1\r\nHost: 127.0.0.1:${port}\r\nConnection: keep-alive\r\n\r\n`);
+  });
+}
+
+// agy shows a Code Assist error, and its request stays in this process.
+function refusal(message) {
+  const body = JSON.stringify({ error: { code: 502, status: 'UNAVAILABLE', message } });
+  return `HTTP/1.1 502 Bad Gateway\r\nContent-Type: application/json\r\nContent-Length: ${Buffer.byteLength(body)}\r\nConnection: close\r\n\r\n${body}`;
+}
+const NOT_PROVED = 'LLM Switcher: the gateway did not prove its identity, so this request was not sent. Run `switch on`, or `switch off agy`.';
+const OLD_GATEWAY = 'LLM Switcher: the running gateway is older than this relay. Restart it: `switch off`, then `switch on`.';
+
+function startRelay(port) {
+  // pauseOnConnect: agy's bytes stay unread until the gateway on this connection has proved itself.
+  const server = net.createServer({ pauseOnConnect: true }, async (client) => {
+    client.on('error', () => client.destroy());
+    const { sock: up, old } = await provenSocket(port);
+    if (client.destroyed) return up?.destroy();
+    if (!up) {
+      client.end(refusal(old ? OLD_GATEWAY : NOT_PROVED));
+      client.resume(); // read and drop the request; nothing of it leaves this process
+      return;
+    }
+    up.on('error', () => client.destroy());
+    client.on('close', () => up.destroy());
+    up.on('close', () => client.destroy());
+    client.pipe(up);
+    up.pipe(client);
+    client.resume();
+  });
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => resolve(server));
+  });
+}
+
+// A .cmd/.bat cannot start without cmd.exe. It is always the one in System32: a bare name would be
+// looked up in the current directory first.
+function launch(file, args, env) {
+  if (process.platform === 'win32' && /\.(cmd|bat)$/i.test(file)) {
+    const line = batCommandLine(file, args);
+    if (line.error) {
+      console.error(`[llm-switcher] cannot start agy: ${line.error}`);
+      process.exit(2);
+    }
+    const cmd = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'cmd.exe');
+    return spawn(cmd, line.args, { stdio: 'inherit', env, windowsVerbatimArguments: true });
+  }
+  return spawn(file, args, { stdio: 'inherit', env });
+}
+
+const [gatewayUrl, agy, ...args] = process.argv.slice(2);
+if (!agy) {
+  console.error('Usage: node agy-relay.mjs <gateway-url> <agy> [args...]');
+  process.exit(2);
+}
+if (args.some(a => a.includes('\0'))) {
+  console.error('[llm-switcher] cannot start agy: an argument holds a NUL character.');
+  process.exit(2);
+}
+
+const env = { ...process.env };
+delete env.CLOUD_CODE_URL;
+const port = gatewayPort(gatewayUrl);
+if (port) {
+  const server = await startRelay(port);
+  env.CLOUD_CODE_URL = `http://127.0.0.1:${server.address().port}`;
+} else {
+  console.error(`[llm-switcher] ${String(gatewayUrl)} is not the address of this switcher's gateway; agy uses its official endpoint.`);
+}
+
+const child = launch(agy, args, env);
+// Ctrl+C reaches agy and this relay together. agy decides what it means; the relay ends with agy.
+process.on('SIGINT', () => {});
+if (process.platform === 'win32') process.on('SIGBREAK', () => {});
+process.on('SIGTERM', () => child.kill());
+child.on('error', (err) => {
+  console.error(`[llm-switcher] cannot start agy (${agy}): ${err.message}`);
+  process.exit(127);
+});
+child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-switcher",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "description": "Zero-dependency multi-protocol edge gateway & provider switcher for Claude Code and Codex, with OpenAI-compatible, Anthropic and Vertex upstreams",
   "keywords": [
     "llm",

package/proxy.mjs

@@ -22,7 +22,7 @@ import {
   getActiveMap, setTargetProfile, activateProfile, deactivateProfile, deactivateAll, deleteProfile,
   isProfileActive, profileAcceptsTarget, applyLaunchState, readLaunchFlags, redactConfig, MASKED_KEY,
   modelForSlot, primaryModel, codexPublicModel, isSafeModelName, parsePort, CODEX_MODEL_SLOTS,
-  ensureAdminToken, identityProof, reconcileBlindfold, checkBlindfoldTarget,
+  ensureAdminToken, ensureGatewaySecret, relayProof, identityProof, reconcileBlindfold, checkBlindfoldTarget,
   codexModelEntry, smallestWindows, publicModelWindows, model1MForSlot,
   contractLabSettings, STATE_DIR, stopRecordedBlindfold
 } from './state.mjs';
@@ -116,6 +116,8 @@ function checkRequestOrigin(req) {
 // The Host/Origin guard stops browser pages only. A local process that is not the owner must
 // also present the token from admin.token (mode 0600) to use /api/*.
 const ADMIN_TOKEN = Buffer.from(ensureAdminToken());
+// The relay key. The gateway keeps no copy: relayProof() reads the file for each proof.
+ensureGatewaySecret();
 
 // `switch contract-probe` names the trace id of the exchange it drives, so it can print the id
 // before intact holds it. Only a process that can read admin.token is believed, and the marker
@@ -1298,10 +1300,9 @@ async function route(req, res) {
         'X-Frame-Options': 'DENY',
         'X-Content-Type-Options': 'nosniff'
       });
-      // One gateway serves one user, so the page opened at /ui carries its own token. The Host and Origin
-      // guard above keeps it from other sites; the token is hex, so it needs no escaping.
-      const meta = `<meta name="llm-switcher-token" content="${ADMIN_TOKEN.toString()}">`;
-      return res.end(fs.readFileSync(uiHtmlPath, 'utf8').replace('<head>', `<head>\n  ${meta}`));
+      // No token in the page: any process on the machine can GET /ui. The dashboard gets it from the
+      // #token of the private launcher that `switch ui` opens.
+      return res.end(fs.readFileSync(uiHtmlPath, 'utf8'));
     }
   }
 
@@ -1315,7 +1316,9 @@ async function route(req, res) {
       proxy: 'llm-switcher',
       ...(challenge ? {
         pid: process.pid,
-        proof: identityProof(challenge, { role: 'gateway', port: PORT, pid: process.pid }, ADMIN_TOKEN.toString())
+        proof: identityProof(challenge, { role: 'gateway', port: PORT, pid: process.pid }, ADMIN_TOKEN.toString()),
+        // The only proof agy-relay.mjs accepts: its key is not on the dashboard page.
+        relayProof: relayProof(challenge, { port: PORT, pid: process.pid })
       } : {}),
       port: PORT,
       configLoaded: Boolean(loadConfig()),
@@ -2262,7 +2265,7 @@ if (!handedOver) server.listen(PORT, '127.0.0.1', () => {
     serialized(() => reconcile(cfg));
   }
   console.log(`[llm-switcher] Server running on http://127.0.0.1:${PORT}`);
-  console.log(`[llm-switcher] Web UI available at: http://127.0.0.1:${PORT}/ui`);
+  console.log(`[llm-switcher] Web UI available at: http://127.0.0.1:${PORT}/ui (open it with \`switch ui\`)`);
   console.log(`[llm-switcher] Endpoints: /v1/messages (Claude Code) | /v1/responses (Codex)`);
   // Asynchronously discover latest tool models in the background without blocking startup
   refreshCatalog(STATE_DIR).catch(() => {});

package/shim.mjs

@@ -40,6 +40,9 @@ const ROUTE_NOTIFIER = path.join(path.dirname(fileURLToPath(import.meta.url)), '
 // agy sends its Google token in clear text to CLOUD_CODE_URL. Its shim asks this helper for the
 // gateway's identity proof first, so a process that took the port never receives the token.
 const GATEWAY_CHECK = path.join(path.dirname(fileURLToPath(import.meta.url)), 'verify-gateway.mjs');
+// The launch check covers the start only. A routed agy then runs behind this relay, which proves
+// the gateway on every connection, so a port freed later never receives the token.
+const AGY_RELAY = path.join(path.dirname(fileURLToPath(import.meta.url)), 'agy-relay.mjs');
 
 // CLIs to wrap. `claude` is the most important case (--resume); codex and agy have their own files.
 export const SHIMMED = ['claude', 'codex', 'agy'];
@@ -191,6 +194,13 @@ if [ -z "$REAL" ]; then
   exit 127
 fi
 
+${name !== 'agy' ? '' : `# A routed agy talks only to its relay, which lives as long as agy (agy-relay.mjs).
+if [ "$TOOL_ACTIVE" = "1" ] && [ -n "\${CLOUD_CODE_URL:-}" ]; then
+  GATEWAY_URL="$CLOUD_CODE_URL"
+  unset CLOUD_CODE_URL
+  exec node "${AGY_RELAY}" "$GATEWAY_URL" "$REAL" "$@"
+fi
+`}
 # No override of any kind: the tool keeps its own configuration and its own model names (F3, R1).
 exec "$REAL" "$@"
 `;
@@ -266,14 +276,26 @@ for /f "tokens=1 delims==" %%V in ('set LLM_SWITCHER_CODEX_ 2^>nul ^| findstr /b
 ${caBlock}
 
 REM Find the real binary: drop this shim's own directory so it never calls itself.
-for /f "delims=" %%i in ('where ${name}.cmd 2^>nul ^| findstr /v /i "\\.llm-switcher\\\\bin"') do (
+${name === 'agy' ? `set "REAL_BIN="
+for /f "delims=" %%i in ('where ${name}.cmd 2^>nul ^| findstr /v /i "\\.llm-switcher\\\\bin"') do if not defined REAL_BIN set "REAL_BIN=%%i"
+if not defined REAL_BIN for /f "delims=" %%i in ('where ${name}.exe 2^>nul ^| findstr /v /i "\\.llm-switcher\\\\bin"') do if not defined REAL_BIN set "REAL_BIN=%%i"
+if not defined REAL_BIN goto :NOT_FOUND
+REM A routed agy talks only to its relay, which lives as long as agy (agy-relay.mjs).
+if not "%TOOL_ACTIVE%"=="1" goto :RUN_PLAIN
+if not defined CLOUD_CODE_URL goto :RUN_PLAIN
+node "${AGY_RELAY}" "%CLOUD_CODE_URL%" "%REAL_BIN%" %*
+exit /b
+:RUN_PLAIN
+call "%REAL_BIN%" %*
+exit /b
+:NOT_FOUND` : `for /f "delims=" %%i in ('where ${name}.cmd 2^>nul ^| findstr /v /i "\\.llm-switcher\\\\bin"') do (
   call "%%i" %*
   exit /b
 )
 for /f "delims=" %%i in ('where ${name}.exe 2^>nul ^| findstr /v /i "\\.llm-switcher\\\\bin"') do (
   call "%%i" %*
   exit /b
-)
+)`}
 echo [llm-switcher] cannot find the real '${name}' on PATH.>&2
 exit /b 127
 

package/state.mjs

@@ -107,6 +107,38 @@ export function ensureAdminToken() {
   return token;
 }
 
+// The key of the proof that agy-relay.mjs checks. Random, never derived from admin.token: the
+// dashboard page carries admin.token, so a proof keyed by it can be made by anyone who loads /ui.
+export const gatewaySecretPath = path.join(path.dirname(configPath), 'gateway.secret');
+
+export function readGatewaySecret() {
+  try {
+    return fs.readFileSync(gatewaySecretPath, 'utf8').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+// A good secret is kept. A missing, empty or blank file is replaced through a rename, so a damaged
+// file never leaves agy without a key. Throws when it cannot write; never leaves a temporary file.
+export function ensureGatewaySecret() {
+  if (readGatewaySecret()) return;
+  const tmp = `${gatewaySecretPath}.${process.pid}.tmp`;
+  try {
+    fs.rmSync(tmp, { force: true });
+    fs.writeFileSync(tmp, crypto.randomBytes(32).toString('hex'), { mode: 0o600, flag: 'wx' });
+    fs.renameSync(tmp, gatewaySecretPath);
+  } catch (err) {
+    try { fs.rmSync(tmp, { force: true }); } catch {}
+    throw err;
+  }
+}
+
+export function relayProof(nonce, { port, pid }, secret = readGatewaySecret()) {
+  if (!secret) return '';
+  return crypto.createHmac('sha256', secret).update(['relay', port, pid, nonce].join('|')).digest('hex');
+}
+
 // `switch ui` must not put the token on a command line: /proc/<pid>/cmdline is readable by every
 // account. It opens this private file instead, which redirects to the dashboard with the token.
 export function writeDashboardLauncher(url) {

package/switch.mjs

@@ -232,8 +232,8 @@ async function stopProxy(port) {
   };
   // Our own unit needs no identity proof: its manager stops it. That also covers a unit that is
   // still starting (the port is free) and a hung gateway under the unit (the probe is silent).
-  const svc = installedService();
-  const ownUnit = svc && [port, null].includes(servicePort(svc));
+  const svc = serviceForPort(port);
+  const ownUnit = Boolean(svc);
   if (state === 'free') {
     if (!ownUnit) return 'not-running';
     serviceStop(svc);
@@ -271,7 +271,7 @@ async function changePort(newPortStr) {
   // Refuse before anything stops: the old gateway keeps running when the new port is taken.
   const target = await probeGateway(p);
   if (isHeld(target)) refuseForeignPort(p, 'this switcher', target);
-  const svc = installedService();
+  const svc = serviceForPort(oldPort);
   // The unit is rewritten below. It keeps the choice that `service install --no-autoupdate` made.
   const svcText = svc ? serviceText(svc) : null;
   const autoupdate = svcText === null || autoupdateFromServiceText(svcText);
@@ -616,7 +616,7 @@ async function showStatus() {
   console.log('=== LLM Switcher Status ===');
   const held = { legacy: `OLD GATEWAY (< 1.1.1) ON PORT ${port}: stop it, then run \`switch on\``, foreign: `PORT ${port} HELD BY ANOTHER PROCESS`, silent: `PORT ${port} DOES NOT ANSWER (hung gateway or another program)` };
   console.log(`Proxy Service:  ${isRunning ? `RUNNING (port ${port})` : held[gateway] || 'STOPPED'}`);
-  console.log(`Web UI:         http://127.0.0.1:${port}/ui`);
+  console.log(`Web UI:         http://127.0.0.1:${port}/ui  (open it with \`switch ui\`)`);
   console.log(`Launcher Flag:  ${flagged ? 'active.flag present' : 'absent (launchers use official endpoints)'}`);
   if (flagged && !isRunning) {
     console.log(`[WARN] active.flag exists but proxy is STOPPED -> launched CLIs will fail to connect. Run 'switch on' or 'switch off'.`);
@@ -688,6 +688,13 @@ function servicePort(kind) {
   return text === null ? null : portFromServiceText(text);
 }
 
+// The installed service runs the gateway of the port its definition names. A second instance
+// (LLM_SWITCHER_PORT) must never stop or rewrite it. A definition with no readable port counts.
+function serviceForPort(port) {
+  const svc = installedService();
+  return svc && [port, null].includes(servicePort(svc)) ? svc : null;
+}
+
 function reportBackup(backup) {
   if (backup) console.log(`[Service] The previous definition differed and is kept as ${backup}.`);
 }