@tonyclaw/agent-inspector 2.1.24 → 3.0.1

package/.output/server/index.mjs

@@ -38,114 +38,114 @@ const assets = {
   "/assets/alibaba-TTwafVwX.svg": {
     "type": "image/svg+xml",
     "etag": '"171b-6dyV5K8QjiaY35sN9qNprh9zDIs"',
-    "mtime": "2026-07-06T23:47:30.045Z",
+    "mtime": "2026-07-07T00:47:56.086Z",
     "size": 5915,
     "path": "../public/assets/alibaba-TTwafVwX.svg"
   },
-  "/assets/index-CUKpd9jb.js": {
+  "/assets/CompareDrawer-BgcAk1te.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"74-S5coP0OJAkI32YF22K1A7pIhhaQ"',
-    "mtime": "2026-07-06T23:47:30.045Z",
-    "size": 116,
-    "path": "../public/assets/index-CUKpd9jb.js"
+    "etag": '"4bbf-gA9nBXsloTEIMhmM3ql/4qNmhOs"',
+    "mtime": "2026-07-07T00:47:56.086Z",
+    "size": 19391,
+    "path": "../public/assets/CompareDrawer-BgcAk1te.js"
   },
-  "/assets/json-viewer-CWxF2eLV.js": {
+  "/assets/index-DXR7RB48.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"1ae6-W5gyZM3eWBF1xbeKMyl4smbFfEM"',
-    "mtime": "2026-07-06T23:47:30.047Z",
-    "size": 6886,
-    "path": "../public/assets/json-viewer-CWxF2eLV.js"
+    "etag": '"1cd2c-3SEnnZb993yst8Dzg9UbKuoON3A"',
+    "mtime": "2026-07-07T00:47:56.086Z",
+    "size": 118060,
+    "path": "../public/assets/index-DXR7RB48.js"
   },
-  "/assets/CompareDrawer-DsHSCHSx.js": {
+  "/assets/json-viewer-CiMN_9sG.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"4bbf-nlyV9TgErKS/2wxRBsjCrr8IQBo"',
-    "mtime": "2026-07-06T23:47:30.047Z",
-    "size": 19391,
-    "path": "../public/assets/CompareDrawer-DsHSCHSx.js"
+    "etag": '"1ae6-uMTpz3tfSXntmUuk5MzHyqBxhWI"',
+    "mtime": "2026-07-07T00:47:56.086Z",
+    "size": 6886,
+    "path": "../public/assets/json-viewer-CiMN_9sG.js"
   },
   "/assets/index-Tq5s9NV0.css": {
     "type": "text/css; charset=utf-8",
     "etag": '"22408-MQKT02eqQudVEj/DozyiEJoTl6E"',
-    "mtime": "2026-07-06T23:47:30.045Z",
+    "mtime": "2026-07-07T00:47:56.086Z",
     "size": 140296,
     "path": "../public/assets/index-Tq5s9NV0.css"
   },
   "/assets/minimax-BPMzvuL-.jpeg": {
     "type": "image/jpeg",
     "etag": '"1b06-IwivU89ko5UTMUM1/t7hn4sQK9A"',
-    "mtime": "2026-07-06T23:47:30.042Z",
+    "mtime": "2026-07-07T00:47:56.084Z",
     "size": 6918,
     "path": "../public/assets/minimax-BPMzvuL-.jpeg"
   },
-  "/assets/RequestAnatomy-BG5mb14k.js": {
+  "/assets/index-MfTE52Ty.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"43f2-5+JmeO4mEgbfXx4qZ0z/5j/kGC0"',
-    "mtime": "2026-07-06T23:47:30.047Z",
-    "size": 17394,
-    "path": "../public/assets/RequestAnatomy-BG5mb14k.js"
+    "etag": '"74-xI8cgjppS3YpgGFVqBj/+DUVe/4"',
+    "mtime": "2026-07-07T00:47:56.086Z",
+    "size": 116,
+    "path": "../public/assets/index-MfTE52Ty.js"
+  },
+  "/assets/ReplayDialog-7Pvhjbjk.js": {
+    "type": "text/javascript; charset=utf-8",
+    "etag": '"31d6-WfysEtvfuOApCBk5olHqKk8rMfU"',
+    "mtime": "2026-07-07T00:47:56.086Z",
+    "size": 12758,
+    "path": "../public/assets/ReplayDialog-7Pvhjbjk.js"
   },
-  "/assets/StreamingChunkSequence-BeqKXAS6.js": {
+  "/assets/main-Ba9x64uY.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"dd6-+UuLiAyXfMce8K34YDVdE2+W+dQ"',
-    "mtime": "2026-07-06T23:47:30.047Z",
+    "etag": '"512fd-xrDcMUYYndBJtS06eXJ9QM25lz4"',
+    "mtime": "2026-07-07T00:47:56.086Z",
+    "size": 332541,
+    "path": "../public/assets/main-Ba9x64uY.js"
+  },
+  "/assets/StreamingChunkSequence-DzXzVtBF.js": {
+    "type": "text/javascript; charset=utf-8",
+    "etag": '"dd6-FSNaNigsd1X+gyqALfVxeG2s4fo"',
+    "mtime": "2026-07-07T00:47:56.086Z",
     "size": 3542,
-    "path": "../public/assets/StreamingChunkSequence-BeqKXAS6.js"
+    "path": "../public/assets/StreamingChunkSequence-DzXzVtBF.js"
   },
   "/assets/zhipuai-BPNAnxo-.svg": {
     "type": "image/svg+xml",
     "etag": '"2bf8-hNaLCTi89nOFCsIIfWpP/jrfo0s"',
-    "mtime": "2026-07-06T23:47:30.045Z",
+    "mtime": "2026-07-07T00:47:56.086Z",
     "size": 11256,
     "path": "../public/assets/zhipuai-BPNAnxo-.svg"
   },
-  "/assets/main-BDfcCp_1.js": {
-    "type": "text/javascript; charset=utf-8",
-    "etag": '"512fd-wNI+QxyzwhA/0QqJbbcpb3MMxmg"',
-    "mtime": "2026-07-06T23:47:30.047Z",
-    "size": 332541,
-    "path": "../public/assets/main-BDfcCp_1.js"
-  },
-  "/assets/ReplayDialog-D0ixqStX.js": {
+  "/assets/RequestAnatomy-BX-UKYQg.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"31d6-kYb7AI9zYbXu6Y118c89CIIKsQk"',
-    "mtime": "2026-07-06T23:47:30.047Z",
-    "size": 12758,
-    "path": "../public/assets/ReplayDialog-D0ixqStX.js"
+    "etag": '"43f2-Zq3l43VsakNoYmpaf2yidbFacQg"',
+    "mtime": "2026-07-07T00:47:56.086Z",
+    "size": 17394,
+    "path": "../public/assets/RequestAnatomy-BX-UKYQg.js"
   },
-  "/assets/ResponseView-Bgns6xum.js": {
+  "/assets/ResponseView-zFxGX8xH.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"47fa-9tCNwF7F78L1zRC3UidiQKud7L8"',
-    "mtime": "2026-07-06T23:47:30.047Z",
+    "etag": '"47fa-7HB1lxdpkTuo7BEzpS+JAr6zRjM"',
+    "mtime": "2026-07-07T00:47:56.086Z",
     "size": 18426,
-    "path": "../public/assets/ResponseView-Bgns6xum.js"
+    "path": "../public/assets/ResponseView-zFxGX8xH.js"
   },
-  "/assets/_sessionId-Nme0kuTf.js": {
+  "/assets/_sessionId-CmsUOEIS.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"36c-gpP2xqLaqXgb4GOWSbhVDrqjv3g"',
-    "mtime": "2026-07-06T23:47:30.045Z",
+    "etag": '"36c-oBFmeA36vW57pay3tX7/Tm7ZnGI"',
+    "mtime": "2026-07-07T00:47:56.086Z",
     "size": 876,
-    "path": "../public/assets/_sessionId-Nme0kuTf.js"
+    "path": "../public/assets/_sessionId-CmsUOEIS.js"
   },
   "/assets/qwen-CONDcHqt.png": {
     "type": "image/png",
     "etag": '"572c3-cdJAPaHdOvFCGzuaQjagdgOu6XE"',
-    "mtime": "2026-07-06T23:47:30.045Z",
+    "mtime": "2026-07-07T00:47:56.086Z",
     "size": 357059,
     "path": "../public/assets/qwen-CONDcHqt.png"
   },
-  "/assets/index-hbDdeKtc.js": {
-    "type": "text/javascript; charset=utf-8",
-    "etag": '"1cd2c-o4cSL+ZBVABZPPb9xrCnibEnQQQ"',
-    "mtime": "2026-07-06T23:47:30.047Z",
-    "size": 118060,
-    "path": "../public/assets/index-hbDdeKtc.js"
-  },
-  "/assets/ProxyViewerContainer-GI3xErl5.js": {
+  "/assets/ProxyViewerContainer-7b_uwvT7.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"aef16-1fUWo2IWu+2OgSdsAPCGVYmzUNU"',
-    "mtime": "2026-07-06T23:47:30.047Z",
-    "size": 716566,
-    "path": "../public/assets/ProxyViewerContainer-GI3xErl5.js"
+    "etag": '"aef11-9vtbsodrImAt3S4nrgSZgSQRdnc"',
+    "mtime": "2026-07-07T00:47:56.086Z",
+    "size": 716561,
+    "path": "../public/assets/ProxyViewerContainer-7b_uwvT7.js"
   }
 };
 function readAsset(id) {

package/README.md

@@ -62,13 +62,13 @@ The onboarding command installs guided setup skills for local agents:
 
 - Claude Code: `~/.claude/skills/agent-inspector-onboard/SKILL.md` plus a slash command.
 - Codex: `~/.codex/skills/agent-inspector-onboard/SKILL.md`, focused on connecting
-  `http://localhost:25947/api/mcp` through Codex `mcp_servers.agent-inspector`.
+  `http://localhost:9527/api/mcp` through Codex `mcp_servers.agent-inspector`.
 - OpenCode: run `agent-inspector onboard --opencode-only` to merge
   `mcp.agent-inspector` into `~/.config/opencode/opencode.json` or `opencode.jsonc`, then verify
   with `opencode mcp list`.
 - MiMo Code: run `agent-inspector onboard --mimo-only` to merge `mcp.agent-inspector` into
   `~/.config/mimocode/mimocode.jsonc` or `mimocode.json`, then route MiMo through the proxy with
-  `OPENAI_BASE_URL=http://localhost:25947/proxy`.
+  `OPENAI_BASE_URL=http://localhost:9527/proxy`.
 
 During npm global install, Agent Inspector also makes a best-effort onboarding skill install for
 detected local agents. If `~/.claude` exists, it installs the Claude Code skill and slash command.
@@ -123,20 +123,39 @@ agent-inspector doctor --chrome-extension
 Then point an AI coding tool at the proxy:
 
 ```bash
-ANTHROPIC_BASE_URL=http://localhost:25947/proxy <tool>
+ANTHROPIC_BASE_URL=http://localhost:9527/proxy <tool>
 ```
 
-The web UI runs at http://localhost:25947. The public proxy endpoint is also
-`http://localhost:25947/proxy`; internally Agent Inspector may run the app on a private helper port,
+The web UI runs at http://localhost:9527. The public proxy endpoint is also
+`http://localhost:9527/proxy`; internally Agent Inspector may run the app on a private helper port,
 but AI tools should use the public URL printed by the CLI.
 
+For v3 compatibility, the packaged CLI also keeps `http://localhost:25947` open as a legacy alias
+when it starts on the default port. Existing AI tool and MCP configs that still point at `25947`
+continue to work for now, but new configs should use `9527`.
+
+## v3.0 Port Migration
+
+Agent Inspector v3.0 changes the default public port from `25947` to `9527`. The packaged CLI keeps
+`25947` as a legacy alias when you run the default `agent-inspector` command, so existing AI coding
+tool and MCP configs do not need to be edited immediately.
+
+Use these endpoints for new configs:
+
+- Web UI: `http://localhost:9527`
+- Proxy: `http://localhost:9527/proxy`
+- OpenAI-compatible `/v1` proxy: `http://localhost:9527/proxy/v1`
+- MCP: `http://localhost:9527/api/mcp`
+
+If you intentionally want only the new port, start with `agent-inspector --no-legacy-port`.
+
 For Codex-style OpenAI Responses clients, configure the proxy as an OpenAI-compatible `/v1` base:
 
 ```toml
 model_provider = "agent-inspector"
 
 [model_providers."agent-inspector"]
-base_url = "http://127.0.0.1:25947/proxy/v1"
+base_url = "http://127.0.0.1:9527/proxy/v1"
 wire_api = "responses"
 ```
 
@@ -226,7 +245,7 @@ upstream URL failed.
 Agent Inspector exposes MCP at:
 
 ```text
-http://localhost:25947/api/mcp
+http://localhost:9527/api/mcp
 ```
 
 Coding agents can connect to this MCP surface directly over Streamable HTTP, or through the
@@ -244,10 +263,13 @@ The MCP HTTP surface is also documented as OpenAPI YAML in
 [`docs/mcp-openapi.yaml`](docs/mcp-openapi.yaml).
 
 Use only one transport for the same Inspector instance. If the MCP client supports Streamable HTTP,
-configure `http://localhost:25947/api/mcp` directly. If it only supports stdio, configure
+configure `http://localhost:9527/api/mcp` directly. If it only supports stdio, configure
 `agent-inspector-mcp stdio`; that command is only a bridge to `/api/mcp`, not a second Inspector
 server.
 
+Legacy MCP configs that still use `http://localhost:25947/api/mcp` are accepted by the default v3
+CLI alias during the compatibility window.
+
 Coding agents can use the MCP surface in three ways:
 
 - Tools: perform actions such as listing logs, reading bounded log details, testing providers,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tonyclaw/agent-inspector",
-  "version": "2.1.24",
+  "version": "3.0.1",
   "type": "module",
   "description": "Agent observability and knowledge capture layer for AI coding tools.",
   "license": "MIT",

package/src/cli/doctor.ts

@@ -3,7 +3,7 @@ import { isAbsolute, join, resolve } from "node:path";
 import { createConnection } from "node:net";
 import { migrateLegacyDataDirs, resolveDataDir } from "../proxy/dataDir";
 
-const DEFAULT_PORT = 25947;
+const DEFAULT_PORT = 9527;
 const PROBE_TIMEOUT_MS = 2000;
 const EXTENSION_REQUIRED_FILES = [
   "manifest.json",

package/src/cli/onboard.ts

@@ -35,8 +35,9 @@ import { renderSkillOnboard, REQUIRED_PHASE_HEADINGS } from "./templates/skill-o
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-const DEFAULT_PORT = 25947;
+const DEFAULT_PORT = 9527;
 const DEFAULT_MCP_URL = `http://localhost:${DEFAULT_PORT}/api/mcp`;
+const LEGACY_MCP_URL = "http://localhost:25947/api/mcp";
 const SKILL_DIR_NAME = "agent-inspector-onboard";
 const SKILL_FILE_NAME = "SKILL.md";
 // Windows reserves `:` for NTFS alternate data streams, so a file named
@@ -630,6 +631,10 @@ function stringArrayEquals(value: unknown, expected: readonly string[]): boolean
   return value.every((item, index) => item === expected[index]);
 }
 
+function knownMcpEndpoints(endpoint: string): readonly string[] {
+  return endpoint === DEFAULT_MCP_URL ? [DEFAULT_MCP_URL, LEGACY_MCP_URL] : [endpoint];
+}
+
 function isAgentLocalEntry(value: unknown, endpoint: string, ignoreEnabled: boolean): boolean {
   if (!isObject(value)) {
     return false;
@@ -641,16 +646,14 @@ function isAgentLocalEntry(value: unknown, endpoint: string, ignoreEnabled: bool
   }
 
   const env = value["environment"];
-  const usesUrlArg = stringArrayEquals(value["command"], [
-    "agent-inspector-mcp",
-    "stdio",
-    "--url",
-    endpoint,
-  ]);
+  const endpoints = knownMcpEndpoints(endpoint);
+  const usesUrlArg = endpoints.some((candidate) =>
+    stringArrayEquals(value["command"], ["agent-inspector-mcp", "stdio", "--url", candidate]),
+  );
   const usesEnv =
     stringArrayEquals(value["command"], ["agent-inspector-mcp", "stdio"]) &&
     isObject(env) &&
-    env["AGENT_INSPECTOR_MCP_URL"] === endpoint;
+    endpoints.some((candidate) => env["AGENT_INSPECTOR_MCP_URL"] === candidate);
 
   return value["type"] === "local" && (usesUrlArg || usesEnv);
 }
@@ -665,7 +668,10 @@ function isAgentRemoteEntry(value: unknown, endpoint: string, ignoreEnabled: boo
     return false;
   }
 
-  return value["type"] === "remote" && value["url"] === endpoint;
+  return (
+    value["type"] === "remote" &&
+    knownMcpEndpoints(endpoint).some((candidate) => value["url"] === candidate)
+  );
 }
 
 function isKnownAgentEntry(value: unknown, endpoint: string, ignoreEnabled: boolean): boolean {

package/src/cli.ts

@@ -23,14 +23,13 @@ import { startIdentityProxy } from "./proxy/identityProxy.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-// External-facing port stays at 25947 so existing tooling / AI clients
-// (Claude Code, OpenCode, MiMo Code, etc.) keep working with the
-// unchanged `ANTHROPIC_BASE_URL=http://localhost:25947/proxy`. The
-// identity-injecting proxy listens on that port; the TanStack Start
-// upstream is moved to a private port (25949 by default) and reverse-
-// proxied through.
-const DEFAULT_PORT = 25947;
-const DEFAULT_UPSTREAM_PORT = 25949;
+// v3 defaults the public entrypoint to 9527 while keeping 25947 as a
+// compatibility alias for older AI-tool and MCP configs. The TanStack Start
+// runtime stays on a private upstream port and both public ports reverse-proxy
+// to that same runtime, so logs, sessions, and MCP state remain unified.
+const DEFAULT_PORT = 9527;
+const LEGACY_ALIAS_PORT = 25947;
+const DEFAULT_UPSTREAM_PORT = 9529;
 const LOCAL_PROBE_TIMEOUT_MS = 2000;
 const BRANDED_WINDOWS_RUNTIME_EXE = "agent-inspector.exe";
 const DEFAULT_CAPTURE_MODE = "simple";
@@ -159,6 +158,10 @@ function openBrowser(targetUrl: string): void {
     detached: true,
     windowsHide: true,
   });
+  browserProcess.once("error", () => {
+    // Opening a browser is best-effort. Minimal Linux/container images may not
+    // include xdg-open, and that should not make the CLI look unhealthy.
+  });
   browserProcess.unref();
 }
 
