refactor: serve canvas host on gateway port

2025-12-20 17:13:36 +01:00
parent ba85f4a62a
commit 65329496a7
21 changed files with 404 additions and 153 deletions
--- a/src/canvas-host/a2ui.ts
+++ b/src/canvas-host/a2ui.ts
@@ -6,7 +6,8 @@ import { fileURLToPath } from "node:url";
 import { detectMime } from "../media/mime.js";

 export const A2UI_PATH = "/__clawdis__/a2ui";
-const WS_PATH = "/__clawdis/ws";
+export const CANVAS_HOST_PATH = "/__clawdis__/canvas";
+export const CANVAS_WS_PATH = "/__clawdis/ws";

 let cachedA2uiRootReal: string | null | undefined;
 let resolvingA2uiRoot: Promise<string | null> | null = null;
@@ -132,7 +133,7 @@ export function injectCanvasLiveReload(html: string): string {

  try {
    const proto = location.protocol === "https:" ? "wss" : "ws";
-    const ws = new WebSocket(proto + "://" + location.host + ${JSON.stringify(WS_PATH)});
+    const ws = new WebSocket(proto + "://" + location.host + ${JSON.stringify(CANVAS_WS_PATH)});
    ws.onmessage = (ev) => {
      if (String(ev.data || "") === "reload") location.reload();
    };
--- a/src/canvas-host/server.test.ts
+++ b/src/canvas-host/server.test.ts
@@ -1,16 +1,22 @@
+import { createServer } from "node:http";
+import { type AddressInfo } from "node:net";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
 import { WebSocket } from "ws";
 import { defaultRuntime } from "../runtime.js";
-import { startCanvasHost } from "./server.js";
-import { injectCanvasLiveReload } from "./a2ui.js";
+import { createCanvasHostHandler, startCanvasHost } from "./server.js";
+import {
+  CANVAS_HOST_PATH,
+  CANVAS_WS_PATH,
+  injectCanvasLiveReload,
+} from "./a2ui.js";

 describe("canvas host", () => {
  it("injects live reload script", () => {
    const out = injectCanvasLiveReload("<html><body>Hello</body></html>");
-    expect(out).toContain("/__clawdis/ws");
+    expect(out).toContain(CANVAS_WS_PATH);
    expect(out).toContain("location.reload");
    expect(out).toContain("clawdisCanvasA2UIAction");
    expect(out).toContain("clawdisSendUserAction");
@@ -33,13 +39,66 @@ describe("canvas host", () => {
      expect(res.status).toBe(200);
      expect(html).toContain("Interactive test page");
      expect(html).toContain("clawdisSendUserAction");
-      expect(html).toContain("/__clawdis/ws");
+      expect(html).toContain(CANVAS_WS_PATH);
    } finally {
      await server.close();
      await fs.rm(dir, { recursive: true, force: true });
    }
  });

+  it("serves canvas content from the mounted base path", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdis-canvas-"));
+    await fs.writeFile(
+      path.join(dir, "index.html"),
+      "<html><body>v1</body></html>",
+      "utf8",
+    );
+
+    const handler = await createCanvasHostHandler({
+      runtime: defaultRuntime,
+      rootDir: dir,
+      basePath: CANVAS_HOST_PATH,
+      allowInTests: true,
+    });
+
+    const server = createServer((req, res) => {
+      void (async () => {
+        if (await handler.handleHttpRequest(req, res)) return;
+        res.statusCode = 404;
+        res.setHeader("Content-Type", "text/plain; charset=utf-8");
+        res.end("Not Found");
+      })();
+    });
+    server.on("upgrade", (req, socket, head) => {
+      if (handler.handleUpgrade(req, socket, head)) return;
+      socket.destroy();
+    });
+
+    await new Promise<void>((resolve) =>
+      server.listen(0, "127.0.0.1", resolve),
+    );
+    const port = (server.address() as AddressInfo).port;
+
+    try {
+      const res = await fetch(
+        `http://127.0.0.1:${port}${CANVAS_HOST_PATH}/`,
+      );
+      const html = await res.text();
+      expect(res.status).toBe(200);
+      expect(html).toContain("v1");
+      expect(html).toContain(CANVAS_WS_PATH);
+
+      const miss = await fetch(`http://127.0.0.1:${port}/`);
+      expect(miss.status).toBe(404);
+    } finally {
+      await handler.close();
+      await new Promise<void>((resolve, reject) =>
+        server.close((err) => (err ? reject(err) : resolve())),
+      );
+      await fs.rm(dir, { recursive: true, force: true });
+    }
+  });
+
  it("serves HTML with injection and broadcasts reload on file changes", async () => {
    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdis-canvas-"));
    const index = path.join(dir, "index.html");
@@ -58,9 +117,11 @@ describe("canvas host", () => {
      const html = await res.text();
      expect(res.status).toBe(200);
      expect(html).toContain("v1");
-      expect(html).toContain("/__clawdis/ws");
+      expect(html).toContain(CANVAS_WS_PATH);

-      const ws = new WebSocket(`ws://127.0.0.1:${server.port}/__clawdis/ws`);
+      const ws = new WebSocket(
+        `ws://127.0.0.1:${server.port}${CANVAS_WS_PATH}`,
+      );
      await new Promise<void>((resolve, reject) => {
        const timer = setTimeout(
          () => reject(new Error("ws open timeout")),
--- a/src/canvas-host/server.ts
+++ b/src/canvas-host/server.ts
@@ -1,15 +1,24 @@
 import fs from "node:fs/promises";
-import http, { type Server } from "node:http";
+import http, {
+  type IncomingMessage,
+  type Server,
+  type ServerResponse,
+} from "node:http";
+import type { Socket } from "node:net";
 import os from "node:os";
 import path from "node:path";

 import chokidar from "chokidar";
-import express from "express";
 import { type WebSocket, WebSocketServer } from "ws";
 import { detectMime } from "../media/mime.js";
 import type { RuntimeEnv } from "../runtime.js";
 import { ensureDir, resolveUserPath } from "../utils.js";
-import { handleA2uiHttpRequest, injectCanvasLiveReload } from "./a2ui.js";
+import {
+  CANVAS_HOST_PATH,
+  CANVAS_WS_PATH,
+  handleA2uiHttpRequest,
+  injectCanvasLiveReload,
+} from "./a2ui.js";

 export type CanvasHostOpts = {
  runtime: RuntimeEnv;
@@ -25,7 +34,23 @@ export type CanvasHostServer = {
  close: () => Promise<void>;
 };

-const WS_PATH = "/__clawdis/ws";
+export type CanvasHostHandlerOpts = {
+  runtime: RuntimeEnv;
+  rootDir?: string;
+  basePath?: string;
+  allowInTests?: boolean;
+};
+
+export type CanvasHostHandler = {
+  rootDir: string;
+  basePath: string;
+  handleHttpRequest: (
+    req: IncomingMessage,
+    res: ServerResponse,
+  ) => Promise<boolean>;
+  handleUpgrade: (req: IncomingMessage, socket: Socket, head: Buffer) => boolean;
+  close: () => Promise<void>;
+};

 function defaultIndexHTML() {
  return `<!doctype html>
@@ -153,16 +178,14 @@ function isDisabledByEnv() {
  return false;
 }

-export async function startCanvasHost(
-  opts: CanvasHostOpts,
-): Promise<CanvasHostServer> {
-  if (isDisabledByEnv() && opts.allowInTests !== true) {
-    return { port: 0, rootDir: "", close: async () => {} };
-  }
+function normalizeBasePath(rawPath: string | undefined) {
+  const trimmed = (rawPath ?? CANVAS_HOST_PATH).trim();
+  const normalized = normalizeUrlPath(trimmed || CANVAS_HOST_PATH);
+  if (normalized === "/") return "/";
+  return normalized.replace(/\/+$/, "");
+}

-  const rootDir = resolveUserPath(
-    opts.rootDir ?? path.join(os.homedir(), "clawd", "canvas"),
-  );
+async function prepareCanvasRoot(rootDir: string) {
  await ensureDir(rootDir);
  const rootReal = await fs.realpath(rootDir);
  try {
@@ -179,58 +202,29 @@ export async function startCanvasHost(
      // ignore; we'll still serve the "missing file" message if needed.
    }
  }
+  return rootReal;
+}

-  const bindHost = opts.listenHost?.trim() || "0.0.0.0";
-  const app = express();
-  app.disable("x-powered-by");
+export async function createCanvasHostHandler(
+  opts: CanvasHostHandlerOpts,
+): Promise<CanvasHostHandler> {
+  const basePath = normalizeBasePath(opts.basePath);
+  if (isDisabledByEnv() && opts.allowInTests !== true) {
+    return {
+      rootDir: "",
+      basePath,
+      handleHttpRequest: async () => false,
+      handleUpgrade: () => false,
+      close: async () => {},
+    };
+  }

-  app.get(/.*/, async (req, res) => {
-    try {
-      const url = new URL(req.url ?? "/", "http://localhost");
-      if (url.pathname === WS_PATH) {
-        res.status(426).send("upgrade required");
-        return;
-      }
+  const rootDir = resolveUserPath(
+    opts.rootDir ?? path.join(os.homedir(), "clawd", "canvas"),
+  );
+  const rootReal = await prepareCanvasRoot(rootDir);

-      if (await handleA2uiHttpRequest(req, res)) return;
-
-      const filePath = await resolveFilePath(rootReal, url.pathname);
-      if (!filePath) {
-        if (url.pathname === "/" || url.pathname.endsWith("/")) {
-          res
-            .status(404)
-            .type("text/html")
-            .send(
-              `<!doctype html><meta charset="utf-8" /><title>Clawdis Canvas</title><pre>Missing file.\nCreate ${rootDir}/index.html</pre>`,
-            );
-          return;
-        }
-        res.status(404).send("not found");
-        return;
-      }
-
-      const lower = filePath.toLowerCase();
-      const mime =
-        lower.endsWith(".html") || lower.endsWith(".htm")
-          ? "text/html"
-          : (detectMime({ filePath }) ?? "application/octet-stream");
-
-      res.setHeader("Cache-Control", "no-store");
-      if (mime === "text/html") {
-        const html = await fs.readFile(filePath, "utf8");
-        res.type("text/html; charset=utf-8").send(injectCanvasLiveReload(html));
-        return;
-      }
-
-      res.type(mime).send(await fs.readFile(filePath));
-    } catch (err) {
-      opts.runtime.error(`canvasHost request failed: ${String(err)}`);
-      res.status(500).send("error");
-    }
-  });
-
-  const server: Server = http.createServer(app);
-  const wss = new WebSocketServer({ server, path: WS_PATH });
+  const wss = new WebSocketServer({ noServer: true });
  const sockets = new Set<WebSocket>();
  wss.on("connection", (ws) => {
    sockets.add(ws);
@@ -266,6 +260,143 @@ export async function startCanvasHost(
  });
  watcher.on("all", () => scheduleReload());

+  const handleUpgrade = (
+    req: IncomingMessage,
+    socket: Socket,
+    head: Buffer,
+  ) => {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    if (url.pathname !== CANVAS_WS_PATH) return false;
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      wss.emit("connection", ws, req);
+    });
+    return true;
+  };
+
+  const handleHttpRequest = async (
+    req: IncomingMessage,
+    res: ServerResponse,
+  ) => {
+    const urlRaw = req.url;
+    if (!urlRaw) return false;
+
+    try {
+      const url = new URL(urlRaw, "http://localhost");
+      if (url.pathname === CANVAS_WS_PATH) {
+        res.statusCode = 426;
+        res.setHeader("Content-Type", "text/plain; charset=utf-8");
+        res.end("upgrade required");
+        return true;
+      }
+
+      let urlPath = url.pathname;
+      if (basePath !== "/") {
+        if (urlPath === basePath) {
+          urlPath = "/";
+        } else if (urlPath.startsWith(`${basePath}/`)) {
+          urlPath = urlPath.slice(basePath.length) || "/";
+        } else {
+          return false;
+        }
+      }
+
+      if (req.method !== "GET" && req.method !== "HEAD") {
+        res.statusCode = 405;
+        res.setHeader("Content-Type", "text/plain; charset=utf-8");
+        res.end("Method Not Allowed");
+        return true;
+      }
+
+      const filePath = await resolveFilePath(rootReal, urlPath);
+      if (!filePath) {
+        if (urlPath === "/" || urlPath.endsWith("/")) {
+          res.statusCode = 404;
+          res.setHeader("Content-Type", "text/html; charset=utf-8");
+          res.end(
+            `<!doctype html><meta charset="utf-8" /><title>Clawdis Canvas</title><pre>Missing file.\nCreate ${rootDir}/index.html</pre>`,
+          );
+          return true;
+        }
+        res.statusCode = 404;
+        res.setHeader("Content-Type", "text/plain; charset=utf-8");
+        res.end("not found");
+        return true;
+      }
+
+      const lower = filePath.toLowerCase();
+      const mime =
+        lower.endsWith(".html") || lower.endsWith(".htm")
+          ? "text/html"
+          : (detectMime({ filePath }) ?? "application/octet-stream");
+
+      res.setHeader("Cache-Control", "no-store");
+      if (mime === "text/html") {
+        const html = await fs.readFile(filePath, "utf8");
+        res.setHeader("Content-Type", "text/html; charset=utf-8");
+        res.end(injectCanvasLiveReload(html));
+        return true;
+      }
+
+      res.setHeader("Content-Type", mime);
+      res.end(await fs.readFile(filePath));
+      return true;
+    } catch (err) {
+      opts.runtime.error(`canvasHost request failed: ${String(err)}`);
+      res.statusCode = 500;
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.end("error");
+      return true;
+    }
+  };
+
+  return {
+    rootDir,
+    basePath,
+    handleHttpRequest,
+    handleUpgrade,
+    close: async () => {
+      if (debounce) clearTimeout(debounce);
+      await watcher.close().catch(() => {});
+      await new Promise<void>((resolve) => wss.close(() => resolve()));
+    },
+  };
+}
+
+export async function startCanvasHost(
+  opts: CanvasHostOpts,
+): Promise<CanvasHostServer> {
+  if (isDisabledByEnv() && opts.allowInTests !== true) {
+    return { port: 0, rootDir: "", close: async () => {} };
+  }
+
+  const handler = await createCanvasHostHandler({
+    runtime: opts.runtime,
+    rootDir: opts.rootDir,
+    basePath: "/",
+    allowInTests: opts.allowInTests,
+  });
+
+  const bindHost = opts.listenHost?.trim() || "0.0.0.0";
+  const server: Server = http.createServer((req, res) => {
+    if (String(req.headers.upgrade ?? "").toLowerCase() === "websocket") return;
+    void (async () => {
+      if (await handleA2uiHttpRequest(req, res)) return;
+      if (await handler.handleHttpRequest(req, res)) return;
+      res.statusCode = 404;
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.end("Not Found");
+    })().catch((err) => {
+      opts.runtime.error(`canvasHost request failed: ${String(err)}`);
+      res.statusCode = 500;
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.end("error");
+    });
+  });
+  server.on("upgrade", (req, socket, head) => {
+    if (handler.handleUpgrade(req, socket, head)) return;
+    socket.destroy();
+  });
+
  const listenPort =
    typeof opts.port === "number" && Number.isFinite(opts.port) && opts.port > 0
      ? opts.port
@@ -287,16 +418,14 @@ export async function startCanvasHost(
  const addr = server.address();
  const boundPort = typeof addr === "object" && addr ? addr.port : 0;
  opts.runtime.log(
-    `canvas host listening on http://${bindHost}:${boundPort} (root ${rootDir})`,
+    `canvas host listening on http://${bindHost}:${boundPort} (root ${handler.rootDir})`,
  );

  return {
    port: boundPort,
-    rootDir,
+    rootDir: handler.rootDir,
    close: async () => {
-      if (debounce) clearTimeout(debounce);
-      await watcher.close().catch(() => {});
-      await new Promise<void>((resolve) => wss.close(() => resolve()));
+      await handler.close();
      await new Promise<void>((resolve, reject) =>
        server.close((err) => (err ? reject(err) : resolve())),
      );
--- a/src/config/config.ts
+++ b/src/config/config.ts
@@ -97,7 +97,7 @@ export type CanvasHostConfig = {
  enabled?: boolean;
  /** Directory to serve (default: ~/clawd/canvas). */
  root?: string;
-  /** HTTP port to listen on (default: 18793). */
+  /** HTTP port to listen on (deprecated; Gateway port is used). */
  port?: number;
 };

@@ -135,6 +135,11 @@ export type SkillsLoadConfig = {
  extraDirs?: string[];
 };

+export type SkillsInstallConfig = {
+  preferBrew?: boolean;
+  nodeManager?: "npm" | "pnpm" | "bun";
+};
+
 export type ClawdisConfig = {
  identity?: {
    name?: string;
@@ -185,6 +190,7 @@ export type ClawdisConfig = {
  canvasHost?: CanvasHostConfig;
  gateway?: GatewayConfig;
  skills?: Record<string, SkillConfig>;
+  skillsInstall?: SkillsInstallConfig;
 };

 // New branding path (preferred)
@@ -371,6 +377,14 @@ const ClawdisSchema = z.object({
      extraDirs: z.array(z.string()).optional(),
    })
    .optional(),
+  skillsInstall: z
+    .object({
+      preferBrew: z.boolean().optional(),
+      nodeManager: z
+        .union([z.literal("npm"), z.literal("pnpm"), z.literal("bun")])
+        .optional(),
+    })
+    .optional(),
  skills: z
    .record(
      z.string(),
--- a/src/gateway/server.test.ts
+++ b/src/gateway/server.test.ts
@@ -1564,14 +1564,17 @@ describe("gateway server", () => {
    await server.close();
  });

-  test("hello-ok prefers gateway port for A2UI when tailnet present", async () => {
+  test("hello-ok advertises the gateway port for canvas host", async () => {
    const prevToken = process.env.CLAWDIS_GATEWAY_TOKEN;
    process.env.CLAWDIS_GATEWAY_TOKEN = "secret";
    testTailnetIPv4.value = "100.64.0.1";
    testGatewayBind = "lan";

    const port = await getFreePort();
-    const server = await startGatewayServer(port, { bind: "lan" });
+    const server = await startGatewayServer(port, {
+      bind: "lan",
+      allowCanvasHostInTests: true,
+    });
    const ws = new WebSocket(`ws://127.0.0.1:${port}`, {
      headers: { Host: `100.64.0.1:${port}` },
    });
--- a/src/gateway/server.ts
+++ b/src/gateway/server.ts
@@ -18,11 +18,11 @@ import {
  normalizeThinkLevel,
  normalizeVerboseLevel,
 } from "../auto-reply/thinking.js";
+import { handleA2uiHttpRequest, CANVAS_HOST_PATH } from "../canvas-host/a2ui.js";
 import {
-  type CanvasHostServer,
-  startCanvasHost,
+  type CanvasHostHandler,
+  createCanvasHostHandler,
 } from "../canvas-host/server.js";
-import { handleA2uiHttpRequest } from "../canvas-host/a2ui.js";
 import { createDefaultDeps } from "../cli/deps.js";
 import { agentCommand } from "../commands/agent.js";
 import { getHealthSnapshot, type HealthSummary } from "../commands/health.js";
@@ -339,6 +339,10 @@ export type GatewayServerOptions = {
   * Default: config `gateway.controlUi.enabled` (or true when absent).
   */
  controlUiEnabled?: boolean;
+  /**
+   * Test-only: allow canvas host startup even when NODE_ENV/VITEST would disable it.
+   */
+  allowCanvasHostInTests?: boolean;
 };

 function isLoopbackAddress(ip: string | undefined): boolean {
@@ -1000,31 +1004,54 @@ export async function startGatewayServer(
  port = 18789,
  opts: GatewayServerOptions = {},
 ): Promise<GatewayServer> {
-  const cfgForServer = loadConfig();
-  const bindMode = opts.bind ?? cfgForServer.gateway?.bind ?? "loopback";
+  const cfgAtStart = loadConfig();
+  const bindMode = opts.bind ?? cfgAtStart.gateway?.bind ?? "loopback";
  const bindHost = opts.host ?? resolveGatewayBindHost(bindMode);
  if (!bindHost) {
    throw new Error(
      "gateway bind is tailnet, but no tailnet interface was found; refusing to start gateway",
    );
  }
-  const tailnetIPv4 = pickPrimaryTailnetIPv4();
-  const tailnetIPv6 = pickPrimaryTailnetIPv6();
-  const hasTailnet = Boolean(tailnetIPv4 || tailnetIPv6);
  const controlUiEnabled =
-    opts.controlUiEnabled ?? cfgForServer.gateway?.controlUi?.enabled ?? true;
+    opts.controlUiEnabled ?? cfgAtStart.gateway?.controlUi?.enabled ?? true;
+  const canvasHostEnabled =
+    process.env.CLAWDIS_SKIP_CANVAS_HOST !== "1" &&
+    cfgAtStart.canvasHost?.enabled !== false;
  if (!isLoopbackHost(bindHost) && !getGatewayToken()) {
    throw new Error(
      `refusing to bind gateway to ${bindHost}:${port} without CLAWDIS_GATEWAY_TOKEN`,
    );
  }

+  let canvasHost: CanvasHostHandler | null = null;
+  if (canvasHostEnabled) {
+    try {
+      const handler = await createCanvasHostHandler({
+        runtime: defaultRuntime,
+        rootDir: cfgAtStart.canvasHost?.root,
+        basePath: CANVAS_HOST_PATH,
+        allowInTests: opts.allowCanvasHostInTests,
+      });
+      if (handler.rootDir) {
+        canvasHost = handler;
+        defaultRuntime.log(
+          `canvas host mounted at http://${bindHost}:${port}${CANVAS_HOST_PATH}/ (root ${handler.rootDir})`,
+        );
+      }
+    } catch (err) {
+      logWarn(`gateway: canvas host failed to start: ${String(err)}`);
+    }
+  }
+
  const httpServer: HttpServer = createHttpServer((req, res) => {
    // Don't interfere with WebSocket upgrades; ws handles the 'upgrade' event.
    if (String(req.headers.upgrade ?? "").toLowerCase() === "websocket") return;

    void (async () => {
-      if (await handleA2uiHttpRequest(req, res)) return;
+      if (canvasHost) {
+        if (await handleA2uiHttpRequest(req, res)) return;
+        if (await canvasHost.handleHttpRequest(req, res)) return;
+      }
      if (controlUiEnabled) {
        if (handleControlUiHttpRequest(req, res)) return;
      }
@@ -1040,7 +1067,6 @@ export async function startGatewayServer(
  });
  let bonjourStop: (() => Promise<void>) | null = null;
  let bridge: Awaited<ReturnType<typeof startNodeBridgeServer>> | null = null;
-  let canvasHost: CanvasHostServer | null = null;
  const bridgeNodeSubscriptions = new Map<string, Set<string>>();
  const bridgeSessionSubscribers = new Map<string, Set<string>>();
  try {
@@ -1072,9 +1098,15 @@ export async function startGatewayServer(
  }

  const wss = new WebSocketServer({
-    server: httpServer,
+    noServer: true,
    maxPayload: MAX_PAYLOAD_BYTES,
  });
+  httpServer.on("upgrade", (req, socket, head) => {
+    if (canvasHost?.handleUpgrade(req, socket, head)) return;
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      wss.emit("connection", ws, req);
+    });
+  });
  const providerAbort = new AbortController();
  const providerTasks: Array<Promise<unknown>> = [];
  const clients = new Set<Client>();
@@ -1093,27 +1125,8 @@ export async function startGatewayServer(
    string,
    { controller: AbortController; sessionId: string; sessionKey: string }
  >();
-  const cfgAtStart = loadConfig();
  setCommandLaneConcurrency("cron", cfgAtStart.cron?.maxConcurrentRuns ?? 1);

-  const canvasHostEnabled =
-    process.env.CLAWDIS_SKIP_CANVAS_HOST !== "1" &&
-    cfgAtStart.canvasHost?.enabled !== false;
-  const preferGatewayA2uiHost = hasTailnet && !isLoopbackHost(bindHost);
-
-  if (canvasHostEnabled) {
-    try {
-      const server = await startCanvasHost({
-        runtime: defaultRuntime,
-        rootDir: cfgAtStart.canvasHost?.root,
-        port: cfgAtStart.canvasHost?.port ?? 18793,
-      });
-      if (server.port > 0) canvasHost = server;
-    } catch (err) {
-      logWarn(`gateway: canvas host failed to start: ${String(err)}`);
-    }
-  }
-
  const cronStorePath = resolveCronStorePath(cfgAtStart.cron?.store);
  const cronLogger = getChildLogger({
    module: "cron",
@@ -2065,6 +2078,11 @@ export async function startGatewayServer(
  };

  const machineDisplayName = await getMachineDisplayName();
+  const bridgeHostIsLoopback = bridgeHost ? isLoopbackHost(bridgeHost) : false;
+  const canvasHostPortForBridge =
+    canvasHost && (!isLoopbackHost(bindHost) || bridgeHostIsLoopback)
+      ? port
+      : undefined;

  if (bridgeEnabled && bridgePort > 0 && bridgeHost) {
    try {
@@ -2072,7 +2090,7 @@ export async function startGatewayServer(
        host: bridgeHost,
        port: bridgePort,
        serverName: machineDisplayName,
-        canvasHostPort: preferGatewayA2uiHost ? port : canvasHost?.port,
+        canvasHostPort: canvasHostPortForBridge,
        onRequest: (nodeId, req) => handleBridgeRequest(nodeId, req),
        onAuthenticated: async (node) => {
          const host = node.displayName?.trim() || node.nodeId;
@@ -2188,7 +2206,7 @@ export async function startGatewayServer(
      instanceName: formatBonjourInstanceName(machineDisplayName),
      gatewayPort: port,
      bridgePort: bridge?.port,
-      canvasPort: canvasHost?.port,
+      canvasPort: canvasHostPortForBridge,
      sshPort,
      tailnetDns,
      cliPath: resolveBonjourCliPath(),
@@ -2362,10 +2380,7 @@ export async function startGatewayServer(
    const remoteAddr = (
      socket as WebSocket & { _socket?: { remoteAddress?: string } }
    )._socket?.remoteAddress;
-    const canvasHostUrl = deriveCanvasHostUrl(
-      req,
-      preferGatewayA2uiHost ? port : canvasHost?.port,
-    );
+    const canvasHostUrl = deriveCanvasHostUrl(req, canvasHost ? port : undefined);
    logWs("in", "open", { connId, remoteAddr });
    const isWebchatConnect = (params: ConnectParams | null | undefined) =>
      params?.client?.mode === "webchat" ||
@@ -3255,6 +3270,7 @@ export async function startGatewayServer(
                skillName: p.name,
                installId: p.installId,
                timeoutMs: p.timeoutMs,
+                config: cfg,
              });
              respond(
                result.ok,