@vellumai/cli 0.4.10 → 0.4.11

package/README.md

@@ -14,6 +14,29 @@ bun run ./src/index.ts <command> [options]
 
 ## Commands
 
+### Lifecycle: `ps`, `sleep`, `wake`
+
+Day-to-day process management for the daemon and gateway.
+
+| Command | Description |
+|---------|-------------|
+| `vellum ps` | List assistants and per-assistant process status (daemon, gateway PIDs and health). |
+| `vellum sleep` | Stop daemon and gateway processes. Directory-agnostic — works from anywhere. |
+| `vellum wake` | Start the daemon and gateway from the current checkout. |
+
+```bash
+# Start everything
+vellum wake
+
+# Check what's running
+vellum ps
+
+# Stop everything
+vellum sleep
+```
+
+> **Note:** `vellum wake` requires a hatched assistant. Run `vellum hatch` first, or launch the macOS app which handles hatching automatically.
+
 ### `hatch`
 
 Provision a new assistant instance and bootstrap the Vellum runtime on it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.4.10",
+  "version": "0.4.11",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/coverage.test.ts

@@ -0,0 +1,41 @@
+// Bun's coverage reporter only tracks files that are actually loaded during
+// test execution. There is no config option to include all source files.
+// See: https://github.com/oven-sh/bun/issues/5928
+import { resolve } from "node:path";
+import { expect, test } from "bun:test";
+
+const EXCLUDE_PATTERNS = [".test.ts", ".d.ts"];
+const EXCLUDE_FILES = [
+  // index.ts calls main() at module level, causing side effects on import
+  "index.ts",
+];
+
+async function importAllModules(dir: string): Promise<string[]> {
+  const glob = new Bun.Glob("**/*.{ts,tsx}");
+  const files = [...glob.scanSync(dir)].filter(
+    (f) =>
+      !EXCLUDE_PATTERNS.some((pattern) => f.endsWith(pattern)) &&
+      !EXCLUDE_FILES.some((excluded) => f === excluded) &&
+      !f.includes("__tests__"),
+  );
+
+  await Promise.all(files.map((relPath) => import(resolve(dir, relPath))));
+
+  return files;
+}
+
+test("imports all source modules for coverage tracking", async () => {
+  /**
+   * Ensures all source files are loaded so Bun's coverage reporter
+   * includes them in the report, not just files touched by other tests.
+   */
+
+  // GIVEN the src directory containing all source modules
+  const srcDir = resolve(import.meta.dir, "..");
+
+  // WHEN we dynamically import every source module
+  const files = await importAllModules(srcDir);
+
+  // THEN at least one file should have been imported
+  expect(files.length).toBeGreaterThan(0);
+});

package/src/commands/config.ts

@@ -1,8 +1,13 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
 
 import { syncConfigToLockfile } from "../lib/assistant-config";
