refactor: route browser control via gateway/node

2026-05-08 00:21:23 +00:00 · 2026-01-27 03:23:42 +00:00
parent b151b8d196
commit e7fdccce39
91 changed files with 1909 additions and 1608 deletions
--- a/src/browser/bridge-server.ts
+++ b/src/browser/bridge-server.ts
@@ -4,6 +4,7 @@ import express from "express";

 import type { ResolvedBrowserConfig } from "./config.js";
 import { registerBrowserRoutes } from "./routes/index.js";
+import type { BrowserRouteRegistrar } from "./routes/types.js";
 import {
  type BrowserServerState,
  createBrowserRouteContext,
@@ -50,7 +51,7 @@ export async function startBrowserBridgeServer(params: {
    getState: () => state,
    onEnsureAttachTarget: params.onEnsureAttachTarget,
  });
-  registerBrowserRoutes(app, ctx);
+  registerBrowserRoutes(app as unknown as BrowserRouteRegistrar, ctx);

  const server = await new Promise<Server>((resolve, reject) => {
    const s = app.listen(port, host, () => resolve(s));
@@ -61,11 +62,9 @@ export async function startBrowserBridgeServer(params: {
  const resolvedPort = address?.port ?? port;
  state.server = server;
  state.port = resolvedPort;
-  state.resolved.controlHost = host;
  state.resolved.controlPort = resolvedPort;
-  state.resolved.controlUrl = `http://${host}:${resolvedPort}`;

-  const baseUrl = state.resolved.controlUrl;
+  const baseUrl = `http://${host}:${resolvedPort}`;
  return { server, port: resolvedPort, baseUrl, state };
 }

--- a/src/browser/client-actions-core.ts
+++ b/src/browser/client-actions-core.ts
@@ -9,6 +9,12 @@ function buildProfileQuery(profile?: string): string {
  return profile ? `?profile=${encodeURIComponent(profile)}` : "";
 }

+function withBaseUrl(baseUrl: string | undefined, path: string): string {
+  const trimmed = baseUrl?.trim();
+  if (!trimmed) return path;
+  return `${trimmed.replace(/\/$/, "")}${path}`;
+}
+
 export type BrowserFormField = {
  ref: string;
  type: string;
@@ -92,11 +98,15 @@ export type BrowserDownloadPayload = {
 };

 export async function browserNavigate(
-  baseUrl: string,
-  opts: { url: string; targetId?: string; profile?: string },
+  baseUrl: string | undefined,
+  opts: {
+    url: string;
+    targetId?: string;
+    profile?: string;
+  },
 ): Promise<BrowserActionTabResult> {
  const q = buildProfileQuery(opts.profile);
-  return await fetchBrowserJson<BrowserActionTabResult>(`${baseUrl}/navigate${q}`, {
+  return await fetchBrowserJson<BrowserActionTabResult>(withBaseUrl(baseUrl, `/navigate${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ url: opts.url, targetId: opts.targetId }),
@@ -105,7 +115,7 @@ export async function browserNavigate(
 }

 export async function browserArmDialog(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: {
    accept: boolean;
    promptText?: string;
@@ -115,7 +125,7 @@ export async function browserArmDialog(
  },
 ): Promise<BrowserActionOk> {
  const q = buildProfileQuery(opts.profile);
-  return await fetchBrowserJson<BrowserActionOk>(`${baseUrl}/hooks/dialog${q}`, {
+  return await fetchBrowserJson<BrowserActionOk>(withBaseUrl(baseUrl, `/hooks/dialog${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
@@ -129,7 +139,7 @@ export async function browserArmDialog(
 }

 export async function browserArmFileChooser(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: {
    paths: string[];
    ref?: string;
@@ -141,7 +151,7 @@ export async function browserArmFileChooser(
  },
 ): Promise<BrowserActionOk> {
  const q = buildProfileQuery(opts.profile);
-  return await fetchBrowserJson<BrowserActionOk>(`${baseUrl}/hooks/file-chooser${q}`, {
+  return await fetchBrowserJson<BrowserActionOk>(withBaseUrl(baseUrl, `/hooks/file-chooser${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
@@ -157,7 +167,7 @@ export async function browserArmFileChooser(
 }

 export async function browserWaitForDownload(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: {
    path?: string;
    targetId?: string;
@@ -170,7 +180,7 @@ export async function browserWaitForDownload(
    ok: true;
    targetId: string;
    download: BrowserDownloadPayload;
-  }>(`${baseUrl}/wait/download${q}`, {
+  }>(withBaseUrl(baseUrl, `/wait/download${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
@@ -183,7 +193,7 @@ export async function browserWaitForDownload(
 }

 export async function browserDownload(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: {
    ref: string;
    path: string;
@@ -197,7 +207,7 @@ export async function browserDownload(
    ok: true;
    targetId: string;
    download: BrowserDownloadPayload;
-  }>(`${baseUrl}/download${q}`, {
+  }>(withBaseUrl(baseUrl, `/download${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
@@ -211,12 +221,12 @@ export async function browserDownload(
 }

 export async function browserAct(
-  baseUrl: string,
+  baseUrl: string | undefined,
  req: BrowserActRequest,
  opts?: { profile?: string },
 ): Promise<BrowserActResponse> {
  const q = buildProfileQuery(opts?.profile);
-  return await fetchBrowserJson<BrowserActResponse>(`${baseUrl}/act${q}`, {
+  return await fetchBrowserJson<BrowserActResponse>(withBaseUrl(baseUrl, `/act${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(req),
@@ -225,7 +235,7 @@ export async function browserAct(
 }

 export async function browserScreenshotAction(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: {
    targetId?: string;
    fullPage?: boolean;
@@ -236,7 +246,7 @@ export async function browserScreenshotAction(
  },
 ): Promise<BrowserActionPathResult> {
  const q = buildProfileQuery(opts.profile);
-  return await fetchBrowserJson<BrowserActionPathResult>(`${baseUrl}/screenshot${q}`, {
+  return await fetchBrowserJson<BrowserActionPathResult>(withBaseUrl(baseUrl, `/screenshot${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
--- a/src/browser/client-actions-observe.ts
+++ b/src/browser/client-actions-observe.ts
@@ -10,8 +10,14 @@ function buildProfileQuery(profile?: string): string {
  return profile ? `?profile=${encodeURIComponent(profile)}` : "";
 }

+function withBaseUrl(baseUrl: string | undefined, path: string): string {
+  const trimmed = baseUrl?.trim();
+  if (!trimmed) return path;
+  return `${trimmed.replace(/\/$/, "")}${path}`;
+}
+
 export async function browserConsoleMessages(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: { level?: string; targetId?: string; profile?: string } = {},
 ): Promise<{ ok: true; messages: BrowserConsoleMessage[]; targetId: string }> {
  const q = new URLSearchParams();
@@ -23,15 +29,15 @@ export async function browserConsoleMessages(
    ok: true;
    messages: BrowserConsoleMessage[];
    targetId: string;
-  }>(`${baseUrl}/console${suffix}`, { timeoutMs: 20000 });
+  }>(withBaseUrl(baseUrl, `/console${suffix}`), { timeoutMs: 20000 });
 }

 export async function browserPdfSave(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: { targetId?: string; profile?: string } = {},
 ): Promise<BrowserActionPathResult> {
  const q = buildProfileQuery(opts.profile);
-  return await fetchBrowserJson<BrowserActionPathResult>(`${baseUrl}/pdf${q}`, {
+  return await fetchBrowserJson<BrowserActionPathResult>(withBaseUrl(baseUrl, `/pdf${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ targetId: opts.targetId }),
@@ -40,7 +46,7 @@ export async function browserPdfSave(
 }

 export async function browserPageErrors(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: { targetId?: string; clear?: boolean; profile?: string } = {},
 ): Promise<{ ok: true; targetId: string; errors: BrowserPageError[] }> {
  const q = new URLSearchParams();
@@ -52,11 +58,11 @@ export async function browserPageErrors(
    ok: true;
    targetId: string;
    errors: BrowserPageError[];
-  }>(`${baseUrl}/errors${suffix}`, { timeoutMs: 20000 });
+  }>(withBaseUrl(baseUrl, `/errors${suffix}`), { timeoutMs: 20000 });
 }

 export async function browserRequests(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: {
    targetId?: string;
    filter?: string;
@@ -74,11 +80,11 @@ export async function browserRequests(
    ok: true;
    targetId: string;
    requests: BrowserNetworkRequest[];
-  }>(`${baseUrl}/requests${suffix}`, { timeoutMs: 20000 });
+  }>(withBaseUrl(baseUrl, `/requests${suffix}`), { timeoutMs: 20000 });
 }

 export async function browserTraceStart(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: {
    targetId?: string;
    screenshots?: boolean;
@@ -88,7 +94,7 @@ export async function browserTraceStart(
  } = {},
 ): Promise<BrowserActionTargetOk> {
  const q = buildProfileQuery(opts.profile);
-  return await fetchBrowserJson<BrowserActionTargetOk>(`${baseUrl}/trace/start${q}`, {
+  return await fetchBrowserJson<BrowserActionTargetOk>(withBaseUrl(baseUrl, `/trace/start${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
@@ -102,11 +108,11 @@ export async function browserTraceStart(
 }

 export async function browserTraceStop(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: { targetId?: string; path?: string; profile?: string } = {},
 ): Promise<BrowserActionPathResult> {
  const q = buildProfileQuery(opts.profile);
-  return await fetchBrowserJson<BrowserActionPathResult>(`${baseUrl}/trace/stop${q}`, {
+  return await fetchBrowserJson<BrowserActionPathResult>(withBaseUrl(baseUrl, `/trace/stop${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ targetId: opts.targetId, path: opts.path }),
@@ -115,11 +121,11 @@ export async function browserTraceStop(
 }

 export async function browserHighlight(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: { ref: string; targetId?: string; profile?: string },
 ): Promise<BrowserActionTargetOk> {
  const q = buildProfileQuery(opts.profile);
-  return await fetchBrowserJson<BrowserActionTargetOk>(`${baseUrl}/highlight${q}`, {
+  return await fetchBrowserJson<BrowserActionTargetOk>(withBaseUrl(baseUrl, `/highlight${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ targetId: opts.targetId, ref: opts.ref }),
@@ -128,7 +134,7 @@ export async function browserHighlight(
 }

 export async function browserResponseBody(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: {
    url: string;
    targetId?: string;
@@ -158,7 +164,7 @@ export async function browserResponseBody(
      body: string;
      truncated?: boolean;
    };
-  }>(`${baseUrl}/response/body${q}`, {
+  }>(withBaseUrl(baseUrl, `/response/body${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
--- a/src/browser/client-actions-state.ts
+++ b/src/browser/client-actions-state.ts
@@ -5,8 +5,14 @@ function buildProfileQuery(profile?: string): string {
  return profile ? `?profile=${encodeURIComponent(profile)}` : "";
 }

+function withBaseUrl(baseUrl: string | undefined, path: string): string {
+  const trimmed = baseUrl?.trim();
+  if (!trimmed) return path;
+  return `${trimmed.replace(/\/$/, "")}${path}`;
+}
+
 export async function browserCookies(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: { targetId?: string; profile?: string } = {},
 ): Promise<{ ok: true; targetId: string; cookies: unknown[] }> {
  const q = new URLSearchParams();
@@ -17,11 +23,11 @@ export async function browserCookies(
    ok: true;
    targetId: string;
    cookies: unknown[];
-  }>(`${baseUrl}/cookies${suffix}`, { timeoutMs: 20000 });
+  }>(withBaseUrl(baseUrl, `/cookies${suffix}`), { timeoutMs: 20000 });
 }

 export async function browserCookiesSet(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: {
    cookie: Record<string, unknown>;
    targetId?: string;
@@ -29,7 +35,7 @@ export async function browserCookiesSet(
  },
 ): Promise<BrowserActionTargetOk> {
  const q = buildProfileQuery(opts.profile);
-  return await fetchBrowserJson<BrowserActionTargetOk>(`${baseUrl}/cookies/set${q}`, {
+  return await fetchBrowserJson<BrowserActionTargetOk>(withBaseUrl(baseUrl, `/cookies/set${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ targetId: opts.targetId, cookie: opts.cookie }),
@@ -38,11 +44,11 @@ export async function browserCookiesSet(
 }

 export async function browserCookiesClear(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: { targetId?: string; profile?: string } = {},
 ): Promise<BrowserActionTargetOk> {
  const q = buildProfileQuery(opts.profile);
-  return await fetchBrowserJson<BrowserActionTargetOk>(`${baseUrl}/cookies/clear${q}`, {
+  return await fetchBrowserJson<BrowserActionTargetOk>(withBaseUrl(baseUrl, `/cookies/clear${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ targetId: opts.targetId }),
@@ -51,7 +57,7 @@ export async function browserCookiesClear(
 }

 export async function browserStorageGet(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: {
    kind: "local" | "session";
    key?: string;
@@ -68,11 +74,11 @@ export async function browserStorageGet(
    ok: true;
    targetId: string;
    values: Record<string, string>;
-  }>(`${baseUrl}/storage/${opts.kind}${suffix}`, { timeoutMs: 20000 });
+  }>(withBaseUrl(baseUrl, `/storage/${opts.kind}${suffix}`), { timeoutMs: 20000 });
 }

 export async function browserStorageSet(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: {
    kind: "local" | "session";
    key: string;
@@ -82,25 +88,28 @@ export async function browserStorageSet(
  },
 ): Promise<BrowserActionTargetOk> {
  const q = buildProfileQuery(opts.profile);
-  return await fetchBrowserJson<BrowserActionTargetOk>(`${baseUrl}/storage/${opts.kind}/set${q}`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
-      targetId: opts.targetId,
-      key: opts.key,
-      value: opts.value,
-    }),
-    timeoutMs: 20000,
-  });
+  return await fetchBrowserJson<BrowserActionTargetOk>(
+    withBaseUrl(baseUrl, `/storage/${opts.kind}/set${q}`),
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        targetId: opts.targetId,
+        key: opts.key,
+        value: opts.value,
+      }),
+      timeoutMs: 20000,
+    },
+  );
 }

 export async function browserStorageClear(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: { kind: "local" | "session"; targetId?: string; profile?: string },
 ): Promise<BrowserActionTargetOk> {
  const q = buildProfileQuery(opts.profile);
  return await fetchBrowserJson<BrowserActionTargetOk>(
-    `${baseUrl}/storage/${opts.kind}/clear${q}`,
+    withBaseUrl(baseUrl, `/storage/${opts.kind}/clear${q}`),
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
@@ -111,11 +120,11 @@ export async function browserStorageClear(
 }

 export async function browserSetOffline(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: { offline: boolean; targetId?: string; profile?: string },
 ): Promise<BrowserActionTargetOk> {
  const q = buildProfileQuery(opts.profile);
-  return await fetchBrowserJson<BrowserActionTargetOk>(`${baseUrl}/set/offline${q}`, {
+  return await fetchBrowserJson<BrowserActionTargetOk>(withBaseUrl(baseUrl, `/set/offline${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ targetId: opts.targetId, offline: opts.offline }),
@@ -124,7 +133,7 @@ export async function browserSetOffline(
 }

 export async function browserSetHeaders(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: {
    headers: Record<string, string>;
    targetId?: string;
@@ -132,7 +141,7 @@ export async function browserSetHeaders(
  },
 ): Promise<BrowserActionTargetOk> {
  const q = buildProfileQuery(opts.profile);
-  return await fetchBrowserJson<BrowserActionTargetOk>(`${baseUrl}/set/headers${q}`, {
+  return await fetchBrowserJson<BrowserActionTargetOk>(withBaseUrl(baseUrl, `/set/headers${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ targetId: opts.targetId, headers: opts.headers }),
@@ -141,7 +150,7 @@ export async function browserSetHeaders(
 }

 export async function browserSetHttpCredentials(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: {
    username?: string;
    password?: string;
@@ -151,21 +160,24 @@ export async function browserSetHttpCredentials(
  } = {},
 ): Promise<BrowserActionTargetOk> {
  const q = buildProfileQuery(opts.profile);
-  return await fetchBrowserJson<BrowserActionTargetOk>(`${baseUrl}/set/credentials${q}`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
-      targetId: opts.targetId,
-      username: opts.username,
-      password: opts.password,
-      clear: opts.clear,
-    }),
-    timeoutMs: 20000,
-  });
+  return await fetchBrowserJson<BrowserActionTargetOk>(
+    withBaseUrl(baseUrl, `/set/credentials${q}`),
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        targetId: opts.targetId,
+        username: opts.username,
+        password: opts.password,
+        clear: opts.clear,
+      }),
+      timeoutMs: 20000,
+    },
+  );
 }

 export async function browserSetGeolocation(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: {
    latitude?: number;
    longitude?: number;
@@ -177,23 +189,26 @@ export async function browserSetGeolocation(
  } = {},
 ): Promise<BrowserActionTargetOk> {
  const q = buildProfileQuery(opts.profile);
-  return await fetchBrowserJson<BrowserActionTargetOk>(`${baseUrl}/set/geolocation${q}`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
-      targetId: opts.targetId,
-      latitude: opts.latitude,
-      longitude: opts.longitude,
-      accuracy: opts.accuracy,
-      origin: opts.origin,
-      clear: opts.clear,
-    }),
-    timeoutMs: 20000,
-  });
+  return await fetchBrowserJson<BrowserActionTargetOk>(
+    withBaseUrl(baseUrl, `/set/geolocation${q}`),
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        targetId: opts.targetId,
+        latitude: opts.latitude,
+        longitude: opts.longitude,
+        accuracy: opts.accuracy,
+        origin: opts.origin,
+        clear: opts.clear,
+      }),
+      timeoutMs: 20000,
+    },
+  );
 }

 export async function browserSetMedia(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: {
    colorScheme: "dark" | "light" | "no-preference" | "none";
    targetId?: string;
@@ -201,7 +216,7 @@ export async function browserSetMedia(
  },
 ): Promise<BrowserActionTargetOk> {
  const q = buildProfileQuery(opts.profile);
-  return await fetchBrowserJson<BrowserActionTargetOk>(`${baseUrl}/set/media${q}`, {
+  return await fetchBrowserJson<BrowserActionTargetOk>(withBaseUrl(baseUrl, `/set/media${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
@@ -213,11 +228,11 @@ export async function browserSetMedia(
 }

 export async function browserSetTimezone(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: { timezoneId: string; targetId?: string; profile?: string },
 ): Promise<BrowserActionTargetOk> {
  const q = buildProfileQuery(opts.profile);
-  return await fetchBrowserJson<BrowserActionTargetOk>(`${baseUrl}/set/timezone${q}`, {
+  return await fetchBrowserJson<BrowserActionTargetOk>(withBaseUrl(baseUrl, `/set/timezone${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
@@ -229,11 +244,11 @@ export async function browserSetTimezone(
 }

 export async function browserSetLocale(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: { locale: string; targetId?: string; profile?: string },
 ): Promise<BrowserActionTargetOk> {
  const q = buildProfileQuery(opts.profile);
-  return await fetchBrowserJson<BrowserActionTargetOk>(`${baseUrl}/set/locale${q}`, {
+  return await fetchBrowserJson<BrowserActionTargetOk>(withBaseUrl(baseUrl, `/set/locale${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ targetId: opts.targetId, locale: opts.locale }),
@@ -242,11 +257,11 @@ export async function browserSetLocale(
 }

 export async function browserSetDevice(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: { name: string; targetId?: string; profile?: string },
 ): Promise<BrowserActionTargetOk> {
  const q = buildProfileQuery(opts.profile);
-  return await fetchBrowserJson<BrowserActionTargetOk>(`${baseUrl}/set/device${q}`, {
+  return await fetchBrowserJson<BrowserActionTargetOk>(withBaseUrl(baseUrl, `/set/device${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ targetId: opts.targetId, name: opts.name }),
@@ -255,11 +270,11 @@ export async function browserSetDevice(
 }

 export async function browserClearPermissions(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: { targetId?: string; profile?: string } = {},
 ): Promise<BrowserActionOk> {
  const q = buildProfileQuery(opts.profile);
-  return await fetchBrowserJson<BrowserActionOk>(`${baseUrl}/set/geolocation${q}`, {
+  return await fetchBrowserJson<BrowserActionOk>(withBaseUrl(baseUrl, `/set/geolocation${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ targetId: opts.targetId, clear: true }),
--- a/src/browser/client-fetch.ts
+++ b/src/browser/client-fetch.ts
@@ -1,57 +1,44 @@
-import { extractErrorCode, formatErrorMessage } from "../infra/errors.js";
-import { loadConfig } from "../config/config.js";
 import { formatCliCommand } from "../cli/command-format.js";
-import { resolveBrowserConfig } from "./config.js";
+import {
+  createBrowserControlContext,
+  startBrowserControlServiceFromConfig,
+} from "./control-service.js";
+import { createBrowserRouteDispatcher } from "./routes/dispatcher.js";

-let cachedConfigToken: string | null | undefined = undefined;
-
-function getBrowserControlToken(): string | null {
-  const env = process.env.CLAWDBOT_BROWSER_CONTROL_TOKEN?.trim();
-  if (env) return env;
-
-  if (cachedConfigToken !== undefined) return cachedConfigToken;
-  try {
-    const cfg = loadConfig();
-    const resolved = resolveBrowserConfig(cfg.browser);
-    const token = resolved.controlToken?.trim() || "";
-    cachedConfigToken = token ? token : null;
-  } catch {
-    cachedConfigToken = null;
-  }
-  return cachedConfigToken;
-}
-
-function unwrapCause(err: unknown): unknown {
-  if (!err || typeof err !== "object") return null;
-  const cause = (err as { cause?: unknown }).cause;
-  return cause ?? null;
+function isAbsoluteHttp(url: string): boolean {
+  return /^https?:\/\//i.test(url.trim());
 }

 function enhanceBrowserFetchError(url: string, err: unknown, timeoutMs: number): Error {
-  const cause = unwrapCause(err);
-  const code = extractErrorCode(cause) ?? extractErrorCode(err) ?? "";
-
-  const hint = `Start (or restart) the Clawdbot gateway (Clawdbot.app menubar, or \`${formatCliCommand("clawdbot gateway")}\`) and try again.`;
-
-  if (code === "ECONNREFUSED") {
+  const hint = isAbsoluteHttp(url)
+    ? "If this is a sandboxed session, ensure the sandbox browser is running and try again."
+    : `Start (or restart) the Clawdbot gateway (Clawdbot.app menubar, or \`${formatCliCommand("clawdbot gateway")}\`) and try again.`;
+  const msg = String(err);
+  if (msg.toLowerCase().includes("timed out") || msg.toLowerCase().includes("timeout")) {
    return new Error(
-      `Can't reach the clawd browser control server at ${url} (connection refused). ${hint}`,
-    );
-  }
-  if (code === "ETIMEDOUT" || code === "UND_ERR_CONNECT_TIMEOUT") {
-    return new Error(
-      `Can't reach the clawd browser control server at ${url} (timed out after ${timeoutMs}ms). ${hint}`,
+      `Can't reach the clawd browser control service (timed out after ${timeoutMs}ms). ${hint}`,
    );
  }
+  return new Error(`Can't reach the clawd browser control service. ${hint} (${msg})`);
+}

-  const msg = formatErrorMessage(err);
-  if (msg.toLowerCase().includes("abort")) {
-    return new Error(
-      `Can't reach the clawd browser control server at ${url} (timed out after ${timeoutMs}ms). ${hint}`,
-    );
+async function fetchHttpJson<T>(
+  url: string,
+  init: RequestInit & { timeoutMs?: number },
+): Promise<T> {
+  const timeoutMs = init.timeoutMs ?? 5000;
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { ...init, signal: ctrl.signal });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(text || `HTTP ${res.status}`);
+    }
+    return (await res.json()) as T;
+  } finally {
+    clearTimeout(t);
  }
-
-  return new Error(`Can't reach the clawd browser control server at ${url}. ${hint} (${msg})`);
 }

 export async function fetchBrowserJson<T>(
@@ -59,32 +46,58 @@ export async function fetchBrowserJson<T>(
  init?: RequestInit & { timeoutMs?: number },
 ): Promise<T> {
  const timeoutMs = init?.timeoutMs ?? 5000;
-  const ctrl = new AbortController();
-  const t = setTimeout(() => ctrl.abort(), timeoutMs);
-  let res: Response;
  try {
-    const token = getBrowserControlToken();
-    const mergedHeaders = (() => {
-      if (!token) return init?.headers;
-      const h = new Headers(init?.headers ?? {});
-      if (!h.has("Authorization")) {
-        h.set("Authorization", `Bearer ${token}`);
+    if (isAbsoluteHttp(url)) {
+      return await fetchHttpJson<T>(url, { ...(init ?? {}), timeoutMs });
+    }
+    const started = await startBrowserControlServiceFromConfig();
+    if (!started) {
+      throw new Error("browser control disabled");
+    }
+    const dispatcher = createBrowserRouteDispatcher(createBrowserControlContext());
+    const parsed = new URL(url, "http://localhost");
+    const query: Record<string, unknown> = {};
+    for (const [key, value] of parsed.searchParams.entries()) {
+      query[key] = value;
+    }
+    let body = init?.body;
+    if (typeof body === "string") {
+      try {
+        body = JSON.parse(body);
+      } catch {
+        // keep as string
      }
-      return h;
-    })();
-    res = await fetch(url, {
-      ...init,
-      ...(mergedHeaders ? { headers: mergedHeaders } : {}),
-      signal: ctrl.signal,
-    } as RequestInit);
+    }
+    const dispatchPromise = dispatcher.dispatch({
+      method:
+        init?.method?.toUpperCase() === "DELETE"
+          ? "DELETE"
+          : init?.method?.toUpperCase() === "POST"
+            ? "POST"
+            : "GET",
+      path: parsed.pathname,
+      query,
+      body,
+    });
+
+    const result = await (timeoutMs
+      ? Promise.race([
+          dispatchPromise,
+          new Promise<never>((_, reject) =>
+            setTimeout(() => reject(new Error("timed out")), timeoutMs),
+          ),
+        ])
+      : dispatchPromise);
+
+    if (result.status >= 400) {
+      const message =
+        result.body && typeof result.body === "object" && "error" in result.body
+          ? String((result.body as { error?: unknown }).error)
+          : `HTTP ${result.status}`;
+      throw new Error(message);
+    }
+    return result.body as T;
  } catch (err) {
    throw enhanceBrowserFetchError(url, err, timeoutMs);
-  } finally {
-    clearTimeout(t);
  }
-  if (!res.ok) {
-    const text = await res.text().catch(() => "");
-    throw new Error(text ? `${res.status}: ${text}` : `HTTP ${res.status}`);
-  }
-  return (await res.json()) as T;
 }
--- a/src/browser/client.test.ts
+++ b/src/browser/client.test.ts
@@ -16,7 +16,7 @@ describe("browser client", () => {
    vi.unstubAllGlobals();
  });

-  it("wraps connection failures with a gateway hint", async () => {
+  it("wraps connection failures with a sandbox hint", async () => {
    const refused = Object.assign(new Error("connect ECONNREFUSED 127.0.0.1"), {
      code: "ECONNREFUSED",
    });
@@ -26,7 +26,7 @@ describe("browser client", () => {

    vi.stubGlobal("fetch", vi.fn().mockRejectedValue(fetchFailed));

-    await expect(browserStatus("http://127.0.0.1:18791")).rejects.toThrow(/Start .*gateway/i);
+    await expect(browserStatus("http://127.0.0.1:18791")).rejects.toThrow(/sandboxed session/i);
  });

  it("adds useful timeout messaging for abort-like failures", async () => {
@@ -34,41 +34,6 @@ describe("browser client", () => {
    await expect(browserStatus("http://127.0.0.1:18791")).rejects.toThrow(/timed out/i);
  });

-  it("adds Authorization when CLAWDBOT_BROWSER_CONTROL_TOKEN is set", async () => {
-    const prev = process.env.CLAWDBOT_BROWSER_CONTROL_TOKEN;
-    process.env.CLAWDBOT_BROWSER_CONTROL_TOKEN = "t1";
-
-    const calls: Array<{ url: string; init?: RequestInit }> = [];
-    vi.stubGlobal(
-      "fetch",
-      vi.fn(async (url: string, init?: RequestInit) => {
-        calls.push({ url, init });
-        return {
-          ok: true,
-          json: async () => ({
-            enabled: true,
-            controlUrl: "http://127.0.0.1:18791",
-            running: false,
-            pid: null,
-            cdpPort: 18792,
-            chosenBrowser: null,
-            userDataDir: null,
-            color: "#FF0000",
-            headless: true,
-            attachOnly: false,
-          }),
-        } as unknown as Response;
-      }),
-    );
-
-    await browserStatus("http://127.0.0.1:18791");
-    const init = calls[0]?.init;
-    const auth = new Headers(init?.headers ?? {}).get("Authorization");
-    expect(auth).toBe("Bearer t1");
-
-    process.env.CLAWDBOT_BROWSER_CONTROL_TOKEN = prev;
-  });
-
  it("surfaces non-2xx responses with body text", async () => {
    vi.stubGlobal(
      "fetch",
@@ -81,7 +46,7 @@ describe("browser client", () => {

    await expect(
      browserSnapshot("http://127.0.0.1:18791", { format: "aria", limit: 1 }),
-    ).rejects.toThrow(/409: conflict/i);
+    ).rejects.toThrow(/conflict/i);
  });

  it("adds labels + efficient mode query params to snapshots", async () => {
@@ -255,7 +220,6 @@ describe("browser client", () => {
          ok: true,
          json: async () => ({
            enabled: true,
-            controlUrl: "http://127.0.0.1:18791",
            running: true,
            pid: 1,
            cdpPort: 18792,
--- a/src/browser/client.ts
+++ b/src/browser/client.ts
@@ -1,10 +1,7 @@
-import { loadConfig } from "../config/config.js";
 import { fetchBrowserJson } from "./client-fetch.js";
-import { resolveBrowserConfig } from "./config.js";

 export type BrowserStatus = {
  enabled: boolean;
-  controlUrl: string;
  profile?: string;
  running: boolean;
  cdpReady?: boolean;
@@ -89,59 +86,64 @@ export type SnapshotResult =
      imageType?: "png" | "jpeg";
    };

-export function resolveBrowserControlUrl(overrideUrl?: string) {
-  const cfg = loadConfig();
-  const resolved = resolveBrowserConfig(cfg.browser);
-  const url = overrideUrl?.trim() ? overrideUrl.trim() : resolved.controlUrl;
-  return url.replace(/\/$/, "");
-}
-
 function buildProfileQuery(profile?: string): string {
  return profile ? `?profile=${encodeURIComponent(profile)}` : "";
 }

+function withBaseUrl(baseUrl: string | undefined, path: string): string {
+  const trimmed = baseUrl?.trim();
+  if (!trimmed) return path;
+  return `${trimmed.replace(/\/$/, "")}${path}`;
+}
+
 export async function browserStatus(
-  baseUrl: string,
+  baseUrl?: string,
  opts?: { profile?: string },
 ): Promise<BrowserStatus> {
  const q = buildProfileQuery(opts?.profile);
-  return await fetchBrowserJson<BrowserStatus>(`${baseUrl}/${q}`, {
+  return await fetchBrowserJson<BrowserStatus>(withBaseUrl(baseUrl, `/${q}`), {
    timeoutMs: 1500,
  });
 }

-export async function browserProfiles(baseUrl: string): Promise<ProfileStatus[]> {
-  const res = await fetchBrowserJson<{ profiles: ProfileStatus[] }>(`${baseUrl}/profiles`, {
-    timeoutMs: 3000,
-  });
+export async function browserProfiles(baseUrl?: string): Promise<ProfileStatus[]> {
+  const res = await fetchBrowserJson<{ profiles: ProfileStatus[] }>(
+    withBaseUrl(baseUrl, `/profiles`),
+    {
+      timeoutMs: 3000,
+    },
+  );
  return res.profiles ?? [];
 }

-export async function browserStart(baseUrl: string, opts?: { profile?: string }): Promise<void> {
+export async function browserStart(baseUrl?: string, opts?: { profile?: string }): Promise<void> {
  const q = buildProfileQuery(opts?.profile);
-  await fetchBrowserJson(`${baseUrl}/start${q}`, {
+  await fetchBrowserJson(withBaseUrl(baseUrl, `/start${q}`), {
    method: "POST",
    timeoutMs: 15000,
  });
 }

-export async function browserStop(baseUrl: string, opts?: { profile?: string }): Promise<void> {
+export async function browserStop(baseUrl?: string, opts?: { profile?: string }): Promise<void> {
  const q = buildProfileQuery(opts?.profile);
-  await fetchBrowserJson(`${baseUrl}/stop${q}`, {
+  await fetchBrowserJson(withBaseUrl(baseUrl, `/stop${q}`), {
    method: "POST",
    timeoutMs: 15000,
  });
 }

 export async function browserResetProfile(
-  baseUrl: string,
+  baseUrl?: string,
  opts?: { profile?: string },
 ): Promise<BrowserResetProfileResult> {
  const q = buildProfileQuery(opts?.profile);
-  return await fetchBrowserJson<BrowserResetProfileResult>(`${baseUrl}/reset-profile${q}`, {
-    method: "POST",
-    timeoutMs: 20000,
-  });
+  return await fetchBrowserJson<BrowserResetProfileResult>(
+    withBaseUrl(baseUrl, `/reset-profile${q}`),
+    {
+      method: "POST",
+      timeoutMs: 20000,
+    },
+  );
 }

 export type BrowserCreateProfileResult = {
@@ -154,7 +156,7 @@ export type BrowserCreateProfileResult = {
 };

 export async function browserCreateProfile(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: {
    name: string;
    color?: string;
@@ -162,17 +164,20 @@ export async function browserCreateProfile(
    driver?: "clawd" | "extension";
  },
 ): Promise<BrowserCreateProfileResult> {
-  return await fetchBrowserJson<BrowserCreateProfileResult>(`${baseUrl}/profiles/create`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
-      name: opts.name,
-      color: opts.color,
-      cdpUrl: opts.cdpUrl,
-      driver: opts.driver,
-    }),
-    timeoutMs: 10000,
-  });
+  return await fetchBrowserJson<BrowserCreateProfileResult>(
+    withBaseUrl(baseUrl, `/profiles/create`),
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        name: opts.name,
+        color: opts.color,
+        cdpUrl: opts.cdpUrl,
+        driver: opts.driver,
+      }),
+      timeoutMs: 10000,
+    },
+  );
 }

 export type BrowserDeleteProfileResult = {
@@ -182,11 +187,11 @@ export type BrowserDeleteProfileResult = {
 };

 export async function browserDeleteProfile(
-  baseUrl: string,
+  baseUrl: string | undefined,
  profile: string,
 ): Promise<BrowserDeleteProfileResult> {
  return await fetchBrowserJson<BrowserDeleteProfileResult>(
-    `${baseUrl}/profiles/${encodeURIComponent(profile)}`,
+    withBaseUrl(baseUrl, `/profiles/${encodeURIComponent(profile)}`),
    {
      method: "DELETE",
      timeoutMs: 20000,
@@ -195,24 +200,24 @@ export async function browserDeleteProfile(
 }

 export async function browserTabs(
-  baseUrl: string,
+  baseUrl?: string,
  opts?: { profile?: string },
 ): Promise<BrowserTab[]> {
  const q = buildProfileQuery(opts?.profile);
  const res = await fetchBrowserJson<{ running: boolean; tabs: BrowserTab[] }>(
-    `${baseUrl}/tabs${q}`,
+    withBaseUrl(baseUrl, `/tabs${q}`),
    { timeoutMs: 3000 },
  );
  return res.tabs ?? [];
 }

 export async function browserOpenTab(
-  baseUrl: string,
+  baseUrl: string | undefined,
  url: string,
  opts?: { profile?: string },
 ): Promise<BrowserTab> {
  const q = buildProfileQuery(opts?.profile);
-  return await fetchBrowserJson<BrowserTab>(`${baseUrl}/tabs/open${q}`, {
+  return await fetchBrowserJson<BrowserTab>(withBaseUrl(baseUrl, `/tabs/open${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ url }),
@@ -221,12 +226,12 @@ export async function browserOpenTab(
 }

 export async function browserFocusTab(
-  baseUrl: string,
+  baseUrl: string | undefined,
  targetId: string,
  opts?: { profile?: string },
 ): Promise<void> {
  const q = buildProfileQuery(opts?.profile);
-  await fetchBrowserJson(`${baseUrl}/tabs/focus${q}`, {
+  await fetchBrowserJson(withBaseUrl(baseUrl, `/tabs/focus${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ targetId }),
@@ -235,19 +240,19 @@ export async function browserFocusTab(
 }

 export async function browserCloseTab(
-  baseUrl: string,
+  baseUrl: string | undefined,
  targetId: string,
  opts?: { profile?: string },
 ): Promise<void> {
  const q = buildProfileQuery(opts?.profile);
-  await fetchBrowserJson(`${baseUrl}/tabs/${encodeURIComponent(targetId)}${q}`, {
+  await fetchBrowserJson(withBaseUrl(baseUrl, `/tabs/${encodeURIComponent(targetId)}${q}`), {
    method: "DELETE",
    timeoutMs: 5000,
  });
 }

 export async function browserTabAction(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: {
    action: "list" | "new" | "close" | "select";
    index?: number;
@@ -255,7 +260,7 @@ export async function browserTabAction(
  },
 ): Promise<unknown> {
  const q = buildProfileQuery(opts.profile);
-  return await fetchBrowserJson(`${baseUrl}/tabs/action${q}`, {
+  return await fetchBrowserJson(withBaseUrl(baseUrl, `/tabs/action${q}`), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
@@ -267,7 +272,7 @@ export async function browserTabAction(
 }

 export async function browserSnapshot(
-  baseUrl: string,
+  baseUrl: string | undefined,
  opts: {
    format: "aria" | "ai";
    targetId?: string;
@@ -301,7 +306,7 @@ export async function browserSnapshot(
  if (opts.labels === true) q.set("labels", "1");
  if (opts.mode) q.set("mode", opts.mode);
  if (opts.profile) q.set("profile", opts.profile);
-  return await fetchBrowserJson<SnapshotResult>(`${baseUrl}/snapshot?${q.toString()}`, {
+  return await fetchBrowserJson<SnapshotResult>(withBaseUrl(baseUrl, `/snapshot?${q.toString()}`), {
    timeoutMs: 20000,
  });
 }
--- a/src/browser/config.test.ts
+++ b/src/browser/config.test.ts
@@ -2,13 +2,14 @@ import { describe, expect, it } from "vitest";
 import { resolveBrowserConfig, resolveProfile, shouldStartLocalBrowserServer } from "./config.js";

 describe("browser config", () => {
-  it("defaults to enabled with loopback control url and lobster-orange color", () => {
+  it("defaults to enabled with loopback defaults and lobster-orange color", () => {
    const resolved = resolveBrowserConfig(undefined);
    expect(resolved.enabled).toBe(true);
    expect(resolved.controlPort).toBe(18791);
-    expect(resolved.controlHost).toBe("127.0.0.1");
    expect(resolved.color).toBe("#FF4500");
    expect(shouldStartLocalBrowserServer(resolved)).toBe(true);
+    expect(resolved.cdpHost).toBe("127.0.0.1");
+    expect(resolved.cdpProtocol).toBe("http");
    const profile = resolveProfile(resolved, resolved.defaultProfile);
    expect(profile?.name).toBe("chrome");
    expect(profile?.driver).toBe("extension");
@@ -46,9 +47,31 @@ describe("browser config", () => {
    }
  });

+  it("derives default ports from gateway.port when env is unset", () => {
+    const prev = process.env.CLAWDBOT_GATEWAY_PORT;
+    delete process.env.CLAWDBOT_GATEWAY_PORT;
+    try {
+      const resolved = resolveBrowserConfig(undefined, { gateway: { port: 19011 } });
+      expect(resolved.controlPort).toBe(19013);
+      const chrome = resolveProfile(resolved, "chrome");
+      expect(chrome?.driver).toBe("extension");
+      expect(chrome?.cdpPort).toBe(19014);
+      expect(chrome?.cdpUrl).toBe("http://127.0.0.1:19014");
+
+      const clawd = resolveProfile(resolved, "clawd");
+      expect(clawd?.cdpPort).toBe(19022);
+      expect(clawd?.cdpUrl).toBe("http://127.0.0.1:19022");
+    } finally {
+      if (prev === undefined) {
+        delete process.env.CLAWDBOT_GATEWAY_PORT;
+      } else {
+        process.env.CLAWDBOT_GATEWAY_PORT = prev;
+      }
+    }
+  });
+
  it("normalizes hex colors", () => {
    const resolved = resolveBrowserConfig({
-      controlUrl: "http://localhost:18791",
      color: "ff4500",
    });
    expect(resolved.color).toBe("#FF4500");
@@ -56,7 +79,6 @@ describe("browser config", () => {

  it("supports custom remote CDP timeouts", () => {
    const resolved = resolveBrowserConfig({
-      controlUrl: "http://127.0.0.1:18791",
      remoteCdpTimeoutMs: 2200,
      remoteCdpHandshakeTimeoutMs: 5000,
    });
@@ -66,31 +88,21 @@ describe("browser config", () => {

  it("falls back to default color for invalid hex", () => {
    const resolved = resolveBrowserConfig({
-      controlUrl: "http://localhost:18791",
      color: "#GGGGGG",
    });
    expect(resolved.color).toBe("#FF4500");
  });

-  it("treats non-loopback control urls as remote", () => {
+  it("treats non-loopback cdpUrl as remote", () => {
    const resolved = resolveBrowserConfig({
-      controlUrl: "http://example.com:18791",
+      cdpUrl: "http://example.com:9222",
    });
-    expect(shouldStartLocalBrowserServer(resolved)).toBe(false);
-  });
-
-  it("derives CDP host/protocol from control url when cdpUrl is unset", () => {
-    const resolved = resolveBrowserConfig({
-      controlUrl: "http://127.0.0.1:19000",
-    });
-    expect(resolved.controlPort).toBe(19000);
-    expect(resolved.cdpHost).toBe("127.0.0.1");
-    expect(resolved.cdpProtocol).toBe("http");
+    const profile = resolveProfile(resolved, "clawd");
+    expect(profile?.cdpIsLoopback).toBe(false);
  });

  it("supports explicit CDP URLs for the default profile", () => {
    const resolved = resolveBrowserConfig({
-      controlUrl: "http://127.0.0.1:18791",
      cdpUrl: "http://example.com:9222",
    });
    const profile = resolveProfile(resolved, "clawd");
@@ -101,7 +113,6 @@ describe("browser config", () => {

  it("uses profile cdpUrl when provided", () => {
    const resolved = resolveBrowserConfig({
-      controlUrl: "http://127.0.0.1:18791",
      profiles: {
        remote: { cdpUrl: "http://10.0.0.42:9222", color: "#0066CC" },
      },
@@ -115,7 +126,6 @@ describe("browser config", () => {

  it("uses base protocol for profiles with only cdpPort", () => {
    const resolved = resolveBrowserConfig({
-      controlUrl: "http://127.0.0.1:18791",
      cdpUrl: "https://example.com:9443",
      profiles: {
        work: { cdpPort: 18801, color: "#0066CC" },
@@ -127,14 +137,11 @@ describe("browser config", () => {
  });

  it("rejects unsupported protocols", () => {
-    expect(() => resolveBrowserConfig({ controlUrl: "ws://127.0.0.1:18791" })).toThrow(
-      /must be http/i,
-    );
+    expect(() => resolveBrowserConfig({ cdpUrl: "ws://127.0.0.1:18791" })).toThrow(/must be http/i);
  });

  it("does not add the built-in chrome extension profile if the derived relay port is already used", () => {
    const resolved = resolveBrowserConfig({
-      controlUrl: "http://127.0.0.1:18791",
      profiles: {
        clawd: { cdpPort: 18792, color: "#FF4500" },
      },
--- a/src/browser/config.ts
+++ b/src/browser/config.ts
@@ -1,11 +1,12 @@
-import type { BrowserConfig, BrowserProfileConfig } from "../config/config.js";
+import type { BrowserConfig, BrowserProfileConfig, ClawdbotConfig } from "../config/config.js";
 import {
  deriveDefaultBrowserCdpPortRange,
  deriveDefaultBrowserControlPort,
+  DEFAULT_BROWSER_CONTROL_PORT,
 } from "../config/port-defaults.js";
+import { resolveGatewayPort } from "../config/paths.js";
 import {
  DEFAULT_CLAWD_BROWSER_COLOR,
-  DEFAULT_CLAWD_BROWSER_CONTROL_URL,
  DEFAULT_CLAWD_BROWSER_ENABLED,
  DEFAULT_BROWSER_DEFAULT_PROFILE_NAME,
  DEFAULT_CLAWD_BROWSER_PROFILE_NAME,
@@ -14,10 +15,7 @@ import { CDP_PORT_RANGE_START, getUsedPorts } from "./profiles.js";

 export type ResolvedBrowserConfig = {
  enabled: boolean;
-  controlUrl: string;
-  controlHost: string;
  controlPort: number;
-  controlToken?: string;
  cdpProtocol: "http" | "https";
  cdpHost: string;
  cdpIsLoopback: boolean;
@@ -137,24 +135,13 @@ function ensureDefaultChromeExtensionProfile(
  };
  return result;
 }
-export function resolveBrowserConfig(cfg: BrowserConfig | undefined): ResolvedBrowserConfig {
+export function resolveBrowserConfig(
+  cfg: BrowserConfig | undefined,
+  rootConfig?: ClawdbotConfig,
+): ResolvedBrowserConfig {
  const enabled = cfg?.enabled ?? DEFAULT_CLAWD_BROWSER_ENABLED;
-  const envControlUrl = process.env.CLAWDBOT_BROWSER_CONTROL_URL?.trim();
-  const controlToken = cfg?.controlToken?.trim() || undefined;
-  const derivedControlPort = (() => {
-    const raw = process.env.CLAWDBOT_GATEWAY_PORT?.trim();
-    if (!raw) return null;
-    const gatewayPort = Number.parseInt(raw, 10);
-    if (!Number.isFinite(gatewayPort) || gatewayPort <= 0) return null;
-    return deriveDefaultBrowserControlPort(gatewayPort);
-  })();
-  const derivedControlUrl = derivedControlPort ? `http://127.0.0.1:${derivedControlPort}` : null;
-
-  const controlInfo = parseHttpUrl(
-    cfg?.controlUrl ?? envControlUrl ?? derivedControlUrl ?? DEFAULT_CLAWD_BROWSER_CONTROL_URL,
-    "browser.controlUrl",
-  );
-  const controlPort = controlInfo.port;
+  const gatewayPort = resolveGatewayPort(rootConfig);
+  const controlPort = deriveDefaultBrowserControlPort(gatewayPort ?? DEFAULT_BROWSER_CONTROL_PORT);
  const defaultColor = normalizeHexColor(cfg?.color);
  const remoteCdpTimeoutMs = normalizeTimeoutMs(cfg?.remoteCdpTimeoutMs, 1500);
  const remoteCdpHandshakeTimeoutMs = normalizeTimeoutMs(
@@ -178,11 +165,10 @@ export function resolveBrowserConfig(cfg: BrowserConfig | undefined): ResolvedBr
    const derivedPort = controlPort + 1;
    if (derivedPort > 65535) {
      throw new Error(
-        `browser.controlUrl port (${controlPort}) is too high; cannot derive CDP port (${derivedPort})`,
+        `Derived CDP port (${derivedPort}) is too high; check gateway port configuration.`,
      );
    }
-    const derived = new URL(controlInfo.normalized);
-    derived.port = String(derivedPort);
+    const derived = new URL(`http://127.0.0.1:${derivedPort}`);
    cdpInfo = {
      parsed: derived,
      port: derivedPort,
@@ -211,10 +197,7 @@ export function resolveBrowserConfig(cfg: BrowserConfig | undefined): ResolvedBr

  return {
    enabled,
-    controlUrl: controlInfo.normalized,
-    controlHost: controlInfo.parsed.hostname,
    controlPort,
-    ...(controlToken ? { controlToken } : {}),
    cdpProtocol,
    cdpHost: cdpInfo.parsed.hostname,
    cdpIsLoopback: isLoopbackHost(cdpInfo.parsed.hostname),
@@ -269,6 +252,6 @@ export function resolveProfile(
  };
 }

-export function shouldStartLocalBrowserServer(resolved: ResolvedBrowserConfig) {
-  return isLoopbackHost(resolved.controlHost);
+export function shouldStartLocalBrowserServer(_resolved: ResolvedBrowserConfig) {
+  return true;
 }
--- a/src/browser/constants.ts
+++ b/src/browser/constants.ts
@@ -1,5 +1,4 @@
 export const DEFAULT_CLAWD_BROWSER_ENABLED = true;
-export const DEFAULT_CLAWD_BROWSER_CONTROL_URL = "http://127.0.0.1:18791";
 export const DEFAULT_CLAWD_BROWSER_COLOR = "#FF4500";
 export const DEFAULT_CLAWD_BROWSER_PROFILE_NAME = "clawd";
 export const DEFAULT_BROWSER_DEFAULT_PROFILE_NAME = "chrome";
--- a/src/browser/control-service.ts
+++ b/src/browser/control-service.ts
@@ -0,0 +1,80 @@
+import { loadConfig } from "../config/config.js";
+import { createSubsystemLogger } from "../logging/subsystem.js";
+import { resolveBrowserConfig, resolveProfile } from "./config.js";
+import { ensureChromeExtensionRelayServer } from "./extension-relay.js";
+import { type BrowserServerState, createBrowserRouteContext } from "./server-context.js";
+
+let state: BrowserServerState | null = null;
+const log = createSubsystemLogger("browser");
+const logService = log.child("service");
+
+export function getBrowserControlState(): BrowserServerState | null {
+  return state;
+}
+
+export function createBrowserControlContext() {
+  return createBrowserRouteContext({
+    getState: () => state,
+  });
+}
+
+export async function startBrowserControlServiceFromConfig(): Promise<BrowserServerState | null> {
+  if (state) return state;
+
+  const cfg = loadConfig();
+  const resolved = resolveBrowserConfig(cfg.browser, cfg);
+  if (!resolved.enabled) return null;
+
+  state = {
+    server: null,
+    port: resolved.controlPort,
+    resolved,
+    profiles: new Map(),
+  };
+
+  // If any profile uses the Chrome extension relay, start the local relay server eagerly
+  // so the extension can connect before the first browser action.
+  for (const name of Object.keys(resolved.profiles)) {
+    const profile = resolveProfile(resolved, name);
+    if (!profile || profile.driver !== "extension") continue;
+    await ensureChromeExtensionRelayServer({ cdpUrl: profile.cdpUrl }).catch((err) => {
+      logService.warn(`Chrome extension relay init failed for profile "${name}": ${String(err)}`);
+    });
+  }
+
+  logService.info(
+    `Browser control service ready (profiles=${Object.keys(resolved.profiles).length})`,
+  );
+  return state;
+}
+
+export async function stopBrowserControlService(): Promise<void> {
+  const current = state;
+  if (!current) return;
+
+  const ctx = createBrowserRouteContext({
+    getState: () => state,
+  });
+
+  try {
+    for (const name of Object.keys(current.resolved.profiles)) {
+      try {
+        await ctx.forProfile(name).stopRunningBrowser();
+      } catch {
+        // ignore
+      }
+    }
+  } catch (err) {
+    logService.warn(`clawd browser stop failed: ${String(err)}`);
+  }
+
+  state = null;
+
+  // Optional: Playwright is not always available (e.g. embedded gateway builds).
+  try {
+    const mod = await import("./pw-ai.js");
+    await mod.closePlaywrightBrowserConnection();
+  } catch {
+    // ignore
+  }
+}
--- a/src/browser/profiles-service.test.ts
+++ b/src/browser/profiles-service.test.ts
@@ -49,9 +49,7 @@ function createCtx(resolved: BrowserServerState["resolved"]) {

 describe("BrowserProfilesService", () => {
  it("allocates next local port for new profiles", async () => {
-    const resolved = resolveBrowserConfig({
-      controlUrl: "http://127.0.0.1:18791",
-    });
+    const resolved = resolveBrowserConfig({});
    const { ctx, state } = createCtx(resolved);

    vi.mocked(loadConfig).mockReturnValue({ browser: { profiles: {} } });
@@ -66,9 +64,7 @@ describe("BrowserProfilesService", () => {
  });

  it("accepts per-profile cdpUrl for remote Chrome", async () => {
-    const resolved = resolveBrowserConfig({
-      controlUrl: "http://127.0.0.1:18791",
-    });
+    const resolved = resolveBrowserConfig({});
    const { ctx } = createCtx(resolved);

    vi.mocked(loadConfig).mockReturnValue({ browser: { profiles: {} } });
@@ -97,7 +93,6 @@ describe("BrowserProfilesService", () => {

  it("deletes remote profiles without stopping or removing local data", async () => {
    const resolved = resolveBrowserConfig({
-      controlUrl: "http://127.0.0.1:18791",
      profiles: {
        remote: { cdpUrl: "http://10.0.0.42:9222", color: "#0066CC" },
      },
@@ -124,7 +119,6 @@ describe("BrowserProfilesService", () => {

  it("deletes local profiles and moves data to Trash", async () => {
    const resolved = resolveBrowserConfig({
-      controlUrl: "http://127.0.0.1:18791",
      profiles: {
        work: { cdpPort: 18801, color: "#0066CC" },
      },
--- a/src/browser/routes/agent.act.ts
+++ b/src/browser/routes/agent.act.ts
@@ -1,5 +1,3 @@
-import type express from "express";
-
 import type { BrowserFormField } from "../client-actions-core.js";
 import type { BrowserRouteContext } from "../server-context.js";
 import {
@@ -16,8 +14,12 @@ import {
  SELECTOR_UNSUPPORTED_MESSAGE,
 } from "./agent.shared.js";
 import { jsonError, toBoolean, toNumber, toStringArray, toStringOrEmpty } from "./utils.js";
+import type { BrowserRouteRegistrar } from "./types.js";

-export function registerBrowserAgentActRoutes(app: express.Express, ctx: BrowserRouteContext) {
+export function registerBrowserAgentActRoutes(
+  app: BrowserRouteRegistrar,
+  ctx: BrowserRouteContext,
+) {
  app.post("/act", async (req, res) => {
    const profileCtx = resolveProfileContext(req, res, ctx);
    if (!profileCtx) return;
--- a/src/browser/routes/agent.debug.ts
+++ b/src/browser/routes/agent.debug.ts
@@ -2,13 +2,15 @@ import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";

-import type express from "express";
-
 import type { BrowserRouteContext } from "../server-context.js";
 import { handleRouteError, readBody, requirePwAi, resolveProfileContext } from "./agent.shared.js";
 import { toBoolean, toStringOrEmpty } from "./utils.js";
+import type { BrowserRouteRegistrar } from "./types.js";

-export function registerBrowserAgentDebugRoutes(app: express.Express, ctx: BrowserRouteContext) {
+export function registerBrowserAgentDebugRoutes(
+  app: BrowserRouteRegistrar,
+  ctx: BrowserRouteContext,
+) {
  app.get("/console", async (req, res) => {
    const profileCtx = resolveProfileContext(req, res, ctx);
    if (!profileCtx) return;
--- a/src/browser/routes/agent.shared.ts
+++ b/src/browser/routes/agent.shared.ts
@@ -1,9 +1,8 @@
-import type express from "express";
-
 import type { BrowserRouteContext, ProfileContext } from "../server-context.js";
 import type { PwAiModule } from "../pw-ai-module.js";
 import { getPwAiModule as getPwAiModuleBase } from "../pw-ai-module.js";
 import { getProfileContext, jsonError } from "./utils.js";
+import type { BrowserRequest, BrowserResponse } from "./types.js";

 export const SELECTOR_UNSUPPORTED_MESSAGE = [
  "Error: 'selector' is not supported. Use 'ref' from snapshot instead.",
@@ -15,21 +14,21 @@ export const SELECTOR_UNSUPPORTED_MESSAGE = [
  "This is more reliable for modern SPAs.",
 ].join("\n");

-export function readBody(req: express.Request): Record<string, unknown> {
+export function readBody(req: BrowserRequest): Record<string, unknown> {
  const body = req.body as Record<string, unknown> | undefined;
  if (!body || typeof body !== "object" || Array.isArray(body)) return {};
  return body;
 }

-export function handleRouteError(ctx: BrowserRouteContext, res: express.Response, err: unknown) {
+export function handleRouteError(ctx: BrowserRouteContext, res: BrowserResponse, err: unknown) {
  const mapped = ctx.mapTabError(err);
  if (mapped) return jsonError(res, mapped.status, mapped.message);
  jsonError(res, 500, String(err));
 }

 export function resolveProfileContext(
-  req: express.Request,
-  res: express.Response,
+  req: BrowserRequest,
+  res: BrowserResponse,
  ctx: BrowserRouteContext,
 ): ProfileContext | null {
  const profileCtx = getProfileContext(req, ctx);
@@ -45,7 +44,7 @@ export async function getPwAiModule(): Promise<PwAiModule | null> {
 }

 export async function requirePwAi(
-  res: express.Response,
+  res: BrowserResponse,
  feature: string,
 ): Promise<PwAiModule | null> {
  const mod = await getPwAiModule();
--- a/src/browser/routes/agent.snapshot.ts
+++ b/src/browser/routes/agent.snapshot.ts
@@ -1,7 +1,5 @@
 import path from "node:path";

-import type express from "express";
-
 import { ensureMediaDir, saveMediaBuffer } from "../../media/store.js";
 import { captureScreenshot, snapshotAria } from "../cdp.js";
 import {
@@ -23,8 +21,12 @@ import {
  resolveProfileContext,
 } from "./agent.shared.js";
 import { jsonError, toBoolean, toNumber, toStringOrEmpty } from "./utils.js";
+import type { BrowserRouteRegistrar } from "./types.js";

-export function registerBrowserAgentSnapshotRoutes(app: express.Express, ctx: BrowserRouteContext) {
+export function registerBrowserAgentSnapshotRoutes(
+  app: BrowserRouteRegistrar,
+  ctx: BrowserRouteContext,
+) {
  app.post("/navigate", async (req, res) => {
    const profileCtx = resolveProfileContext(req, res, ctx);
    if (!profileCtx) return;
--- a/src/browser/routes/agent.storage.ts
+++ b/src/browser/routes/agent.storage.ts
@@ -1,10 +1,12 @@
-import type express from "express";
-
 import type { BrowserRouteContext } from "../server-context.js";
 import { handleRouteError, readBody, requirePwAi, resolveProfileContext } from "./agent.shared.js";
 import { jsonError, toBoolean, toNumber, toStringOrEmpty } from "./utils.js";
+import type { BrowserRouteRegistrar } from "./types.js";

-export function registerBrowserAgentStorageRoutes(app: express.Express, ctx: BrowserRouteContext) {
+export function registerBrowserAgentStorageRoutes(
+  app: BrowserRouteRegistrar,
+  ctx: BrowserRouteContext,
+) {
  app.get("/cookies", async (req, res) => {
    const profileCtx = resolveProfileContext(req, res, ctx);
    if (!profileCtx) return;
--- a/src/browser/routes/agent.ts
+++ b/src/browser/routes/agent.ts
@@ -1,12 +1,11 @@
-import type express from "express";
-
 import type { BrowserRouteContext } from "../server-context.js";
 import { registerBrowserAgentActRoutes } from "./agent.act.js";
 import { registerBrowserAgentDebugRoutes } from "./agent.debug.js";
 import { registerBrowserAgentSnapshotRoutes } from "./agent.snapshot.js";
 import { registerBrowserAgentStorageRoutes } from "./agent.storage.js";
+import type { BrowserRouteRegistrar } from "./types.js";

-export function registerBrowserAgentRoutes(app: express.Express, ctx: BrowserRouteContext) {
+export function registerBrowserAgentRoutes(app: BrowserRouteRegistrar, ctx: BrowserRouteContext) {
  registerBrowserAgentSnapshotRoutes(app, ctx);
  registerBrowserAgentActRoutes(app, ctx);
  registerBrowserAgentDebugRoutes(app, ctx);
--- a/src/browser/routes/basic.ts
+++ b/src/browser/routes/basic.ts
@@ -1,11 +1,10 @@
-import type express from "express";
-
 import { resolveBrowserExecutableForPlatform } from "../chrome.executables.js";
 import { createBrowserProfilesService } from "../profiles-service.js";
 import type { BrowserRouteContext } from "../server-context.js";
 import { getProfileContext, jsonError, toStringOrEmpty } from "./utils.js";
+import type { BrowserRouteRegistrar } from "./types.js";

-export function registerBrowserBasicRoutes(app: express.Express, ctx: BrowserRouteContext) {
+export function registerBrowserBasicRoutes(app: BrowserRouteRegistrar, ctx: BrowserRouteContext) {
  // List all profiles with their status
  app.get("/profiles", async (_req, res) => {
    try {
@@ -53,7 +52,6 @@ export function registerBrowserBasicRoutes(app: express.Express, ctx: BrowserRou

    res.json({
      enabled: current.resolved.enabled,
-      controlUrl: current.resolved.controlUrl,
      profile: profileCtx.profile.name,
      running: cdpReady,
      cdpReady,
--- a/src/browser/routes/dispatcher.ts
+++ b/src/browser/routes/dispatcher.ts
@@ -0,0 +1,122 @@
+import type { BrowserRouteContext } from "../server-context.js";
+import { registerBrowserRoutes } from "./index.js";
+import type { BrowserRequest, BrowserResponse, BrowserRouteRegistrar } from "./types.js";
+
+type BrowserDispatchRequest = {
+  method: "GET" | "POST" | "DELETE";
+  path: string;
+  query?: Record<string, unknown>;
+  body?: unknown;
+};
+
+type BrowserDispatchResponse = {
+  status: number;
+  body: unknown;
+};
+
+type RouteEntry = {
+  method: BrowserDispatchRequest["method"];
+  path: string;
+  regex: RegExp;
+  paramNames: string[];
+  handler: (req: BrowserRequest, res: BrowserResponse) => void | Promise<void>;
+};
+
+function escapeRegex(value: string) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function compileRoute(path: string): { regex: RegExp; paramNames: string[] } {
+  const paramNames: string[] = [];
+  const parts = path.split("/").map((part) => {
+    if (part.startsWith(":")) {
+      const name = part.slice(1);
+      paramNames.push(name);
+      return "([^/]+)";
+    }
+    return escapeRegex(part);
+  });
+  return { regex: new RegExp(`^${parts.join("/")}$`), paramNames };
+}
+
+function createRegistry() {
+  const routes: RouteEntry[] = [];
+  const register =
+    (method: RouteEntry["method"]) => (path: string, handler: RouteEntry["handler"]) => {
+      const { regex, paramNames } = compileRoute(path);
+      routes.push({ method, path, regex, paramNames, handler });
+    };
+  const router: BrowserRouteRegistrar = {
+    get: register("GET"),
+    post: register("POST"),
+    delete: register("DELETE"),
+  };
+  return { routes, router };
+}
+
+function normalizePath(path: string) {
+  if (!path) return "/";
+  return path.startsWith("/") ? path : `/${path}`;
+}
+
+export function createBrowserRouteDispatcher(ctx: BrowserRouteContext) {
+  const registry = createRegistry();
+  registerBrowserRoutes(registry.router, ctx);
+
+  return {
+    dispatch: async (req: BrowserDispatchRequest): Promise<BrowserDispatchResponse> => {
+      const method = req.method;
+      const path = normalizePath(req.path);
+      const query = req.query ?? {};
+      const body = req.body;
+
+      const match = registry.routes.find((route) => {
+        if (route.method !== method) return false;
+        return route.regex.test(path);
+      });
+      if (!match) {
+        return { status: 404, body: { error: "Not Found" } };
+      }
+
+      const exec = match.regex.exec(path);
+      const params: Record<string, string> = {};
+      if (exec) {
+        for (const [idx, name] of match.paramNames.entries()) {
+          const value = exec[idx + 1];
+          if (typeof value === "string") {
+            params[name] = decodeURIComponent(value);
+          }
+        }
+      }
+
+      let status = 200;
+      let payload: unknown = undefined;
+      const res: BrowserResponse = {
+        status(code) {
+          status = code;
+          return res;
+        },
+        json(bodyValue) {
+          payload = bodyValue;
+        },
+      };
+
+      try {
+        await match.handler(
+          {
+            params,
+            query,
+            body,
+          },
+          res,
+        );
+      } catch (err) {
+        return { status: 500, body: { error: String(err) } };
+      }
+
+      return { status, body: payload };
+    },
+  };
+}
+
+export type { BrowserDispatchRequest, BrowserDispatchResponse };
--- a/src/browser/routes/index.ts
+++ b/src/browser/routes/index.ts
@@ -1,11 +1,10 @@
-import type express from "express";
-
 import type { BrowserRouteContext } from "../server-context.js";
 import { registerBrowserAgentRoutes } from "./agent.js";
 import { registerBrowserBasicRoutes } from "./basic.js";
 import { registerBrowserTabRoutes } from "./tabs.js";
+import type { BrowserRouteRegistrar } from "./types.js";

-export function registerBrowserRoutes(app: express.Express, ctx: BrowserRouteContext) {
+export function registerBrowserRoutes(app: BrowserRouteRegistrar, ctx: BrowserRouteContext) {
  registerBrowserBasicRoutes(app, ctx);
  registerBrowserTabRoutes(app, ctx);
  registerBrowserAgentRoutes(app, ctx);
--- a/src/browser/routes/tabs.ts
+++ b/src/browser/routes/tabs.ts
@@ -1,9 +1,8 @@
-import type express from "express";
-
 import type { BrowserRouteContext } from "../server-context.js";
 import { getProfileContext, jsonError, toNumber, toStringOrEmpty } from "./utils.js";
+import type { BrowserRouteRegistrar } from "./types.js";

-export function registerBrowserTabRoutes(app: express.Express, ctx: BrowserRouteContext) {
+export function registerBrowserTabRoutes(app: BrowserRouteRegistrar, ctx: BrowserRouteContext) {
  app.get("/tabs", async (req, res) => {
    const profileCtx = getProfileContext(req, ctx);
    if ("error" in profileCtx) return jsonError(res, profileCtx.status, profileCtx.error);
--- a/src/browser/routes/types.ts
+++ b/src/browser/routes/types.ts
@@ -0,0 +1,21 @@
+export type BrowserRequest = {
+  params: Record<string, string>;
+  query: Record<string, unknown>;
+  body?: unknown;
+};
+
+export type BrowserResponse = {
+  status: (code: number) => BrowserResponse;
+  json: (body: unknown) => void;
+};
+
+export type BrowserRouteHandler = (
+  req: BrowserRequest,
+  res: BrowserResponse,
+) => void | Promise<void>;
+
+export type BrowserRouteRegistrar = {
+  get: (path: string, handler: BrowserRouteHandler) => void;
+  post: (path: string, handler: BrowserRouteHandler) => void;
+  delete: (path: string, handler: BrowserRouteHandler) => void;
+};
--- a/src/browser/routes/utils.ts
+++ b/src/browser/routes/utils.ts
@@ -1,14 +1,13 @@
-import type express from "express";
-
 import type { BrowserRouteContext, ProfileContext } from "../server-context.js";
 import { parseBooleanValue } from "../../utils/boolean.js";
+import type { BrowserRequest, BrowserResponse } from "./types.js";

 /**
 * Extract profile name from query string or body and get profile context.
 * Query string takes precedence over body for consistency with GET routes.
 */
 export function getProfileContext(
-  req: express.Request,
+  req: BrowserRequest,
  ctx: BrowserRouteContext,
 ): ProfileContext | { error: string; status: number } {
  let profileName: string | undefined;
@@ -33,7 +32,7 @@ export function getProfileContext(
  }
 }

-export function jsonError(res: express.Response, status: number, message: string) {
+export function jsonError(res: BrowserResponse, status: number, message: string) {
  res.status(status).json({ error: message });
 }

--- a/src/browser/server-context.ensure-tab-available.prefers-last-target.test.ts
+++ b/src/browser/server-context.ensure-tab-available.prefers-last-target.test.ts
@@ -62,8 +62,6 @@ describe("browser server-context ensureTabAvailable", () => {
      port: 0,
      resolved: {
        enabled: true,
-        controlUrl: "http://127.0.0.1:18791",
-        controlHost: "127.0.0.1",
        controlPort: 18791,
        cdpProtocol: "http",
        cdpHost: "127.0.0.1",
@@ -121,8 +119,6 @@ describe("browser server-context ensureTabAvailable", () => {
      port: 0,
      resolved: {
        enabled: true,
-        controlUrl: "http://127.0.0.1:18791",
-        controlHost: "127.0.0.1",
        controlPort: 18791,
        cdpProtocol: "http",
        cdpHost: "127.0.0.1",
@@ -170,8 +166,6 @@ describe("browser server-context ensureTabAvailable", () => {
      port: 0,
      resolved: {
        enabled: true,
-        controlUrl: "http://127.0.0.1:18791",
-        controlHost: "127.0.0.1",
        controlPort: 18791,
        cdpProtocol: "http",
        cdpHost: "127.0.0.1",
--- a/src/browser/server-context.remote-tab-ops.test.ts
+++ b/src/browser/server-context.remote-tab-ops.test.ts
@@ -21,8 +21,6 @@ function makeState(
    port: 0,
    resolved: {
      enabled: true,
-      controlUrl: "http://127.0.0.1:18791",
-      controlHost: "127.0.0.1",
      controlPort: 18791,
      cdpProtocol: profile === "remote" ? "https" : "http",
      cdpHost: profile === "remote" ? "browserless.example" : "127.0.0.1",
--- a/src/browser/server-context.types.ts
+++ b/src/browser/server-context.types.ts
@@ -17,7 +17,7 @@ export type ProfileRuntimeState = {
 };

 export type BrowserServerState = {
-  server: Server;
+  server?: Server | null;
  port: number;
  resolved: ResolvedBrowserConfig;
  profiles: Map<string, ProfileRuntimeState>;
--- a/src/browser/server.agent-contract-form-layout-act-commands.test.ts
+++ b/src/browser/server.agent-contract-form-layout-act-commands.test.ts
@@ -8,6 +8,7 @@ let cdpBaseUrl = "";
 let reachable = false;
 let cfgAttachOnly = false;
 let createTargetId: string | null = null;
+let prevGatewayPort: string | undefined;

 const cdpMocks = vi.hoisted(() => ({
  createTargetViaCdp: vi.fn(async () => {
@@ -88,7 +89,6 @@ vi.mock("../config/config.js", async (importOriginal) => {
    loadConfig: () => ({
      browser: {
        enabled: true,
-        controlUrl: `http://127.0.0.1:${testPort}`,
        color: "#FF4500",
        attachOnly: cfgAttachOnly,
        headless: true,
@@ -197,6 +197,8 @@ describe("browser control server", () => {

    testPort = await getFreePort();
    cdpBaseUrl = `http://127.0.0.1:${testPort + 1}`;
+    prevGatewayPort = process.env.CLAWDBOT_GATEWAY_PORT;
+    process.env.CLAWDBOT_GATEWAY_PORT = String(testPort - 2);

    // Minimal CDP JSON endpoints used by the server.
    let putNewCalls = 0;
@@ -248,6 +250,11 @@ describe("browser control server", () => {
  afterEach(async () => {
    vi.unstubAllGlobals();
    vi.restoreAllMocks();
+    if (prevGatewayPort === undefined) {
+      delete process.env.CLAWDBOT_GATEWAY_PORT;
+    } else {
+      process.env.CLAWDBOT_GATEWAY_PORT = prevGatewayPort;
+    }
    const { stopBrowserControlServer } = await import("./server.js");
    await stopBrowserControlServer();
  });
--- a/src/browser/server.agent-contract-snapshot-endpoints.test.ts
+++ b/src/browser/server.agent-contract-snapshot-endpoints.test.ts
@@ -9,6 +9,7 @@ let cdpBaseUrl = "";
 let reachable = false;
 let cfgAttachOnly = false;
 let createTargetId: string | null = null;
+let prevGatewayPort: string | undefined;

 const cdpMocks = vi.hoisted(() => ({
  createTargetViaCdp: vi.fn(async () => {
@@ -89,7 +90,6 @@ vi.mock("../config/config.js", async (importOriginal) => {
    loadConfig: () => ({
      browser: {
        enabled: true,
-        controlUrl: `http://127.0.0.1:${testPort}`,
        color: "#FF4500",
        attachOnly: cfgAttachOnly,
        headless: true,
@@ -198,6 +198,8 @@ describe("browser control server", () => {

    testPort = await getFreePort();
    cdpBaseUrl = `http://127.0.0.1:${testPort + 1}`;
+    prevGatewayPort = process.env.CLAWDBOT_GATEWAY_PORT;
+    process.env.CLAWDBOT_GATEWAY_PORT = String(testPort - 2);

    // Minimal CDP JSON endpoints used by the server.
    let putNewCalls = 0;
@@ -249,6 +251,11 @@ describe("browser control server", () => {
  afterEach(async () => {
    vi.unstubAllGlobals();
    vi.restoreAllMocks();
+    if (prevGatewayPort === undefined) {
+      delete process.env.CLAWDBOT_GATEWAY_PORT;
+    } else {
+      process.env.CLAWDBOT_GATEWAY_PORT = prevGatewayPort;
+    }
    const { stopBrowserControlServer } = await import("./server.js");
    await stopBrowserControlServer();
  });
--- a/src/browser/server.covers-additional-endpoint-branches.test.ts
+++ b/src/browser/server.covers-additional-endpoint-branches.test.ts
@@ -8,6 +8,7 @@ let _cdpBaseUrl = "";
 let reachable = false;
 let cfgAttachOnly = false;
 let createTargetId: string | null = null;
+let prevGatewayPort: string | undefined;

 const cdpMocks = vi.hoisted(() => ({
  createTargetViaCdp: vi.fn(async () => {
@@ -88,7 +89,6 @@ vi.mock("../config/config.js", async (importOriginal) => {
    loadConfig: () => ({
      browser: {
        enabled: true,
-        controlUrl: `http://127.0.0.1:${testPort}`,
        color: "#FF4500",
        attachOnly: cfgAttachOnly,
        headless: true,
@@ -197,6 +197,8 @@ describe("browser control server", () => {

    testPort = await getFreePort();
    _cdpBaseUrl = `http://127.0.0.1:${testPort + 1}`;
+    prevGatewayPort = process.env.CLAWDBOT_GATEWAY_PORT;
+    process.env.CLAWDBOT_GATEWAY_PORT = String(testPort - 2);

    // Minimal CDP JSON endpoints used by the server.
    let putNewCalls = 0;
@@ -248,6 +250,11 @@ describe("browser control server", () => {
  afterEach(async () => {
    vi.unstubAllGlobals();
    vi.restoreAllMocks();
+    if (prevGatewayPort === undefined) {
+      delete process.env.CLAWDBOT_GATEWAY_PORT;
+    } else {
+      process.env.CLAWDBOT_GATEWAY_PORT = prevGatewayPort;
+    }
    const { stopBrowserControlServer } = await import("./server.js");
    await stopBrowserControlServer();
  });
--- a/src/browser/server.post-tabs-open-profile-unknown-returns-404.test.ts
+++ b/src/browser/server.post-tabs-open-profile-unknown-returns-404.test.ts
@@ -8,6 +8,7 @@ let _cdpBaseUrl = "";
 let reachable = false;
 let cfgAttachOnly = false;
 let createTargetId: string | null = null;
+let prevGatewayPort: string | undefined;

 const cdpMocks = vi.hoisted(() => ({
  createTargetViaCdp: vi.fn(async () => {
@@ -88,7 +89,6 @@ vi.mock("../config/config.js", async (importOriginal) => {
    loadConfig: () => ({
      browser: {
        enabled: true,
-        controlUrl: `http://127.0.0.1:${testPort}`,
        color: "#FF4500",
        attachOnly: cfgAttachOnly,
        headless: true,
@@ -197,6 +197,8 @@ describe("browser control server", () => {

    testPort = await getFreePort();
    _cdpBaseUrl = `http://127.0.0.1:${testPort + 1}`;
+    prevGatewayPort = process.env.CLAWDBOT_GATEWAY_PORT;
+    process.env.CLAWDBOT_GATEWAY_PORT = String(testPort - 2);

    // Minimal CDP JSON endpoints used by the server.
    let putNewCalls = 0;
@@ -248,6 +250,11 @@ describe("browser control server", () => {
  afterEach(async () => {
    vi.unstubAllGlobals();
    vi.restoreAllMocks();
+    if (prevGatewayPort === undefined) {
+      delete process.env.CLAWDBOT_GATEWAY_PORT;
+    } else {
+      process.env.CLAWDBOT_GATEWAY_PORT = prevGatewayPort;
+    }
    const { stopBrowserControlServer } = await import("./server.js");
    await stopBrowserControlServer();
  });
--- a/src/browser/server.serves-status-starts-browser-requested.test.ts
+++ b/src/browser/server.serves-status-starts-browser-requested.test.ts
@@ -8,6 +8,7 @@ let _cdpBaseUrl = "";
 let reachable = false;
 let cfgAttachOnly = false;
 let createTargetId: string | null = null;
+let prevGatewayPort: string | undefined;

 const cdpMocks = vi.hoisted(() => ({
  createTargetViaCdp: vi.fn(async () => {
@@ -88,7 +89,6 @@ vi.mock("../config/config.js", async (importOriginal) => {
    loadConfig: () => ({
      browser: {
        enabled: true,
-        controlUrl: `http://127.0.0.1:${testPort}`,
        color: "#FF4500",
        attachOnly: cfgAttachOnly,
        headless: true,
@@ -197,6 +197,8 @@ describe("browser control server", () => {

    testPort = await getFreePort();
    _cdpBaseUrl = `http://127.0.0.1:${testPort + 1}`;
+    prevGatewayPort = process.env.CLAWDBOT_GATEWAY_PORT;
+    process.env.CLAWDBOT_GATEWAY_PORT = String(testPort - 2);

    // Minimal CDP JSON endpoints used by the server.
    let putNewCalls = 0;
@@ -248,6 +250,11 @@ describe("browser control server", () => {
  afterEach(async () => {
    vi.unstubAllGlobals();
    vi.restoreAllMocks();
+    if (prevGatewayPort === undefined) {
+      delete process.env.CLAWDBOT_GATEWAY_PORT;
+    } else {
+      process.env.CLAWDBOT_GATEWAY_PORT = prevGatewayPort;
+    }
    const { stopBrowserControlServer } = await import("./server.js");
    await stopBrowserControlServer();
  });
--- a/src/browser/server.skips-default-maxchars-explicitly-set-zero.test.ts
+++ b/src/browser/server.skips-default-maxchars-explicitly-set-zero.test.ts
@@ -8,6 +8,7 @@ let cdpBaseUrl = "";
 let reachable = false;
 let cfgAttachOnly = false;
 let createTargetId: string | null = null;
+let prevGatewayPort: string | undefined;

 const cdpMocks = vi.hoisted(() => ({
  createTargetViaCdp: vi.fn(async () => {
@@ -88,7 +89,6 @@ vi.mock("../config/config.js", async (importOriginal) => {
    loadConfig: () => ({
      browser: {
        enabled: true,
-        controlUrl: `http://127.0.0.1:${testPort}`,
        color: "#FF4500",
        attachOnly: cfgAttachOnly,
        headless: true,
@@ -197,6 +197,8 @@ describe("browser control server", () => {

    testPort = await getFreePort();
    cdpBaseUrl = `http://127.0.0.1:${testPort + 1}`;
+    prevGatewayPort = process.env.CLAWDBOT_GATEWAY_PORT;
+    process.env.CLAWDBOT_GATEWAY_PORT = String(testPort - 2);

    // Minimal CDP JSON endpoints used by the server.
    let putNewCalls = 0;
@@ -248,6 +250,11 @@ describe("browser control server", () => {
  afterEach(async () => {
    vi.unstubAllGlobals();
    vi.restoreAllMocks();
+    if (prevGatewayPort === undefined) {
+      delete process.env.CLAWDBOT_GATEWAY_PORT;
+    } else {
+      process.env.CLAWDBOT_GATEWAY_PORT = prevGatewayPort;
+    }
    const { stopBrowserControlServer } = await import("./server.js");
    await stopBrowserControlServer();
  });
@@ -394,8 +401,6 @@ describe("browser control server", () => {
    const bridge = await startBrowserBridgeServer({
      resolved: {
        enabled: true,
-        controlUrl: "http://127.0.0.1:0",
-        controlHost: "127.0.0.1",
        controlPort: 0,
        cdpProtocol: "http",
        cdpHost: "127.0.0.1",
--- a/src/browser/server.ts
+++ b/src/browser/server.ts
@@ -3,9 +3,10 @@ import express from "express";

 import { loadConfig } from "../config/config.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
-import { resolveBrowserConfig, resolveProfile, shouldStartLocalBrowserServer } from "./config.js";
+import { resolveBrowserConfig, resolveProfile } from "./config.js";
 import { ensureChromeExtensionRelayServer } from "./extension-relay.js";
 import { registerBrowserRoutes } from "./routes/index.js";
+import type { BrowserRouteRegistrar } from "./routes/types.js";
 import { type BrowserServerState, createBrowserRouteContext } from "./server-context.js";

 let state: BrowserServerState | null = null;
@@ -16,23 +17,16 @@ export async function startBrowserControlServerFromConfig(): Promise<BrowserServ
  if (state) return state;

  const cfg = loadConfig();
-  const resolved = resolveBrowserConfig(cfg.browser);
+  const resolved = resolveBrowserConfig(cfg.browser, cfg);
  if (!resolved.enabled) return null;

-  if (!shouldStartLocalBrowserServer(resolved)) {
-    logServer.info(
-      `browser control URL is non-loopback (${resolved.controlUrl}); skipping local server start`,
-    );
-    return null;
-  }
-
  const app = express();
  app.use(express.json({ limit: "1mb" }));

  const ctx = createBrowserRouteContext({
    getState: () => state,
  });
-  registerBrowserRoutes(app, ctx);
+  registerBrowserRoutes(app as unknown as BrowserRouteRegistrar, ctx);

  const port = resolved.controlPort;
  const server = await new Promise<Server>((resolve, reject) => {
@@ -89,9 +83,11 @@ export async function stopBrowserControlServer(): Promise<void> {
    logServer.warn(`clawd browser stop failed: ${String(err)}`);
  }

-  await new Promise<void>((resolve) => {
-    current.server.close(() => resolve());
-  });
+  if (current.server) {
+    await new Promise<void>((resolve) => {
+      current.server?.close(() => resolve());
+    });
+  }
  state = null;

  // Optional: Playwright is not always available (e.g. embedded gateway builds).