@tonyclaw/agent-inspector 3.0.45 → 3.0.46

package/src/{routes → backend/routes}/api/providers.$providerId.test.log.ts

@@ -1,17 +1,17 @@
 import { createFileRoute } from "@tanstack/react-router";
 import { basename } from "node:path";
-import { getProvider, getModelUsageName } from "../../proxy/providers";
-import { addTestLogEntry } from "../../proxy/store";
-import { getConfig } from "../../proxy/config";
-import { buildProviderTestSessionId } from "../../proxy/sessionSupervisor";
-import { buildProviderTestRequestBody } from "../../lib/providerTestPrompt";
+import { getProvider, getModelUsageName } from "../../../proxy/providers";
+import { addTestLogEntry } from "../../../proxy/store";
+import { getConfig } from "../../../proxy/config";
+import { buildProviderTestSessionId } from "../../../proxy/sessionSupervisor";
+import { buildProviderTestRequestBody } from "../../../lib/providerTestPrompt";
 import {
   ProviderTestResultsSchema,
   type ProviderModelTestResults,
   type ProviderTestResult as TestResult,
   type ProviderTestState,
-} from "../../lib/providerTestContract";
-import { computeTokensPerSecond, firstChunkMsFromChunks } from "../../proxy/streamTiming";
+} from "../../../lib/providerTestContract";
+import { computeTokensPerSecond, firstChunkMsFromChunks } from "../../../proxy/streamTiming";
 
 function hasSuccessField(result: ProviderTestState): result is TestResult {
   return Object.prototype.hasOwnProperty.call(result, "success");

package/src/{routes → backend/routes}/api/providers.$providerId.ts

@@ -5,15 +5,15 @@ import {
   updateProvider,
   deleteProvider,
   redactProvider,
-} from "../../proxy/providers";
+} from "../../../proxy/providers";
 import {
   getProviderModelLimitViolation,
   ProviderModelMetadataListSchema,
   ProviderModelNameSchema,
   ProviderModelsSchema,
-} from "../../lib/providerContract";
-import { evaluateUpstreamUrl } from "../../lib/ssrfGuard";
-import { resourceLimitResponse } from "../../lib/resourceLimits";
+} from "../../../lib/providerContract";
+import { evaluateUpstreamUrl } from "../../../lib/ssrfGuard";
+import { resourceLimitResponse } from "../../../lib/resourceLimits";
 
 const ALLOW_LOOPBACK = process.env["AGENT_INSPECTOR_ALLOW_LOOPBACK"] === "1";
 

package/src/{routes → backend/routes}/api/providers.export.ts

@@ -1,6 +1,6 @@
 import { createFileRoute } from "@tanstack/react-router";
 import { z } from "zod";