+import {
+  getAllowlistPath,
+  getNestedValue,
+  loadRawConfig,
+  saveRawConfig,
+  setNestedValue,
+} from "../lib/config";
 
 interface AllowlistConfig {
   values?: string[];
@@ -16,76 +21,6 @@ interface AllowlistValidationError {
   message: string;
 }
 
-function getRootDir(): string {
-  return join(process.env.BASE_DATA_DIR?.trim() || homedir(), ".vellum");
-}
-
-function getConfigPath(): string {
-  return join(getRootDir(), "workspace", "config.json");
-}
-
-function getAllowlistPath(): string {
-  return join(getRootDir(), "protected", "secret-allowlist.json");
-}
-
-function loadRawConfig(): Record<string, unknown> {
-  const configPath = getConfigPath();
-  if (!existsSync(configPath)) {
-    return {};
-  }
-  const raw = readFileSync(configPath, "utf-8");
-  return JSON.parse(raw) as Record<string, unknown>;
-}
-
-function saveRawConfig(config: Record<string, unknown>): void {
-  const configPath = getConfigPath();
-  const dir = dirname(configPath);
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
-  }
-  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
-}
-
-function getNestedValue(
-  obj: Record<string, unknown>,
-  path: string,
-): unknown {
-  const keys = path.split(".");
-  let current: unknown = obj;
-  for (const key of keys) {
-    if (
-      current === null ||
-      current === undefined ||
-      typeof current !== "object"
-    ) {
-      return undefined;
-    }
-    current = (current as Record<string, unknown>)[key];
-  }
-  return current;
-}
-
-function setNestedValue(
-  obj: Record<string, unknown>,
-  path: string,
-  value: unknown,
-): void {
-  const keys = path.split(".");
-  let current = obj;
-  for (let i = 0; i < keys.length - 1; i++) {
-    const key = keys[i];
-    if (
-      current[key] === undefined ||
-      current[key] === null ||
-      typeof current[key] !== "object"
-    ) {
-      current[key] = {};
-    }
-    current = current[key] as Record<string, unknown>;
-  }
-  current[keys[keys.length - 1]] = value;
-}
-
 function validateAllowlist(
   allowlistConfig: AllowlistConfig,
 ): AllowlistValidationError[] {

package/src/commands/retire.ts

@@ -1,5 +1,5 @@
 import { spawn } from "child_process";
-import { rmSync, writeFileSync } from "fs";
+import { renameSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import { basename, dirname, join } from "path";
 
@@ -63,20 +63,37 @@ async function retireLocal(name: string, entry: AssistantEntry): Promise<void> {
     } catch {}
   }
 
-  // Archive ~/.vellum before deleting
+  // Move ~/.vellum out of the way so the path is immediately available for the
+  // next hatch, then kick off the tar archive in the background.
+  const archivePath = getArchivePath(name);
+  const metadataPath = getMetadataPath(name);
+  const stagingDir = `${archivePath}.staging`;
+
   try {
-    const archivePath = getArchivePath(name);
-    const metadataPath = getMetadataPath(name);
-    await exec("tar", ["czf", archivePath, "-C", dirname(vellumDir), basename(vellumDir)]);
-    writeFileSync(metadataPath, JSON.stringify(entry, null, 2) + "\n");
-    console.log(`📦 Archived to ${archivePath}`);
+    renameSync(vellumDir, stagingDir);
   } catch (err) {
-    console.warn(`⚠️  Failed to archive: ${err instanceof Error ? err.message : err}`);
-    console.warn("Proceeding with permanent deletion.");
+    console.warn(`⚠️  Failed to move ${vellumDir}: ${err instanceof Error ? err.message : err}`);
+    console.warn("Skipping archive.");
+    console.log("\u2705 Local instance retired.");
+    return;
   }
 
-  rmSync(vellumDir, { recursive: true, force: true });
+  writeFileSync(metadataPath, JSON.stringify(entry, null, 2) + "\n");
+
+  // Spawn tar + cleanup in the background and detach so the CLI can exit
+  // immediately. The staging directory is removed once the archive is written.
+  const tarCmd = [
+    `tar czf ${JSON.stringify(archivePath)} -C ${JSON.stringify(dirname(stagingDir))} ${JSON.stringify(basename(stagingDir))}`,
+    `rm -rf ${JSON.stringify(stagingDir)}`,
+  ].join(" && ");
+
+  const child = spawn("sh", ["-c", tarCmd], {
+    stdio: "ignore",
+    detached: true,
+  });
+  child.unref();
 
+  console.log(`📦 Archiving to ${archivePath} in the background.`);
   console.log("\u2705 Local instance retired.");
 }
 

package/src/commands/tunnel.ts

