@vellumai/cli 0.10.11 → 0.10.12-dev.202607242227.e52a30c

package/src/commands/backup.ts

@@ -134,15 +134,18 @@ export async function backup(): Promise<void> {
   // Call the export endpoint
   let response: Response;
   try {
-    response = await loopbackSafeFetch(`${entry.runtimeUrl}/v1/migrations/export`, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${accessToken}`,
-        "Content-Type": "application/json",
+    response = await loopbackSafeFetch(
+      `${entry.runtimeUrl}/v1/migrations/export`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ description: "CLI backup" }),
+        signal: AbortSignal.timeout(exportTimeoutMs),
       },
-      body: JSON.stringify({ description: "CLI backup" }),
-      signal: AbortSignal.timeout(exportTimeoutMs),
-    });
+    );
 
     // Retry once with a fresh token on 401 — the cached token may be stale
     // after a container restart that generated a new gateway signing key.
@@ -160,15 +163,18 @@ export async function backup(): Promise<void> {
       }
       if (refreshedToken) {
         accessToken = refreshedToken;
-        response = await loopbackSafeFetch(`${entry.runtimeUrl}/v1/migrations/export`, {
-          method: "POST",
-          headers: {
-            Authorization: `Bearer ${accessToken}`,
-            "Content-Type": "application/json",
+        response = await loopbackSafeFetch(
+          `${entry.runtimeUrl}/v1/migrations/export`,
+          {
+            method: "POST",
+            headers: {
+              Authorization: `Bearer ${accessToken}`,
+              "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ description: "CLI backup" }),
+            signal: AbortSignal.timeout(exportTimeoutMs),
           },
-          body: JSON.stringify({ description: "CLI backup" }),
-          signal: AbortSignal.timeout(exportTimeoutMs),
-        });
+        );
       }
     }
   } catch (err) {

package/src/commands/client.ts

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { closeSync, existsSync } from "node:fs";
 import path from "node:path";
 
 import {
@@ -61,6 +61,8 @@ import { tuiLog } from "../lib/tui-log";
 import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
 import { probePort } from "../lib/port-probe.js";
 import { openBrowser } from "../lib/open-browser";
+import { isCompiledCli } from "../lib/local.js";
+import { getLogDir, openLogFile, resetLogFile } from "../lib/xdg-log.js";
 
 const SUPPORTED_INTERFACES = ["cli", "web"] as const;
 type SupportedInterface = (typeof SUPPORTED_INTERFACES)[number];
@@ -93,6 +95,10 @@ interface ParsedArgs {
   disablePlatform: boolean;
   /** Auto-open the web interface in the default browser (--interface web only). */
   openBrowser: boolean;
+  /** Explicit web server port (--interface web only). Binds strictly — no scan. */
+  webPort?: number;
+  /** Run the web server as a detached background process (--interface web only). */
+  background: boolean;
 }
 
 function readAssistantName(entry: AssistantEntry | null): string | undefined {
@@ -138,9 +144,12 @@ export function parseArgs(): ParsedArgs {
     "-i",
     "--token",
     "-t",
+    "--port",
   ]);
   // Auto-open the web interface in the browser by default; --no-open opts out.
   let openBrowserPref = true;
+  let webPort: number | undefined;
+  let background = false;
   const flagArgs: string[] = [];
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -151,6 +160,19 @@ export function parseArgs(): ParsedArgs {
       disablePlatform = true;
     } else if (arg === "--no-open") {
       openBrowserPref = false;
+    } else if (arg === "--background") {
+      background = true;
+    } else if (arg === "--port") {
+      const value = args[++i];
+      const parsed =
+        value === undefined ? Number.NaN : Number.parseInt(value, 10);
+      if (String(parsed) !== value || parsed < 1 || parsed > 65535) {
+        console.error(
+          `Invalid --port '${value ?? ""}'. Expected an integer between 1 and 65535.`,
+        );
+        process.exit(1);
+      }
+      webPort = parsed;
     } else if (
       (arg === "--url" ||
         arg === "-u" ||
@@ -259,6 +281,17 @@ export function parseArgs(): ParsedArgs {
     }
   }
 
+  if (interfaceId !== WEB_INTERFACE_ID) {
+    if (webPort !== undefined) {
+      console.error("--port requires --interface web.");
+      process.exit(1);
+    }
+    if (background) {
+      console.error("--background requires --interface web.");
+      process.exit(1);
+    }
+  }
+
   return {
     runtimeUrl: normalizeRuntimeUrl(runtimeUrl),
     assistantId,
@@ -272,6 +305,8 @@ export function parseArgs(): ParsedArgs {
     parsedFlagOverrides,
     disablePlatform,
     openBrowser: openBrowserPref,
+    webPort,
+    background,
   };
 }
 
@@ -292,6 +327,12 @@ ${ANSI.bold}OPTIONS:${ANSI.reset}
     -a, --assistant-id <id>    Assistant ID
     -i, --interface <id>       Interface identifier: cli (default) or web
     --no-open                  Don't auto-open the browser (--interface web)
+    --port <port>              Web server port, 1-65535 (--interface web).
+                              Errors if the port is taken. Default: 3000,
+                              scanning upward when busy.
+    --background               Run the web server as a background process
+                              (--interface web). Prints the URL, PID, and log
+                              path, then returns to the shell.
     --flag <key=value>         Feature flag override (repeatable, kebab-case key)
     --disable-platform         Suppress all outbound platform API calls
     -h, --help                 Show this help message
@@ -311,6 +352,9 @@ ${ANSI.bold}EXAMPLES:${ANSI.reset}
     # Ephemeral: connect to another machine's assistant with a paired token
     # (no lockfile entry, nothing persisted):
     vellum client --url https://your-tunnel.example --token <jwt>
+
+    # Web interface on a fixed port, detached from the shell:
+    vellum client --interface web --port 4000 --background
 `);
 }
 
@@ -775,12 +819,12 @@ function tryBindLoopback(
  * Never binds wildcard interfaces (`0.0.0.0`/`::`): the server exposes
  * `/__local/*` control endpoints, so it must stay loopback-only.
  */
-function serveLoopback(preferredPort: number, fetchHandler: WebFetchHandler) {
-  for (
-    let port = preferredPort;
-    port < preferredPort + WEB_PORT_SCAN_LIMIT;
-    port++
-  ) {
+function serveLoopback(
+  preferredPort: number,
+  fetchHandler: WebFetchHandler,
+  scanLimit = WEB_PORT_SCAN_LIMIT,
+) {
+  for (let port = preferredPort; port < preferredPort + scanLimit; port++) {
     const primary = tryBindLoopback(port, "127.0.0.1", fetchHandler);
     if (!primary) continue;
 
@@ -804,10 +848,21 @@ function serveLoopback(preferredPort: number, fetchHandler: WebFetchHandler) {
     }
   }
   throw new Error(
-    `Could not bind a free loopback port in [${preferredPort}, ${preferredPort + WEB_PORT_SCAN_LIMIT - 1}]`,
+    scanLimit === 1
+      ? `Port ${preferredPort} is already in use`
+      : `Could not bind a free loopback port in [${preferredPort}, ${preferredPort + scanLimit - 1}]`,
   );
 }
 
+/** True when neither loopback family has a listener on `port`. */
+async function isDualLoopbackPortFree(port: number): Promise<boolean> {
+  const [busyV4, busyV6] = await Promise.all([
+    probePort(port, "127.0.0.1"),
+    probePort(port, "::1"),
+  ]);
+  return !busyV4 && !busyV6;
+}
+
 /**
  * Find the first port at/above `preferred` with nothing listening on either
  * loopback family. Used for the Vite dev server, which binds the port itself
@@ -816,15 +871,29 @@ function serveLoopback(preferredPort: number, fetchHandler: WebFetchHandler) {
  */
 async function findFreeDualLoopbackPort(preferred: number): Promise<number> {
   for (let port = preferred; port < preferred + WEB_PORT_SCAN_LIMIT; port++) {
-    const [busyV4, busyV6] = await Promise.all([
-      probePort(port, "127.0.0.1"),
-      probePort(port, "::1"),
-    ]);
-    if (!busyV4 && !busyV6) return port;
+    if (await isDualLoopbackPortFree(port)) {
+      return port;
+    }
   }
   return preferred;
 }
 
+/**
+ * Resolve the port for a probe-based web server launch: an explicit --port
+ * must be free (exit 1 otherwise — strict, no silent move), the default picks
+ * the first free port at/above 3000.
+ */
+async function resolveWebPort(webPort: number | undefined): Promise<number> {
+  if (webPort === undefined) {
+    return findFreeDualLoopbackPort(3000);
+  }
+  if (!(await isDualLoopbackPortFree(webPort))) {
+    console.error(`Port ${webPort} is already in use`);
+    process.exit(1);
+  }
+  return webPort;
+}
+
 /**
  * Open `url` in the browser once `port` is accepting connections, polling for
  * up to ~10s. Used for the Vite dev server, which binds the port asynchronously
@@ -840,11 +909,118 @@ async function openBrowserWhenReady(url: string, port: number): Promise<void> {
   }
 }
 
+const WEB_BACKGROUND_LOG_FILE = "client-web.log";
+// Generous cap so a cold Vite dev-server boot (dependency optimization) still
+// counts as a successful start.
+const WEB_BACKGROUND_START_TIMEOUT_MS = 30_000;
+
+/**
+ * Launch `vellum client --interface web` as a detached background process.
+ *
+ * The port is resolved up front (explicit --port must be free; otherwise the
+ * first free port at/above 3000) and pinned via `--port` on the child so the
+ * URL printed here is the one the child binds. The child's stdout/stderr go to
+ * `<xdg-log-dir>/client-web.log` — same detach idiom as the nginx/ngrok
+ * spawns. Success is only reported once the child is accepting connections on
+ * the port; an early child exit (e.g. missing @vellumai/web assets) or a
+ * startup timeout fails with a pointer at the log file.
+ */
+async function spawnBackgroundWebInterface(
+  webPort: number | undefined,
+): Promise<void> {
+  const port = await resolveWebPort(webPort);
+
+  // Rebuild the argv without --background, pinning the resolved port.
+  const childArgs: string[] = ["client"];
+  const rawArgs = process.argv.slice(3);
+  for (let i = 0; i < rawArgs.length; i++) {
+    const arg = rawArgs[i];
+    if (arg === "--background") {
+      continue;
+    }
+    // A dangling --port can't reach here — parseArgs already rejected it.
+    if (arg === "--port") {
+      i++;
+      continue;
+    }
+    childArgs.push(arg);
+  }
+  childArgs.push("--port", String(port));
+
+  // A compiled binary re-invokes itself; under plain bun (source tree, npm
+  // install) the entry script is argv[1].
+  const spawnArgs = isCompiledCli()
+    ? childArgs
+    : [process.argv[1], ...childArgs];
+
+  resetLogFile(WEB_BACKGROUND_LOG_FILE);
+  const fd = openLogFile(WEB_BACKGROUND_LOG_FILE);
+  const child = spawn(process.execPath, spawnArgs, {
+    detached: true,
+    stdio: ["ignore", fd, fd],
+  });
+  if (typeof fd === "number") {
+    closeSync(fd);
+  }
+  child.unref();
+
+  const logPath = path.join(getLogDir(), WEB_BACKGROUND_LOG_FILE);
+
+  // Don't report success until the child is actually serving: watch for an
+  // early exit (e.g. missing @vellumai/web assets, port lost to the TOCTOU
+  // window) and poll the port until it accepts connections.
+  let exit: { code: number | null } | undefined;
+  child.on("error", () => {
+    exit = { code: null };
+  });
+  child.on("exit", (code) => {
+    exit = { code };
+  });
+
+  const deadline = Date.now() + WEB_BACKGROUND_START_TIMEOUT_MS;
+  let listening = false;
+  while (Date.now() < deadline && !exit) {
+    if (await probePort(port, "127.0.0.1")) {
+      listening = true;
+      break;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+
+  if (exit) {
+    console.error(
+      `Web interface exited during startup${exit.code !== null ? ` (exit code ${exit.code})` : ""}. Logs: ${logPath}`,
+    );
+    process.exit(1);
+  }
+  if (!listening) {
+    // Kill the detached child (its whole process group — the Vite path spawns
+    // grandchildren) so a slow startup can't bind the port and linger after
+    // we've reported failure.
+    if (child.pid !== undefined) {
+      try {
+        process.kill(-child.pid, "SIGTERM");
+      } catch {
+        child.kill("SIGTERM");
+      }
+    }
+    console.error(
+      `Web interface did not start listening on port ${port} within ${WEB_BACKGROUND_START_TIMEOUT_MS / 1000}s; terminated it. Logs: ${logPath}`,
+    );
+    process.exit(1);
+  }
+
+  console.log(`Vellum web interface: http://localhost:${port}${SPA_BASE}`);
+  console.log(`Running in background (pid ${child.pid}). Logs: ${logPath}`);
+  console.log(`Stop with: kill ${child.pid}`);
+}
+
 async function runWebInterface(
   flagEnvVars: Record<string, string>,
   parsedFlagOverrides: Record<string, boolean | string>,
   disablePlatform: boolean,
   openInBrowser: boolean,
+  webPort: number | undefined,
 ): Promise<void> {
   // Propagate flag env vars so child processes (e.g. hatch from the web UI) inherit them.
   Object.assign(process.env, flagEnvVars);
@@ -858,6 +1034,7 @@ async function runWebInterface(
       flagEnvVars,
       disablePlatform,
       openInBrowser,
+      webPort,
     );
   }
 
@@ -1001,9 +1178,23 @@ async function runWebInterface(
     return new Response("Not Found", { status: 404 });
   };
 
-  const { port, servers } = serveLoopback(3000, fetchHandler);
-  if (port !== 3000) {
-    console.log(`Port 3000 in use; using ${port}.`);
+  // An explicit --port binds strictly (no scan) so the user gets the port they
+  // asked for or a clear error.
+  const preferredPort = webPort ?? 3000;
+  let bound: ReturnType<typeof serveLoopback>;
+  try {
+    bound = serveLoopback(
+      preferredPort,
+      fetchHandler,
+      webPort !== undefined ? 1 : WEB_PORT_SCAN_LIMIT,
+    );
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+  const { port, servers } = bound;
+  if (port !== preferredPort) {
+    console.log(`Port ${preferredPort} in use; using ${port}.`);
   }
   // Advertise `localhost` (not `127.0.0.1`) so the app origin matches the host
   // the platform hardcodes in its loopback callback. We bind both loopback
@@ -1027,6 +1218,7 @@ async function runViteDevServer(
   flagEnvVars: Record<string, string>,
   disablePlatform: boolean,
   openInBrowser: boolean,
+  webPort: number | undefined,
 ): Promise<void> {
   const platformUrl = getPlatformUrl();
 
@@ -1039,8 +1231,9 @@ async function runViteDevServer(
   // Auto-pick a free port (Vite uses strictPort) so a running `vel up` stack
   // on :3000 doesn't wedge dev. The loopback callback port follows
   // window.location.port, so a non-3000 port propagates automatically.
-  const port = await findFreeDualLoopbackPort(3000);
-  if (port !== 3000) {
+  // An explicit --port is strict: error rather than silently moving.
+  const port = await resolveWebPort(webPort);
+  if (webPort === undefined && port !== 3000) {
     console.log(`Port 3000 in use; using ${port}.`);
   }
 
@@ -1139,6 +1332,8 @@ export async function client(): Promise<void> {
     parsedFlagOverrides,
     disablePlatform,
     openBrowser: openInBrowser,
+    webPort,
+    background,
   } = parseArgs();
 
   if (disablePlatform) {
@@ -1146,11 +1341,16 @@ export async function client(): Promise<void> {
   }
 
   if (interfaceId === WEB_INTERFACE_ID) {
+    if (background) {
+      await spawnBackgroundWebInterface(webPort);
+      return;
+    }
     await runWebInterface(
       flagEnvVars,
       parsedFlagOverrides,
       disablePlatform,
       openInBrowser,
+      webPort,
     );
     return;
   }

package/src/commands/exec.ts

@@ -220,7 +220,11 @@ export async function exec(): Promise<void> {
 
     if (interactive) {
       // Interactive mode: shell-escape argv and delegate to full terminal
-      await interactiveSession(assistant, shellEscapeArgs(command), serviceParam);
+      await interactiveSession(
+        assistant,
+        shellEscapeArgs(command),
+        serviceParam,
+      );
       return;
     }
 

package/src/commands/flags.ts

@@ -4,6 +4,7 @@ import {
   formatAssistantLookupError,
   lookupAssistantByIdentifier,
 } from "../lib/assistant-config.js";
+import { crossEnvironmentAssistantHint } from "../lib/environments/detect.js";
 
 type FeatureFlagEntry = {
   key: string;
@@ -132,7 +133,9 @@ function rethrowFetchError(err: unknown): never {
     (err.message.includes("fetch") || err.message.includes("connect"))
   ) {
     throw new Error(
-      "Could not reach the assistant gateway. Is it running? Try 'vellum wake'.",
+      `Could not reach the assistant gateway. Is it running? Try 'vellum wake'.${
+        crossEnvironmentAssistantHint() ?? ""
+      }`,
     );
   }
   throw err;

package/src/commands/nginx-ingress.ts

@@ -14,22 +14,16 @@ import {
   isAssistantFeatureFlagEnabled,
   WEB_REMOTE_INGRESS_FLAG,
 } from "../lib/feature-flags.js";
-import { waitForDaemonReady } from "../lib/http-client.js";
 import {
   DEFAULT_NGINX_INGRESS_PORT,
-  findWebDistDir,
   getIngressPaths,
   getIngressPid,
-  getNginxIngressPort,
-  getNginxVersion,
   isIngressRunning,
   resolveTunnelTargetPort,
-  startIngressNginx,
+  startRemoteWebIngress,
   stopIngressNginx,
 } from "../lib/nginx-ingress.js";
 
-const READY_TIMEOUT_MS = 5_000;
-
 function printHelp(): void {
   console.log("Usage: vellum nginx-ingress <subcommand> [<name>] [options]");
   console.log("");
@@ -164,79 +158,71 @@ async function assertWebRemoteIngressEnabled(
 
 async function up(target: NginxIngressTarget): Promise<void> {
   const { workspaceDir, gatewayPort } = target;
-  const listenPort = getNginxIngressPort();
 
   await assertWebRemoteIngressEnabled(target);
 
-  const version = getNginxVersion();
-  if (!version) {
-    console.error("Error: nginx is not installed.");
-    console.error("");
-    console.error("Install nginx:");
-    console.error("  macOS:  brew install nginx");
-    console.error("  Linux:  sudo apt install nginx");
-    console.error("");
-    console.error(
-      "Or point NGINX_BIN at an existing binary: NGINX_BIN=/path/to/nginx",
-    );
-    process.exit(1);
-  }
-
-  if (isIngressRunning(workspaceDir)) {
-    console.log("nginx ingress is already running.");
-    await status(target);
-    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 clients/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} → web ${webDistDir} + gateway 127.0.0.1:${gatewayPort}...`,
-  );
-
-  const child = startIngressNginx({
+  const result = await startRemoteWebIngress({
     workspaceDir,
     gatewayPort,
-    listenPort,
-    remoteWebIngress: { webDistDir },
+    onStarting: ({ version, webDistDir, listenPort }) => {
+      console.log(`Using ${version}`);
+      console.log(
+        `Starting nginx ingress on 127.0.0.1:${listenPort} → web ${webDistDir} + gateway 127.0.0.1:${gatewayPort}...`,
+      );
+    },
   });
-  child.unref();
 
-  // /healthz proxies through nginx to the gateway, so a 200 proves the whole
-  // ingress → gateway path works.
-  const ready = await waitForDaemonReady(listenPort, READY_TIMEOUT_MS);
-  if (!ready) {
-    const { logPath } = getIngressPaths(workspaceDir);
-    await stopIngressNginx(workspaceDir);
-    console.error(
-      `Error: nginx ingress did not become reachable on 127.0.0.1:${listenPort}.`,
-    );
-    console.error(`Check the nginx log: ${logPath}`);
-    process.exit(1);
+  switch (result.status) {
+    case "already-running":
+      console.log("nginx ingress is already running.");
+      await status(target);
+      return;
+    case "started":
+      console.log("");
+      console.log(
+        `nginx ingress running: http://127.0.0.1:${result.listenPort}`,
+      );
+      console.log("");
+      console.log("Next steps:");
+      console.log(
+        "  vellum tunnel --provider ngrok   # tunnel now targets nginx ingress",
+      );
+      console.log("  vellum nginx-ingress down        # stop the proxy");
+      return;
+    case "nginx-missing":
+      console.error("Error: nginx is not installed.");
+      console.error("");
+      console.error("Install nginx:");
+      console.error("  macOS:  brew install nginx");
+      console.error("  Linux:  sudo apt install nginx");
+      console.error("");
+      console.error(
+        "Or point NGINX_BIN at an existing binary: NGINX_BIN=/path/to/nginx",
+      );
+      break;
+    case "web-dist-missing":
+      console.error(
+        "Error: unable to locate built web assets for remote web ingress.",
+      );
+      console.error("");
+      console.error("Build the SPA first:");
+      console.error(
+        "  cd clients/web && VITE_PLATFORM_MODE=false bun run build",
+      );
+      console.error("");
+      console.error(
+        "Or install @vellumai/web so its packaged dist directory is available.",
+      );
+      break;
+    case "unreachable":
+      console.error(
+        `Error: nginx ingress did not become reachable on 127.0.0.1:${result.listenPort}.`,
+      );
+      console.error(`Check the nginx log: ${result.logPath}`);
+      break;
   }
 
-  console.log("");
-  console.log(`nginx ingress running: http://127.0.0.1:${listenPort}`);
-  console.log("");
-  console.log("Next steps:");
-  console.log(
-    "  vellum tunnel --provider ngrok   # tunnel now targets nginx ingress",
-  );
-  console.log("  vellum nginx-ingress down        # stop the proxy");
+  process.exit(1);
 }
 
 async function down(target: NginxIngressTarget): Promise<void> {