portless 0.13.0 → 0.13.1

package/README.md

@@ -255,11 +255,16 @@ Install the proxy as an OS startup service so clean HTTPS URLs are available aft
 
 ```bash
 portless service install
+portless service install --lan
+portless service install --wildcard
+PORTLESS_STATE_DIR=~/.portless-lan PORTLESS_LAN=1 portless service install
 portless service status
 portless service uninstall
 ```
 
-The service uses portless defaults: HTTPS on port 443 with `.localhost` names. 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. Installation and removal may require administrator privileges. `portless clean` automatically removes the service.
+The service uses portless defaults unless install options or `PORTLESS_*` environment variables are provided: HTTPS on port 443 with `.localhost` names. `service install` accepts the proxy options you would use with `proxy start`, including `--port`, `--no-tls`, `--lan`, `--ip`, `--tld`, `--wildcard`, `--cert`, and `--key`. Use `--state-dir <path>` or `PORTLESS_STATE_DIR=<path>` to choose where service state and logs are written.
+
+The chosen service configuration is written into launchd, systemd, or Task Scheduler and reused after reboot. `portless service status` reports the installed port, HTTPS mode, TLD, LAN mode, wildcard mode, and state directory. 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. Installation and removal may require administrator privileges. `portless clean` automatically removes the service.
 
 ## LAN mode
 
@@ -349,6 +354,8 @@ portless proxy stop              # Stop the proxy
 
 # OS startup service
 portless service install         # Start HTTPS proxy when the OS starts
+portless service install --lan   # Start service in LAN mode
+portless service install --wildcard  # Persist wildcard routing in the service
 portless service status          # Show service and proxy status
 portless service uninstall       # Remove the startup service
 ```
@@ -366,6 +373,7 @@ portless service uninstall       # Remove the startup service
 --foreground                     Run proxy in foreground instead of daemon
 --tld <tld>                      Use a custom TLD instead of .localhost (e.g. test)
 --wildcard                       Allow unregistered subdomains to fall back to parent route
+--state-dir <path>               Use a custom state directory with service install
 --script <name>                  Run a specific package.json script (default: dev)
 --app-port <number>              Use a fixed port for the app (skip auto-assignment)
 --tailscale                      Share the app on your Tailscale network (tailnet)
@@ -382,6 +390,7 @@ PORTLESS_PORT=<number>           Override the default proxy port
 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 (auto-detects LAN IP)
+PORTLESS_LAN_IP=<address>        Pin a specific LAN IP for LAN mode
 PORTLESS_TLD=<tld>               Use a custom TLD (e.g. test; default: localhost)
 PORTLESS_WILDCARD=1              Allow unregistered subdomains to fall back to parent route
 PORTLESS_SYNC_HOSTS=0            Disable auto-sync of /etc/hosts (on by default)
@@ -460,6 +469,8 @@ Portless detects this misconfiguration and responds with `508 Loop Detected` alo
 
 This repo is a pnpm workspace monorepo using [Turborepo](https://turbo.build). The publishable package lives in `packages/portless/`.
 
+Use Node.js 24+ and pnpm 11 for repository development. The `.node-version` file pins the Node major for version managers.
+
 ```bash
 pnpm install          # Install all dependencies
 pnpm build            # Build all packages
@@ -472,6 +483,6 @@ pnpm format           # Format all files with Prettier
 
 ## Requirements
 
-- Node.js 20+
+- Node.js 24+
 - macOS, Linux, or Windows
 - Tailscale CLI (optional, for `--tailscale` and `--funnel`)

package/dist/cli.js

@@ -1556,12 +1556,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 +1578,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 +1591,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 +1674,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;
     }
@@ -1898,7 +1898,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 +1910,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"));
       }
@@ -2596,11 +2596,24 @@ 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);
+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";
+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 defaultRunner2(command, args, options) {
   return spawnSync3(command, args, {
     encoding: "utf-8",
@@ -2619,6 +2632,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 +2815,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 +2927,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 +2949,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 +2961,7 @@ function buildServiceSpec(options) {
       plistPath: `/Library/LaunchDaemons/${SERVICE_LABEL}.plist`,
       plist: buildLaunchdPlist(ctx, programArguments),
       stateDir: ctx.stateDir,
+      config: ctx.config,
       programArguments
     };
   }
@@ -2780,6 +2973,7 @@ function buildServiceSpec(options) {
       unitPath: `/etc/systemd/system/${SYSTEMD_SERVICE}`,
       unit: buildSystemdUnit(ctx, execStart),
       stateDir: ctx.stateDir,
+      config: ctx.config,
       execStart
     };
   }
@@ -2791,6 +2985,7 @@ function buildServiceSpec(options) {
     platform: "win32",
     taskName: WINDOWS_TASK_NAME,
     stateDir: ctx.stateDir,
+    config: ctx.config,
     scriptDir,
     scriptPath,
     script,
@@ -2814,11 +3009,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 +3028,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 +3222,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 +3272,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 +3302,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 +3310,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 +3318,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);
@@ -3019,13 +3372,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 +3396,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 +3408,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,12 +3438,27 @@ 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.
 `);
@@ -3086,7 +3472,7 @@ async function handleService(args, options) {
   }
   try {
     if (action === "install") {
-      await installService(options.entryScript, runner);
+      await installService(options.entryScript, runner, args);
       return;
     }
     if (action === "uninstall") {
@@ -4121,6 +4507,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,6 +4537,8 @@ ${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)
@@ -4227,6 +4618,7 @@ ${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
@@ -4239,6 +4631,7 @@ ${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)
@@ -4275,7 +4668,7 @@ ${colors_default.bold("Reserved names:")}
   process.exit(0);
 }
 function printVersion() {
-  console.log("0.13.0");
+  console.log("0.13.1");
   process.exit(0);
 }
 async function handleTrust() {
@@ -5527,8 +5920,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 +5985,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 +6073,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))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portless",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Replace port numbers with stable, named .localhost URLs. For humans and agents.",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,7 +18,7 @@
     "dist"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=24"
   },
   "os": [
     "darwin",
@@ -53,7 +53,7 @@
     "url": "https://github.com/vercel-labs/portless/issues"
   },
   "devDependencies": {
-    "@types/node": "^20.11.0",
+    "@types/node": "^24.12.4",
     "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^9.39.2",
     "tsup": "^8.0.1",