@@ -0,0 +1,88 @@
+import { findAssistantByName, loadLatestAssistant } from "../lib/assistant-config";
+import { runNgrokTunnel } from "../lib/ngrok";
+
+const VALID_PROVIDERS = ["vellum", "ngrok", "cloudflare", "tailscale"] as const;
+type TunnelProvider = (typeof VALID_PROVIDERS)[number];
+
+const DEFAULT_PROVIDER: TunnelProvider = "vellum";
+
+interface TunnelArgs {
+  assistantName: string | null;
+  provider: TunnelProvider;
+}
+
+function parseArgs(): TunnelArgs {
+  const args = process.argv.slice(3);
+  let assistantName: string | null = null;
+  let provider: TunnelProvider = DEFAULT_PROVIDER;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") {
+      console.log("Usage: vellum tunnel [<name>] [options]");
+      console.log("");
+      console.log("Create a tunnel for a locally hosted assistant.");
+      console.log("");
+      console.log("Arguments:");
+      console.log(
+        "  <name>                        Name of the assistant (defaults to latest)",
+      );
+      console.log("");
+      console.log("Options:");
+      console.log(
+        `  --provider <provider>         Tunnel provider: ${VALID_PROVIDERS.join(", ")} (default: ${DEFAULT_PROVIDER})`,
+      );
+      process.exit(0);
+    } else if (arg === "--provider") {
+      const next = args[i + 1];
+      if (!next || !VALID_PROVIDERS.includes(next as TunnelProvider)) {
+        console.error(
+          `Error: --provider requires one of: ${VALID_PROVIDERS.join(", ")}`,
+        );
+        process.exit(1);
+      }
+      provider = next as TunnelProvider;
+      i++;
+    } else if (arg.startsWith("-")) {
+      console.error(`Error: Unknown option '${arg}'.`);
+      process.exit(1);
+    } else if (!assistantName) {
+      assistantName = arg;
+    } else {
+      console.error(`Error: Unexpected argument '${arg}'.`);
+      process.exit(1);
+    }
+  }
+
+  return { assistantName, provider };
+}
+
+export async function tunnel(): Promise<void> {
+  const { assistantName, provider } = parseArgs();
+
+  const entry = assistantName
+    ? findAssistantByName(assistantName)
+    : loadLatestAssistant();
+
+  if (!entry) {
+    if (assistantName) {
+      console.error(
+        `No assistant instance found with name '${assistantName}'.`,
+      );
+    } else {
+      console.error(
+        "No assistant instance found. Run `vellum hatch` first.",
+      );
+    }
+    process.exit(1);
+  }
+
+  if (provider === "ngrok") {
+    await runNgrokTunnel();
+    return;
+  }
+
+  throw new Error(
+    `Tunnel provider '${provider}' is not yet implemented.`,
+  );
+}

package/src/index.ts

@@ -21,6 +21,7 @@ import { retire } from "./commands/retire";
 import { skills } from "./commands/skills";
 import { sleep } from "./commands/sleep";
 import { ssh } from "./commands/ssh";
