@vellumai/cli 0.8.12-dev.202606152248.70317d3 → 0.8.12-dev.202606152340.7efde97

package/node_modules/@vellumai/local-mode/src/__tests__/status.test.ts

@@ -0,0 +1,224 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import { createServer, type Server } from "node:http";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { getLocalAssistantStatus } from "../status";
+
+let tempDir: string;
+let lockfilePath: string;
+let instanceDir: string;
+
+function writeLockfile(entry: Record<string, unknown>): void {
+  writeFileSync(
+    lockfilePath,
+    JSON.stringify({
+      assistants: [entry],
+      activeAssistant: entry.assistantId,
+    }),
+  );
+}
+
+function writeLocalLockfile(overrides: Record<string, unknown> = {}): void {
+  writeLockfile({
+    assistantId: "local-1",
+    cloud: "local",
+    resources: {
+      instanceDir,
+      daemonPort: 30101,
+      gatewayPort: 30102,
+      qdrantPort: 30103,
+    },
+    ...overrides,
+  });
+}
+
+function writeAssistantPid(value: string): string {
+  const pidDir = path.join(instanceDir, ".vellum", "workspace");
+  mkdirSync(pidDir, { recursive: true });
+  const pidPath = path.join(pidDir, "vellum.pid");
+  writeFileSync(pidPath, value);
+  return pidPath;
+}
+
+function markStale(filePath: string): void {
+  const stale = new Date(Date.now() - 120_000);
+  utimesSync(filePath, stale, stale);
+}
+
+function listen(server: Server, port = 0): Promise<number> {
+  return new Promise((resolve) => {
+    server.listen(port, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        throw new Error("expected TCP server address");
+      }
+      resolve(address.port);
+    });
+  });
+}
+
+function close(server: Server): Promise<void> {
+  return new Promise((resolve, reject) => {
+    server.close((err) => (err ? reject(err) : resolve()));
+  });
+}
+
+async function unusedPort(): Promise<number> {
+  const server = createServer();
+  const port = await listen(server);
+  await close(server);
+  return port;
+}
+
+beforeEach(() => {
+  tempDir = path.join(
+    tmpdir(),
+    `vellum-local-status-test-${Date.now()}-${Math.random()}`,
+  );
+  mkdirSync(tempDir, { recursive: true });
+  lockfilePath = path.join(tempDir, "lockfile.json");
+  instanceDir = path.join(tempDir, "instance");
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe("getLocalAssistantStatus", () => {
+  test("returns sleeping when the assistant PID file is absent", async () => {
+    writeLocalLockfile();
+
+    expect(await getLocalAssistantStatus([lockfilePath], "local-1")).toEqual({
+      ok: true,
+      state: "sleeping",
+    });
+  });
+
+  test("returns sleeping for legacy local entries without cloud/resources", async () => {
+    writeLockfile({
+      assistantId: "legacy-local",
+      baseDataDir: instanceDir,
+      runtimeUrl: "http://127.0.0.1:30102",
+    });
+
+    expect(
+      await getLocalAssistantStatus([lockfilePath], "legacy-local"),
+    ).toEqual({
+      ok: true,
+      state: "sleeping",
+    });
+  });
+
+  test("returns sleeping when the assistant PID file points at a dead process", async () => {
+    writeLocalLockfile();
+    writeAssistantPid("999999999");
+
+    const result = await getLocalAssistantStatus([lockfilePath], "local-1");
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.state).toBe("sleeping");
+    }
+  });
+
+  test("returns crashed when the assistant PID file is invalid", async () => {
+    writeLocalLockfile();
+    writeAssistantPid("not-a-pid");
+
+    const result = await getLocalAssistantStatus([lockfilePath], "local-1");
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.state).toBe("crashed");
+      expect(result.detail).toContain("PID file");
+    }
+  });
+
+  test("returns starting when a fresh assistant PID is alive but health is not ready yet", async () => {
+    writeLocalLockfile({
+      resources: {
+        instanceDir,
+        daemonPort: await unusedPort(),
+        gatewayPort: 30102,
+        qdrantPort: 30103,
+      },
+    });
+    writeAssistantPid(String(process.pid));
+
+    const result = await getLocalAssistantStatus([lockfilePath], "local-1");
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.state).toBe("starting");
+      expect(result.pid).toBe(process.pid);
+    }
+  });
+
+  test("returns crashed when an old live assistant PID is still not responding", async () => {
+    writeLocalLockfile({
+      resources: {
+        instanceDir,
+        daemonPort: await unusedPort(),
+        gatewayPort: 30102,
+        qdrantPort: 30103,
+      },
+    });
+    const pidPath = writeAssistantPid(String(process.pid));
+    markStale(pidPath);
+
+    const result = await getLocalAssistantStatus([lockfilePath], "local-1");
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.state).toBe("crashed");
+      expect(result.detail).toContain("not responding");
+    }
+  });
+
+  test("returns starting while the gateway is coming up for a freshly started assistant", async () => {
+    const server = createServer((_req, res) => {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ status: "healthy" }));
+    });
+    const daemonPort = await listen(server);
+    try {
+      writeLocalLockfile({
+        resources: {
+          instanceDir,
+          daemonPort,
+          gatewayPort: await unusedPort(),
+          qdrantPort: 30103,
+        },
+      });
+      writeAssistantPid(String(process.pid));
+
+      const result = await getLocalAssistantStatus([lockfilePath], "local-1");
+
+      expect(result.ok).toBe(true);
+      if (result.ok) {
+        expect(result.state).toBe("starting");
+        expect(result.pid).toBe(process.pid);
+      }
+    } finally {
+      await close(server);
+    }
+  });
+
+  test("rejects non-local assistants", async () => {
+    writeLockfile({
+      assistantId: "platform-1",
+      cloud: "vellum",
+      runtimeUrl: "https://example.com",
+    });
+
+    expect(await getLocalAssistantStatus([lockfilePath], "platform-1")).toEqual(
+      {
+        ok: false,
+        status: 404,
+        error: "Local assistant not found",
+      },
+    );
+  });
+});

