portless 0.13.1 → 0.15.0

package/dist/cli.js

@@ -4,16 +4,19 @@ import {
   PORTLESS_HEADER,
   RouteConflictError,
   RouteStore,
+  checkHostResolution,
   cleanHostsFile,
   createHttpRedirectServer,
   createProxyServer,
   fixOwnership,
   formatUrl,
+  getManagedHostnames,
   isErrnoException,
+  isProcessAlive,
   parseHostname,
   shouldAutoSyncHosts,
   syncHostsFile
-} from "./chunk-3WLVQXFE.js";
+} from "./chunk-PCBKLZK2.js";
 
 // src/colors.ts
 function supportsColor() {
@@ -41,7 +44,7 @@ var colors_default = { bold, dim, red, green, yellow, blue, cyan, white, gray };
 // src/cli.ts
 import * as fs9 from "fs";
 import * as path9 from "path";
-import { spawn as spawn3, spawnSync as spawnSync4 } from "child_process";
+import { spawn as spawn4, spawnSync as spawnSync5 } from "child_process";
 import { StringDecoder } from "string_decoder";
 
 // src/certs.ts
@@ -999,6 +1002,178 @@ function formatTailscaleUrl(baseUrl, httpsPort) {
   return `${trimmed}:${httpsPort}`;
 }
 
+// src/ngrok.ts
+import { spawn, spawnSync as spawnSync2 } from "child_process";
+var NGROK_BINARY = "ngrok";
+var NGROK_START_TIMEOUT_MS = 3e4;
+var NGROK_COMMAND_TIMEOUT_MS = 1e4;
+var OUTPUT_BUFFER_LIMIT = 16384;
+function defaultSpawner(args) {
+  return spawn(NGROK_BINARY, args, {
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true
+  });
+}
+function defaultRunner2(args) {
+  const result = spawnSync2(NGROK_BINARY, args, {
+    encoding: "utf-8",
+    killSignal: "SIGKILL",
+    timeout: NGROK_COMMAND_TIMEOUT_MS
+  });
+  return {
+    status: result.status,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    ...result.error ? { error: result.error } : {}
+  };
+}
+function normalizeSpace2(value) {
+  return value.trim().replace(/\s+/g, " ");
+}
+function formatSpawnError(error) {
+  const errno = error;
+  if (errno.code === "ENOENT") {
+    return new Error(
+      "ngrok CLI not found. Install ngrok (https://ngrok.com/download) and ensure `ngrok` is on PATH."
+    );
+  }
+  return new Error(`Failed to start ngrok: ${error.message}`);
+}
+function formatOutputError(output) {
+  const details = normalizeSpace2(output);
+  const lower = details.toLowerCase();
+  if (lower.includes("authtoken") || lower.includes("authentication") || lower.includes("not logged in")) {
+    return new Error(
+      "ngrok could not start because authentication is not configured. Run `ngrok config add-authtoken <token>`, then run portless again."
+    );
+  }
+  return new Error(
+    `Failed to start ngrok tunnel: ${details || "ngrok exited before printing a public URL"}`
+  );
+}
+function ensureNgrokAvailable(runner = defaultRunner2) {
+  const result = runner(["version"]);
+  if (result.error) {
+    throw formatSpawnError(result.error);
+  }
+  if (result.status !== 0) {
+    const details = normalizeSpace2(result.stderr || result.stdout);
+    throw new Error(`Failed to check ngrok version: ${details || "unknown ngrok error"}`);
+  }
+}
+function cleanUrl(value) {
+  return value.replace(/[),.]+$/g, "");
+}
+function extractNgrokUrl(output) {
+  const urlMatches = output.matchAll(/https:\/\/[^\s"'<>]+/g);
+  for (const match of urlMatches) {
+    const raw = match[0];
+    const matchIndex = match.index ?? 0;
+    const before = output.slice(Math.max(0, matchIndex - 80), matchIndex).toLowerCase();
+    const looksLikeTunnel = before.includes("forwarding") || before.includes("url=") || before.includes('"url"') || before.includes("started tunnel");
+    if (!looksLikeTunnel) continue;
+    const candidate = cleanUrl(raw);
+    try {
+      const parsed = new URL(candidate);
+      if (parsed.hostname === "ngrok.com" || parsed.hostname.endsWith(".ngrok.com")) {
+        continue;
+      }
+      return parsed.toString().replace(/\/$/, "");
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+function buildNgrokArgs(localPort, hostHeader = "rewrite") {
+  return [
+    "http",
+    "--log=stdout",
+    "--log-format=logfmt",
+    `--host-header=${hostHeader}`,
+    `http://127.0.0.1:${localPort}`
+  ];
+}
+function startNgrok(localPort, options = {}) {
+  const spawner = options.spawner ?? defaultSpawner;
+  const timeoutMs = options.timeoutMs ?? NGROK_START_TIMEOUT_MS;
+  const args = buildNgrokArgs(localPort, options.hostHeader);
+  let child;
+  try {
+    child = spawner(args);
+  } catch (err) {
+    return Promise.reject(formatSpawnError(err instanceof Error ? err : new Error(String(err))));
+  }
+  return new Promise((resolve4, reject) => {
+    let settled = false;
+    let started = false;
+    let output = "";
+    const settle = (fn) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      fn();
+    };
+    const appendOutput = (chunk) => {
+      if (settled) return;
+      output += chunk.toString();
+      if (output.length > OUTPUT_BUFFER_LIMIT) {
+        output = output.slice(-OUTPUT_BUFFER_LIMIT);
+      }
+      const url = extractNgrokUrl(output);
+      if (url) {
+        settle(() => {
+          started = true;
+          resolve4({ url, pid: child.pid, child });
+        });
+      }
+    };
+    const timer = setTimeout(() => {
+      try {
+        child.kill("SIGTERM");
+      } catch {
+      }
+      settle(
+        () => reject(
+          new Error(
+            "Timed out waiting for ngrok to print a public URL. Check that ngrok is authenticated and can connect."
+          )
+        )
+      );
+    }, timeoutMs);
+    child.stdout?.on("data", appendOutput);
+    child.stderr?.on("data", appendOutput);
+    child.on("error", (err) => {
+      settle(() => reject(formatSpawnError(err)));
+    });
+    child.on("exit", (code, signal) => {
+      if (settled) {
+        if (started) options.onExit?.(code, signal);
+        return;
+      }
+      settle(() => {
+        const suffix = signal ? ` (signal ${signal})` : code !== null ? ` (exit ${code})` : "";
+        const error = formatOutputError(output);
+        reject(new Error(`${error.message}${suffix}`));
+      });
+    });
+  });
+}
+function stopNgrokProcess(child) {
+  if (!child) return;
+  try {
+    child.kill("SIGTERM");
+  } catch {
+  }
+}
+function stopNgrok(route) {
+  if (!route.ngrokPid) return;
+  try {
+    process.kill(route.ngrokPid, "SIGTERM");
+  } catch {
+  }
+}
+
 // src/auto.ts
 import { createHash as createHash2 } from "crypto";
 import { execFileSync as execFileSync2 } from "child_process";
@@ -1181,7 +1356,7 @@ import * as net from "net";
 import * as os from "os";
 import * as path3 from "path";
 import * as readline from "readline";
-import { execSync, spawn } from "child_process";
+import { execSync, spawn as spawn2 } from "child_process";
 var isWindows = process.platform === "win32";
 var FALLBACK_PROXY_PORT = 1355;
 var PRIVILEGED_PORT_THRESHOLD = 1024;
@@ -1331,6 +1506,7 @@ function readPortFromDir(dir) {
   }
 }
 var TLS_MARKER_FILE = "proxy.tls";
+var CUSTOM_CERT_MARKER_FILE = "proxy.custom-cert";
 function readTlsMarker(dir) {
   try {
     return fs3.existsSync(path3.join(dir, TLS_MARKER_FILE));
@@ -1349,6 +1525,24 @@ function writeTlsMarker(dir, enabled2) {
     }
   }
 }
+function readCustomCertMarker(dir) {
+  try {
+    return fs3.existsSync(path3.join(dir, CUSTOM_CERT_MARKER_FILE));
+  } catch {
+    return false;
+  }
+}
+function writeCustomCertMarker(dir, enabled2) {
+  const markerPath = path3.join(dir, CUSTOM_CERT_MARKER_FILE);
+  if (enabled2) {
+    fs3.writeFileSync(markerPath, "1", { mode: 420 });
+  } else {
+    try {
+      fs3.unlinkSync(markerPath);
+    } catch {
+    }
+  }
+}
 var LAN_MARKER_FILE = "proxy.lan";
 function readLanMarker(dir) {
   try {
@@ -1718,10 +1912,10 @@ function spawnCommand(commandArgs, options) {
       }
     }
   }
-  const child = isWindows ? spawn("cmd.exe", ["/d", "/s", "/c", commandArgs.join(" ")], {
+  const child = isWindows ? spawn2("cmd.exe", ["/d", "/s", "/c", commandArgs.join(" ")], {
     stdio: "inherit",
     env
-  }) : spawn("/bin/sh", ["-c", commandArgs.map(shellEscape).join(" ")], {
+  }) : spawn2("/bin/sh", ["-c", commandArgs.map(shellEscape).join(" ")], {
     stdio: "inherit",
     env,
     detached: true
@@ -1829,6 +2023,7 @@ var PORTLESS_STATE_FILES = [
   "proxy.port",
   "proxy.log",
   "proxy.tls",
+  "proxy.custom-cert",
   "proxy.tld",
   "proxy.lan",
   "ca-key.pem",
@@ -1867,7 +2062,7 @@ function removePortlessStateFiles(dir) {
 }
 
 // src/mdns.ts
-import { spawn as spawn2, spawnSync as spawnSync2 } from "child_process";
+import { spawn as spawn3, spawnSync as spawnSync3 } from "child_process";
 
 // src/lan-ip.ts
 import { createSocket } from "dgram";
@@ -1983,7 +2178,7 @@ function getMdnsPublisher() {
   return null;
 }
 function hasCommand(command, probeArgs) {
-  const result = spawnSync2(command, probeArgs, {
+  const result = spawnSync3(command, probeArgs, {
     stdio: "ignore",
     timeout: 1e3,
     windowsHide: true
@@ -2042,7 +2237,7 @@ function publish(hostname, port, ip, onError) {
   if (!publisher) {
     return;
   }
-  const child = spawn2(publisher.command, publisher.buildArgs(fqdn, name, port, ip), {
+  const child = spawn3(publisher.command, publisher.buildArgs(fqdn, name, port, ip), {
     stdio: "ignore",
     detached: false
   });
@@ -2595,7 +2790,7 @@ function hasTurboConfig(wsRoot) {
 import * as fs8 from "fs";
 import * as os2 from "os";
 import * as path8 from "path";
-import { spawnSync as spawnSync3 } from "child_process";
+import { spawnSync as spawnSync4 } from "child_process";
 var DEFAULT_SERVICE_PORT = getProtocolPort(true);
 var SERVICE_LABEL = "sh.portless.proxy";
 var SYSTEMD_SERVICE = "portless.service";
@@ -2614,8 +2809,8 @@ var DEFAULT_SERVICE_CONFIG = {
   useWildcard: false,
   extraEnv: {}
 };
-function defaultRunner2(command, args, options) {
-  return spawnSync3(command, args, {
+function defaultRunner3(command, args, options) {
+  return spawnSync4(command, args, {
     encoding: "utf-8",
     stdio: options?.stdio ?? "pipe"
   });
@@ -3337,7 +3532,7 @@ async function uninstallService(entryScript, runner) {
   }
   console.log(colors_default.green("Portless service uninstalled."));
 }
-function tryUninstallService(entryScript, runner = defaultRunner2) {
+function tryUninstallService(entryScript, runner = defaultRunner3) {
   let installed = false;
   try {
     const spec = currentServiceSpec(entryScript);
@@ -3465,7 +3660,7 @@ ${colors_default.bold("Notes:")}
 }
 async function handleService(args, options) {
   const action = args[1];
-  const runner = options.runner || defaultRunner2;
+  const runner = options.runner || defaultRunner3;
   if (!action || action === "--help" || action === "-h") {
     printServiceHelp();
     process.exit(0);
@@ -3666,7 +3861,7 @@ function collectPortlessEnvArgs2() {
 function sudoStop(port) {
   const stopArgs = [process.execPath, getEntryScript(), "proxy", "stop", "-p", String(port)];
   console.log(colors_default.yellow("Proxy is running as root. Elevating with sudo to stop it..."));
-  const result = spawnSync4("sudo", ["env", ...collectPortlessEnvArgs2(), ...stopArgs], {
+  const result = spawnSync5("sudo", ["env", ...collectPortlessEnvArgs2(), ...stopArgs], {
     stdio: "inherit",
     timeout: SUDO_SPAWN_TIMEOUT_MS
   });
@@ -3675,7 +3870,7 @@ function sudoStop(port) {
 function runCleanWithSudo(reason) {
   console.log(colors_default.yellow(`${reason} Requesting sudo...`));
   const home = process.env.HOME;
-  const result = spawnSync4(
+  const result = spawnSync5(
     "sudo",
     [
       "env",
@@ -3694,13 +3889,21 @@ function runCleanWithSudo(reason) {
 }
 function runServiceUninstallWithSudo(reason) {
   console.log(colors_default.yellow(`${reason} Requesting sudo...`));
-  const result = spawnSync4("sudo", buildServiceUninstallSudoArgs(getEntryScript()), {
+  const result = spawnSync5("sudo", buildServiceUninstallSudoArgs(getEntryScript()), {
     stdio: "inherit",
     timeout: SUDO_SPAWN_TIMEOUT_MS
   });
   return result.status === 0;
 }
-function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict) {
+function isEnabledEnv(value) {
+  return value === "1" || value === "true";
+}
+function formatProcessExitSuffix(code, signal) {
+  if (signal) return ` (signal ${signal})`;
+  if (code !== null) return ` (exit ${code})`;
+  return "";
+}
+function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict, customCert = false) {
   store.ensureDir();
   const isTls = !!tlsOptions;
   const mdnsSupport = isMdnsSupported();
@@ -3829,6 +4032,7 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict) {
     fs9.writeFileSync(store.pidPath, process.pid.toString(), { mode: FILE_MODE });
     fs9.writeFileSync(store.portFilePath, proxyPort.toString(), { mode: FILE_MODE });
     writeTlsMarker(store.dir, isTls);
+    writeCustomCertMarker(store.dir, isTls && customCert);
     writeTldFile(store.dir, tld);
     writeLanMarker(store.dir, activeLanIp);
     fixOwnership(store.dir, store.pidPath, store.portFilePath);
@@ -3841,7 +4045,7 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict) {
     if (activeLanIp) {
       console.log(chalk.green(`LAN mode: ${activeLanIp}`));
       console.log(chalk.gray("Services are discoverable as <name>.local on your network"));
-      if (isTls) {
+      if (isTls && !customCert) {
         console.log(chalk.yellow("For HTTPS on devices, install the CA certificate:"));
         console.log(chalk.gray(`  ${path9.join(store.dir, "ca.pem")}`));
       }
@@ -3883,6 +4087,7 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict) {
     } catch {
     }
     writeTlsMarker(store.dir, false);
+    writeCustomCertMarker(store.dir, false);
     writeTldFile(store.dir, DEFAULT_TLD);
     writeLanMarker(store.dir, null);
     if (autoSyncHosts) cleanHostsFile();
@@ -3921,6 +4126,7 @@ async function stopProxy(store, proxyPort, _tls) {
           } catch {
           }
           writeTlsMarker(store.dir, false);
+          writeCustomCertMarker(store.dir, false);
           writeTldFile(store.dir, DEFAULT_TLD);
           writeLanMarker(store.dir, null);
           console.log(colors_default.green(`Killed process ${pid}. Proxy stopped.`));
@@ -3960,6 +4166,7 @@ async function stopProxy(store, proxyPort, _tls) {
       console.error(colors_default.red("Corrupted PID file. Removing it."));
       fs9.unlinkSync(pidPath);
       writeTlsMarker(store.dir, false);
+      writeCustomCertMarker(store.dir, false);
       writeTldFile(store.dir, DEFAULT_TLD);
       writeLanMarker(store.dir, null);
       return;
@@ -3978,6 +4185,7 @@ async function stopProxy(store, proxyPort, _tls) {
       } catch {
       }
       writeTlsMarker(store.dir, false);
+      writeCustomCertMarker(store.dir, false);
       writeTldFile(store.dir, DEFAULT_TLD);
       writeLanMarker(store.dir, null);
       return;
@@ -3991,6 +4199,7 @@ async function stopProxy(store, proxyPort, _tls) {
       console.log(colors_default.yellow("Removing stale PID file."));
       fs9.unlinkSync(pidPath);
       writeTlsMarker(store.dir, false);
+      writeCustomCertMarker(store.dir, false);
       writeTldFile(store.dir, DEFAULT_TLD);
       writeLanMarker(store.dir, null);
       return;
@@ -4002,6 +4211,7 @@ async function stopProxy(store, proxyPort, _tls) {
     } catch {
     }
     writeTlsMarker(store.dir, false);
+    writeCustomCertMarker(store.dir, false);
     writeTldFile(store.dir, DEFAULT_TLD);
     writeLanMarker(store.dir, null);
     console.log(colors_default.green("Proxy stopped."));
@@ -4038,6 +4248,9 @@ function listRoutes(store, proxyPort, tls2) {
       const tsLabel = route.tailscaleFunnel ? "funnel" : "tailscale";
       console.log(`    ${colors_default.gray(tsLabel + ":")} ${colors_default.green(route.tailscaleUrl)}`);
     }
+    if (route.ngrokUrl) {
+      console.log(`    ${colors_default.gray("ngrok:")} ${colors_default.green(route.ngrokUrl)}`);
+    }
   }
   console.log();
 }
@@ -4121,7 +4334,7 @@ async function ensureProxyRunning(proxyPort, tls2, desired) {
     proxyPort: startPort
   });
   const startArgs = [getEntryScript(), "proxy", "start", ...proxyStartConfig.args];
-  const result = spawnSync4(process.execPath, startArgs, {
+  const result = spawnSync5(process.execPath, startArgs, {
     stdio: "inherit",
     timeout: SUDO_SPAWN_TIMEOUT_MS
   });
@@ -4155,8 +4368,9 @@ async function runApp(initialStore, proxyPort, stateDir, name, commandArgs, tls2
   console.log(chalk.blue.bold(`
 portless
 `));
-  const wantsFunnel = process.env.PORTLESS_FUNNEL === "1" || process.env.PORTLESS_FUNNEL === "true";
-  const wantsTailscale = wantsFunnel || process.env.PORTLESS_TAILSCALE === "1" || process.env.PORTLESS_TAILSCALE === "true";
+  const wantsFunnel = isEnabledEnv(process.env.PORTLESS_FUNNEL);
+  const wantsTailscale = wantsFunnel || isEnabledEnv(process.env.PORTLESS_TAILSCALE);
+  const wantsNgrok = isEnabledEnv(process.env.PORTLESS_NGROK);
   let tsBaseUrl;
   if (wantsTailscale) {
     try {
@@ -4177,6 +4391,18 @@ portless
       process.exit(1);
     }
   }
+  if (wantsNgrok) {
+    try {
+      ensureNgrokAvailable();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(colors_default.red(`Error: ${message}`));
+      if (message.includes("not found")) {
+        console.error(colors_default.blue("Install ngrok: https://ngrok.com/download"));
+      }
+      process.exit(1);
+    }
+  }
   let desired;
   try {
     desired = resolveProxyDesiredState(lanMode);
@@ -4262,6 +4488,36 @@ portless
   }
   let tailscaleHttpsPort;
   let tailscaleUrl;
+  let ngrokUrl;
+  let ngrokProcess;
+  let stoppingNgrok = false;
+  let ngrokRouteReady = false;
+  let ngrokExitHandled = false;
+  let pendingNgrokExit;
+  const handleNgrokExit = (code, signal) => {
+    if (stoppingNgrok || ngrokExitHandled) return;
+    if (!ngrokRouteReady) {
+      pendingNgrokExit = { code, signal };
+      return;
+    }
+    ngrokExitHandled = true;
+    ngrokUrl = void 0;
+    console.warn(
+      colors_default.yellow(
+        `Warning: ngrok tunnel for ${hostname} stopped${formatProcessExitSuffix(
+          code,
+          signal
+        )}. Removing its public URL from the route list.`
+      )
+    );
+    try {
+      store.updateRoute(hostname, {
+        ngrokUrl: null,
+        ngrokPid: null
+      });
+    } catch {
+    }
+  };
   if (wantsTailscale && tsBaseUrl) {
     const maxAttempts = 3;
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
@@ -4299,6 +4555,51 @@ portless
     } catch {
     }
   }
+  if (wantsNgrok) {
+    try {
+      ngrokProcess = await startNgrok(port, {
+        hostHeader: hostname,
+        onExit: handleNgrokExit
+      });
+      ngrokUrl = ngrokProcess.url;
+      console.log(chalk.green(`  ngrok -> ${ngrokUrl}`));
+      console.log(chalk.gray("  (accessible from the public internet via ngrok)\n"));
+      try {
+        store.updateRoute(hostname, {
+          ngrokUrl,
+          ngrokPid: ngrokProcess.pid
+        });
+      } catch {
+      } finally {
+        ngrokRouteReady = true;
+        if (pendingNgrokExit) {
+          handleNgrokExit(pendingNgrokExit.code, pendingNgrokExit.signal);
+          pendingNgrokExit = void 0;
+        }
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(colors_default.red(`Error: ${message}`));
+      if (message.includes("not found")) {
+        console.error(colors_default.blue("Install ngrok: https://ngrok.com/download"));
+      } else if (message.includes("authentication")) {
+        console.error(colors_default.blue("Configure ngrok authentication:"));
+        console.error(colors_default.cyan("  ngrok config add-authtoken <token>"));
+      }
+      try {
+        unregisterTailscale({
+          tailscaleHttpsPort,
+          tailscaleFunnel: wantsFunnel || void 0
+        });
+      } catch {
+      }
+      try {
+        store.removeRoute(hostname, process.pid);
+      } catch {
+      }
+      process.exit(1);
+    }
+  }
   const basename5 = path9.basename(commandArgs[0]);
   const isExpo = basename5 === "expo";
   const isExpoLan = isExpo && (lanMode || isLanEnvEnabled());
@@ -4333,9 +4634,12 @@ portless
       // own LAN discovery natively.
       ...lanMode ? { PORTLESS_LAN: "1" } : {},
       ...tailscaleUrl ? { PORTLESS_TAILSCALE_URL: tailscaleUrl } : {},
+      ...ngrokUrl ? { PORTLESS_NGROK_URL: ngrokUrl } : {},
       ...caEnv
     },
     onCleanup: () => {
+      stoppingNgrok = true;
+      stopNgrokProcess(ngrokProcess?.child);
       try {
         unregisterTailscale({
           tailscaleHttpsPort,
@@ -4344,7 +4648,7 @@ portless
       } catch {
       }
       try {
-        store.removeRoute(hostname);
+        store.removeRoute(hostname, process.pid);
       } catch {
       }
     }
@@ -4372,7 +4676,7 @@ function appPortFromEnv() {
   }
   return port;
 }
-function applyTailscaleFlag(flag) {
+function applySharingFlag(flag) {
   if (flag === "--tailscale") {
     process.env.PORTLESS_TAILSCALE = "1";
     return true;
@@ -4382,6 +4686,10 @@ function applyTailscaleFlag(flag) {
     process.env.PORTLESS_TAILSCALE = "1";
     return true;
   }
+  if (flag === "--ngrok") {
+    process.env.PORTLESS_NGROK = "1";
+    return true;
+  }
   return false;
 }
 function parseRunArgs(args) {
@@ -4407,6 +4715,9 @@ ${colors_default.bold("Options:")}
   --name <name>          Override the inferred base name (worktree prefix still applies)
   --force                Kill the existing process and take over its route
   --app-port <number>    Use a fixed port for the app (skip auto-assignment)
+  --tailscale            Share the app on your Tailscale network (tailnet)
+  --funnel               Share the app publicly via Tailscale Funnel
+  --ngrok                Share the app publicly via ngrok
   --help, -h             Show this help
 
 ${colors_default.bold("Name inference (in order):")}
@@ -4440,11 +4751,13 @@ ${colors_default.bold("Examples:")}
         process.exit(1);
       }
       name = args[i];
-    } else if (applyTailscaleFlag(args[i])) {
+    } else if (applySharingFlag(args[i])) {
     } else {
       console.error(colors_default.red(`Error: Unknown flag "${args[i]}".`));
       console.error(
-        colors_default.blue("Known flags: --name, --force, --app-port, --tailscale, --funnel, --help")
+        colors_default.blue(
+          "Known flags: --name, --force, --app-port, --tailscale, --funnel, --ngrok, --help"
+        )
       );
       process.exit(1);
     }
@@ -4466,10 +4779,12 @@ function parseAppArgs(args) {
     } else if (args[i] === "--app-port") {
       i++;
       appPort = parseAppPort(args[i]);
-    } else if (applyTailscaleFlag(args[i])) {
+    } else if (applySharingFlag(args[i])) {
     } else {
       console.error(colors_default.red(`Error: Unknown flag "${args[i]}".`));
-      console.error(colors_default.blue("Known flags: --force, --app-port, --tailscale, --funnel"));
+      console.error(
+        colors_default.blue("Known flags: --force, --app-port, --tailscale, --funnel, --ngrok")
+      );
       process.exit(1);
     }
     i++;
@@ -4485,10 +4800,12 @@ function parseAppArgs(args) {
     } else if (args[i] === "--app-port") {
       i++;
       appPort = parseAppPort(args[i]);
-    } else if (applyTailscaleFlag(args[i])) {
+    } else if (applySharingFlag(args[i])) {
     } else {
       console.error(colors_default.red(`Error: Unknown flag "${args[i]}".`));
-      console.error(colors_default.blue("Known flags: --force, --app-port, --tailscale, --funnel"));
+      console.error(
+        colors_default.blue("Known flags: --force, --app-port, --tailscale, --funnel, --ngrok")
+      );
       process.exit(1);
     }
     i++;
@@ -4516,13 +4833,14 @@ ${colors_default.bold("Usage:")}
   ${colors_default.cyan("portless run")}                     Same as above
   ${colors_default.cyan("portless run <cmd>")}               Run a command through the proxy
   ${colors_default.cyan("portless <name> <cmd>")}            Run with an explicit app name
-  ${colors_default.cyan("portless proxy start")}             Start the proxy (HTTPS on port 443, daemon)
+  ${colors_default.cyan("portless proxy start")}             Start the proxy (HTTPS on port 443, daemon); rarely needed since it auto-starts on first run
   ${colors_default.cyan("portless proxy stop")}              Stop the proxy
   ${colors_default.cyan("portless service install")}         Start proxy automatically when the OS starts
   ${colors_default.cyan("portless get <name>")}              Print URL for a service (for cross-service refs)
   ${colors_default.cyan("portless alias <name> <port>")}     Register a static route (e.g. for Docker)
   ${colors_default.cyan("portless alias --remove <name>")}   Remove a static route
   ${colors_default.cyan("portless list")}                    Show active routes
+  ${colors_default.cyan("portless doctor")}                  Check local portless health
   ${colors_default.cyan("portless trust")}                   Add local CA to system trust store
   ${colors_default.cyan("portless clean")}                   Remove portless state, trust entry, and hosts block
   ${colors_default.cyan("portless prune")}                   Kill orphaned dev servers from crashed sessions
@@ -4540,8 +4858,10 @@ ${colors_default.bold("Examples:")}
   portless service install --lan      # Persist LAN mode in the startup service
   portless service install --wildcard # Persist wildcard routing in the startup service
   portless get backend                # -> https://backend.localhost
+  portless doctor                     # Check proxy, routes, DNS, and CA trust
   portless myapp --tailscale next dev # -> also https://<node>.ts.net (tailnet)
   portless myapp --funnel next dev    # -> also https://<node>.ts.net (public)
+  portless myapp --ngrok next dev     # -> also https://<random>.ngrok.app (public)
 
 ${colors_default.bold("Configuration (portless.json):")}
   Optional. Portless works out of the box by running the "dev" script
@@ -4603,6 +4923,11 @@ ${colors_default.bold("Tailscale sharing:")}
   ${colors_default.cyan("portless myapp --tailscale next dev")}
   ${colors_default.cyan("portless myapp --funnel next dev")}
 
+${colors_default.bold("ngrok sharing:")}
+  Use --ngrok to expose your dev server to the public internet with ngrok.
+  Requires the ngrok CLI to be installed and authenticated.
+  ${colors_default.cyan("portless myapp --ngrok next dev")}
+
 ${colors_default.bold("Options:")}
   run [--name <name>] <cmd>      Infer project name (or override with --name)
                                 Adds worktree prefix in git worktrees
@@ -4622,6 +4947,7 @@ ${colors_default.bold("Options:")}
   --app-port <number>           Use a fixed port for the app (skip auto-assignment)
   --tailscale                   Share the app on your Tailscale network (tailnet)
   --funnel                      Share the app publicly via Tailscale Funnel
+  --ngrok                       Share the app publicly via ngrok
   --force                       Kill the existing process and take over its route
   --name <name>                 Use <name> as the app name (bypasses subcommand dispatch)
   --                            Stop flag parsing; everything after is passed to the child
@@ -4637,6 +4963,7 @@ ${colors_default.bold("Environment variables:")}
   PORTLESS_SYNC_HOSTS=0         Disable auto-sync of ${HOSTS_DISPLAY} (on by default)
   PORTLESS_TAILSCALE=1          Share apps on your Tailscale network (same as --tailscale)
   PORTLESS_FUNNEL=1             Share apps publicly via Tailscale Funnel (same as --funnel)
+  PORTLESS_NGROK=1              Share apps publicly via ngrok (same as --ngrok)
   PORTLESS_STATE_DIR=<path>     Override the state directory
   PORTLESS=0                    Run command directly without proxy
 
@@ -4646,6 +4973,7 @@ ${colors_default.bold("Child process environment:")}
   PORTLESS_URL                  Public URL of the app (e.g. https://myapp.localhost)
   PORTLESS_LAN                  Set to 1 when proxy is in LAN mode
   PORTLESS_TAILSCALE_URL        Tailscale URL of the app (when --tailscale is active)
+  PORTLESS_NGROK_URL            ngrok URL of the app (when --ngrok is active)
   NODE_EXTRA_CA_CERTS           Path to the portless CA (set when HTTPS is active)
 
 ${colors_default.bold("Safari / DNS:")}
@@ -4661,14 +4989,14 @@ ${colors_default.bold("Skip portless:")}
   PORTLESS=0 pnpm dev           # Runs command directly without proxy
 
 ${colors_default.bold("Reserved names:")}
-  run, get, alias, hosts, list, trust, clean, prune, proxy, service are subcommands and
+  run, get, alias, hosts, list, doctor, trust, clean, prune, proxy, service are subcommands and
   cannot be used as app names directly. Use "portless run" to infer the name,
   or "portless --name <name>" to force any name including reserved ones.
 `);
   process.exit(0);
 }
 function printVersion() {
-  console.log("0.13.1");
+  console.log("0.15.0");
   process.exit(0);
 }
 async function handleTrust() {
@@ -4689,7 +5017,7 @@ async function handleTrust() {
   const isPermissionError2 = result.error?.includes("Permission denied") || result.error?.includes("EACCES");
   if (isPermissionError2 && !isWindows && process.getuid?.() !== 0) {
     console.log(colors_default.yellow("Trusting the CA requires elevated privileges. Requesting sudo..."));
-    const sudoResult = spawnSync4(
+    const sudoResult = spawnSync5(
       "sudo",
       [
         "env",
@@ -4772,6 +5100,10 @@ ${colors_default.bold("Options:")}
       } catch {
       }
     }
+    if (route.ngrokPid) {
+      stopNgrok(route);
+      console.log(colors_default.green(`Stopped ngrok tunnel for ${route.hostname}.`));
+    }
   }
   const stateDirs = collectStateDirsForCleanup();
   for (const stateDir of stateDirs) {
@@ -4851,6 +5183,10 @@ ${colors_default.bold("Options:")}
       } catch {
       }
     }
+    if (route.ngrokPid) {
+      stopNgrok(route);
+      console.log(`  ${route.hostname} - stopped ngrok tunnel`);
+    }
   }
   let killed = 0;
   for (const route of stale) {
@@ -5029,7 +5365,7 @@ ${colors_default.bold("Auto-sync:")}
           `Writing to ${HOSTS_DISPLAY} requires elevated privileges. Requesting sudo...`
         )
       );
-      const result = spawnSync4(
+      const result = spawnSync5(
         "sudo",
         ["env", ...collectPortlessEnvArgs2(), process.execPath, getEntryScript(), "hosts", "clean"],
         {
@@ -5082,7 +5418,7 @@ ${colors_default.bold("Usage: portless hosts <command>")}
     console.log(
       colors_default.yellow(`Writing to ${HOSTS_DISPLAY} requires elevated privileges. Requesting sudo...`)
     );
-    const result = spawnSync4(
+    const result = spawnSync5(
       "sudo",
       ["env", ...collectPortlessEnvArgs2(), process.execPath, getEntryScript(), "hosts", "sync"],
       {
@@ -5097,6 +5433,355 @@ ${colors_default.bold("Usage: portless hosts <command>")}
   );
   process.exit(1);
 }
+function colorDoctorStatus(status) {
+  if (status === "fail") return colors_default.red;
+  if (status === "warn") return colors_default.yellow;
+  if (status === "ok") return colors_default.green;
+  return colors_default.gray;
+}
+function printDoctorFinding(finding) {
+  const status = finding.status.padEnd(5);
+  console.log(`${colorDoctorStatus(finding.status)(status)} ${finding.message}`);
+  if (finding.hint) {
+    console.log(colors_default.gray(`      ${finding.hint}`));
+  }
+}
+function isProcessAliveForDoctor(pid) {
+  if (pid <= 0) return true;
+  return isProcessAlive(pid);
+}
+function checkPathWritable(targetPath) {
+  try {
+    fs9.accessSync(targetPath, fs9.constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function findExistingAncestor(targetPath) {
+  let current = targetPath;
+  for (; ; ) {
+    if (fs9.existsSync(current)) return current;
+    const parent = path9.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+function checkCommandAvailable(command, args) {
+  const result = spawnSync5(command, args, {
+    stdio: "ignore",
+    timeout: 3e3,
+    windowsHide: true
+  });
+  return !result.error && (result.status === 0 || result.status === null);
+}
+function pluralize(count, singular, plural = `${singular}s`) {
+  return `${count} ${count === 1 ? singular : plural}`;
+}
+function isValidTcpPort(port) {
+  return Number.isInteger(port) && port >= 1 && port <= 65535;
+}
+function doctorProxyStartHint(proxyPort, tls2) {
+  const defaultPort = getDefaultPort(tls2);
+  const portArgs = proxyPort === defaultPort ? "" : ` -p ${proxyPort}`;
+  const tlsArgs = tls2 ? "" : " --no-tls";
+  return `Run: portless proxy start${portArgs}${tlsArgs}`;
+}
+async function handleDoctor(args) {
+  if (args[1] === "--help" || args[1] === "-h") {
+    console.log(`
+${colors_default.bold("portless doctor")} - Check local portless health and print suggested fixes.
+
+${colors_default.bold("Usage:")}
+  ${colors_default.cyan("portless doctor")}
+
+Checks Node.js, the state directory, proxy liveness, route entries, HTTPS CA
+trust, hostname resolution, and LAN mode prerequisites. It does not start,
+stop, clean, prune, trust, or modify portless state.
+
+${colors_default.bold("Options:")}
+  --help, -h             Show this help
+`);
+    process.exit(0);
+  }
+  if (args.length > 1) {
+    console.error(colors_default.red(`Error: Unknown argument "${args[1]}".`));
+    console.error(colors_default.cyan("  portless doctor --help"));
+    process.exit(1);
+  }
+  const findings = [];
+  const add = (status, message, hint) => {
+    findings.push({ status, message, hint });
+  };
+  let state;
+  try {
+    state = await discoverState();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    add("fail", `Could not discover portless state: ${message}`);
+    state = {
+      dir: resolveStateDir(),
+      port: getDefaultPort(!isHttpsEnvDisabled()),
+      tls: !isHttpsEnvDisabled(),
+      tld: DEFAULT_TLD,
+      lanMode: isLanEnvEnabled(),
+      lanIp: null
+    };
+  }
+  const store = new RouteStore(state.dir, {
+    onWarning: (msg) => add("warn", msg)
+  });
+  const hasPortFile = fs9.existsSync(store.portFilePath);
+  const configuredTls = hasPortFile ? state.tls : !isHttpsEnvDisabled();
+  const configuredPort = hasPortFile ? state.port : getDefaultPort(configuredTls);
+  const initialProxyRunning = await isProxyRunning(state.port, state.tls);
+  const probePort = initialProxyRunning || hasPortFile ? state.port : configuredPort;
+  const probeTls = initialProxyRunning || hasPortFile ? state.tls : configuredTls;
+  const proxyRunning = initialProxyRunning && probePort === state.port ? true : await isProxyRunning(probePort, probeTls);
+  const portListening = proxyRunning ? true : await isPortListening(probePort);
+  const proxyPort = proxyRunning || portListening || hasPortFile ? probePort : configuredPort;
+  const proxyTls = proxyRunning || portListening || hasPortFile ? probeTls : configuredTls;
+  const currentProxyStateIsHttp = (proxyRunning || portListening || hasPortFile) && !proxyTls;
+  const proxyUsesCustomCert = proxyTls && readCustomCertMarker(state.dir);
+  const stateExists = fs9.existsSync(state.dir);
+  console.log(colors_default.blue.bold("\nportless doctor\n"));
+  console.log(`Version: ${"0.15.0"}`);
+  console.log(`Node.js: ${process.versions.node}`);
+  console.log(`Platform: ${process.platform} ${process.arch}`);
+  console.log(`State dir: ${state.dir}`);
+  console.log(`Proxy target: ${formatUrl("127.0.0.1", proxyPort, proxyTls)}`);
+  console.log(`Mode: ${proxyTls ? "HTTPS" : "HTTP"}, .${state.tld}${state.lanMode ? ", LAN" : ""}`);
+  console.log("");
+  const nodeMajor = parseInt(process.versions.node.split(".")[0], 10);
+  if (nodeMajor >= 24) {
+    add("ok", `Node.js ${process.versions.node} satisfies portless requirements.`);
+  } else {
+    add("fail", `Node.js ${process.versions.node} is unsupported.`, "Install Node.js 24 or newer.");
+  }
+  if (stateExists) {
+    try {
+      const stat = fs9.statSync(state.dir);
+      if (!stat.isDirectory()) {
+        add("fail", `State path exists but is not a directory: ${state.dir}`);
+      } else if (checkPathWritable(state.dir)) {
+        add("ok", `State directory is writable: ${state.dir}`);
+      } else {
+        add("fail", `State directory is not writable: ${state.dir}`);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      add("fail", `Could not inspect state directory: ${message}`);
+    }
+  } else {
+    const ancestor = findExistingAncestor(path9.dirname(state.dir));
+    if (!ancestor) {
+      add(
+        "fail",
+        `State directory does not exist and no writable ancestor was found: ${state.dir}`
+      );
+    } else {
+      const ancestorStat = fs9.statSync(ancestor);
+      if (!ancestorStat.isDirectory()) {
+        add("fail", `State directory does not exist and ancestor is not a directory: ${ancestor}`);
+      } else if (checkPathWritable(ancestor)) {
+        add("info", `State directory has not been created yet: ${state.dir}`);
+      } else {
+        add("fail", `State directory does not exist and ancestor is not writable: ${ancestor}`);
+      }
+    }
+  }
+  if (proxyRunning) {
+    add("ok", `Proxy is responding on port ${proxyPort}.`);
+  } else if (portListening) {
+    const pid = findPidOnPort(proxyPort);
+    add(
+      "fail",
+      `Port ${proxyPort} is in use, but it is not a portless proxy.`,
+      pid ? `Process on port: PID ${pid}` : "Could not identify the process holding the port."
+    );
+  } else {
+    add(
+      "warn",
+      `Proxy is not running on port ${proxyPort}.`,
+      doctorProxyStartHint(proxyPort, proxyTls)
+    );
+  }
+  if (fs9.existsSync(store.pidPath)) {
+    try {
+      const rawPid = fs9.readFileSync(store.pidPath, "utf-8").trim();
+      const pid = parseInt(rawPid, 10);
+      if (isNaN(pid) || pid <= 0) {
+        add("fail", `Proxy PID file is invalid: ${store.pidPath}`);
+      } else if (!isProcessAliveForDoctor(pid)) {
+        add("warn", `Proxy PID file is stale: ${pid}`, "Run: portless proxy stop");
+      } else if (!proxyRunning) {
+        add(
+          "warn",
+          `Proxy PID file points to PID ${pid}, but no portless proxy is responding on port ${proxyPort}.`,
+          "Run: portless proxy stop"
+        );
+      } else {
+        const portPid = findPidOnPort(proxyPort);
+        if (portPid !== null && portPid !== pid) {
+          add(
+            "warn",
+            `Proxy PID file points to PID ${pid}, but port ${proxyPort} is owned by PID ${portPid}.`,
+            "Run: portless proxy stop"
+          );
+        } else {
+          add("ok", `Proxy PID file points to the responding proxy process: ${pid}`);
+        }
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      add("fail", `Could not read proxy PID file: ${message}`);
+    }
+  } else if (proxyRunning) {
+    add("warn", `Proxy is running but the PID file is missing: ${store.pidPath}`);
+  }
+  if (proxyUsesCustomCert) {
+    add("ok", "Proxy is configured with a custom TLS certificate.");
+  } else if (proxyTls || !currentProxyStateIsHttp && !isHttpsEnvDisabled()) {
+    if (checkCommandAvailable("openssl", ["version"])) {
+      add("ok", "OpenSSL is available for certificate generation.");
+    } else {
+      add(
+        "fail",
+        "OpenSSL is not available on PATH.",
+        isWindows ? "Install OpenSSL or add Git for Windows OpenSSL to PATH." : "Install OpenSSL with your system package manager."
+      );
+    }
+  } else {
+    add("info", "HTTPS is disabled, so OpenSSL is not required for this run.");
+  }
+  if (proxyTls && proxyUsesCustomCert) {
+    add("info", "Generated local CA is not required for custom TLS certificates.");
+  } else if (proxyTls) {
+    const caPath = path9.join(state.dir, "ca.pem");
+    if (fs9.existsSync(caPath)) {
+      if (isCATrusted(state.dir)) {
+        add("ok", "Local CA is trusted by the OS trust store.");
+      } else {
+        add(
+          "warn",
+          "Local CA exists but is not trusted by the OS trust store.",
+          "Run: portless trust"
+        );
+      }
+    } else if (proxyRunning) {
+      add("warn", `Generated CA file is missing: ${caPath}`);
+    } else {
+      add("info", "Local CA has not been generated yet.");
+    }
+  } else {
+    add("info", "HTTPS is disabled for the current proxy state.");
+  }
+  let rawRoutes = [];
+  try {
+    rawRoutes = store.loadRoutesRaw();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    add("fail", `Could not read routes: ${message}`);
+  }
+  const liveRoutes = rawRoutes.filter(
+    (route) => route.pid === 0 || isProcessAliveForDoctor(route.pid)
+  );
+  const staleRoutes = rawRoutes.filter(
+    (route) => route.pid !== 0 && !isProcessAliveForDoctor(route.pid)
+  );
+  if (rawRoutes.length === 0) {
+    add("info", "No routes are registered.");
+  } else if (staleRoutes.length === 0) {
+    add("ok", `Routes: ${pluralize(liveRoutes.length, "active route")}.`);
+  } else {
+    add(
+      "warn",
+      `Routes: ${pluralize(liveRoutes.length, "active route")}, ${pluralize(staleRoutes.length, "stale route")}.`,
+      "Run: portless prune"
+    );
+  }
+  for (const route of staleRoutes.slice(0, 5)) {
+    add("warn", `Stale route ${route.hostname} is owned by exited PID ${route.pid}.`);
+  }
+  if (staleRoutes.length > 5) {
+    add("warn", `${staleRoutes.length - 5} additional stale routes hidden.`);
+  }
+  const routePortChecks = await Promise.all(
+    liveRoutes.map(async (route) => {
+      const validPort = isValidTcpPort(route.port);
+      return {
+        route,
+        invalidPort: !validPort,
+        listening: validPort ? await isPortListening(route.port) : false
+      };
+    })
+  );
+  for (const { route, invalidPort, listening } of routePortChecks) {
+    if (invalidPort) {
+      add(
+        "warn",
+        `Route ${route.hostname} has invalid port ${route.port}.`,
+        route.pid === 0 ? "Remove or recreate the alias." : "Run: portless prune"
+      );
+      continue;
+    }
+    if (listening) continue;
+    add(
+      "warn",
+      `Route ${route.hostname} points to port ${route.port}, but nothing is listening there.`,
+      route.pid === 0 ? "Remove the alias or start that service." : "The app may still be starting."
+    );
+  }
+  if (state.lanMode || isLanEnvEnabled()) {
+    const mdns = isMdnsSupported();
+    if (mdns.supported) {
+      add("ok", "mDNS publishing support is available for LAN mode.");
+    } else {
+      add("fail", `LAN mode is enabled but mDNS publishing is unavailable: ${mdns.reason}`);
+    }
+    if (state.lanIp) {
+      add("ok", `LAN IP is recorded: ${state.lanIp}`);
+    } else {
+      add("warn", "LAN mode is enabled but no LAN IP is recorded.");
+    }
+  } else if (liveRoutes.length > 0) {
+    const managedHosts = new Set(getManagedHostnames());
+    const resolutionChecks = await Promise.all(
+      liveRoutes.map(async (route) => ({
+        hostname: route.hostname,
+        resolves: await checkHostResolution(route.hostname),
+        managed: managedHosts.has(route.hostname)
+      }))
+    );
+    const unresolved = resolutionChecks.filter((result) => !result.resolves);
+    if (unresolved.length === 0) {
+      add("ok", "Registered hostnames resolve through the system resolver.");
+    } else {
+      add(
+        "warn",
+        `${pluralize(unresolved.length, "hostname")} did not resolve through the system resolver.`,
+        "Run: portless hosts sync"
+      );
+      for (const result of unresolved.slice(0, 5)) {
+        const hostState = result.managed ? "present in hosts block" : "missing from hosts block";
+        add("warn", `${result.hostname} is ${hostState}.`);
+      }
+    }
+  }
+  for (const finding of findings) {
+    printDoctorFinding(finding);
+  }
+  const failures = findings.filter((finding) => finding.status === "fail").length;
+  const warnings = findings.filter((finding) => finding.status === "warn").length;
+  console.log("");
+  if (failures > 0) {
+    console.log(
+      colors_default.red(`Summary: ${pluralize(failures, "failure")}, ${pluralize(warnings, "warning")}.`)
+    );
+    process.exit(1);
+  }
+  console.log(colors_default.green(`Summary: 0 failures, ${pluralize(warnings, "warning")}.`));
+}
 async function handleProxy(args) {
   if (args[1] === "stop") {
     let explicitPort;
@@ -5373,7 +6058,7 @@ ${colors_default.bold("LAN mode (--lan):")}
     if (!hasExplicitPort) {
       console.log(colors_default.gray(`(To skip sudo, use an unprivileged port: ${fallbackCommand})`));
     }
-    const result = spawnSync4("sudo", ["env", ...collectPortlessEnvArgs2(), ...startArgs], {
+    const result = spawnSync5("sudo", ["env", ...collectPortlessEnvArgs2(), ...startArgs], {
       stdio: "inherit",
       timeout: SUDO_SPAWN_TIMEOUT_MS
     });
@@ -5482,7 +6167,15 @@ ${colors_default.bold("LAN mode (--lan):")}
   }
   if (isForeground) {
     console.log(chalk.blue.bold("\nportless proxy\n"));
-    startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, desiredWildcard ? false : void 0);
+    startProxyServer(
+      store,
+      proxyPort,
+      tld,
+      tlsOptions,
+      lanIp,
+      desiredWildcard ? false : void 0,
+      !!(customCertPath && customKeyPath)
+    );
     return;
   }
   store.ensureDir();
@@ -5513,7 +6206,7 @@ ${colors_default.bold("LAN mode (--lan):")}
         skipTrust: true
       }).args
     ];
-    const child = spawn3(process.execPath, daemonArgs, {
+    const child = spawn4(process.execPath, daemonArgs, {
       detached: true,
       stdio: ["ignore", logFd, logFd],
       env: process.env,
@@ -5619,7 +6312,7 @@ async function handleDefaultSingle(cwd, scriptName, appConfig) {
   );
 }
 function spawnChildProcess(commandArgs, env, cwd) {
-  return spawn3(commandArgs[0], commandArgs.slice(1), {
+  return spawn4(commandArgs[0], commandArgs.slice(1), {
     stdio: ["ignore", "pipe", "pipe"],
     env,
     cwd,
@@ -5698,7 +6391,7 @@ async function spawnProxiedApp(app, stateDir, proxyPort, tls2, tld, exitCodes) {
     }
     if (capturedStore && capturedHostname) {
       try {
-        capturedStore.removeRoute(capturedHostname);
+        capturedStore.removeRoute(capturedHostname, process.pid);
       } catch {
       }
     }
@@ -5890,7 +6583,7 @@ async function runWithTurbo(wsRoot, stateDir, proxyPort, tls2, tld, scriptName,
   const pm = detectPackageManager(wsRoot);
   const useRootScript = hasScript(scriptName, wsRoot);
   const turboArgs = useRootScript ? [pm, "run", scriptName, ...extraArgs] : pm === "npm" ? ["npx", "turbo", "run", scriptName, ...extraArgs] : pm === "bun" ? ["bunx", "turbo", "run", scriptName, ...extraArgs] : [pm, "exec", "turbo", "run", scriptName, ...extraArgs];
-  const turboChild = spawn3(turboArgs[0], turboArgs.slice(1), {
+  const turboChild = spawn4(turboArgs[0], turboArgs.slice(1), {
     stdio: "inherit",
     cwd: wsRoot,
     env: {
@@ -5912,7 +6605,7 @@ async function runWithTurbo(wsRoot, stateDir, proxyPort, tls2, tld, scriptName,
     }, SIGKILL_TIMEOUT_MS).unref();
     for (const { hostname } of routes) {
       try {
-        store.removeRoute(hostname);
+        store.removeRoute(hostname, process.pid);
       } catch {
       }
     }
@@ -5976,7 +6669,7 @@ async function runWithDirectSpawn(stateDir, proxyPort, tls2, tld, proxiedApps, t
     }, SIGKILL_TIMEOUT_MS).unref();
     for (const { store, hostname } of routeEntries) {
       try {
-        store.removeRoute(hostname);
+        store.removeRoute(hostname, process.pid);
       } catch {
       }
     }
@@ -6153,6 +6846,9 @@ async function main() {
     process.env.PORTLESS_FUNNEL = "1";
     process.env.PORTLESS_TAILSCALE = "1";
   }
+  if (stripGlobalFlag("--ngrok", false)) {
+    process.env.PORTLESS_NGROK = "1";
+  }
   const scriptResult = stripGlobalFlag("--script", true);
   if (scriptResult === false) {
     console.error(colors_default.red("Error: --script requires a script name."));
@@ -6185,7 +6881,7 @@ async function main() {
     args.shift();
   }
   const skipPortless = process.env.PORTLESS === "0" || process.env.PORTLESS === "false" || process.env.PORTLESS === "skip";
-  if (skipPortless && (isRunCommand || args.length === 0 || args.length >= 2 && args[0] !== "proxy" && args[0] !== "clean" && args[0] !== "service")) {
+  if (skipPortless && (isRunCommand || args.length === 0 || args.length >= 2 && args[0] !== "proxy" && args[0] !== "clean" && args[0] !== "doctor" && args[0] !== "service")) {
     const parsed = isRunCommand ? parseRunArgs(args) : parseAppArgs(args);
     let commandArgs = parsed.commandArgs;
     if (commandArgs.length === 0 && (isRunCommand || args.length === 0)) {
@@ -6233,6 +6929,10 @@ async function main() {
       await handleList();
       return;
     }
+    if (args[0] === "doctor") {
+      await handleDoctor(args);
+      return;
+    }
     if (args[0] === "get") {
       await handleGet(args);
       return;