portless 0.13.0 → 0.14.0

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;
@@ -1556,12 +1728,12 @@ async function findFreePort(minPort = MIN_APP_PORT, maxPort = MAX_APP_PORT) {
     throw new Error(`minPort (${minPort}) must be <= maxPort (${maxPort})`);
   }
   const tryPort = (port) => {
-    return new Promise((resolve3) => {
+    return new Promise((resolve4) => {
       const server = net.createServer();
       server.listen(port, () => {
-        server.close(() => resolve3(true));
+        server.close(() => resolve4(true));
       });
-      server.on("error", () => resolve3(false));
+      server.on("error", () => resolve4(false));
     });
   };
   for (let i = 0; i < RANDOM_PORT_ATTEMPTS; i++) {
@@ -1578,7 +1750,7 @@ async function findFreePort(minPort = MIN_APP_PORT, maxPort = MAX_APP_PORT) {
   throw new Error(`No free port found in range ${minPort}-${maxPort}`);
 }
 function isProxyRunning(port, tls2 = false) {
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     const requestFn = tls2 ? https.request : http.request;
     const req = requestFn(
       {
@@ -1591,26 +1763,26 @@ function isProxyRunning(port, tls2 = false) {
       },
       (res) => {
         res.resume();
-        resolve3(res.headers[PORTLESS_HEADER.toLowerCase()] === "1");
+        resolve4(res.headers[PORTLESS_HEADER.toLowerCase()] === "1");
       }
     );
-    req.on("error", () => resolve3(false));
+    req.on("error", () => resolve4(false));
     req.on("timeout", () => {
       req.destroy();
-      resolve3(false);
+      resolve4(false);
     });
     req.end();
   });
 }
 function isPortListening(port) {
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     const socket = net.createConnection({ host: "127.0.0.1", port });
     let settled = false;
     const finish = (result) => {
       if (settled) return;
       settled = true;
       socket.destroy();
-      resolve3(result);
+      resolve4(result);
     };
     socket.setTimeout(SOCKET_TIMEOUT_MS);
     socket.once("connect", () => finish(true));
@@ -1674,7 +1846,7 @@ function findPidOnPort(port) {
 }
 async function waitForProxy(port, maxAttempts = WAIT_FOR_PROXY_MAX_ATTEMPTS, intervalMs = WAIT_FOR_PROXY_INTERVAL_MS, tls2 = false) {
   for (let i = 0; i < maxAttempts; i++) {
-    await new Promise((resolve3) => setTimeout(resolve3, intervalMs));
+    await new Promise((resolve4) => setTimeout(resolve4, intervalMs));
     if (await isProxyRunning(port, tls2)) {
       return true;
     }
@@ -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";
@@ -1898,7 +2070,7 @@ function isInternalInterface(iname, macStr, internal) {
   return false;
 }
 function probeDefaultRouteIPv4() {
-  return new Promise((resolve3, reject) => {
+  return new Promise((resolve4, reject) => {
     const socket = createSocket({ type: "udp4", reuseAddr: true });
     socket.on("error", (error) => {
       socket.close();
@@ -1910,7 +2082,7 @@ function probeDefaultRouteIPv4() {
       socket.close();
       socket.unref();
       if (addr && "address" in addr && addr.address && addr.address !== NO_ROUTE_IP) {
-        resolve3(addr.address);
+        resolve4(addr.address);
       } else {
         reject(new Error("No route to host"));
       }
@@ -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,14 +2767,27 @@ 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";
-var SERVICE_PORT = getProtocolPort(true);
+import { spawnSync as spawnSync4 } from "child_process";
+var DEFAULT_SERVICE_PORT = getProtocolPort(true);
 var SERVICE_LABEL = "sh.portless.proxy";
 var SYSTEMD_SERVICE = "portless.service";
 var WINDOWS_TASK_NAME = "Portless Proxy";
 var INTERNAL_ELEVATED_ENV = "PORTLESS_INTERNAL_SERVICE_ELEVATED";
-function defaultRunner2(command, args, options) {
-  return spawnSync3(command, args, {
+var SERVICE_ENV_KEYS = /* @__PURE__ */ new Set(["PORTLESS_SYNC_HOSTS"]);
+var DEFAULT_SERVICE_CONFIG = {
+  proxyPort: DEFAULT_SERVICE_PORT,
+  useHttps: true,
+  customCertPath: null,
+  customKeyPath: null,
+  lanMode: false,
+  lanIp: null,
+  lanIpExplicit: false,
+  tld: DEFAULT_TLD,
+  useWildcard: false,
+  extraEnv: {}
+};
+function defaultRunner3(command, args, options) {
+  return spawnSync4(command, args, {
     encoding: "utf-8",
     stdio: options?.stdio ?? "pipe"
   });
@@ -2619,6 +2804,156 @@ function systemdEscape(value) {
 function windowsQuote(value) {
   return `"${value.replace(/"/g, '\\"')}"`;
 }
+function xmlUnescape(value) {
+  return value.replace(/&apos;/g, "'").replace(/&quot;/g, '"').replace(/&gt;/g, ">").replace(/&lt;/g, "<").replace(/&amp;/g, "&");
+}
+function parseBooleanEnv(value) {
+  if (value === void 0) return null;
+  if (value === "1" || value === "true") return true;
+  if (value === "0" || value === "false") return false;
+  return null;
+}
+function parsePortValue(value, source) {
+  const port = parseInt(value, 10);
+  if (isNaN(port) || port < 1 || port > 65535) {
+    throw new Error(`${source} must be a number between 1 and 65535.`);
+  }
+  return port;
+}
+function getFlagValue(args, index, flag) {
+  const value = args[index + 1];
+  if (!value || value.startsWith("-")) {
+    throw new Error(`${flag} requires a value.`);
+  }
+  return value;
+}
+function resolveServicePath(value) {
+  const expanded = value === "~" ? os2.homedir() : value.startsWith("~/") || value.startsWith("~\\") ? path8.join(os2.homedir(), value.slice(2)) : value;
+  return path8.resolve(expanded);
+}
+function normalizeServiceInstallPaths(config) {
+  return {
+    ...config,
+    stateDir: config.stateDir ? resolveServicePath(config.stateDir) : void 0,
+    customCertPath: config.customCertPath ? resolveServicePath(config.customCertPath) : null,
+    customKeyPath: config.customKeyPath ? resolveServicePath(config.customKeyPath) : null
+  };
+}
+function collectServiceExtraEnv(env) {
+  const extraEnv = {};
+  for (const key of SERVICE_ENV_KEYS) {
+    const value = env[key];
+    if (value) extraEnv[key] = value;
+  }
+  return extraEnv;
+}
+function parseServiceInstallConfig(args, env = process.env, options = {}) {
+  const config = {
+    ...DEFAULT_SERVICE_CONFIG,
+    extraEnv: collectServiceExtraEnv(env)
+  };
+  if (env.PORTLESS_STATE_DIR) {
+    config.stateDir = env.PORTLESS_STATE_DIR;
+  }
+  const envHttps = parseBooleanEnv(env.PORTLESS_HTTPS);
+  if (envHttps !== null) {
+    config.useHttps = envHttps;
+  }
+  const envLan = parseBooleanEnv(env.PORTLESS_LAN);
+  if (envLan !== null) {
+    config.lanMode = envLan;
+  }
+  if (env.PORTLESS_LAN_IP) {
+    config.lanMode = true;
+    config.lanIp = env.PORTLESS_LAN_IP;
+    config.lanIpExplicit = true;
+  }
+  if (env.PORTLESS_TLD) {
+    const tld = env.PORTLESS_TLD.trim().toLowerCase();
+    const err = validateTld(tld);
+    if (err) throw new Error(`PORTLESS_TLD: ${err}`);
+    config.tld = tld;
+  }
+  const envWildcard = parseBooleanEnv(env.PORTLESS_WILDCARD);
+  if (envWildcard !== null) {
+    config.useWildcard = envWildcard;
+  }
+  if (env.PORTLESS_PORT) {
+    config.proxyPort = parsePortValue(env.PORTLESS_PORT, "PORTLESS_PORT");
+  } else {
+    config.proxyPort = getProtocolPort(config.useHttps);
+  }
+  const tokens = args[0] === "service" ? args.slice(2) : args;
+  for (let i = 0; i < tokens.length; i += 1) {
+    const token = tokens[i];
+    switch (token) {
+      case "-p":
+      case "--port":
+        config.proxyPort = parsePortValue(getFlagValue(tokens, i, token), token);
+        i += 1;
+        break;
+      case "--https":
+        config.useHttps = true;
+        break;
+      case "--no-tls":
+        config.useHttps = false;
+        break;
+      case "--lan":
+        config.lanMode = true;
+        break;
+      case "--ip":
+        config.lanMode = true;
+        config.lanIp = getFlagValue(tokens, i, token);
+        config.lanIpExplicit = true;
+        i += 1;
+        break;
+      case "--tld": {
+        const tld = getFlagValue(tokens, i, token).trim().toLowerCase();
+        const err = validateTld(tld);
+        if (err) throw new Error(err);
+        config.tld = tld;
+        i += 1;
+        break;
+      }
+      case "--wildcard":
+        config.useWildcard = true;
+        break;
+      case "--cert":
+        config.customCertPath = getFlagValue(tokens, i, token);
+        config.useHttps = true;
+        i += 1;
+        break;
+      case "--key":
+        config.customKeyPath = getFlagValue(tokens, i, token);
+        config.useHttps = true;
+        i += 1;
+        break;
+      case "--state-dir":
+        config.stateDir = getFlagValue(tokens, i, token);
+        i += 1;
+        break;
+      case "--foreground":
+      case "--skip-trust":
+        if (!options.allowRuntimeFlags) {
+          throw new Error(`Unknown service install option "${token}".`);
+        }
+        break;
+      default:
+        throw new Error(`Unknown service install option "${token}".`);
+    }
+  }
+  if (config.customCertPath && !config.customKeyPath || !config.customCertPath && config.customKeyPath) {
+    throw new Error("--cert and --key must be used together.");
+  }
+  if (!env.PORTLESS_PORT && !tokens.includes("--port") && !tokens.includes("-p")) {
+    config.proxyPort = getProtocolPort(config.useHttps);
+  }
+  if (!config.lanMode) {
+    config.lanIp = null;
+    config.lanIpExplicit = false;
+  }
+  return config;
+}
 function readPasswdHome(username) {
   try {
     const passwd = fs8.readFileSync("/etc/passwd", "utf-8");
@@ -2652,22 +2987,40 @@ function resolveUserContext(platform) {
     username: userInfo2.username
   };
 }
-function buildProxyCommand(entryScript) {
-  const config = buildProxyStartConfig({
-    useHttps: true,
-    lanMode: false,
-    tld: DEFAULT_TLD,
+function buildProxyCommand(entryScript, serviceConfig) {
+  const proxyConfig = buildProxyStartConfig({
+    useHttps: serviceConfig.useHttps,
+    customCertPath: serviceConfig.customCertPath,
+    customKeyPath: serviceConfig.customKeyPath,
+    lanMode: serviceConfig.lanMode,
+    lanIp: serviceConfig.lanIp,
+    lanIpExplicit: serviceConfig.lanIpExplicit,
+    tld: serviceConfig.tld,
+    useWildcard: serviceConfig.useWildcard,
     foreground: true,
     includePort: true,
-    proxyPort: SERVICE_PORT,
+    proxyPort: serviceConfig.proxyPort,
     skipTrust: true
   });
-  return [entryScript, "proxy", "start", ...config.args];
+  return [entryScript, "proxy", "start", ...proxyConfig.args];
 }
 function buildServiceEnv(ctx) {
   const env = {
-    PORTLESS_STATE_DIR: ctx.stateDir
+    PORTLESS_STATE_DIR: ctx.stateDir,
+    PORTLESS_PORT: ctx.config.proxyPort.toString(),
+    PORTLESS_HTTPS: ctx.config.useHttps ? "1" : "0",
+    PORTLESS_LAN: ctx.config.lanMode ? "1" : "0",
+    PORTLESS_WILDCARD: ctx.config.useWildcard ? "1" : "0",
+    ...ctx.config.extraEnv
   };
+  if (ctx.config.lanMode && ctx.config.lanIpExplicit && ctx.config.lanIp) {
+    env.PORTLESS_LAN_IP = ctx.config.lanIp;
+  }
+  if (ctx.config.lanMode) {
+    env.PORTLESS_TLD = "local";
+  } else if (ctx.config.tld !== DEFAULT_TLD) {
+    env.PORTLESS_TLD = ctx.config.tld;
+  }
   if (ctx.platform === "win32") {
     env.USERPROFILE = ctx.user.home;
     env.PATH = ctx.pathEnv;
@@ -2746,11 +3099,21 @@ ${proxyCommand}\r
 `;
 }
 function buildServiceSpec(options) {
+  const installConfig = {
+    ...DEFAULT_SERVICE_CONFIG,
+    ...options.installConfig,
+    extraEnv: options.installConfig?.extraEnv ?? {}
+  };
+  const stateDir = options.stateDir || installConfig.stateDir || defaultStateDir(options.platform, options.userHome);
+  const normalizedConfig = {
+    ...installConfig,
+    stateDir
+  };
   const ctx = {
     platform: options.platform,
     nodePath: options.nodePath,
     entryScript: options.entryScript,
-    stateDir: options.stateDir || defaultStateDir(options.platform, options.userHome),
+    stateDir,
     user: {
       home: options.userHome,
       uid: options.uid,
@@ -2758,9 +3121,10 @@ function buildServiceSpec(options) {
       username: options.username
     },
     pathEnv: options.pathEnv || "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
-    programData: options.programData || "C:\\ProgramData"
+    programData: options.programData || "C:\\ProgramData",
+    config: normalizedConfig
   };
-  const proxyCommand = buildProxyCommand(ctx.entryScript);
+  const proxyCommand = buildProxyCommand(ctx.entryScript, ctx.config);
   if (ctx.platform === "darwin") {
     const programArguments = [ctx.nodePath, ...proxyCommand];
     return {
@@ -2769,6 +3133,7 @@ function buildServiceSpec(options) {
       plistPath: `/Library/LaunchDaemons/${SERVICE_LABEL}.plist`,
       plist: buildLaunchdPlist(ctx, programArguments),
       stateDir: ctx.stateDir,
+      config: ctx.config,
       programArguments
     };
   }
@@ -2780,6 +3145,7 @@ function buildServiceSpec(options) {
       unitPath: `/etc/systemd/system/${SYSTEMD_SERVICE}`,
       unit: buildSystemdUnit(ctx, execStart),
       stateDir: ctx.stateDir,
+      config: ctx.config,
       execStart
     };
   }
@@ -2791,6 +3157,7 @@ function buildServiceSpec(options) {
     platform: "win32",
     taskName: WINDOWS_TASK_NAME,
     stateDir: ctx.stateDir,
+    config: ctx.config,
     scriptDir,
     scriptPath,
     script,
@@ -2814,11 +3181,17 @@ function buildServiceSpec(options) {
     queryArgs: ["/Query", "/TN", WINDOWS_TASK_NAME, "/FO", "LIST", "/V"]
   };
 }
-function currentServiceSpec(entryScript) {
+function currentServiceSpec(entryScript, installConfig) {
   if (!isSupportedPlatform(process.platform)) {
     throw new Error(`Unsupported platform: ${process.platform}`);
   }
   const user = resolveUserContext(process.platform);
+  const stateDir = installConfig?.stateDir || process.env.PORTLESS_STATE_DIR || defaultStateDir(process.platform, user.home);
+  const config = installConfig ?? {
+    ...DEFAULT_SERVICE_CONFIG,
+    stateDir,
+    extraEnv: collectServiceExtraEnv(process.env)
+  };
   return buildServiceSpec({
     platform: process.platform,
     nodePath: process.execPath,
@@ -2827,11 +3200,131 @@ function currentServiceSpec(entryScript) {
     uid: user.uid,
     gid: user.gid,
     username: user.username,
-    stateDir: process.env.PORTLESS_STATE_DIR || defaultStateDir(process.platform, user.home),
+    stateDir,
     pathEnv: process.env.PATH,
-    programData: process.env.ProgramData
+    programData: process.env.ProgramData,
+    installConfig: config
   });
 }
+function parseQuotedWords(input, options = {}) {
+  const words = [];
+  let current = "";
+  let inQuote = false;
+  let inWord = false;
+  const unescapeBackslash = options.unescapeBackslash ?? true;
+  for (let i = 0; i < input.length; i += 1) {
+    const char = input[i];
+    if (char === '"') {
+      inQuote = !inQuote;
+      inWord = true;
+      continue;
+    }
+    if (char === "\\" && i + 1 < input.length && (input[i + 1] === '"' || unescapeBackslash && input[i + 1] === "\\")) {
+      current += input[i + 1];
+      inWord = true;
+      i += 1;
+      continue;
+    }
+    if (/\s/.test(char) && !inQuote) {
+      if (inWord) {
+        words.push(current);
+        current = "";
+        inWord = false;
+      }
+      continue;
+    }
+    current += char;
+    inWord = true;
+  }
+  if (inWord) {
+    words.push(current);
+  }
+  return words;
+}
+function parsePlistStrings(block) {
+  return [...block.matchAll(/<string>([\s\S]*?)<\/string>/g)].map((match) => xmlUnescape(match[1]));
+}
+function parsePlistEnv(block) {
+  const env = {};
+  for (const match of block.matchAll(/<key>([\s\S]*?)<\/key>\s*<string>([\s\S]*?)<\/string>/g)) {
+    env[xmlUnescape(match[1])] = xmlUnescape(match[2]);
+  }
+  return env;
+}
+function readInstalledServiceSnapshot(spec) {
+  try {
+    if (spec.platform === "darwin") {
+      if (!fs8.existsSync(spec.plistPath)) return null;
+      const plist = fs8.readFileSync(spec.plistPath, "utf-8");
+      const argsBlock = plist.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/);
+      const envBlock = plist.match(/<key>EnvironmentVariables<\/key>\s*<dict>([\s\S]*?)<\/dict>/);
+      if (!argsBlock) return null;
+      return {
+        command: parsePlistStrings(argsBlock[1]),
+        env: envBlock ? parsePlistEnv(envBlock[1]) : {}
+      };
+    }
+    if (spec.platform === "linux") {
+      if (!fs8.existsSync(spec.unitPath)) return null;
+      const unit = fs8.readFileSync(spec.unitPath, "utf-8");
+      const env2 = {};
+      let command = null;
+      for (const line of unit.split("\n")) {
+        if (line.startsWith("Environment=")) {
+          const entry = line.slice("Environment=".length);
+          const eq = entry.indexOf("=");
+          if (eq > 0) {
+            const key = entry.slice(0, eq);
+            const value = parseQuotedWords(entry.slice(eq + 1))[0] ?? "";
+            env2[key] = value;
+          }
+        } else if (line.startsWith("ExecStart=")) {
+          command = parseQuotedWords(line.slice("ExecStart=".length));
+        }
+      }
+      return command ? { command, env: env2 } : null;
+    }
+    if (!fs8.existsSync(spec.scriptPath)) return null;
+    const script = fs8.readFileSync(spec.scriptPath, "utf-8");
+    const env = {};
+    let commandLine = null;
+    for (const rawLine of script.split(/\r?\n/)) {
+      const line = rawLine.trim();
+      if (!line || line.toLowerCase() === "@echo off") continue;
+      const envMatch = line.match(/^set "([^=]+)=(.*)"$/);
+      if (envMatch) {
+        env[envMatch[1]] = envMatch[2].replace(/%%/g, "%");
+        continue;
+      }
+      commandLine = line;
+    }
+    return commandLine ? { command: parseQuotedWords(commandLine, { unescapeBackslash: false }), env } : null;
+  } catch {
+    return null;
+  }
+}
+function installedConfigFromSnapshot(snapshot, fallback) {
+  const proxyIndex = snapshot.command.findIndex(
+    (arg, index) => arg === "proxy" && snapshot.command[index + 1] === "start"
+  );
+  if (proxyIndex === -1) return null;
+  try {
+    const parsed = parseServiceInstallConfig(
+      ["service", "install", ...snapshot.command.slice(proxyIndex + 2)],
+      snapshot.env,
+      { allowRuntimeFlags: true }
+    );
+    const stateDir = parsed.stateDir || snapshot.env.PORTLESS_STATE_DIR || fallback.stateDir;
+    return { ...parsed, stateDir };
+  } catch {
+    return null;
+  }
+}
+function readInstalledServiceConfig(spec) {
+  const snapshot = readInstalledServiceSnapshot(spec);
+  if (!snapshot) return null;
+  return installedConfigFromSnapshot(snapshot, spec.config);
+}
 function collectPortlessEnvArgs(env = process.env, omit = /* @__PURE__ */ new Set()) {
   const envArgs = [];
   for (const key of Object.keys(env)) {
@@ -2901,18 +3394,34 @@ function isPermissionError(err) {
   const message = err instanceof Error ? err.message : String(err);
   return code === "EACCES" || code === "EPERM" || /permission denied|operation not permitted|access is denied/i.test(message);
 }
-function stopExistingProxy(entryScript, runner) {
+function stopProxyOnPort(entryScript, runner, proxyPort) {
   runRequired(runner, process.execPath, [
     entryScript,
     "proxy",
     "stop",
     "--port",
-    SERVICE_PORT.toString()
+    proxyPort.toString()
   ]);
 }
-function prepareTrust(stateDir) {
+async function stopExistingProxy(entryScript, runner, proxyPort) {
+  const ports = /* @__PURE__ */ new Set();
+  try {
+    const currentState = await discoverState();
+    if (currentState.port !== proxyPort && await isProxyRunning(currentState.port)) {
+      ports.add(currentState.port);
+    }
+  } catch {
+  }
+  ports.add(proxyPort);
+  for (const port of ports) {
+    stopProxyOnPort(entryScript, runner, port);
+  }
+}
+function prepareServiceState(stateDir) {
   fs8.mkdirSync(stateDir, { recursive: true });
   fixOwnership(stateDir);
+}
+function prepareTrust(stateDir) {
   try {
     ensureCerts(stateDir);
   } catch (err) {
@@ -2935,13 +3444,28 @@ ${detail}`
   }
   console.warn(colors_default.yellow("Run `portless trust` if browsers show certificate warnings."));
 }
-async function installService(entryScript, runner) {
-  requireUnixElevation([entryScript, "service", "install"], runner);
-  const spec = currentServiceSpec(entryScript);
-  prepareTrust(spec.stateDir);
+function ensureServiceConfigSupported(config) {
+  if (!config.lanMode) return;
+  const mdnsSupport = isMdnsSupported();
+  if (mdnsSupport.supported) return;
+  const reason = mdnsSupport.reason ? `
+${mdnsSupport.reason}` : "";
+  throw new Error(
+    `LAN mode requires mDNS publishing, which is not supported on this platform.${reason}`
+  );
+}
+async function installService(entryScript, runner, args) {
+  const installConfig = normalizeServiceInstallPaths(parseServiceInstallConfig(args));
+  ensureServiceConfigSupported(installConfig);
+  requireUnixElevation([entryScript, ...args], runner);
+  const spec = currentServiceSpec(entryScript, installConfig);
+  prepareServiceState(spec.stateDir);
+  if (spec.config.useHttps && !spec.config.customCertPath) {
+    prepareTrust(spec.stateDir);
+  }
   if (spec.platform === "darwin") {
     runOptional(runner, "launchctl", ["bootout", "system", spec.plistPath]);
-    stopExistingProxy(entryScript, runner);
+    await stopExistingProxy(entryScript, runner, spec.config.proxyPort);
     fs8.writeFileSync(spec.plistPath, spec.plist);
     fs8.chmodSync(spec.plistPath, 420);
     runRequired(runner, "chown", ["root:wheel", spec.plistPath]);
@@ -2950,7 +3474,7 @@ async function installService(entryScript, runner) {
     runRequired(runner, "launchctl", ["kickstart", "-k", `system/${spec.label}`]);
   } else if (spec.platform === "linux") {
     runOptional(runner, "systemctl", ["disable", "--now", spec.serviceName]);
-    stopExistingProxy(entryScript, runner);
+    await stopExistingProxy(entryScript, runner, spec.config.proxyPort);
     fs8.writeFileSync(spec.unitPath, spec.unit);
     fs8.chmodSync(spec.unitPath, 420);
     runRequired(runner, "systemctl", ["daemon-reload"]);
@@ -2958,7 +3482,7 @@ async function installService(entryScript, runner) {
     runRequired(runner, "systemctl", ["restart", spec.serviceName]);
   } else {
     runOptional(runner, "schtasks", ["/End", "/TN", spec.taskName]);
-    stopExistingProxy(entryScript, runner);
+    await stopExistingProxy(entryScript, runner, spec.config.proxyPort);
     fs8.mkdirSync(spec.scriptDir, { recursive: true });
     fs8.writeFileSync(spec.scriptPath, spec.script);
     runRequired(runner, "schtasks", spec.createArgs);
@@ -2966,6 +3490,7 @@ async function installService(entryScript, runner) {
   }
   console.log(colors_default.green("Portless service installed."));
   console.log(colors_default.gray(`State directory: ${spec.stateDir}`));
+  console.log(colors_default.gray(`Proxy port: ${spec.config.proxyPort}`));
 }
 async function uninstallService(entryScript, runner) {
   requireUnixElevation([entryScript, "service", "uninstall"], runner);
@@ -2984,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);
@@ -3019,13 +3544,20 @@ function tryUninstallService(entryScript, runner = defaultRunner2) {
 }
 async function getServiceStatus(entryScript, runner) {
   const spec = currentServiceSpec(entryScript);
-  const proxyRunning = await isProxyRunning(SERVICE_PORT);
+  const installedConfig = readInstalledServiceConfig(spec) ?? spec.config;
+  const proxyRunning = await isProxyRunning(installedConfig.proxyPort, installedConfig.useHttps);
   if (spec.platform === "darwin") {
     const installed2 = fs8.existsSync(spec.plistPath);
     const result = runner("launchctl", ["print", `system/${spec.label}`]);
     const output2 = `${result.stdout || ""}${result.stderr || ""}`;
     const managerState = result.status === 0 && /state = running|pid = \d+/.test(output2) ? "running" : installed2 ? "installed" : "not installed";
-    return { installed: installed2, managerState, proxyRunning, details: spec.plistPath };
+    return {
+      installed: installed2,
+      managerState,
+      proxyRunning,
+      config: installedConfig,
+      details: spec.plistPath
+    };
   }
   if (spec.platform === "linux") {
     const enabled2 = runner("systemctl", ["is-enabled", spec.serviceName]);
@@ -3036,6 +3568,7 @@ async function getServiceStatus(entryScript, runner) {
       installed: installed2,
       managerState: active.status === 0 ? activeText || "active" : installed2 ? "installed" : "not installed",
       proxyRunning,
+      config: installedConfig,
       details: spec.unitPath
     };
   }
@@ -3047,17 +3580,27 @@ async function getServiceStatus(entryScript, runner) {
     installed,
     managerState: installed ? stateMatch?.[1]?.trim() || "installed" : "not installed",
     proxyRunning,
+    config: installedConfig,
     details: spec.taskName
   };
 }
 async function printServiceStatus(entryScript, runner) {
-  const spec = currentServiceSpec(entryScript);
   const status = await getServiceStatus(entryScript, runner);
+  const config = status.config;
   console.log(colors_default.bold("portless service"));
   console.log(`  Manager state: ${status.managerState}`);
   console.log(`  Installed: ${status.installed ? "yes" : "no"}`);
-  console.log(`  Proxy on 443: ${status.proxyRunning ? "responding" : "not responding"}`);
-  console.log(`  State directory: ${spec.stateDir}`);
+  console.log(
+    `  Proxy on ${config.proxyPort}: ${status.proxyRunning ? "responding" : "not responding"}`
+  );
+  console.log(`  HTTPS: ${config.useHttps ? "yes" : "no"}`);
+  console.log(`  TLD: ${config.lanMode ? "local" : config.tld}`);
+  console.log(`  LAN mode: ${config.lanMode ? "yes" : "no"}`);
+  if (config.lanIpExplicit && config.lanIp) {
+    console.log(`  LAN IP: ${config.lanIp}`);
+  }
+  console.log(`  Wildcard: ${config.useWildcard ? "yes" : "no"}`);
+  console.log(`  State directory: ${config.stateDir}`);
   if (status.details) {
     console.log(`  Service entry: ${status.details}`);
   }
@@ -3067,26 +3610,41 @@ function printServiceHelp() {
 ${colors_default.bold("portless service")} - Start portless automatically when the OS starts.
 
 ${colors_default.bold("Usage:")}
-  ${colors_default.cyan("portless service install")}      Install and start the HTTPS service on port 443
-  ${colors_default.cyan("portless service uninstall")}    Stop and remove the startup service
-  ${colors_default.cyan("portless service status")}       Show service and proxy status
+  ${colors_default.cyan("portless service install")}             Install and start the HTTPS service on port 443
+  ${colors_default.cyan("portless service install --lan")}       Enable LAN mode for the startup service
+  ${colors_default.cyan("portless service install -p 8443")}     Use a custom proxy port
+  ${colors_default.cyan("portless service uninstall")}           Stop and remove the startup service
+  ${colors_default.cyan("portless service status")}              Show service and proxy status
+
+${colors_default.bold("Install options:")}
+  -p, --port <number>              Port for the proxy service
+  --no-tls                         Disable HTTPS
+  --https                          Enable HTTPS
+  --lan                            Enable LAN mode
+  --ip <address>                   Pin a specific LAN IP
+  --tld <tld>                      Use a custom TLD outside LAN mode
+  --wildcard                       Allow subdomain fallback
+  --cert <path>                    Use a custom TLS certificate
+  --key <path>                     Use a custom TLS private key
+  --state-dir <path>               Use a custom service state directory
 
 ${colors_default.bold("Notes:")}
-  The service uses the default clean URL mode: HTTPS on port 443.
+  The service uses the default clean URL mode unless options or PORTLESS_*
+  environment variables are provided during install.
   macOS and Linux install a root-owned service so port 443 can bind at boot.
   Windows installs a Task Scheduler startup task that runs as SYSTEM.
 `);
 }
 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);
   }
   try {
     if (action === "install") {
-      await installService(options.entryScript, runner);
+      await installService(options.entryScript, runner, args);
       return;
     }
     if (action === "uninstall") {
@@ -3280,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
   });
@@ -3289,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",
@@ -3308,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;
@@ -3652,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();
 }
@@ -3735,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
   });
@@ -3769,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 {
@@ -3791,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);
@@ -3876,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++) {
@@ -3913,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());
@@ -3947,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,
@@ -3986,7 +4646,7 @@ function appPortFromEnv() {
   }
   return port;
 }
-function applyTailscaleFlag(flag) {
+function applySharingFlag(flag) {
   if (flag === "--tailscale") {
     process.env.PORTLESS_TAILSCALE = "1";
     return true;
@@ -3996,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) {
@@ -4021,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):")}
@@ -4054,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);
     }
@@ -4080,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++;
@@ -4099,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++;
@@ -4121,6 +4794,9 @@ ${colors_default.bold("Install:")}
   ${colors_default.cyan("npm install -g portless")}          Global (recommended)
   ${colors_default.cyan("npm install -D portless")}          Project dev dependency
 
+${colors_default.bold("Requirements:")}
+  Node.js 24+
+
 ${colors_default.bold("Usage:")}
   ${colors_default.cyan("portless")}                         Run dev script through proxy
   ${colors_default.cyan("portless")}                         From monorepo root: run all workspace packages
@@ -4148,9 +4824,12 @@ ${colors_default.bold("Examples:")}
   portless run next dev               # -> https://<project>.localhost
   portless run next dev               # in worktree -> https://<worktree>.<project>.localhost
   portless service install            # Start HTTPS proxy on OS startup
+  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 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
@@ -4212,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
@@ -4227,9 +4911,11 @@ ${colors_default.bold("Options:")}
   --foreground                  Run proxy in foreground (for debugging)
   --tld <tld>                   Use a custom TLD instead of .localhost (e.g. test, dev)
   --wildcard                    Allow unregistered subdomains to fall back to parent route
+  --state-dir <path>            Use a custom state directory with service install
   --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
@@ -4239,11 +4925,13 @@ ${colors_default.bold("Environment variables:")}
   PORTLESS_APP_PORT=<number>    Use a fixed port for the app (same as --app-port)
   PORTLESS_HTTPS=0              Disable HTTPS (same as --no-tls)
   PORTLESS_LAN=1                Enable LAN mode when set to 1 (set in .bashrc / .zshrc)
+  PORTLESS_LAN_IP=<address>     Pin a specific LAN IP for LAN mode
   PORTLESS_TLD=<tld>            Use a custom TLD (e.g. test, dev; default: localhost)
   PORTLESS_WILDCARD=1           Allow unregistered subdomains to fall back to parent route
   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
 
@@ -4253,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:")}
@@ -4275,7 +4964,7 @@ ${colors_default.bold("Reserved names:")}
   process.exit(0);
 }
 function printVersion() {
-  console.log("0.13.0");
+  console.log("0.14.0");
   process.exit(0);
 }
 async function handleTrust() {
@@ -4296,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",
@@ -4379,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) {
@@ -4458,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) {
@@ -4636,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"],
         {
@@ -4689,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"],
       {
@@ -4980,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
     });
@@ -5120,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,
@@ -5226,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,
@@ -5497,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: {
@@ -5527,8 +6224,8 @@ async function runWithTurbo(wsRoot, stateDir, proxyPort, tls2, tld, scriptName,
   };
   process.on("SIGINT", cleanup);
   process.on("SIGTERM", cleanup);
-  const exitCode = await new Promise((resolve3) => {
-    turboChild.on("exit", (code) => resolve3(code));
+  const exitCode = await new Promise((resolve4) => {
+    turboChild.on("exit", (code) => resolve4(code));
   });
   cleanup();
   if (exitCode !== 0 && exitCode !== null) {
@@ -5592,8 +6289,8 @@ async function runWithDirectSpawn(stateDir, proxyPort, tls2, tld, proxiedApps, t
   process.on("SIGTERM", cleanup);
   await Promise.all(
     children.map(
-      (child) => new Promise((resolve3) => {
-        child.on("exit", () => resolve3());
+      (child) => new Promise((resolve4) => {
+        child.on("exit", () => resolve4());
       })
     )
   );
@@ -5680,6 +6377,7 @@ async function handleNamedMode(args) {
     }
   }
   const safeName = parsed.name.split(".").map((label) => truncateLabel(label)).join(".");
+  parseHostname(safeName, DEFAULT_TLD);
   const { dir, port, tls: tls2, tld, lanMode, lanIp } = await discoverState();
   const store = new RouteStore(dir, {
     onWarning: (msg) => console.warn(colors_default.yellow(msg))
@@ -5759,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."));