+import { tunnel } from "./commands/tunnel";
 import { wake } from "./commands/wake";
 
 const commands = {
@@ -39,6 +40,7 @@ const commands = {
   skills,
   sleep,
   ssh,
+  tunnel,
   wake,
   whoami,
 } as const;
@@ -99,6 +101,7 @@ async function main() {
     console.log("  skills   Browse and install skills from the Vellum catalog");
     console.log("  sleep    Stop the daemon process");
     console.log("  ssh      SSH into a remote assistant instance");
+    console.log("  tunnel   Create a tunnel for a locally hosted assistant");
     console.log("  wake     Start the daemon and gateway");
     console.log("  whoami   Show current logged-in user");
     process.exit(0);

package/src/lib/config.ts

@@ -0,0 +1,73 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+function getRootDir(): string {
+  return join(process.env.BASE_DATA_DIR?.trim() || homedir(), ".vellum");
+}
+
+export function getConfigPath(): string {
+  return join(getRootDir(), "workspace", "config.json");
+}
+
+export function getAllowlistPath(): string {
+  return join(getRootDir(), "protected", "secret-allowlist.json");
+}
+
+export function loadRawConfig(): Record<string, unknown> {
+  const configPath = getConfigPath();
+  if (!existsSync(configPath)) {
+    return {};
+  }
+  const raw = readFileSync(configPath, "utf-8");
+  return JSON.parse(raw) as Record<string, unknown>;
+}
+
+export function saveRawConfig(config: Record<string, unknown>): void {
+  const configPath = getConfigPath();
+  const dir = dirname(configPath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+}
+
+export function getNestedValue(
+  obj: Record<string, unknown>,
+  path: string,
+): unknown {
+  const keys = path.split(".");
+  let current: unknown = obj;
+  for (const key of keys) {
+    if (
+      current === null ||
+      current === undefined ||
+      typeof current !== "object"
+    ) {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[key];
+  }
+  return current;
+}
+
+export function setNestedValue(
+  obj: Record<string, unknown>,
+  path: string,
+  value: unknown,
+): void {
+  const keys = path.split(".");
+  let current = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    if (
+      current[key] === undefined ||
+      current[key] === null ||
+      typeof current[key] !== "object"
+    ) {
+      current[key] = {};
+    }
+    current = current[key] as Record<string, unknown>;
+  }
+  current[keys[keys.length - 1]] = value;
+}

package/src/lib/local.ts

@@ -2,7 +2,7 @@ import { execFileSync, spawn } from "child_process";
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
 import { createRequire } from "module";
 import { createConnection } from "net";
-import { homedir } from "os";
+import { homedir, hostname, networkInterfaces, platform } from "os";
 import { dirname, join } from "path";
 
 import { loadLatestAssistant } from "./assistant-config.js";
@@ -254,8 +254,8 @@ async function discoverPublicUrl(): Promise<string | undefined> {
 
   let externalIp: string | undefined;
 
-  // Try cloud-specific metadata services first for GCP and AWS.
-  if (cloud && cloud !== "local") {
+  // Try cloud-specific metadata services for GCP and AWS.
+  if (cloud === "gcp" || cloud === "aws") {
     try {
       if (cloud === "gcp") {
         const resp = await fetch(
@@ -281,46 +281,85 @@ async function discoverPublicUrl(): Promise<string | undefined> {
     } catch {
       // metadata service not reachable
     }
+
+    if (externalIp) {
+      console.log(`   Discovered external IP: ${externalIp}`);
+      return `http://${externalIp}:${GATEWAY_PORT}`;
+    }
   }
 
-  // Fall back to a public IP discovery service for all environments
-  // (local, custom, or when cloud-specific metadata didn't resolve).
-  if (!externalIp) {
-    externalIp = await discoverPublicIpFallback();
+  // For local and custom environments, use the local LAN address.
+  // On macOS, prefer the .local hostname (Bonjour/mDNS) so other devices on
+  // the same network can reach the gateway by name.
+  if (platform() === "darwin") {
+    const localHostname = getMacLocalHostname();
+    if (localHostname) {
+      console.log(`   Discovered macOS local hostname: ${localHostname}`);
+      return `http://${localHostname}:${GATEWAY_PORT}`;
+    }
   }
 
-  if (externalIp) {
-    console.log(`   Discovered external IP: ${externalIp}`);
-    return `http://${externalIp}:${GATEWAY_PORT}`;
+  const lanIp = getLocalLanIPv4();
+  if (lanIp) {
+    console.log(`   Discovered LAN IP: ${lanIp}`);
+    return `http://${lanIp}:${GATEWAY_PORT}`;
   }
 
-  // Final fallback to localhost when no public IP could be discovered.
+  // Final fallback to localhost when no LAN address could be discovered.
   return `http://localhost:${GATEWAY_PORT}`;
 }
 
-/** Try to discover the machine's public IP using external services.
- *  Attempts multiple providers for resilience. */
-async function discoverPublicIpFallback(): Promise<string | undefined> {
-  const services = [
-    "https://api.ipify.org",
-    "https://ifconfig.me/ip",
-    "https://icanhazip.com",
-  ];
+/**
+ * Returns the macOS Bonjour/mDNS `.local` hostname (e.g. "Vargass-Mac-Mini.local"),
+ * or undefined if not running on macOS or the hostname cannot be determined.
+ */
+function getMacLocalHostname(): string | undefined {
+  const host = hostname();
+  if (!host) return undefined;
+  // macOS hostnames already end with .local when Bonjour is active
+  if (host.endsWith(".local")) return host;
+  // Otherwise, append .local — macOS resolves <ComputerName>.local via mDNS
+  return `${host}.local`;
+}
 
-  for (const url of services) {
-    try {
-      const resp = await fetch(url, { signal: AbortSignal.timeout(3000) });
-      if (resp.ok) {
-        const ip = (await resp.text()).trim();
-        // Basic validation: must look like an IPv4 or IPv6 address
-        if (ip && /^[\d.:a-fA-F]+$/.test(ip)) {
-          return ip;
-        }
+/**
+ * Returns the local IPv4 address most likely to be reachable from other
+ * devices on the same LAN.
+ *
+ * Priority order:
+ *   1. en0 (Wi-Fi on macOS)
+ *   2. en1 (secondary network on macOS)
+ *   3. First non-loopback IPv4 on any interface
+ *
+ * Skips link-local addresses (169.254.x.x) and IPv6.
+ * Returns undefined if no suitable address is found.
+ */
+function getLocalLanIPv4(): string | undefined {
+  const ifaces = networkInterfaces();
+
+  // Priority interfaces in order
+  const priorityInterfaces = ["en0", "en1"];
+
+  for (const ifName of priorityInterfaces) {
+    const addrs = ifaces[ifName];
+    if (!addrs) continue;
+    for (const addr of addrs) {
+      if (addr.family === "IPv4" && !addr.internal && !addr.address.startsWith("169.254.")) {
+        return addr.address;
+      }
+    }
+  }
+
+  // Fallback: first non-loopback, non-link-local IPv4 on any interface
+  for (const [, addrs] of Object.entries(ifaces)) {
+    if (!addrs) continue;
+    for (const addr of addrs) {
+      if (addr.family === "IPv4" && !addr.internal && !addr.address.startsWith("169.254.")) {
+        return addr.address;
       }
-    } catch {
-      // Service unreachable, try the next one
     }
   }
+
   return undefined;
 }
 

package/src/lib/ngrok.ts

@@ -0,0 +1,263 @@
+import { execFileSync, spawn, type ChildProcess } from "node:child_process";
+
+import { loadRawConfig, saveRawConfig } from "./config";
+import { GATEWAY_PORT } from "./constants";
+
+const NGROK_API_URL = "http://127.0.0.1:4040/api/tunnels";
+const NGROK_POLL_INTERVAL_MS = 500;
+const NGROK_POLL_TIMEOUT_MS = 15_000;
+
+interface NgrokTunnel {
+  public_url: string;
+  config?: { addr?: string };
+}
+
+interface NgrokTunnelsResponse {
+  tunnels: NgrokTunnel[];
+}
+
+/**
+ * Check whether ngrok is installed and accessible on the PATH.
+ * Returns the version string if installed, null otherwise.
+ */
+export function getNgrokVersion(): string | null {
+  try {
+    const output = execFileSync("ngrok", ["version"], {
+      encoding: "utf-8",
+      timeout: 5_000,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return output.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Query the ngrok local API for running tunnels.
+ * Returns the list of tunnels, or null if the API is unreachable.
+ */
+async function queryNgrokTunnels(): Promise<NgrokTunnel[] | null> {
+  try {
+    const res = await fetch(NGROK_API_URL, {
+      signal: AbortSignal.timeout(2_000),
+    });
+    if (!res.ok) return null;
+    const data = (await res.json()) as NgrokTunnelsResponse;
+    return data.tunnels ?? [];
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Find an existing ngrok tunnel that targets the given local address.
+ * Returns the HTTPS public URL if found, null otherwise.
+ */
+export async function findExistingTunnel(
+  targetPort: number,
+): Promise<string | null> {
+  const tunnels = await queryNgrokTunnels();
+  if (!tunnels || tunnels.length === 0) return null;
+
+  const targetAddrs = [
+    `localhost:${targetPort}`,
+    `127.0.0.1:${targetPort}`,
+    `http://localhost:${targetPort}`,
+    `http://127.0.0.1:${targetPort}`,
+  ];
+
+  // Prefer HTTPS tunnel
+  for (const t of tunnels) {
+    const addr = t.config?.addr ?? "";
+    if (targetAddrs.includes(addr) && t.public_url.startsWith("https://")) {
+      return t.public_url;
+    }
+  }
+
+  // Fall back to any tunnel pointing at the target
+  for (const t of tunnels) {
+    const addr = t.config?.addr ?? "";
+    if (targetAddrs.includes(addr) && t.public_url) {
+      return t.public_url;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Start an ngrok process tunneling HTTP traffic to the given local port.
+ * Returns the spawned child process.
+ */
+export function startNgrokProcess(targetPort: number): ChildProcess {
+  const child = spawn("ngrok", ["http", String(targetPort), "--log=stdout"], {
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  return child;
+}
+
+/**
+ * Poll the ngrok local API until an HTTPS tunnel URL appears.
+ * Returns the public URL, or throws if the timeout is exceeded.
+ */
+export async function waitForNgrokUrl(
+  timeoutMs: number = NGROK_POLL_TIMEOUT_MS,
+): Promise<string> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const tunnels = await queryNgrokTunnels();
+    if (tunnels && tunnels.length > 0) {
+      // Prefer HTTPS
+      const httpsTunnel = tunnels.find((t) =>
+        t.public_url.startsWith("https://"),
+      );
+      if (httpsTunnel) return httpsTunnel.public_url;
+      if (tunnels[0]?.public_url) return tunnels[0].public_url;
+    }
+    await new Promise((r) => setTimeout(r, NGROK_POLL_INTERVAL_MS));
+  }
+  throw new Error(
+    `ngrok tunnel did not become available within ${timeoutMs / 1000}s. Check ngrok logs for errors.`,
+  );
+}
+
+/**
+ * Persist a public ingress URL to the workspace config and enable ingress.
+ */
+function saveIngressUrl(publicUrl: string): void {
+  const config = loadRawConfig();
+  const ingress = (config.ingress ?? {}) as Record<string, unknown>;
+  ingress.publicBaseUrl = publicUrl;
+  ingress.enabled = true;
+  config.ingress = ingress;
+  saveRawConfig(config);
+}
+
+/**
+ * Clear the ingress public base URL from the workspace config.
+ */
+function clearIngressUrl(): void {
+  const config = loadRawConfig();
+  const ingress = (config.ingress ?? {}) as Record<string, unknown>;
+  delete ingress.publicBaseUrl;
+  config.ingress = ingress;
+  saveRawConfig(config);
+}
+
+/**
+ * Run the ngrok tunnel workflow: check installation, find or start a tunnel,
+ * save the public URL to config, and block until exit or signal.
+ */
+export async function runNgrokTunnel(): Promise<void> {
+  const version = getNgrokVersion();
+  if (!version) {
+    console.error("Error: ngrok is not installed.");
+    console.error("");
+    console.error("Install ngrok:");
+    console.error("  macOS:  brew install ngrok/ngrok/ngrok");
+    console.error("  Linux:  sudo snap install ngrok");
+    console.error("");
+    console.error(
+      "Then authenticate: ngrok config add-authtoken <your-token>",
+    );
+    console.error(
+      "  Get your token at: https://dashboard.ngrok.com/get-started/your-authtoken",
+    );
+    process.exit(1);
+  }
+
+  console.log(`Using ${version}`);
+
+  const port = GATEWAY_PORT;
+
+  // Check for an existing ngrok tunnel pointing at the gateway
+  const existingUrl = await findExistingTunnel(port);
+  if (existingUrl) {
+    console.log(`Found existing ngrok tunnel: ${existingUrl}`);
+    saveIngressUrl(existingUrl);
+    console.log("Ingress URL saved to config.");
+    console.log("");
+    console.log(
+      "Tunnel is already running. Press Ctrl+C to detach (tunnel stays active).",
+    );
+
+    // Block until SIGINT/SIGTERM
+    await new Promise<void>((resolve) => {
+      process.on("SIGINT", () => resolve());
+      process.on("SIGTERM", () => resolve());
+    });
+    return;
+  }
+
+  console.log(`Starting ngrok tunnel to localhost:${port}...`);
+
+  let publicUrl: string | undefined;
+
+  const ngrokProcess = startNgrokProcess(port);
+
+  const cleanup = () => {
+    if (!ngrokProcess.killed) {
+      ngrokProcess.kill("SIGTERM");
+    }
+    if (publicUrl) {
+      console.log("\nClearing ingress URL from config...");
+      clearIngressUrl();
+    }
+  };
+
+  process.on("SIGINT", () => {
+    cleanup();
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    cleanup();
+    process.exit(0);
+  });
+
+  ngrokProcess.on("error", (err: Error) => {
+    console.error(`ngrok process error: ${err.message}`);
+    process.exit(1);
+  });
+
+  ngrokProcess.on("exit", (code: number | null) => {
+    if (code !== null && code !== 0) {
+      console.error(`ngrok exited with code ${code}.`);
+      console.error(
+        "Check that ngrok is authenticated: ngrok config add-authtoken <token>",
+      );
+      process.exit(1);
+    }
+  });
+
+  // Pipe ngrok stdout/stderr to console for visibility
+  ngrokProcess.stdout?.on("data", (data: Buffer) => {
+    const line = data.toString().trim();
+    if (line) console.log(`[ngrok] ${line}`);
+  });
+  ngrokProcess.stderr?.on("data", (data: Buffer) => {
+    const line = data.toString().trim();
+    if (line) console.error(`[ngrok] ${line}`);
+  });
+
+  try {
+    publicUrl = await waitForNgrokUrl();
+  } catch (err) {
+    cleanup();
+    throw err;
+  }
+
+  console.log("");
+  console.log(`Tunnel established: ${publicUrl}`);
+  console.log(`Forwarding to:     localhost:${port}`);
+
+  saveIngressUrl(publicUrl);
+  console.log("Ingress URL saved to config.");
+  console.log("");
+  console.log("Press Ctrl+C to stop the tunnel and clear the ingress URL.");
+
+  // Keep running until the ngrok process exits or we receive a signal
+  await new Promise<void>((resolve) => {
+    ngrokProcess.on("exit", () => resolve());
+  });
+}