@@ -244,6 +247,26 @@ function printAccessHints(port: number, host?: string): void {
   }
 }
 
+function pickUpstreamPort(publicPort: number, legacyAliasPort: number | null): number {
+  const candidates = [
+    DEFAULT_UPSTREAM_PORT,
+    publicPort + 2 <= 65535 ? publicPort + 2 : publicPort - 2,
+    LEGACY_ALIAS_PORT + 2,
+  ];
+  for (const candidate of candidates) {
+    if (
+      Number.isInteger(candidate) &&
+      candidate > 0 &&
+      candidate <= 65535 &&
+      candidate !== publicPort &&
+      candidate !== legacyAliasPort
+    ) {
+      return candidate;
+    }
+  }
+  return DEFAULT_UPSTREAM_PORT;
+}
+
 /** Try to start the identity proxy. Returns `null` (and prints a warning)
  *  if the listen port is already in use by another process — e.g. when
  *  restarting a previous instance that didn't shut down cleanly. The
@@ -273,7 +296,7 @@ async function tryStartIdentityProxy(
 }
 
 async function runStart(args: string[]): Promise<void> {
-  const envPort = process.env["PORT"];
+  const envPort = process.env["AGENT_INSPECTOR_PORT"] ?? process.env["PORT"];
   const portDefault = envPort !== undefined ? Number(envPort) : DEFAULT_PORT;
   const envHost = process.env["NITRO_HOST"] ?? process.env["HOST"];
   const envMode =
@@ -290,10 +313,7 @@ async function runStart(args: string[]): Promise<void> {
   let captureMode = DEFAULT_CAPTURE_MODE;
   let captureModeWasSpecified = false;
   let enableIdentityProxy = true;
-  let identityProxyPort =
-    process.env["AGENT_INSPECTOR_PORT"] !== undefined
-      ? Number(process.env["AGENT_INSPECTOR_PORT"])
-      : DEFAULT_PORT;
+  let legacyAliasEnabled = true;
 
   if (envMode !== undefined && envMode !== "") {
     const parsedMode = parseCaptureMode(envMode);
@@ -402,10 +422,13 @@ async function runStart(args: string[]): Promise<void> {
           process.exitCode = 1;
           return;
         }
-        identityProxyPort = parsed;
+        port = parsed;
         i++;
         break;
       }
+      case "--no-legacy-port":
+        legacyAliasEnabled = false;
+        break;
       default:
         break;
     }
@@ -489,11 +512,13 @@ async function runStart(args: string[]): Promise<void> {
     }
   }
 
-  // TanStack Start listens on the private upstream port; the identity
-  // proxy owns the public-facing `port`. When the identity proxy is
-  // disabled (or not yet running) we fall back to TanStack listening on
-  // the public port directly.
-  const upstreamPort = enableIdentityProxy ? DEFAULT_UPSTREAM_PORT : port;
+  const legacyAliasPort =
+    enableIdentityProxy && legacyAliasEnabled && port === DEFAULT_PORT ? LEGACY_ALIAS_PORT : null;
+
+  // TanStack Start listens on the private upstream port; identity proxies own
+  // the public-facing port(s). When the identity proxy is disabled we fall
+  // back to TanStack listening on the public port directly.
+  const upstreamPort = enableIdentityProxy ? pickUpstreamPort(port, legacyAliasPort) : port;
   process.env["PORT"] = String(upstreamPort);
 
   const url = urlForHost(port, host);
@@ -526,8 +551,8 @@ async function runStart(args: string[]): Promise<void> {
     const restartPorts = new Set<number>();
     restartPorts.add(port);
     if (enableIdentityProxy) {
-      restartPorts.add(identityProxyPort);
       restartPorts.add(upstreamPort);
+      if (legacyAliasPort !== null) restartPorts.add(legacyAliasPort);
     }
     for (const targetPort of restartPorts) {
       killProcessOnPort(targetPort);
@@ -538,6 +563,11 @@ async function runStart(args: string[]): Promise<void> {
   console.log(`   Capture mode: ${captureMode}`);
   console.log(`   Proxy: ${url}/proxy`);
   printAccessHints(port, host);
+  if (legacyAliasPort !== null) {
+    console.log(`   Legacy UI:      http://localhost:${legacyAliasPort}`);
+    console.log(`   Legacy proxy:   http://localhost:${legacyAliasPort}/proxy`);
+    console.log(`   Legacy MCP:     http://localhost:${legacyAliasPort}/api/mcp`);
+  }
   console.log(``);
   console.log(`Route AI coding tools through the proxy:`);
   console.log(`   Claude Code:  ANTHROPIC_BASE_URL=${url}/proxy claude`);
@@ -594,6 +624,8 @@ async function runStart(args: string[]): Promise<void> {
     serverEnv["HOST"] = host;
     serverEnv["NITRO_HOST"] = host;
   }
+  serverEnv["AGENT_INSPECTOR_PUBLIC_PORT"] = String(port);
+  serverEnv["PROXY_PORT"] = String(port);
   serverEnv["AGENT_INSPECTOR_CAPTURE_MODE"] = captureMode;
   const serverProcess = spawn(serverCommand.command, serverCommand.args, {
     stdio: background ? ["ignore", "ignore", "ignore"] : ["ignore", "pipe", "pipe"],
@@ -601,6 +633,10 @@ async function runStart(args: string[]): Promise<void> {
     env: serverEnv,
     windowsHide: background,
   });
+  serverProcess.once("error", (err) => {
+    console.error(`Failed to start Agent Inspector runtime: ${err.message}`);
+  });
+  const serverExit = waitForProcessExit(serverProcess);
   if (!background) {
     pipeServerOutput(serverProcess, {
       enableIdentityProxy,
@@ -615,9 +651,23 @@ async function runStart(args: string[]): Promise<void> {
   // This lets AI tools (which can't easily set those headers themselves)
   // still get accurate session attribution. Started only after TanStack
   // Start is healthy, so the upstream is ready by the time clients connect.
-  const identityProxy = enableIdentityProxy
-    ? await tryStartIdentityProxy(identityProxyPort, upstreamPort, host)
-    : null;
+  const identityProxies: Array<{
+    label: "primary" | "legacy";
+    port: number;
+    server: import("node:http").Server;
+  }> = [];
+  if (enableIdentityProxy) {
+    const primaryProxy = await tryStartIdentityProxy(port, upstreamPort, host);
+    if (primaryProxy !== null) {
+      identityProxies.push({ label: "primary", port, server: primaryProxy });
+    }
+    if (legacyAliasPort !== null) {
+      const legacyProxy = await tryStartIdentityProxy(legacyAliasPort, upstreamPort, host);
+      if (legacyProxy !== null) {
+        identityProxies.push({ label: "legacy", port: legacyAliasPort, server: legacyProxy });
+      }
+    }
+  }
 
   if (background) {
     serverProcess.unref();
@@ -625,18 +675,24 @@ async function runStart(args: string[]): Promise<void> {
     // not started yet so the public port is not yet accepting traffic.
     if (await waitForInspectorHealthy(upstreamPort, 5000, host)) {
       console.log(`agent-inspector background server is ready at ${url}`);
-      if (identityProxy !== null) {
-        console.log(`Identity proxy ready on port ${identityProxyPort} (PID-attributing proxy).`);
+      if (identityProxies.length > 0) {
+        console.log(`Identity proxy ready on port ${port} (PID-attributing proxy).`);
       }
       printAccessHints(port, host);
-      if (identityProxy !== null) {
+      if (legacyAliasPort !== null) {
+        console.log(`   Legacy proxy:  http://localhost:${legacyAliasPort}/proxy`);
+        console.log(`   Legacy MCP:    http://localhost:${legacyAliasPort}/api/mcp`);
+      }
+      if (identityProxies.length > 0) {
         console.log(
           ``,
           `Route AI coding tools through the identity proxy for accurate PID attribution:`,
-          `   Claude Code:  ANTHROPIC_BASE_URL=http://localhost:${identityProxyPort}/proxy claude`,
-          `   OpenCode:     LLM_BASE_URL=http://localhost:${identityProxyPort}/proxy opencode`,
-          `   MiMo Code:    OPENAI_BASE_URL=http://localhost:${identityProxyPort}/proxy mimo`,
-          `   (Direct ${port} still works; it falls back to OS-scan heuristic.)`,
+          `   Claude Code:  ANTHROPIC_BASE_URL=http://localhost:${port}/proxy claude`,
+          `   OpenCode:     LLM_BASE_URL=http://localhost:${port}/proxy opencode`,
+          `   MiMo Code:    OPENAI_BASE_URL=http://localhost:${port}/proxy mimo`,
+          legacyAliasPort === null
+            ? `   Override the port with --port <n> when needed.`
+            : `   Legacy configs using http://localhost:${legacyAliasPort}/proxy still work.`,
         );
       }
       return;
@@ -646,17 +702,23 @@ async function runStart(args: string[]): Promise<void> {
     return;
   }
 
-  if (identityProxy !== null) {
+  if (identityProxies.length > 0) {
     console.log(``);
     console.log(`Identity proxy ready at ${url} (PID-attributing public entrypoint).`);
+    if (legacyAliasPort !== null) {
+      const legacyReady = identityProxies.some((proxy) => proxy.label === "legacy");
+      if (legacyReady) {
+        console.log(`   Legacy alias ready at http://localhost:${legacyAliasPort}.`);
+      }
+    }
     if (upstreamPort !== port) {
       console.log(`   Internal runtime port ${upstreamPort} is hidden behind the public proxy.`);
     }
   }
 
-  process.exitCode = await waitForProcessExit(serverProcess);
+  process.exitCode = await serverExit;
 
-  if (identityProxy !== null) {
-    await new Promise<void>((resolve) => identityProxy.close(() => resolve()));
+  for (const proxy of identityProxies) {
+    await new Promise<void>((resolve) => proxy.server.close(() => resolve()));
   }
 }

package/src/components/ProxyViewer.tsx

@@ -2143,8 +2143,8 @@ export function ProxyViewer({
                   <div className="bg-white/[0.035] shadow-[inset_0_1px_0_rgba(255,255,255,0.045),0_18px_52px_rgba(0,0,0,0.18)] mx-auto max-w-2xl space-y-4 rounded-[8px] px-4 py-8">
                     <p className="text-sm">No requests captured yet.</p>
                     <div className="flex flex-col items-center gap-2">
-                      <CopyableCommand command="ANTHROPIC_BASE_URL=http://localhost:25947/proxy <your-tool>" />
-                      <CopyableCommand command="OPENAI_BASE_URL=http://localhost:25947/proxy <your-tool>" />
+                      <CopyableCommand command="ANTHROPIC_BASE_URL=http://localhost:9527/proxy <your-tool>" />
+                      <CopyableCommand command="OPENAI_BASE_URL=http://localhost:9527/proxy <your-tool>" />
                     </div>
                     <p className="mx-auto max-w-xl text-xs leading-relaxed text-muted-foreground">
                       Container note: if your AI tool runs in a different container or host than

package/src/components/providers/SettingsDialog.tsx

@@ -303,7 +303,7 @@ function CopyableSetupValue({
 function OnboardingSettingsTab(): JSX.Element {
   const [copiedId, setCopiedId] = useState<string | null>(null);
   const origin = useMemo(() => {
-    if (typeof window === "undefined") return "http://localhost:25947";
+    if (typeof window === "undefined") return "http://localhost:9527";
     return window.location.origin;
   }, []);
   const values = useMemo(
@@ -454,7 +454,7 @@ function OnboardingSettingsTab(): JSX.Element {
 function McpSettingsTab(): JSX.Element {
   const [copiedId, setCopiedId] = useState<string | null>(null);
   const origin = useMemo(() => {
-    if (typeof window === "undefined") return "http://localhost:25947";
+    if (typeof window === "undefined") return "http://localhost:9527";
     return window.location.origin;
   }, []);
   const endpoint = `${origin}/api/mcp`;

package/src/lib/serverPort.ts

@@ -7,9 +7,10 @@
  * Initialization order:
  *   1. `setCurrentPort(port)` — explicit override (used by tests, or any
  *      code that has direct knowledge of the bound port).
- *   2. `process.env.PORT` — fallback. The CLI (`src/cli.ts`) sets this
- *      before spawning the server process, so in normal operation this
- *      branch is taken and no explicit `setCurrentPort` call is needed.
+ *   2. `process.env.AGENT_INSPECTOR_PUBLIC_PORT` — the public identity-proxy
+ *      port. The CLI sets this when the runtime is hidden behind a private
+ *      upstream port.
+ *   3. `process.env.PORT` — fallback for direct dev/server runs.
  *
  * `getCurrentPort()` throws if neither source is available.
  */
@@ -25,6 +26,11 @@ export function setCurrentPort(port: number): void {
 
 export function getCurrentPort(): number {
   if (overridePort !== null) return overridePort;
+  const publicPort = process.env["AGENT_INSPECTOR_PUBLIC_PORT"];
+  if (publicPort !== undefined && publicPort !== "") {
+    const n = Number(publicPort);
+    if (Number.isInteger(n) && n > 0 && n <= 65535) return n;
+  }
   const envPort = process.env["PORT"];
   if (envPort !== undefined && envPort !== "") {
     const n = Number(envPort);