-import { exportProviders, exportProvidersWithKeys } from "../../proxy/providers";
+import { exportProviders, exportProvidersWithKeys } from "../../../proxy/providers";
 
 const SecretExportRequestSchema = z.object({
   confirmation: z.literal("EXPORT_PROVIDER_KEYS"),

package/src/{routes → backend/routes}/api/providers.import.ts

@@ -1,9 +1,9 @@
 import { createFileRoute } from "@tanstack/react-router";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
-import { ProviderScanImportRequestSchema } from "../../lib/providerImportContract";
-import { consumeProviderScan } from "../../proxy/providerScanStore";
-import { importProviders } from "../../proxy/providers";
+import { ProviderScanImportRequestSchema } from "../../../lib/providerImportContract";
+import { consumeProviderScan } from "../../../proxy/providerScanStore";
+import { importProviders } from "../../../proxy/providers";
 
 const ProviderFileImportSchema = z.union([z.string(), z.object({ providers: z.unknown() })]);
 

package/src/{routes → backend/routes}/api/providers.scan.ts

@@ -1,6 +1,6 @@
 import { createFileRoute } from "@tanstack/react-router";
-import { scanExternalProviders } from "../../proxy/providerImporters";
-import { createProviderScan } from "../../proxy/providerScanStore";
+import { scanExternalProviders } from "../../../proxy/providerImporters";
+import { createProviderScan } from "../../../proxy/providerScanStore";
 
 export const Route = createFileRoute("/api/providers/scan")({
   server: {

package/src/{routes → backend/routes}/api/providers.ts

@@ -1,14 +1,19 @@
 import { createFileRoute } from "@tanstack/react-router";
 import { z } from "zod";
-import { getProviders, addProvider, redactProvider, redactProviders } from "../../proxy/providers";
+import {
+  getProviders,
+  addProvider,
+  redactProvider,
+  redactProviders,
+} from "../../../proxy/providers";
 import {
   getProviderModelLimitViolation,
   ProviderModelMetadataListSchema,
   ProviderModelNameSchema,
   ProviderModelsSchema,
-} from "../../lib/providerContract";
-import { evaluateUpstreamUrl } from "../../lib/ssrfGuard";
-import { resourceLimitResponse } from "../../lib/resourceLimits";
+} from "../../../lib/providerContract";
+import { evaluateUpstreamUrl } from "../../../lib/ssrfGuard";
+import { resourceLimitResponse } from "../../../lib/resourceLimits";
 
 const ALLOW_LOOPBACK = process.env["AGENT_INSPECTOR_ALLOW_LOOPBACK"] === "1";
 

package/src/{routes → backend/routes}/api/runs.$runId.evidence.ts

@@ -1,6 +1,6 @@
 import { createFileRoute } from "@tanstack/react-router";
-import { EvidenceExportOptionsSchema } from "../../lib/runContract";
-import { exportInspectorRunEvidence, readInspectorRunEvidence } from "../../services/runs";
+import { EvidenceExportOptionsSchema } from "../../../lib/runContract";
+import { exportInspectorRunEvidence, readInspectorRunEvidence } from "../../../services/runs";
 
 type JsonBodyResult = { ok: true; value: unknown } | { ok: false };
 

package/src/{routes → backend/routes}/api/runs.$runId.ts

@@ -1,6 +1,6 @@
 import { createFileRoute } from "@tanstack/react-router";
-import { UpdateInspectorRunInputSchema } from "../../lib/runContract";
-import { getInspectorRun, updateInspectorRun } from "../../services/runs";
+import { UpdateInspectorRunInputSchema } from "../../../lib/runContract";
+import { getInspectorRun, updateInspectorRun } from "../../../services/runs";
 
 type JsonBodyResult = { ok: true; value: unknown } | { ok: false };
 

package/src/{routes → backend/routes}/api/runs.ts

@@ -1,13 +1,13 @@
 import { createFileRoute } from "@tanstack/react-router";
-import { CreateInspectorRunInputSchema } from "../../lib/runContract";
+import { CreateInspectorRunInputSchema } from "../../../lib/runContract";
 import {
   RECENT_FAILURES_DEFAULT_LIMIT,
   createInspectorRun,
   listInspectorRecentFailures,
   listInspectorRuns,
-} from "../../services/runs";
-import { RECENT_FAILURES_MAX_LIMIT } from "../../proxy/runFailures";
-import { parseBoundedIntegerParameter } from "../../lib/resourceLimits";
+} from "../../../services/runs";
+import { RECENT_FAILURES_MAX_LIMIT } from "../../../proxy/runFailures";
+import { parseBoundedIntegerParameter } from "../../../lib/resourceLimits";
 
 type JsonBodyResult = { ok: true; value: unknown } | { ok: false };
 

package/src/backend/routes/api/runtime.ts

@@ -0,0 +1,46 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { appendBasePathToOrigin } from "../../../lib/basePath";
+import {
+  BROWSER_RUNTIME_SCHEMA_VERSION,
+  type BrowserRuntimeDeployment,
+} from "../../../lib/browserRuntimeContract";
+import { getPublicBasePath, getPublicOrigin } from "../../../lib/publicBasePathContext";
+
+type RuntimeEnvironment = Readonly<Record<string, string | undefined>>;
+
+export const AGENT_INSPECTOR_BACKEND_ONLY_ENV = "AGENT_INSPECTOR_BACKEND_ONLY";
+
+export function runtimeDiscoveryDocument(
+  env: RuntimeEnvironment = process.env,
+): BrowserRuntimeDeployment {
+  const basePath = getPublicBasePath(env);
+  const baseUrl = appendBasePathToOrigin(getPublicOrigin(), "/", basePath);
+
+  return {
+    schemaVersion: BROWSER_RUNTIME_SCHEMA_VERSION,
+    deploymentMode: env[AGENT_INSPECTOR_BACKEND_ONLY_ENV] === "1" ? "backend-only" : "composed",
+    ui: { basePath: basePath.length === 0 ? "/" : basePath },
+    control: { baseUrl },
+    agent: { baseUrl },
+    capabilities: {
+      rest: true,
+      sse: true,
+      proxy: true,
+      mcp: true,
+    },
+  };
+}
+
+export function runtimeDiscoveryResponse(env: RuntimeEnvironment = process.env): Response {
+  return Response.json(runtimeDiscoveryDocument(env), {
+    headers: { "cache-control": "no-store" },
+  });
+}
+
+export const Route = createFileRoute("/api/runtime")({
+  server: {
+    handlers: {
+      GET: () => runtimeDiscoveryResponse(),
+    },
+  },
+});

package/src/{routes → backend/routes}/api/sessions.ts

@@ -1,10 +1,10 @@
 import { createFileRoute } from "@tanstack/react-router";
-import { getSessionInfo, getSessionSnapshots, listSessions } from "../../proxy/store";
+import { getSessionInfo, getSessionSnapshots, listSessions } from "../../../proxy/store";
 import {
   SESSION_INFO_DEFAULT_LATEST_LOG_LIMIT,
   SESSION_INFO_MAX_LATEST_LOG_LIMIT,
-} from "../../proxy/sessionInfo";
-import { parseBoundedIntegerParameter } from "../../lib/resourceLimits";
+} from "../../../proxy/sessionInfo";
+import { parseBoundedIntegerParameter } from "../../../lib/resourceLimits";
 
 function parseBooleanFlag(value: string | null): boolean {
   return value === "1" || value === "true";

package/src/{routes → backend/routes}/proxy/$.ts

@@ -1,5 +1,5 @@
 import { createFileRoute } from "@tanstack/react-router";
-import { handleProxy } from "../../proxy/handler";
+import { handleProxy } from "../../../proxy/handler";
 
 export const Route = createFileRoute("/proxy/$")({
   server: {

package/src/{routes → backend/routes}/readyz.ts

@@ -1,5 +1,5 @@
 import { createFileRoute } from "@tanstack/react-router";
-import { getRuntimeReadiness } from "../proxy/runtimeHealth";
+import { getRuntimeReadiness } from "../../proxy/runtimeHealth";
 
 export async function readinessResponse(): Promise<Response> {
   const readiness = await getRuntimeReadiness();

package/src/{start.ts → backend/start.ts}

@@ -1,7 +1,7 @@
 import { createMiddleware, createStart } from "@tanstack/react-start";
 
 const publicBasePathMiddleware = createMiddleware().server(async ({ next, request }) => {
-  const { runWithRequestPublicBasePath } = await import("./lib/publicBasePathContext");
+  const { runWithRequestPublicBasePath } = await import("../lib/publicBasePathContext");
   return runWithRequestPublicBasePath(request, () => next());
 });
 

package/src/cli/alias.ts

@@ -1,4 +1,4 @@
-import { normalizeBasePath } from "../lib/basePath";
+import { normalizeBasePath, normalizePublicBasePath } from "../lib/basePath";
 
 const DEFAULT_ALIAS_HOST = "localhost";
 const DEFAULT_ALIAS_PORT = 9527;
@@ -67,16 +67,7 @@ function parsePort(raw: string | undefined): number | null {
 }
 
 function normalizeAliasPath(raw: string): string | null {
-  const trimmed = raw.trim();
-  if (
-    !trimmed.startsWith("/") ||
-    trimmed.includes("?") ||
-    trimmed.includes("#") ||
-    trimmed.includes("\\")
-  ) {
-    return null;
-  }
-  return normalizeBasePath(trimmed);
+  return normalizePublicBasePath(raw);
 }
 
 function isValidHost(host: string): boolean {

package/src/cli/doctor.ts

@@ -249,7 +249,7 @@ function checkProviderConfig(options: DoctorOptions, deps: DoctorDeps): DoctorCh
       "Provider config",
       "warn",
       `Provider config exists but no providers were found: ${candidate}`,
-      "Add a provider in Settings or import provider settings.",
+      "Add a provider through the control API/MCP, or use Settings when a UI is available.",
     );
   }
 
@@ -257,29 +257,51 @@ function checkProviderConfig(options: DoctorOptions, deps: DoctorDeps): DoctorCh
     "Provider config",
     "warn",
     "No provider config was found.",
-    "Add a provider in the web UI, import providers, or pass --providers for this check.",
+    "Add a provider through the control API/MCP, use Settings when a UI is available, or pass --providers for this check.",
   );
 }
 
+function publicOriginForDoctor(port: number, env: DoctorDeps["env"]): string {
+  const configured = env["AGENT_INSPECTOR_PUBLIC_ORIGIN"];
+  if (configured !== undefined && configured.trim() === configured) {
+    try {
+      const parsed = new URL(configured);
+      if (
+        (parsed.protocol === "http:" || parsed.protocol === "https:") &&
+        parsed.username.length === 0 &&
+        parsed.password.length === 0 &&
+        parsed.pathname === "/" &&
+        parsed.search.length === 0 &&
+        parsed.hash.length === 0
+      ) {
+        return parsed.origin;
+      }
+    } catch {
+      // Startup reports invalid public-origin configuration; doctor keeps a safe local hint.
+    }
+  }
+  return `http://localhost:${String(port)}`;
+}
+
 async function checkProxyHealth(port: number, deps: DoctorDeps): Promise<DoctorCheck> {
   const basePath = getConfiguredBasePath(deps.env);
   const health = await deps.fetchHealth(port, basePath);
-  const url = `http://localhost:${port}`;
+  const url = publicOriginForDoctor(port, deps.env);
   const proxyUrl = appendBasePathToOrigin(url, "/proxy", basePath);
   const healthPath = appendBasePathToOrigin("", "/api/health", basePath);
   if (health.ok) {
     return check(
-      "Proxy health",
+      "Backend health",
       "pass",
-      `agent-inspector is healthy at ${appendBasePathToOrigin(url, "/", basePath)}.`,
-      `Proxy URL: ${proxyUrl}`,
+      `Agent Inspector backend is healthy at ${appendBasePathToOrigin(url, "/", basePath)}.`,
+      `Agent proxy URL: ${proxyUrl}. UI availability is not part of this backend check.`,
     );
   }
 
   if (await deps.isPortOpen(port)) {
     const suffix = health.status === null ? "" : ` (HTTP ${health.status})`;
     return check(
-      "Proxy health",
+      "Backend health",
       "fail",
       `Port ${port} is accepting connections, but ${healthPath} is not healthy${suffix}.`,
       "Stop that process, choose --port <n>, or start agent-inspector with --force-restart.",
@@ -287,7 +309,7 @@ async function checkProxyHealth(port: number, deps: DoctorDeps): Promise<DoctorC
   }
 
   return check(
-    "Proxy health",
+    "Backend health",
     "warn",
     `No process is listening on port ${port}.`,
     "Start with `agent-inspector`, `agent-inspector --background`, or `bun run dev`.",
@@ -578,7 +600,8 @@ export function doctorHelp(): string {
     "Usage:",
     "  agent-inspector doctor [--port <port>] [--config-dir <dir>] [--providers <json>] [--fix] [--json] [--verbose] [--chrome-extension]",
     "",
-    "Checks local proxy health, provider config presence, and package metadata.",
+    "Checks local backend health, provider config presence, and package metadata.",
+    "The backend check probes the local health endpoint and does not require a composed Web UI.",
     "Pass --fix to run safe local repairs before checks, including legacy data-dir migration.",
     "Pass --json to emit a machine-readable report for CI, scripts, and Jenkins.",
     "Pass --verbose to include local paths, capture mode, and log storage checks.",

package/src/cli/instance.ts

@@ -4,7 +4,7 @@ import {
   AGENT_INSPECTOR_BASE_PATH_ENV,
   appendBasePathToOrigin,
   getConfiguredBasePath,
-  normalizeBasePath,
+  normalizePublicBasePath,
 } from "../lib/basePath";
 import {
   type InstanceConnectionOutput,
@@ -171,6 +171,7 @@ function statusOutput(
     upstreamPort: record.upstreamPort,
     basePath: displayBasePath(record.basePath),
     captureMode: record.captureMode,
+    uiEnabled: record.uiEnabled,
     dataDir: record.dataDir,
     supervisorPid: live.supervisorPid,
     urls: recordUrls(record),
@@ -194,7 +195,16 @@ function connectionOutput(instance: InstanceStatusOutput): InstanceConnectionOut
   const serverName = `agent-inspector-${instance.name}`;
   return {
     schemaVersion: INSTANCE_API_SCHEMA_VERSION,
+    uiEnabled: instance.uiEnabled,
     instance,
+    surfaces: {
+      ui: {
+        enabled: instance.uiEnabled,
+        baseUrl: instance.uiEnabled ? instance.urls.ui : null,
+      },
+      control: { baseUrl: instance.urls.ui },
+      agent: { baseUrl: instance.urls.ui },
+    },
     baseUrl: instance.urls.ui,
     endpoints: instance.urls,
     environment: {
@@ -271,7 +281,7 @@ function defaultOpenUrl(targetUrl: string): void {
   child.unref();
 }
 
-function launchArgs(record: InstanceRecord, open: boolean): string[] {
+export function buildInstanceLaunchArgs(record: InstanceRecord, open: boolean): string[] {
   const args = [
     "--background",
     "--no-open",
@@ -282,7 +292,8 @@ function launchArgs(record: InstanceRecord, open: boolean): string[] {
     "--mode",
     record.captureMode,
   ];
-  if (open) args.push("--open");
+  if (!record.uiEnabled) args.push("--backend-only");
+  if (open && record.uiEnabled) args.push("--open");
   return args;
 }
 
@@ -291,7 +302,7 @@ async function defaultLaunch(
   open: boolean,
   cliEntry: string,
 ): Promise<boolean> {
-  const child = spawn(process.execPath, [cliEntry, ...launchArgs(record, open)], {
+  const child = spawn(process.execPath, [cliEntry, ...buildInstanceLaunchArgs(record, open)], {
     stdio: "ignore",
     windowsHide: true,
     env: {
@@ -468,6 +479,7 @@ function overridesDiffer(
   if (overrides.basePath !== null && overrides.basePath !== record.basePath) return true;
   if (overrides.host !== null && overrides.host !== record.host) return true;
   if (overrides.captureMode !== null && overrides.captureMode !== record.captureMode) return true;
+  if (overrides.uiEnabled !== null && overrides.uiEnabled !== record.uiEnabled) return true;
   if (overrides.dataDir !== null) {
     const requested = canonicalizeDataDirectory(overrides.dataDir);
     const saved = canonicalizeDataDirectory(record.dataDir);
@@ -495,6 +507,7 @@ function updatedRecord(
     upstreamPort: pair.upstreamPort,
     basePath: action.overrides.basePath ?? record.basePath,
     captureMode: action.overrides.captureMode ?? record.captureMode,
+    uiEnabled: action.overrides.uiEnabled ?? record.uiEnabled,
     dataDir,
   };
   const parsed = InstanceRecordSchema.safeParse(candidate);
@@ -556,6 +569,7 @@ async function createNewRecord(
     upstreamPort: pairResult.value.upstreamPort,
     basePath: action.overrides.basePath ?? getConfiguredBasePath(process.env),
     captureMode: action.overrides.captureMode ?? DEFAULT_INSTANCE_CAPTURE_MODE,
+    uiEnabled: action.overrides.uiEnabled ?? true,
     dataDir: dataDirResult.value,
   });
   return created.kind === "error" ? fromRegistry(created) : saveRecord(root, created.value);
@@ -609,7 +623,9 @@ async function startAction(
     }
     const live = await classifyRecord(record, deps);
     if (live.state === "running") {
-      if (action.overrides.open) (deps.openUrl ?? defaultOpenUrl)(recordUrls(record).ui);
+      if (action.overrides.open && record.uiEnabled) {
+        (deps.openUrl ?? defaultOpenUrl)(recordUrls(record).ui);
+      }
       return success(operationOutput("start", "already_running", statusOutput(record, live)));
     }
     if (live.state === "conflict") {
@@ -793,9 +809,10 @@ function requestActionOverrides(
 ): Extract<InstanceAction, { kind: "start" }>["overrides"] {
   return {
     port: input.port ?? null,
-    basePath: input.basePath === undefined ? null : normalizeBasePath(input.basePath),
+    basePath: input.basePath === undefined ? null : normalizePublicBasePath(input.basePath),
     host: input.host ?? null,
     captureMode: input.captureMode ?? null,
+    uiEnabled: input.uiEnabled ?? null,
     dataDir: input.dataDir ?? null,
     open: false,
   };
@@ -873,8 +890,10 @@ export async function listNamedInstances(
 function formatStatus(output: InstanceStatusOutput): string {
   const pid = output.supervisorPid === null ? "-" : String(output.supervisorPid);
   const reason = output.stateReason === null ? "-" : output.stateReason;
+  const ui = output.uiEnabled ? output.urls.ui : `disabled (configured URL: ${output.urls.ui})`;
   return `Instance ${output.name}: ${output.state}
-  UI:             ${output.urls.ui}
+  UI:             ${ui}
+  UI enabled:     ${output.uiEnabled ? "yes" : "no"}
   Proxy:          ${output.urls.proxy}
   OpenAI /v1:     ${output.urls.openai}
   MCP:            ${output.urls.mcp}
@@ -1029,9 +1048,3 @@ export async function runInstance(
     }
   }
 }
-
-export const instanceLifecycleForTests = {
-  classifyRecord,
-  launchArgs,
-  statusOutput,
-};

package/src/cli/instanceArgs.ts

@@ -1,4 +1,4 @@
-import { normalizeBasePath } from "../lib/basePath";
+import { normalizePublicBasePath } from "../lib/basePath";
 import { isValidBindHost } from "./networkHints";
 
 export type InstanceCaptureMode = "simple" | "full";
@@ -9,6 +9,7 @@ export type InstanceStartOverrides = {
   host: string | null;
   captureMode: InstanceCaptureMode | null;
   dataDir: string | null;
+  uiEnabled: boolean | null;
   open: boolean;
 };
 
@@ -36,16 +37,8 @@ function parseMode(value: string | undefined): InstanceCaptureMode | null {
 }
 
 function parseBasePath(value: string | undefined): string | null {
-  if (
-    value === undefined ||
-    !value.startsWith("/") ||
-    value.includes("?") ||
-    value.includes("#") ||
-    value.includes("\\")
-  ) {
-    return null;
-  }
-  return normalizeBasePath(value);
+  if (value === undefined) return null;
+  return normalizePublicBasePath(value);
 }
 
 function optionWithEquals(arg: string): { name: string; value: string } | null {
@@ -61,6 +54,7 @@ function emptyOverrides(): InstanceStartOverrides {
     host: null,
     captureMode: null,
     dataDir: null,
+    uiEnabled: null,
     open: false,
   };
 }
@@ -148,6 +142,24 @@ export function parseInstanceArgs(argv: readonly string[]): InstanceArgsResult {
       case "--open":
         options.overrides.open = true;
         break;
+      case "--backend-only":
+        if (options.overrides.uiEnabled === true) {
+          return {
+            kind: "error",
+            message: "instance: --backend-only and --with-ui are mutually exclusive",
+          };
+        }
+        options.overrides.uiEnabled = false;
+        break;
+      case "--with-ui":
+        if (options.overrides.uiEnabled === false) {
+          return {
+            kind: "error",
+            message: "instance: --backend-only and --with-ui are mutually exclusive",
+          };
+        }
+        options.overrides.uiEnabled = true;
+        break;
       case "--port":
       case "-p":
       case "--base-path":
@@ -181,6 +193,7 @@ export function parseInstanceArgs(argv: readonly string[]): InstanceArgsResult {
       options.overrides.host !== null ||
       options.overrides.captureMode !== null ||
       options.overrides.dataDir !== null ||
+      options.overrides.uiEnabled !== null ||
       options.overrides.open
     ) {
       return { kind: "error", message: "instance: list accepts only --json" };
@@ -203,6 +216,7 @@ export function parseInstanceArgs(argv: readonly string[]): InstanceArgsResult {
       options.overrides.host !== null ||
       options.overrides.captureMode !== null ||
       options.overrides.dataDir !== null ||
+      options.overrides.uiEnabled !== null ||
       options.overrides.open
     ) {
       return {
@@ -220,6 +234,9 @@ export function parseInstanceArgs(argv: readonly string[]): InstanceArgsResult {
     if (name === undefined || options.positional.length !== 2) {
       return { kind: "error", message: `instance: ${command} requires exactly one instance name` };
     }
+    if (options.overrides.uiEnabled === false && options.overrides.open) {
+      return { kind: "error", message: "instance: --open cannot be used with --backend-only" };
+    }
     return {
       kind: "ok",
       action: { kind: command, name, overrides: options.overrides, json: options.json },
@@ -251,6 +268,8 @@ Start/restart options:
   --host, -H <host>       Bind host (default: 127.0.0.1)
   --mode <simple|full>    Capture mode (default: simple)
   --data-dir <path>       Isolated data/config directory
+  --backend-only          Persist a headless backend without serving the UI
+  --with-ui               Persist composed UI serving (the default for new instances)
   --open                  Open the UI after readiness
   --json                  Emit machine-readable output
   --help, -h              Show this help

package/src/cli/instanceControl.ts

@@ -179,5 +179,3 @@ export async function requestInstanceShutdown(
     clearTimeout(timeout);
   }
 }
-
-export const instanceControlForTests = { parseIdentity };

package/src/cli/instanceModel.ts

@@ -1,7 +1,7 @@
 import { randomBytes, randomUUID } from "node:crypto";
 import { isAbsolute } from "node:path";
 import { z } from "zod";
-import { normalizeBasePath } from "../lib/basePath";
+import { normalizePublicBasePath } from "../lib/basePath";
 import { MANAGED_INSTANCE_CONTROL_PATH } from "../lib/managedInstance";
 import { CaptureModeSchema, type CaptureMode } from "../lib/runtimeConfig";
 
@@ -73,26 +73,13 @@ export function validateInstanceName(rawName: string): InstanceRegistryResult<st
 export function normalizeInstanceBasePath(
   rawBasePath: string | undefined,
 ): InstanceRegistryResult<string> {
-  const value = rawBasePath ?? "";
-  const trimmed = value.trim();
-  const hasControlCharacter = [...trimmed].some((character) => {
-    const codePoint = character.codePointAt(0) ?? 0;
-    return codePoint < 32 || codePoint === 127;
-  });
-  if (
-    trimmed.length > 0 &&
-    (!trimmed.startsWith("/") ||
-      trimmed.includes("?") ||
-      trimmed.includes("#") ||
-      trimmed.includes("\\") ||
-      hasControlCharacter)
-  ) {
+  const normalized = normalizePublicBasePath(rawBasePath);
+  if (normalized === null) {
     return instanceRegistryError(
       "record_invalid",
-      "Instance Base Path must be an absolute URL path without a query, hash, backslash, or control character.",
+      "Instance Base Path must use URL-safe path segments without traversal, encoded separators, or markup characters.",
     );
   }
-  const normalized = normalizeBasePath(trimmed);
   const reservedControlRoot = MANAGED_INSTANCE_CONTROL_PATH.replace(/\/instance$/u, "");
   if (normalized === reservedControlRoot || normalized.startsWith(`${reservedControlRoot}/`)) {
     return instanceRegistryError(
@@ -137,6 +124,7 @@ export const InstanceRecordSchema = z
     upstreamPort: PortSchema,
     basePath: NormalizedBasePathSchema,
     captureMode: CaptureModeSchema,
+    uiEnabled: z.boolean().default(true),
     dataDir: z
       .string()
       .min(1)
@@ -168,6 +156,7 @@ export type InstanceRecordOutput = {
   upstreamPort: number;
   basePath: string;
   captureMode: CaptureMode;
+  uiEnabled: boolean;
   dataDir: string;
   launch: {
     launchId: string;
@@ -182,6 +171,7 @@ export type CreateInstanceRecordInput = {
   upstreamPort: number;
   basePath?: string;
   captureMode: CaptureMode;
+  uiEnabled?: boolean;
   dataDir: string;
 };
 
@@ -222,6 +212,7 @@ export function createInstanceRecord(
     upstreamPort: input.upstreamPort,
     basePath: basePath.value,
     captureMode: input.captureMode,
+    uiEnabled: input.uiEnabled ?? true,
     dataDir: input.dataDir,
     launch: createLaunch(factory, now),
   };
@@ -266,6 +257,7 @@ export function toInstanceRecordOutput(record: InstanceRecord): InstanceRecordOu
     upstreamPort: record.upstreamPort,
     basePath: record.basePath,
     captureMode: record.captureMode,
+    uiEnabled: record.uiEnabled,
     dataDir: record.dataDir,
     launch: {
       launchId: record.launch.launchId,