package/node_modules/@vellumai/local-mode/src/index.ts

@@ -37,6 +37,11 @@ export { runRetire } from "./retire";
 export type { RetireResult } from "./retire";
 export { runWake } from "./wake";
 export type { WakeOptions, WakeResult } from "./wake";
+export { getLocalAssistantStatus } from "./status";
+export type {
+  LocalAssistantRuntimeState,
+  LocalAssistantStatusResult,
+} from "./status";
 export { getGuardianAccessToken } from "./guardian-token";
 export type { TokenResult } from "./guardian-token";
 export {

package/node_modules/@vellumai/local-mode/src/lockfile-contract.ts

@@ -31,6 +31,7 @@
  */
 
 export interface LocalAssistantResources {
+  instanceDir?: string;
   gatewayPort: number;
   daemonPort: number;
 }
@@ -69,7 +70,13 @@ function parseResources(value: unknown): LocalAssistantResources | undefined {
   if (!isRecord(value)) return undefined;
   if (typeof value.gatewayPort !== "number") return undefined;
   if (typeof value.daemonPort !== "number") return undefined;
-  return { gatewayPort: value.gatewayPort, daemonPort: value.daemonPort };
+  return {
+    ...(typeof value.instanceDir === "string"
+      ? { instanceDir: value.instanceDir }
+      : {}),
+    gatewayPort: value.gatewayPort,
+    daemonPort: value.daemonPort,
+  };
 }
 
 /**

package/node_modules/@vellumai/local-mode/src/status.ts

@@ -0,0 +1,342 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import os from "node:os";
+import http from "node:http";
+import path from "node:path";
+
+import { SEEDS } from "@vellumai/environments";
+
+import type {
+  LockfileAssistant,
+} from "./lockfile-contract";
+import { getLockfileData } from "./lockfile";
+
+const HEALTH_TIMEOUT_MS = 1_500;
+const STARTING_GRACE_MS = 60_000;
+const PRODUCTION_ENVIRONMENT_NAME = "production";
+const DEFAULT_PORTS = {
+  daemon: 7821,
+  gateway: 7830,
+};
+
+export type LocalAssistantRuntimeState =
+  | "healthy"
+  | "sleeping"
+  | "starting"
+  | "crashed"
+  | "unknown";
+
+export type LocalAssistantStatusResult =
+  | {
+      ok: true;
+      state: LocalAssistantRuntimeState;
+      detail?: string;
+      pid?: number;
+    }
+  | { ok: false; status: number; error: string };
+
+type PidState =
+  | { state: "missing" }
+  | { state: "starting"; updatedAtMs: number }
+  | { state: "alive"; pid: number; updatedAtMs: number }
+  | { state: "dead"; pid: number; updatedAtMs: number }
+  | { state: "invalid"; value: string; updatedAtMs: number };
+
+interface StatusResources {
+  instanceDir: string;
+  gatewayPort: number;
+  daemonPort: number;
+}
+
+function getDaemonPidPath(instanceDir: string): string {
+  return path.join(instanceDir, ".vellum", "workspace", "vellum.pid");
+}
+
+function getGatewayPidPath(instanceDir: string): string {
+  return path.join(instanceDir, ".vellum", "gateway.pid");
+}
+
+function readPidState(pidFile: string): PidState {
+  if (!existsSync(pidFile)) return { state: "missing" };
+
+  const updatedAtMs = statSync(pidFile).mtimeMs;
+  const value = readFileSync(pidFile, "utf-8").trim();
+  if (!value) return { state: "missing" };
+  if (value === "starting") return { state: "starting", updatedAtMs };
+
+  const pid = Number(value);
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return { state: "invalid", value, updatedAtMs };
+  }
+
+  try {
+    process.kill(pid, 0);
+    return { state: "alive", pid, updatedAtMs };
+  } catch {
+    return { state: "dead", pid, updatedAtMs };
+  }
+}
+
+function isFreshPidState(
+  pidState: PidState,
+  observedAtMs: number,
+): boolean {
+  return (
+    "updatedAtMs" in pidState &&
+    observedAtMs - pidState.updatedAtMs <= STARTING_GRACE_MS
+  );
+}
+
+function httpHealthCheck(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const req = http.get(
+      {
+        hostname: "127.0.0.1",
+        port,
+        path: "/healthz",
+        timeout: HEALTH_TIMEOUT_MS,
+      },
+      (res) => {
+        const chunks: Buffer[] = [];
+        res.on("data", (chunk: Buffer) => chunks.push(chunk));
+        res.on("end", () => {
+          if (res.statusCode !== 200) {
+            resolve(false);
+            return;
+          }
+
+          try {
+            const body = JSON.parse(Buffer.concat(chunks).toString()) as {
+              status?: string;
+            };
+            resolve(
+              body.status === undefined ||
+                body.status === "healthy" ||
+                body.status === "ok",
+            );
+          } catch {
+            resolve(true);
+          }
+        });
+      },
+    );
+
+    req.on("timeout", () => {
+      req.destroy();
+      resolve(false);
+    });
+    req.on("error", () => resolve(false));
+  });
+}
+
+function localOnlyEntry(
+  entry: LockfileAssistant | undefined,
+): LockfileAssistant | null {
+  if (!entry || (entry.cloud != null && entry.cloud !== "local")) return null;
+  return entry;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parsePortFromUrl(url: unknown): number | undefined {
+  if (typeof url !== "string") return undefined;
+  try {
+    const parsed = new URL(url);
+    const port = Number(parsed.port);
+    return Number.isInteger(port) && port > 0 ? port : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function defaultPorts(env: Record<string, string | undefined>): {
+  daemon: number;
+  gateway: number;
+} {
+  const envName = env.VELLUM_ENVIRONMENT?.trim() || PRODUCTION_ENVIRONMENT_NAME;
+  const seed = SEEDS[envName] ?? SEEDS[PRODUCTION_ENVIRONMENT_NAME];
+  return {
+    daemon: seed?.portsOverride?.daemon ?? DEFAULT_PORTS.daemon,
+    gateway: seed?.portsOverride?.gateway ?? DEFAULT_PORTS.gateway,
+  };
+}
+
+function defaultInstanceDir(
+  env: Record<string, string | undefined>,
+  assistantId: string,
+): string {
+  const envName = env.VELLUM_ENVIRONMENT?.trim() || PRODUCTION_ENVIRONMENT_NAME;
+  const xdgDataHome =
+    env.XDG_DATA_HOME?.trim() || path.join(os.homedir(), ".local", "share");
+  const dataRoot =
+    envName === PRODUCTION_ENVIRONMENT_NAME ? "vellum" : `vellum-${envName}`;
+  return path.join(xdgDataHome, dataRoot, "assistants", assistantId);
+}
+
+function firstString(...values: unknown[]): string | undefined {
+  for (const value of values) {
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return undefined;
+}
+
+function firstNumber(...values: unknown[]): number | undefined {
+  for (const value of values) {
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return undefined;
+}
+
+function findRawAssistant(
+  lockfilePaths: string[],
+  assistantId: string,
+): Record<string, unknown> | null {
+  for (const candidate of lockfilePaths) {
+    let data: unknown;
+    try {
+      data = JSON.parse(readFileSync(candidate, "utf-8"));
+    } catch {
+      continue;
+    }
+    if (!isRecord(data) || !Array.isArray(data.assistants)) return null;
+    const entry = data.assistants.find(
+      (assistant) =>
+        isRecord(assistant) && assistant.assistantId === assistantId,
+    );
+    return isRecord(entry) ? entry : null;
+  }
+  return null;
+}
+
+function resolveStatusResources(
+  entry: LockfileAssistant,
+  rawEntry: Record<string, unknown> | null,
+  env: Record<string, string | undefined>,
+): StatusResources {
+  const rawResources = isRecord(rawEntry?.resources)
+    ? rawEntry.resources
+    : undefined;
+  const ports = defaultPorts(env);
+  const instanceDir =
+    firstString(
+      entry.resources?.instanceDir,
+      rawResources?.instanceDir,
+      rawEntry?.baseDataDir,
+    ) ?? defaultInstanceDir(env, entry.assistantId);
+  return {
+    instanceDir,
+    daemonPort:
+      firstNumber(entry.resources?.daemonPort, rawResources?.daemonPort) ??
+      ports.daemon,
+    gatewayPort:
+      firstNumber(entry.resources?.gatewayPort, rawResources?.gatewayPort) ??
+      parsePortFromUrl(rawEntry?.localUrl) ??
+      parsePortFromUrl(rawEntry?.runtimeUrl ?? entry.runtimeUrl) ??
+      ports.gateway,
+  };
+}
+
+async function runtimeStatusForEntry(
+  entry: LockfileAssistant,
+  rawEntry: Record<string, unknown> | null,
+  env: Record<string, string | undefined>,
+): Promise<LocalAssistantStatusResult> {
+  const resources = resolveStatusResources(entry, rawEntry, env);
+  const observedAtMs = Date.now();
+
+  const assistantPid = readPidState(getDaemonPidPath(resources.instanceDir));
+  if (assistantPid.state === "missing") {
+    return { ok: true, state: "sleeping" };
+  }
+  if (assistantPid.state === "starting") {
+    return { ok: true, state: "starting" };
+  }
+  if (assistantPid.state === "dead") {
+    return { ok: true, state: "sleeping", pid: assistantPid.pid };
+  }
+  if (assistantPid.state === "invalid") {
+    return {
+      ok: true,
+      state: "crashed",
+      detail: "assistant PID file is invalid",
+    };
+  }
+
+  const assistantHealthy = await httpHealthCheck(resources.daemonPort);
+  if (!assistantHealthy) {
+    if (isFreshPidState(assistantPid, observedAtMs)) {
+      return { ok: true, state: "starting", pid: assistantPid.pid };
+    }
+    return {
+      ok: true,
+      state: "crashed",
+      pid: assistantPid.pid,
+      detail: "assistant process is not responding",
+    };
+  }
+
+  const gatewayPid = readPidState(getGatewayPidPath(resources.instanceDir));
+  if (gatewayPid.state === "starting") {
+    return { ok: true, state: "starting", pid: assistantPid.pid };
+  }
+  if (gatewayPid.state !== "alive") {
+    if (
+      isFreshPidState(assistantPid, observedAtMs) ||
+      isFreshPidState(gatewayPid, observedAtMs)
+    ) {
+      return { ok: true, state: "starting", pid: assistantPid.pid };
+    }
+    return {
+      ok: true,
+      state: "crashed",
+      pid: assistantPid.pid,
+      detail: "gateway process is not running",
+    };
+  }
+
+  const gatewayHealthy = await httpHealthCheck(resources.gatewayPort);
+  if (!gatewayHealthy) {
+    if (isFreshPidState(gatewayPid, observedAtMs)) {
+      return { ok: true, state: "starting", pid: gatewayPid.pid };
+    }
+    return {
+      ok: true,
+      state: "crashed",
+      pid: gatewayPid.pid,
+      detail: "gateway process is not responding",
+    };
+  }
+
+  return { ok: true, state: "healthy", pid: assistantPid.pid };
+}
+
+export async function getLocalAssistantStatus(
+  lockfilePaths: string[],
+  assistantId: string,
+  env: Record<string, string | undefined> = process.env,
+): Promise<LocalAssistantStatusResult> {
+  const result = getLockfileData(lockfilePaths);
+  if (!result.ok) {
+    return {
+      ok: false,
+      status: result.status,
+      error: result.error ?? "Failed to read lockfile",
+    };
+  }
+
+  const entry = localOnlyEntry(
+    result.data.assistants.find(
+      (assistant) => assistant.assistantId === assistantId,
+    ),
+  );
+  if (!entry) {
+    return { ok: false, status: 404, error: "Local assistant not found" };
+  }
+
+  return runtimeStatusForEntry(
+    entry,
+    findRawAssistant(lockfilePaths, assistantId),
+    env,
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.8.12-dev.202606152248.70317d3",
+  "version": "0.8.12-dev.202606152340.7efde97",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/nginx-ingress.test.ts

@@ -21,6 +21,7 @@ mock.module("node:child_process", () => ({
 
 import {
   buildIngressNginxConfig,
+  buildRemoteWebIndexHtml,
   resolveTunnelTargetPort,
   stopIngressNginx,
 } from "../lib/nginx-ingress.js";
@@ -29,6 +30,18 @@ const originalKill = process.kill;
 
 describe("buildIngressNginxConfig", () => {
   const conf = buildIngressNginxConfig({ gatewayPort: 7830, listenPort: 7840 });
+  const remoteConf = buildIngressNginxConfig({
+    gatewayPort: 7830,
+    listenPort: 7840,
+    remoteWebIngress: {
+      webDistDir: "/tmp/vellum web/dist",
+      config: {
+        mode: "remote-gateway",
+        apiBaseUrl: "/v1",
+        platformDisabled: true,
+      },
+    },
+  });
 
   test("listens on loopback only", () => {
     expect(conf).toContain("listen 127.0.0.1:7840;");
@@ -42,12 +55,97 @@ describe("buildIngressNginxConfig", () => {
   test("proxies requests to the gateway", () => {
     expect(conf).toContain("location / {");
     expect(conf).toContain("proxy_pass http://127.0.0.1:7830;");
+    expect(conf).toContain('proxy_set_header X-Vellum-Edge-Forwarded "1";');
     expect(conf).not.toContain("return 404;");
     expect(conf).not.toContain("return 403;");
     expect(conf).not.toContain("location =");
     expect(conf).not.toContain("location ~");
   });
 
+  test("declares static MIME types needed by the SPA", () => {
+    expect(remoteConf).toContain("default_type application/octet-stream;");
+    expect(remoteConf).toContain("types {");
+    expect(remoteConf).toContain("application/javascript js mjs;");
+    expect(remoteConf).toContain("text/css css;");
+    expect(remoteConf).toContain("text/html html htm;");
+    expect(remoteConf).toContain("font/woff2 woff2;");
+    expect(remoteConf).toContain("image/svg+xml svg svgz;");
+  });
+
+  test("serves the remote web SPA from /assistant when configured", () => {
+    expect(remoteConf).toContain("location = / {");
+    expect(remoteConf).toContain("return 302 /assistant/;");
+    expect(remoteConf.indexOf("location = / {")).toBeLessThan(
+      remoteConf.indexOf("location / {"),
+    );
+    expect(remoteConf).toContain("location = /assistant {");
+    expect(remoteConf).toContain("return 302 /assistant/;");
+    expect(remoteConf).toContain("location ^~ /assistant/assets/ {");
+    expect(remoteConf).toContain('alias "/tmp/vellum web/dist/assets/";');
+    expect(remoteConf).toContain("try_files $uri =404;");
+    expect(remoteConf).toContain("location = /assistant/ {");
+    expect(remoteConf).toContain(
+      "rewrite ^ /assistant/__remote-index.html last;",
+    );
+    expect(remoteConf).toContain("location = /assistant/index.html {");
+    expect(remoteConf).toContain("location = /assistant/__remote-index.html {");
+    expect(remoteConf).toContain("internal;");
+    expect(remoteConf).toContain('alias "/tmp/vellum web/dist/index.html";');
+    expect(remoteConf).toContain("location ^~ /assistant/ {");
+    expect(remoteConf).toContain('alias "/tmp/vellum web/dist/";');
+    expect(remoteConf).toContain(
+      "try_files $uri $uri/ /assistant/__remote-index.html;",
+    );
+    expect(remoteConf).toContain("location / {\n      return 404;\n    }");
+  });
+
+  test("serves remote web config for the SPA", () => {
+    expect(remoteConf).toContain("location = /assistant/__config {");
+    expect(remoteConf).toContain("default_type application/json;");
+    expect(remoteConf).toContain('add_header Cache-Control "no-store";');
+    expect(remoteConf).toContain(
+      'return 200 "{\\"mode\\":\\"remote-gateway\\",\\"apiBaseUrl\\":\\"/v1\\",\\"platformDisabled\\":true,\\"disablePlatform\\":true}";',
+    );
+  });
+
+  test("proxies health and public API traffic to the gateway in remote web mode", () => {
+    expect(remoteConf).toContain("location = /healthz {");
+    expect(remoteConf).toContain("location ^~ /v1/ {");
+    expect(remoteConf).toContain("proxy_pass http://127.0.0.1:7830;");
+    expect(remoteConf).toContain("proxy_request_buffering off;");
+    expect(remoteConf).toContain("proxy_buffering off;");
+    expect(remoteConf).toContain(
+      'proxy_set_header X-Vellum-Edge-Forwarded "1";',
+    );
+  });
+
+  test("blocks local-only bootstrap helpers before generic API proxying", () => {
+    const deniedLocations = [
+      "location = /auth/token { return 404; }",
+      "location = /auth/token/ { return 404; }",
+      "location = /v1/pair { return 404; }",
+      "location = /v1/pair/ { return 404; }",
+      "location = /v1/pair/web-init { return 404; }",
+      "location = /v1/pair/web-init/ { return 404; }",
+      "location = /v1/devices { return 404; }",
+      "location = /v1/devices/ { return 404; }",
+      "location = /v1/devices/revoke { return 404; }",
+      "location = /v1/devices/revoke/ { return 404; }",
+      "location = /v1/guardian/init { return 404; }",
+      "location = /v1/guardian/init/ { return 404; }",
+      "location = /v1/guardian/reset-bootstrap { return 404; }",
+      "location = /v1/guardian/reset-bootstrap/ { return 404; }",
+      "location ^~ /assistant/__local/ { return 404; }",
+      "location ^~ /assistant/__gateway/ { return 404; }",
+    ];
+    for (const location of deniedLocations) {
+      expect(remoteConf).toContain(location);
+      expect(remoteConf.indexOf(location)).toBeLessThan(
+        remoteConf.indexOf("location ^~ /v1/ {"),
+      );
+    }
+  });
+
   test("supports websockets and SSE streaming", () => {
     expect(conf).toContain("map $http_upgrade $connection_upgrade");
     expect(conf).toContain("proxy_http_version 1.1;");
@@ -59,6 +157,37 @@ describe("buildIngressNginxConfig", () => {
   });
 });
 
+describe("buildRemoteWebIndexHtml", () => {
+  test("injects the remote gateway config after any bundled local config", () => {
+    const html =
+      '<html><head><script>window.__VELLUM_CONFIG__={"webUrl":"https://www.vellum.ai"}</script></head><body></body></html>';
+    const result = buildRemoteWebIndexHtml(html, {
+      mode: "remote-gateway",
+      apiBaseUrl: "/v1",
+      disablePlatform: true,
+    });
+
+    expect(result).toContain(
+      'window.__VELLUM_CONFIG__={"webUrl":"https://www.vellum.ai"}',
+    );
+    expect(result).toContain(
+      'window.__VELLUM_CONFIG__={"mode":"remote-gateway","apiBaseUrl":"/v1","disablePlatform":true}',
+    );
+    expect(result.indexOf('"webUrl"')).toBeLessThan(
+      result.indexOf('"remote-gateway"'),
+    );
+  });
+
+  test("escapes config JSON before embedding it in a script tag", () => {
+    const result = buildRemoteWebIndexHtml("</head>", {
+      value: "</script><script>alert(1)</script>",
+    });
+
+    expect(result).not.toContain("</script><script>alert(1)</script>");
+    expect(result).toContain("\\u003c/script\\u003e");
+  });
+});
+
 describe("nginx ingress process state", () => {
   const workspaces: string[] = [];
 

package/src/__tests__/tunnel.test.ts

@@ -74,6 +74,19 @@ function writeLockfile(entry: AssistantEntry): void {
   );
 }
 
+function mockEnabledFlagFetch() {
+  const fetchMock = mock(async (_input: string, _init?: RequestInit) => {
+    return new Response(
+      JSON.stringify({
+        flags: [{ key: "web-remote-ingress", enabled: true }],
+      }),
+      { status: 200, headers: { "Content-Type": "application/json" } },
+    );
+  });
+  globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+  return fetchMock;
+}
+
 describe("tunnel nginx ingress feature flag", () => {
   beforeEach(() => {
     process.argv = ["bun", "vellum", "tunnel"];
@@ -116,6 +129,28 @@ describe("tunnel nginx ingress feature flag", () => {
     expect(runCloudflareTunnelMock).not.toHaveBeenCalled();
   });
 
+  test("checks the nginx flag through the local gateway for ngrok", async () => {
+    const entry = makeLocalEntry();
+    entry.runtimeUrl = "https://stale-tunnel.ngrok-free.dev";
+    writeLockfile(entry);
+    process.argv = ["bun", "vellum", "tunnel", "--provider", "ngrok"];
+    const fetchMock = mockEnabledFlagFetch();
+
+    await tunnel();
+
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe(
+      "http://127.0.0.1:7830/v1/assistants/assistant-1/feature-flags",
+    );
+    expect(init?.method).toBe("GET");
+    expect(runNgrokTunnelMock).toHaveBeenCalledWith({
+      port: 7830,
+      workspaceDir: join(entry.resources!.instanceDir, ".vellum", "workspace"),
+      preferNginxIngress: true,
+    });
+    expect(runCloudflareTunnelMock).not.toHaveBeenCalled();
+  });
+
   test("does not start cloudflared when the flag lookup fails", async () => {
     process.argv = ["bun", "vellum", "tunnel", "--provider", "cloudflare"];
 

package/src/commands/nginx-ingress.ts

@@ -17,6 +17,7 @@ import {
 import { waitForDaemonReady } from "../lib/http-client.js";
 import {
   DEFAULT_NGINX_INGRESS_PORT,
+  findWebDistDir,
   getIngressPaths,
   getIngressPid,
   getNginxIngressPort,
@@ -33,14 +34,12 @@ function printHelp(): void {
   console.log("Usage: vellum nginx-ingress <subcommand> [<name>] [options]");
   console.log("");
   console.log(
-    "Manage the nginx reverse proxy that fronts the gateway for remote web",
+    "Manage the nginx web edge that serves the SPA and fronts the gateway",
   );
   console.log(
-    "access: browser → tunnel (TLS) → nginx@127.0.0.1 → gateway. While the",
-  );
-  console.log(
-    "nginx ingress is running, `vellum tunnel` targets it instead of the gateway.",
+    "for remote web access: browser → tunnel (TLS) → nginx@127.0.0.1.",
   );
+  console.log("While nginx ingress is running, `vellum tunnel` targets it.");
   console.log("");
   console.log("Subcommands:");
   console.log("  up       Generate the nginx config and start the proxy");
@@ -148,6 +147,7 @@ async function assertWebRemoteIngressEnabled(
     enabled = await isAssistantFeatureFlagEnabled(
       target.assistantId,
       WEB_REMOTE_INGRESS_FLAG,
+      { runtimeUrl: `http://127.0.0.1:${target.gatewayPort}` },
     );
   } catch (err) {
     throw new Error(
@@ -188,15 +188,31 @@ async function up(target: NginxIngressTarget): Promise<void> {
     return;
   }
 
+  const webDistDir = findWebDistDir();
+  if (!webDistDir) {
+    console.error(
+      "Error: unable to locate built web assets for remote web ingress.",
+    );
+    console.error("");
+    console.error("Build the SPA first:");
+    console.error("  cd apps/web && VITE_PLATFORM_MODE=false bun run build");
+    console.error("");
+    console.error(
+      "Or install @vellumai/web so its packaged dist directory is available.",
+    );
+    process.exit(1);
+  }
+
   console.log(`Using ${version}`);
   console.log(
-    `Starting nginx ingress on 127.0.0.1:${listenPort} → gateway 127.0.0.1:${gatewayPort}...`,
+    `Starting nginx ingress on 127.0.0.1:${listenPort} → web ${webDistDir} + gateway 127.0.0.1:${gatewayPort}...`,
   );
 
   const child = startIngressNginx({
     workspaceDir,
     gatewayPort,
     listenPort,
+    remoteWebIngress: { webDistDir },
   });
   child.unref();
 

package/src/commands/tunnel.ts

@@ -1,7 +1,8 @@
 import { join } from "path";
 
-import { resolveAssistant } from "../lib/assistant-config";
+import { resolveAssistant, type AssistantEntry } from "../lib/assistant-config";
 import { runCloudflareTunnel } from "../lib/cloudflare-tunnel.js";
+import { GATEWAY_PORT } from "../lib/constants.js";
 import {
   isAssistantFeatureFlagEnabled,
   WEB_REMOTE_INGRESS_FLAG,
@@ -92,11 +93,36 @@ function parseArgs(): TunnelArgs {
   return { assistantName, provider };
 }
 
-async function shouldPreferNginxIngress(assistantId: string): Promise<boolean> {
+function parsePortFromUrl(url: unknown): number | undefined {
+  if (typeof url !== "string" || !url.trim()) return undefined;
+  try {
+    const port = Number(new URL(url).port);
+    return Number.isInteger(port) && port > 0 && port <= 65535
+      ? port
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveEntryGatewayPort(entry: AssistantEntry): number {
+  return (
+    entry.resources?.gatewayPort ??
+    parsePortFromUrl(entry.localUrl) ??
+    parsePortFromUrl(entry.runtimeUrl) ??
+    GATEWAY_PORT
+  );
+}
+
+async function shouldPreferNginxIngress(
+  assistantId: string,
+  gatewayPort: number,
+): Promise<boolean> {
   try {
     return await isAssistantFeatureFlagEnabled(
       assistantId,
       WEB_REMOTE_INGRESS_FLAG,
+      { runtimeUrl: `http://127.0.0.1:${gatewayPort}` },
     );
   } catch (err) {
     throw new Error(
@@ -124,17 +150,21 @@ export async function tunnel(): Promise<void> {
   }
 
   const resources = entry.resources;
-  const baseTunnelOpts = resources
-    ? {
-        port: resources.gatewayPort,
-        workspaceDir: join(resources.instanceDir, ".vellum", "workspace"),
-      }
-    : {};
+  const gatewayPort = resolveEntryGatewayPort(entry);
+  const baseTunnelOpts = {
+    port: gatewayPort,
+    ...(resources
+      ? { workspaceDir: join(resources.instanceDir, ".vellum", "workspace") }
+      : {}),
+  };
 
   if (provider === "ngrok") {
     await runNgrokTunnel({
       ...baseTunnelOpts,
-      preferNginxIngress: await shouldPreferNginxIngress(entry.assistantId),
+      preferNginxIngress: await shouldPreferNginxIngress(
+        entry.assistantId,
+        gatewayPort,
+      ),
     });
     return;
   }
@@ -142,7 +172,10 @@ export async function tunnel(): Promise<void> {
   if (provider === "cloudflare") {
     await runCloudflareTunnel({
       ...baseTunnelOpts,
-      preferNginxIngress: await shouldPreferNginxIngress(entry.assistantId),
+      preferNginxIngress: await shouldPreferNginxIngress(
+        entry.assistantId,
+        gatewayPort,
+      ),
     });
     return;
   }

package/src/lib/assistant-client.ts

@@ -26,6 +26,7 @@ const FALLBACK_RUNTIME_URL = `http://127.0.0.1:${GATEWAY_PORT}`;
 
 export interface AssistantClientOpts {
   assistantId?: string;
+  runtimeUrl?: string;
   /**
    * When provided alongside `orgId`, the client authenticates with a
    * session token instead of a guardian token.  The session token is
@@ -73,6 +74,7 @@ export class AssistantClient {
     }
 
     this.runtimeUrl = (
+      opts?.runtimeUrl ||
       entry.localUrl ||
       entry.runtimeUrl ||
       FALLBACK_RUNTIME_URL

package/src/lib/feature-flags.test.ts

@@ -52,6 +52,16 @@ function mockFetch(response: Response): void {
   globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
 }
 
+function mockFetchWithUrls(response: Response): string[] {
+  const urls: string[] = [];
+  const fetchMock = async (input: RequestInfo | URL) => {
+    urls.push(String(input));
+    return response;
+  };
+  globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+  return urls;
+}
+
 describe("isAssistantFeatureFlagEnabled", () => {
   beforeEach(() => {
     process.env.VELLUM_LOCKFILE_DIR = testDir;
@@ -84,6 +94,41 @@ describe("isAssistantFeatureFlagEnabled", () => {
     ).resolves.toBe(true);
   });
 
+  test("uses the supplied runtime URL instead of a stale lockfile runtimeUrl", async () => {
+    writeFileSync(
+      join(testDir, ".vellum.lock.json"),
+      JSON.stringify(
+        {
+          activeAssistant: "assistant-1",
+          assistants: [
+            {
+              assistantId: "assistant-1",
+              runtimeUrl: "https://stale-tunnel.ngrok-free.dev",
+              cloud: "local",
+            },
+          ],
+        },
+        null,
+        2,
+      ),
+    );
+    const urls = mockFetchWithUrls(
+      jsonResponse({
+        flags: [{ key: WEB_REMOTE_INGRESS_FLAG, enabled: true }],
+      }),
+    );
+
+    await expect(
+      isAssistantFeatureFlagEnabled("assistant-1", WEB_REMOTE_INGRESS_FLAG, {
+        runtimeUrl: "http://127.0.0.1:9123",
+      }),
+    ).resolves.toBe(true);
+
+    expect(urls).toEqual([
+      "http://127.0.0.1:9123/v1/assistants/assistant-1/feature-flags",
+    ]);
+  });
+
   test("returns false when the assistant flag is disabled or missing", async () => {
     mockFetch(
       jsonResponse({

package/src/lib/feature-flags.ts

@@ -14,8 +14,12 @@ type FeatureFlagsResponse = {
 export async function isAssistantFeatureFlagEnabled(
   assistantId: string,
   key: string,
+  opts: { runtimeUrl?: string } = {},
 ): Promise<boolean> {
-  const client = new AssistantClient({ assistantId });
+  const client = new AssistantClient({
+    assistantId,
+    runtimeUrl: opts.runtimeUrl,
+  });
   const res = await client.get("/feature-flags");
   if (!res.ok) {
     const body = await res.text().catch(() => "");

package/src/lib/nginx-ingress.ts

@@ -13,6 +13,7 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
+import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 
 import { GATEWAY_PORT } from "./constants.js";
@@ -26,6 +27,7 @@ import { GATEWAY_PORT } from "./constants.js";
  */
 
 export const DEFAULT_NGINX_INGRESS_PORT = 7840;
+const _require = createRequire(import.meta.url);
 
 /** Listen port for nginx ingress, from VELLUM_NGINX_INGRESS_PORT. */
 export function getNginxIngressPort(): number {
@@ -78,13 +80,119 @@ function saveRawConfig(
   writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
 }
 
+/**
+ * Locate the pre-built @vellumai/web dist directory.
+ *
+ * Resolution order:
+ *   1. npm-installed package — require.resolve('@vellumai/web/package.json')
+ *   2. Source checkout — walk up from cli/ to find apps/web/dist/
+ */
+export function findWebDistDir(): string | null {
+  try {
+    const pkgPath = _require.resolve("@vellumai/web/package.json");
+    const distDir = join(dirname(pkgPath), "dist");
+    if (existsSync(join(distDir, "index.html"))) {
+      return distDir;
+    }
+  } catch {
+    // Package not installed; try source checkout.
+  }
+
+  let dir = import.meta.dir;
+  for (let depth = 0; depth < 8; depth++) {
+    const candidate = join(dir, "apps", "web", "dist", "index.html");
+    if (existsSync(candidate)) {
+      return dirname(candidate);
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function nginxQuoted(value: string, label: string): string {
+  if (/[\u0000-\u001f\u007f]/.test(value)) {
+    throw new Error(`${label} contains a control character`);
+  }
+  return `"${value
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\$/g, "\\$")}"`;
+}
+
+function nginxDirPath(dir: string): string {
+  return dir.endsWith("/") ? dir : `${dir}/`;
+}
+
+function gatewayProxyBlock(gatewayPort: number): string {
+  return `      proxy_pass http://127.0.0.1:${gatewayPort};
+      proxy_http_version 1.1;
+      proxy_request_buffering off;
+      proxy_buffering off;
+      proxy_read_timeout 1h;
+      proxy_set_header Host $host;
+      proxy_set_header X-Vellum-Edge-Forwarded "1";
+      proxy_set_header Upgrade $http_upgrade;
+      proxy_set_header Connection $connection_upgrade;`;
+}
+
+export interface RemoteWebIngressOptions {
+  webDistDir: string;
+  indexHtmlPath?: string;
+  config?: Record<string, unknown>;
+}
+
+function remoteWebIngressConfig(
+  config: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  return {
+    mode: "remote-gateway",
+    apiBaseUrl: "/v1",
+    platformDisabled: true,
+    disablePlatform: true,
+    ...config,
+  };
+}
+
+function safeScriptJson(value: unknown): string {
+  return JSON.stringify(value)
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e");
+}
+
+export function buildRemoteWebIndexHtml(
+  rawHtml: string,
+  config: Record<string, unknown>,
+): string {
+  const script = `<script>window.__VELLUM_CONFIG__=${safeScriptJson(config)}</script>`;
+  if (rawHtml.includes("</head>")) {
+    return rawHtml.replace("</head>", `${script}</head>`);
+  }
+  return `${script}${rawHtml}`;
+}
+
 /**
  * Build the nginx config that forwards tunnel web traffic to the gateway.
  */
 export function buildIngressNginxConfig(opts: {
   gatewayPort: number;
   listenPort: number;
+  remoteWebIngress?: RemoteWebIngressOptions;
 }): string {
+  const proxyBlock = gatewayProxyBlock(opts.gatewayPort);
+  const remoteWebIngress = opts.remoteWebIngress;
+  const serverLocations = remoteWebIngress
+    ? buildRemoteWebIngressLocations({
+        gatewayPort: opts.gatewayPort,
+        webDistDir: remoteWebIngress.webDistDir,
+        indexHtmlPath: remoteWebIngress.indexHtmlPath,
+        config: remoteWebIngressConfig(remoteWebIngress.config),
+      })
+    : `    location / {
+${proxyBlock}
+    }`;
+
   return `
 worker_processes 1;
 error_log stderr;
@@ -94,6 +202,24 @@ events {}
 
 http {
   access_log off;
+  default_type application/octet-stream;
+
+  types {
+    application/javascript js mjs;
+    application/json json map;
+    application/wasm wasm;
+    font/woff woff;
+    font/woff2 woff2;
+    image/gif gif;
+    image/jpeg jpeg jpg;
+    image/png png;
+    image/svg+xml svg svgz;
+    image/webp webp;
+    image/x-icon ico;
+    text/css css;
+    text/html html htm;
+    text/plain txt;
+  }
 
   map $http_upgrade $connection_upgrade {
     default upgrade;
@@ -104,21 +230,95 @@ http {
     listen 127.0.0.1:${opts.listenPort};
     client_max_body_size 512m;
 
-    location / {
-      proxy_pass http://127.0.0.1:${opts.gatewayPort};
-      proxy_http_version 1.1;
-      proxy_request_buffering off;
-      proxy_buffering off;
-      proxy_read_timeout 1h;
-      proxy_set_header Host $host;
-      proxy_set_header Upgrade $http_upgrade;
-      proxy_set_header Connection $connection_upgrade;
-    }
+${serverLocations}
   }
 }
 `;
 }
 
+function buildRemoteWebIngressLocations(opts: {
+  gatewayPort: number;
+  webDistDir: string;
+  indexHtmlPath?: string;
+  config: Record<string, unknown>;
+}): string {
+  const proxyBlock = gatewayProxyBlock(opts.gatewayPort);
+  const webDistDir = nginxDirPath(opts.webDistDir);
+  const webAssetsDir = join(opts.webDistDir, "assets");
+  const indexHtmlPath =
+    opts.indexHtmlPath ?? join(opts.webDistDir, "index.html");
+  const configJson = JSON.stringify(opts.config);
+
+  return `    location = /auth/token { return 404; }
+    location = /auth/token/ { return 404; }
+    location = /v1/pair { return 404; }
+    location = /v1/pair/ { return 404; }
+    location = /v1/pair/web-init { return 404; }
+    location = /v1/pair/web-init/ { return 404; }
+    location = /v1/devices { return 404; }
+    location = /v1/devices/ { return 404; }
+    location = /v1/devices/revoke { return 404; }
+    location = /v1/devices/revoke/ { return 404; }
+    location = /v1/guardian/init { return 404; }
+    location = /v1/guardian/init/ { return 404; }
+    location = /v1/guardian/reset-bootstrap { return 404; }
+    location = /v1/guardian/reset-bootstrap/ { return 404; }
+    location ^~ /assistant/__local/ { return 404; }
+    location ^~ /assistant/__gateway/ { return 404; }
+
+    location = /healthz {
+${proxyBlock}
+    }
+
+    location ^~ /v1/ {
+${proxyBlock}
+    }
+
+    location = /assistant {
+      return 302 /assistant/;
+    }
+
+    location = /assistant/ {
+      rewrite ^ /assistant/__remote-index.html last;
+    }
+
+    location = /assistant/index.html {
+      rewrite ^ /assistant/__remote-index.html last;
+    }
+
+    location = /assistant/__remote-index.html {
+      internal;
+      alias ${nginxQuoted(indexHtmlPath, "remote web ingress index path")};
+      add_header Cache-Control "no-store";
+    }
+
+    location = /assistant/__config {
+      default_type application/json;
+      add_header Cache-Control "no-store";
+      return 200 ${nginxQuoted(configJson, "remote web ingress config")};
+    }
+
+    location ^~ /assistant/assets/ {
+      alias ${nginxQuoted(nginxDirPath(webAssetsDir), "web assets path")};
+      try_files $uri =404;
+      add_header Cache-Control "public, max-age=31536000, immutable";
+    }
+
+    location ^~ /assistant/ {
+      alias ${nginxQuoted(webDistDir, "web dist path")};
+      try_files $uri $uri/ /assistant/__remote-index.html;
+      add_header Cache-Control "no-store";
+    }
+
+    location = / {
+      return 302 /assistant/;
+    }
+
+    location / {
+      return 404;
+    }`;
+}
+
 function nginxBin(): string {
   return process.env.NGINX_BIN || "nginx";
 }
@@ -250,15 +450,34 @@ export function startIngressNginx(opts: {
   workspaceDir: string;
   gatewayPort: number;
   listenPort: number;
+  remoteWebIngress?: RemoteWebIngressOptions;
 }): ChildProcess {
   const paths = getIngressPaths(opts.workspaceDir);
   mkdirSync(paths.dir, { recursive: true });
   mkdirSync(join(opts.workspaceDir, "data", "logs"), { recursive: true });
+  const remoteWebIngress = opts.remoteWebIngress
+    ? {
+        ...opts.remoteWebIngress,
+        config: remoteWebIngressConfig(opts.remoteWebIngress.config),
+        indexHtmlPath: join(paths.dir, "assistant-index.html"),
+      }
+    : undefined;
+  if (remoteWebIngress) {
+    const rawIndexHtml = readFileSync(
+      join(remoteWebIngress.webDistDir, "index.html"),
+      "utf-8",
+    );
+    writeFileSync(
+      remoteWebIngress.indexHtmlPath,
+      buildRemoteWebIndexHtml(rawIndexHtml, remoteWebIngress.config),
+    );
+  }
   writeFileSync(
     paths.confPath,
     buildIngressNginxConfig({
       gatewayPort: opts.gatewayPort,
       listenPort: opts.listenPort,
+      remoteWebIngress,
     }),
   );