portless 0.13.1 → 0.14.0

package/README.md

@@ -323,6 +323,20 @@ Set `PORTLESS_TAILSCALE=1` in your shell profile or `.env` to share every app by
 
 Requires the Tailscale CLI to be installed and connected (`tailscale up`), with Tailscale HTTPS certificates enabled.
 
+## ngrok sharing
+
+Expose your dev server to the public internet with [ngrok](https://ngrok.com):
+
+```bash
+portless myapp --ngrok next dev
+# -> https://myapp.localhost           (local)
+# -> https://abc123.ngrok.app          (public)
+```
+
+Set `PORTLESS_NGROK=1` in your shell profile or `.env` to enable ngrok by default when portless runs an app. `portless list` shows both local and ngrok URLs. The ngrok tunnel is cleaned up automatically when the app exits.
+
+Requires the ngrok CLI to be installed and authenticated. If ngrok reports an authentication error, run `ngrok config add-authtoken <token>` and try again.
+
 ## Commands
 
 ```bash
@@ -378,6 +392,7 @@ portless service uninstall       # Remove the startup service
 --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
 ```
@@ -396,6 +411,7 @@ PORTLESS_WILDCARD=1              Allow unregistered subdomains to fall back to p
 PORTLESS_SYNC_HOSTS=0            Disable auto-sync of /etc/hosts (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
 
 # Injected into child processes
@@ -403,6 +419,7 @@ PORT                             Ephemeral port the child should listen on
 HOST                             Usually 127.0.0.1 (omitted for Expo in LAN mode)
 PORTLESS_URL                     Public URL (e.g. https://myapp.localhost)
 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 (when HTTPS is active)
 ```
 
@@ -486,3 +503,4 @@ pnpm format           # Format all files with Prettier
 - Node.js 24+
 - macOS, Linux, or Windows
 - Tailscale CLI (optional, for `--tailscale` and `--funnel`)
+- ngrok CLI (optional, for `--ngrok`)

package/dist/{chunk-3WLVQXFE.js → chunk-OZM4AEYL.js}

@@ -920,10 +920,28 @@ var RouteStore = class _RouteStore {
       const routes = this.loadRoutes(true);
       const route = routes.find((r) => r.hostname === hostname);
       if (!route) return;
-      if (fields.tailscaleUrl !== void 0) route.tailscaleUrl = fields.tailscaleUrl;
-      if (fields.tailscaleHttpsPort !== void 0)
-        route.tailscaleHttpsPort = fields.tailscaleHttpsPort;
-      if (fields.tailscaleFunnel !== void 0) route.tailscaleFunnel = fields.tailscaleFunnel;
+      if ("tailscaleUrl" in fields) {
+        if (fields.tailscaleUrl === null) delete route.tailscaleUrl;
+        else if (fields.tailscaleUrl !== void 0) route.tailscaleUrl = fields.tailscaleUrl;
+      }
+      if ("tailscaleHttpsPort" in fields) {
+        if (fields.tailscaleHttpsPort === null) delete route.tailscaleHttpsPort;
+        else if (fields.tailscaleHttpsPort !== void 0)
+          route.tailscaleHttpsPort = fields.tailscaleHttpsPort;
+      }
+      if ("tailscaleFunnel" in fields) {
+        if (fields.tailscaleFunnel === null) delete route.tailscaleFunnel;
+        else if (fields.tailscaleFunnel !== void 0)
+          route.tailscaleFunnel = fields.tailscaleFunnel;
+      }
+      if ("ngrokUrl" in fields) {
+        if (fields.ngrokUrl === null) delete route.ngrokUrl;
+        else if (fields.ngrokUrl !== void 0) route.ngrokUrl = fields.ngrokUrl;
+      }
+      if ("ngrokPid" in fields) {
+        if (fields.ngrokPid === null) delete route.ngrokPid;
+        else if (fields.ngrokPid !== void 0) route.ngrokPid = fields.ngrokPid;
+      }
       this.saveRoutes(routes);
     } finally {
       this.releaseLock();

package/dist/cli.js

@@ -13,7 +13,7 @@ import {
   parseHostname,
   shouldAutoSyncHosts,
   syncHostsFile
-} from "./chunk-3WLVQXFE.js";
+} from "./chunk-OZM4AEYL.js";
 
 // src/colors.ts
 function supportsColor() {
@@ -41,7 +41,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 +999,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 +1353,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;
@@ -1718,10 +1890,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
@@ -1867,7 +2039,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 +2155,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 +2214,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 +2767,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 +2786,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 +3509,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 +3637,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 +3838,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 +3847,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,12 +3866,20 @@ 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 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) {
   store.ensureDir();
   const isTls = !!tlsOptions;
@@ -4038,6 +4218,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 +4304,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 +4338,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 +4361,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 +4458,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 +4525,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);
+      } catch {
+      }
+      process.exit(1);
+    }
+  }
   const basename5 = path9.basename(commandArgs[0]);
   const isExpo = basename5 === "expo";
   const isExpoLan = isExpo && (lanMode || isLanEnvEnabled());
@@ -4333,9 +4604,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,
@@ -4372,7 +4646,7 @@ function appPortFromEnv() {
   }
   return port;
 }
-function applyTailscaleFlag(flag) {
+function applySharingFlag(flag) {
   if (flag === "--tailscale") {
     process.env.PORTLESS_TAILSCALE = "1";
     return true;
@@ -4382,6 +4656,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 +4685,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 +4721,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 +4749,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 +4770,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++;
@@ -4542,6 +4829,7 @@ ${colors_default.bold("Examples:")}
   portless get backend                # -> https://backend.localhost
   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 +4891,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 +4915,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 +4931,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 +4941,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:")}
@@ -4668,7 +4964,7 @@ ${colors_default.bold("Reserved names:")}
   process.exit(0);
 }
 function printVersion() {
-  console.log("0.13.1");
+  console.log("0.14.0");
   process.exit(0);
 }
 async function handleTrust() {
@@ -4689,7 +4985,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 +5068,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 +5151,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 +5333,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 +5386,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"],
       {
@@ -5373,7 +5677,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
     });
@@ -5513,7 +5817,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 +5923,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,
@@ -5890,7 +6194,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: {
@@ -6153,6 +6457,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."));

package/dist/index.d.ts

@@ -64,7 +64,16 @@ interface RouteMapping extends RouteInfo {
     tailscaleUrl?: string;
     tailscaleHttpsPort?: number;
     tailscaleFunnel?: boolean;
+    ngrokUrl?: string;
+    ngrokPid?: number;
 }
+type RouteMetadataPatch = {
+    tailscaleUrl?: string | null;
+    tailscaleHttpsPort?: number | null;
+    tailscaleFunnel?: boolean | null;
+    ngrokUrl?: string | null;
+    ngrokPid?: number | null;
+};
 /**
  * Thrown when a route is already registered by a live process and --force was
  * not specified. With --force, the existing process is killed instead.
@@ -126,7 +135,7 @@ declare class RouteStore {
      * Update metadata on an existing route entry. Only provided fields are
      * merged; the route must already exist (matched by hostname).
      */
-    updateRoute(hostname: string, fields: Partial<Pick<RouteMapping, "tailscaleUrl" | "tailscaleHttpsPort" | "tailscaleFunnel">>): void;
+    updateRoute(hostname: string, fields: RouteMetadataPatch): void;
     removeRoute(hostname: string): void;
 }
 

package/dist/index.js

@@ -19,7 +19,7 @@ import {
   removeBlock,
   shouldAutoSyncHosts,
   syncHostsFile
-} from "./chunk-3WLVQXFE.js";
+} from "./chunk-OZM4AEYL.js";
 export {
   DIR_MODE,
   FILE_MODE,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portless",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "Replace port numbers with stable, named .localhost URLs. For humans and agents.",
   "type": "module",
   "main": "./dist/index.js",