portless 0.9.5 → 0.10.0

package/dist/cli.js

@@ -3,12 +3,15 @@ import {
   DEFAULT_TLD,
   FALLBACK_PROXY_PORT,
   FILE_MODE,
+  INTERNAL_LAN_IP_ENV,
+  INTERNAL_LAN_IP_FLAG,
   PRIVILEGED_PORT_THRESHOLD,
   RISKY_TLDS,
   RouteConflictError,
   RouteStore,
   WAIT_FOR_PROXY_INTERVAL_MS,
   WAIT_FOR_PROXY_MAX_ATTEMPTS,
+  buildProxyStartConfig,
   cleanHostsFile,
   createHttpRedirectServer,
   createProxyServer,
@@ -19,23 +22,28 @@ import {
   formatUrl,
   getDefaultPort,
   getDefaultTld,
-  getProtocolPort,
   injectFrameworkFlags,
   isErrnoException,
   isHttpsEnvDisabled,
+  isLanEnvEnabled,
+  isPortListening,
   isProxyRunning,
   isWildcardEnvEnabled,
   isWindows,
   parseHostname,
   prompt,
+  readLanMarker,
+  readTldFromDir,
+  readTlsMarker,
   resolveStateDir,
   spawnCommand,
   syncHostsFile,
   validateTld,
   waitForProxy,
+  writeLanMarker,
   writeTldFile,
   writeTlsMarker
-} from "./chunk-D3LR3J7L.js";
+} from "./chunk-WXEE5QH6.js";
 
 // src/colors.ts
 function supportsColor() {
@@ -65,7 +73,7 @@ var colors_default = { bold, red, green, yellow, blue, cyan, white, gray };
 // src/cli.ts
 import * as fs3 from "fs";
 import * as path3 from "path";
-import { spawn, spawnSync } from "child_process";
+import { spawn as spawn2, spawnSync as spawnSync2 } from "child_process";
 
 // src/certs.ts
 import * as fs from "fs";
@@ -135,6 +143,14 @@ function isCertValid(certPath) {
     return false;
   }
 }
+function isCertSansComplete(certPath) {
+  try {
+    const text = openssl(["x509", "-in", certPath, "-noout", "-text"]);
+    return /DNS:\*\.local\b/.test(text);
+  } catch {
+    return false;
+  }
+}
 function isCertSignatureStrong(certPath) {
   try {
     const text = openssl(["x509", "-in", certPath, "-noout", "-text"]);
@@ -216,6 +232,7 @@ function generateServerCert(stateDir) {
   const extPath = path.join(stateDir, "server-ext.cnf");
   openssl(["ecparam", "-genkey", "-name", "prime256v1", "-noout", "-out", serverKeyPath]);
   openssl(["req", "-new", "-key", serverKeyPath, "-out", csrPath, "-subj", "/CN=localhost"]);
+  const sans = ["DNS:localhost", "DNS:*.localhost", "DNS:*.local"];
   fs.writeFileSync(
     extPath,
     [
@@ -223,7 +240,7 @@ function generateServerCert(stateDir) {
       "basicConstraints=CA:FALSE",
       "keyUsage=digitalSignature,keyEncipherment",
       "extendedKeyUsage=serverAuth",
-      "subjectAltName=DNS:localhost,DNS:*.localhost"
+      `subjectAltName=${sans.join(",")}`
     ].join("\n") + "\n"
   );
   const srlPath = path.join(stateDir, "ca.srl");
@@ -273,7 +290,7 @@ function ensureCerts(stateDir) {
     generateCA(stateDir);
     caGenerated = true;
   }
-  if (caGenerated || !fileExists(serverCertPath) || !fileExists(serverKeyPath) || !isCertValid(serverCertPath) || !isCertSignatureStrong(serverCertPath)) {
+  if (caGenerated || !fileExists(serverCertPath) || !fileExists(serverKeyPath) || !isCertValid(serverCertPath) || !isCertSignatureStrong(serverCertPath) || !isCertSansComplete(serverCertPath)) {
     generateServerCert(stateDir);
   }
   return {
@@ -766,12 +783,351 @@ function readBranchFromHead(gitdir) {
   }
 }
 
+// src/mdns.ts
+import { spawn, spawnSync } from "child_process";
+
+// src/lan-ip.ts
+import { createSocket } from "dgram";
+import { networkInterfaces } from "os";
+var PROBE_HOST = "1.1.1.1";
+var PROBE_PORT = 53;
+var NO_ROUTE_IP = "0.0.0.0";
+function isIPv4Family(family) {
+  return family === "IPv4" || family === 4;
+}
+function parseMac(macStr) {
+  return macStr.split(":").slice(0, 16).map((seq) => parseInt(seq, 16));
+}
+function isInternalInterface(iname, macStr, internal) {
+  if (internal) {
+    return true;
+  }
+  const mac = parseMac(macStr);
+  if (mac.every((x) => !x)) {
+    return true;
+  }
+  if (mac[0] === 0 && mac[1] === 21 && mac[2] === 93) {
+    return true;
+  }
+  if (iname.includes("vEthernet") || /^bridge\d+$/.test(iname)) {
+    return true;
+  }
+  return false;
+}
+function probeDefaultRouteIPv4() {
+  return new Promise((resolve2, reject) => {
+    const socket = createSocket({ type: "udp4", reuseAddr: true });
+    socket.on("error", (error) => {
+      socket.close();
+      socket.unref();
+      reject(error);
+    });
+    socket.connect(PROBE_PORT, PROBE_HOST, () => {
+      const addr = socket.address();
+      socket.close();
+      socket.unref();
+      if (addr && "address" in addr && addr.address && addr.address !== NO_ROUTE_IP) {
+        resolve2(addr.address);
+      } else {
+        reject(new Error("No route to host"));
+      }
+    });
+  });
+}
+function findInterfaceRowForIp(ip) {
+  const ifs = networkInterfaces();
+  for (const iname of Object.keys(ifs)) {
+    const entries = ifs[iname];
+    if (!entries) continue;
+    for (const e of entries) {
+      if (!isIPv4Family(e.family)) continue;
+      if (e.address !== ip) continue;
+      return { iname, address: e.address, mac: e.mac, internal: e.internal };
+    }
+  }
+  return null;
+}
+async function getLocalNetworkIp() {
+  try {
+    const ip = await probeDefaultRouteIPv4();
+    if (ip === "127.0.0.1") {
+      return null;
+    }
+    const row = findInterfaceRowForIp(ip);
+    if (!row) {
+      return null;
+    }
+    if (row.address === "127.0.0.1") {
+      return null;
+    }
+    if (isInternalInterface(row.iname, row.mac, row.internal)) {
+      return null;
+    }
+    return row.address;
+  } catch {
+    return null;
+  }
+}
+
+// src/mdns.ts
+var activePublishers = /* @__PURE__ */ new Map();
+var LAN_IP_POLL_INTERVAL_MS = 5e3;
+function getMdnsPublisher() {
+  if (process.platform === "darwin") {
+    return {
+      command: "dns-sd",
+      probeArgs: ["-h"],
+      missingReason: "dns-sd not found",
+      buildArgs: (fqdn, name, port, ip) => [
+        "-P",
+        name,
+        "_http._tcp",
+        "local",
+        port.toString(),
+        fqdn,
+        ip
+      ]
+    };
+  }
+  if (process.platform === "linux") {
+    return {
+      command: "avahi-publish-address",
+      probeArgs: ["--help"],
+      missingReason: "avahi-publish-address not found. Install avahi-utils: sudo apt install avahi-utils",
+      buildArgs: (fqdn, _name, _port, ip) => ["-R", fqdn, ip]
+    };
+  }
+  return null;
+}
+function hasCommand(command, probeArgs) {
+  const result = spawnSync(command, probeArgs, {
+    stdio: "ignore",
+    timeout: 1e3,
+    windowsHide: true
+  });
+  return result.error?.code !== "ENOENT";
+}
+function startLanIpMonitor(options) {
+  const resolveIp = options.resolveIp ?? getLocalNetworkIp;
+  let currentIp = options.initialIp;
+  let stopped = false;
+  let polling = false;
+  const poll = async () => {
+    if (stopped || polling) return;
+    polling = true;
+    try {
+      const nextIp = await resolveIp();
+      if (stopped || nextIp === currentIp) return;
+      const previousIp = currentIp;
+      currentIp = nextIp;
+      options.onChange(nextIp, previousIp);
+    } catch (error) {
+      options.onError?.(error);
+    } finally {
+      polling = false;
+    }
+  };
+  const timer = setInterval(() => {
+    void poll();
+  }, options.intervalMs ?? LAN_IP_POLL_INTERVAL_MS);
+  timer.unref?.();
+  return {
+    stop: () => {
+      stopped = true;
+      clearInterval(timer);
+    }
+  };
+}
+function isMdnsSupported() {
+  const publisher = getMdnsPublisher();
+  if (!publisher) {
+    return { supported: false, reason: "mDNS publishing is not supported on this platform" };
+  }
+  if (!hasCommand(publisher.command, publisher.probeArgs)) {
+    return { supported: false, reason: publisher.missingReason };
+  }
+  return { supported: true };
+}
+function serviceName(hostname) {
+  return hostname.replace(/\.local$/, "");
+}
+function publish(hostname, port, ip, onError) {
+  if (activePublishers.has(hostname)) return;
+  const fqdn = hostname.endsWith(".local") ? hostname : `${hostname}.local`;
+  const name = serviceName(fqdn);
+  const publisher = getMdnsPublisher();
+  if (!publisher) {
+    return;
+  }
+  const child = spawn(publisher.command, publisher.buildArgs(fqdn, name, port, ip), {
+    stdio: "ignore",
+    detached: false
+  });
+  child.on("error", (err) => {
+    activePublishers.delete(hostname);
+    const msg = err.code === "ENOENT" ? publisher.missingReason : `mDNS publish error for ${hostname}: ${err.message}`;
+    onError?.(msg);
+  });
+  child.on("exit", () => {
+    activePublishers.delete(hostname);
+  });
+  activePublishers.set(hostname, child);
+}
+function unpublish(hostname) {
+  const child = activePublishers.get(hostname);
+  if (!child) return;
+  activePublishers.delete(hostname);
+  child.kill("SIGTERM");
+}
+function cleanupAll() {
+  for (const child of activePublishers.values()) {
+    child.kill("SIGTERM");
+  }
+  activePublishers.clear();
+}
+
 // src/cli.ts
+var chalk = colors_default;
 var HOSTS_DISPLAY = isWindows ? "hosts file" : "/etc/hosts";
 var DEBOUNCE_MS = 100;
 var POLL_INTERVAL_MS = 3e3;
 var EXIT_TIMEOUT_MS = 2e3;
 var SUDO_SPAWN_TIMEOUT_MS = 3e4;
+function defaultProxyConfig(tld, useHttps, lanMode) {
+  return {
+    useHttps,
+    customCertPath: null,
+    customKeyPath: null,
+    lanMode,
+    lanIp: null,
+    lanIpExplicit: false,
+    tld: lanMode ? "local" : tld,
+    useWildcard: false
+  };
+}
+function resolveProxyConfig(options) {
+  const config = defaultProxyConfig(
+    options.defaultTld,
+    options.useHttps,
+    options.explicit.lanMode ? options.lanMode : options.persistedLanMode
+  );
+  if (options.explicit.useHttps) {
+    config.useHttps = options.useHttps;
+    if (!options.useHttps) {
+      config.customCertPath = null;
+      config.customKeyPath = null;
+    }
+  }
+  if (options.explicit.customCert) {
+    config.useHttps = true;
+    config.customCertPath = options.customCertPath;
+    config.customKeyPath = options.customKeyPath;
+  }
+  if (options.explicit.lanMode) {
+    config.lanMode = options.lanMode;
+    if (!options.lanMode) {
+      config.lanIp = null;
+      config.lanIpExplicit = false;
+      if (!options.explicit.tld) {
+        config.tld = options.defaultTld;
+      }
+    }
+  }
+  if (options.explicit.lanIp && options.lanIp) {
+    config.lanMode = true;
+    config.lanIp = options.lanIp;
+    config.lanIpExplicit = true;
+  }
+  if (options.explicit.tld) {
+    config.tld = options.tld;
+  }
+  if (options.explicit.useWildcard) {
+    config.useWildcard = options.useWildcard;
+  }
+  if (!config.lanMode) {
+    config.lanIp = null;
+    config.lanIpExplicit = false;
+  }
+  if (config.lanMode) {
+    config.tld = "local";
+    if (!config.lanIpExplicit) {
+      config.lanIp = null;
+    }
+  }
+  if (!config.useHttps) {
+    config.customCertPath = null;
+    config.customKeyPath = null;
+  }
+  return config;
+}
+function readCurrentProxyConfig(dir) {
+  const lanIp = readLanMarker(dir);
+  const tld = readTldFromDir(dir);
+  return {
+    useHttps: readTlsMarker(dir),
+    customCertPath: null,
+    customKeyPath: null,
+    lanMode: lanIp !== null || tld === "local",
+    lanIp,
+    lanIpExplicit: false,
+    tld,
+    useWildcard: false
+  };
+}
+function getProxyConfigMismatchMessages(desiredConfig, actualConfig, explicit) {
+  const messages = [];
+  if (explicit.lanMode && desiredConfig.lanMode !== actualConfig.lanMode) {
+    messages.push(
+      desiredConfig.lanMode ? "requested LAN mode, but the running proxy is not using LAN mode" : "requested non-LAN mode, but the running proxy is using LAN mode"
+    );
+  }
+  if (explicit.lanIp && desiredConfig.lanIp !== actualConfig.lanIp) {
+    messages.push(
+      `requested LAN IP ${desiredConfig.lanIp}, but the running proxy is using ${actualConfig.lanIp ?? "auto-detected LAN mode"}`
+    );
+  }
+  if (explicit.useHttps && desiredConfig.useHttps !== actualConfig.useHttps) {
+    messages.push(
+      desiredConfig.useHttps ? "requested HTTPS, but the running proxy is using HTTP" : "requested HTTP, but the running proxy is using HTTPS"
+    );
+  }
+  if (explicit.tld && desiredConfig.tld !== actualConfig.tld) {
+    messages.push(
+      `requested .${desiredConfig.tld}, but the running proxy is using .${actualConfig.tld}`
+    );
+  }
+  return messages;
+}
+function formatProxyStartCommand(proxyPort, config) {
+  const needsSudo = !isWindows && proxyPort < PRIVILEGED_PORT_THRESHOLD;
+  const { args } = buildProxyStartConfig({
+    useHttps: config.useHttps,
+    customCertPath: config.customCertPath,
+    customKeyPath: config.customKeyPath,
+    lanMode: config.lanMode,
+    lanIp: config.lanIpExplicit ? config.lanIp : null,
+    lanIpExplicit: config.lanIpExplicit,
+    tld: config.tld,
+    useWildcard: config.useWildcard,
+    includePort: proxyPort !== getDefaultPort(config.useHttps),
+    proxyPort
+  });
+  return `${needsSudo ? "sudo " : ""}portless proxy start${args.length > 0 ? ` ${args.join(" ")}` : ""}`;
+}
+function printProxyConfigMismatch(proxyPort, desiredConfig, messages) {
+  const needsSudo = !isWindows && proxyPort < PRIVILEGED_PORT_THRESHOLD;
+  const portFlag = proxyPort !== getDefaultPort(desiredConfig.useHttps) ? ` -p ${proxyPort}` : "";
+  console.error(
+    chalk.yellow(`Proxy is already running on port ${proxyPort} with a different config.`)
+  );
+  for (const message of messages) {
+    console.error(chalk.yellow(`- ${message}`));
+  }
+  console.error(chalk.blue("Stop it first, then restart with the desired settings:"));
+  console.error(chalk.cyan(`  ${needsSudo ? "sudo " : ""}portless proxy stop${portFlag}`));
+  console.error(chalk.cyan(`  ${formatProxyStartCommand(proxyPort, desiredConfig)}`));
+  process.exit(1);
+}
 function getEntryScript() {
   const script = process.argv[1];
   if (!script) {
@@ -803,15 +1159,23 @@ function collectPortlessEnvArgs() {
 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 = spawnSync("sudo", ["env", ...collectPortlessEnvArgs(), ...stopArgs], {
+  const result = spawnSync2("sudo", ["env", ...collectPortlessEnvArgs(), ...stopArgs], {
     stdio: "inherit",
     timeout: SUDO_SPAWN_TIMEOUT_MS
   });
   return result.status === 0;
 }
-function startProxyServer(store, proxyPort, tld, tlsOptions, strict) {
+function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict) {
   store.ensureDir();
   const isTls = !!tlsOptions;
+  const mdnsSupport = isMdnsSupported();
+  let activeLanIp = lanIp && mdnsSupport.supported ? lanIp : null;
+  const lanIpPinned = !!process.env.PORTLESS_LAN_IP;
+  let lanMonitor = null;
+  if (lanIp && !mdnsSupport.supported) {
+    const reason = mdnsSupport.reason ?? "mDNS publishing is not supported on this platform.";
+    console.warn(chalk.yellow(`LAN mode disabled: ${reason}`));
+  }
   const routesPath = store.getRoutesPath();
   if (!fs3.existsSync(routesPath)) {
     fs3.writeFileSync(routesPath, "[]", { mode: FILE_MODE });
@@ -826,13 +1190,54 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, strict) {
   let watcher = null;
   let pollingInterval = null;
   const syncVal = process.env.PORTLESS_SYNC_HOSTS;
-  const autoSyncHosts = syncVal === "1" || syncVal === "true" || tld !== DEFAULT_TLD && syncVal !== "0" && syncVal !== "false";
+  const autoSyncHosts = syncVal === "1" || syncVal === "true" || tld !== DEFAULT_TLD && !activeLanIp && syncVal !== "0" && syncVal !== "false";
+  const onMdnsError = (msg) => console.warn(chalk.yellow(msg));
+  const publishCachedRoutes = () => {
+    if (!activeLanIp) return;
+    for (const route of cachedRoutes) {
+      publish(route.hostname, proxyPort, activeLanIp, onMdnsError);
+    }
+  };
+  const updateLanIp = (nextIp, previousIp = activeLanIp) => {
+    if (nextIp === activeLanIp) return;
+    if (activeLanIp) {
+      cleanupAll();
+    }
+    activeLanIp = nextIp;
+    writeLanMarker(store.dir, activeLanIp);
+    if (previousIp && nextIp) {
+      console.log(chalk.green(`LAN IP changed: ${previousIp} -> ${nextIp}`));
+    } else if (previousIp && !nextIp) {
+      console.warn(chalk.yellow("LAN mode temporarily unavailable: no active LAN IP"));
+    } else if (!previousIp && nextIp) {
+      console.log(chalk.green(`LAN mode restored: ${nextIp}`));
+    }
+    publishCachedRoutes();
+  };
   const reloadRoutes = () => {
     try {
+      const previousRoutes = new Map(cachedRoutes.map((r) => [r.hostname, r.port]));
       cachedRoutes = store.loadRoutes();
       if (autoSyncHosts) {
         syncHostsFile(cachedRoutes.map((r) => r.hostname));
       }
+      if (activeLanIp) {
+        const currentRoutes = new Map(cachedRoutes.map((r) => [r.hostname, r.port]));
+        for (const route of cachedRoutes) {
+          const previousPort = previousRoutes.get(route.hostname);
+          if (previousPort === void 0) {
+            publish(route.hostname, proxyPort, activeLanIp, onMdnsError);
+          } else if (previousPort !== route.port) {
+            unpublish(route.hostname);
+            publish(route.hostname, proxyPort, activeLanIp, onMdnsError);
+          }
+        }
+        for (const hostname of previousRoutes.keys()) {
+          if (!currentRoutes.has(hostname)) {
+            unpublish(hostname);
+          }
+        }
+      }
     } catch {
     }
   };
@@ -848,6 +1253,7 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, strict) {
   if (autoSyncHosts) {
     syncHostsFile(cachedRoutes.map((r) => r.hostname));
   }
+  publishCachedRoutes();
   const server = createProxyServer({
     getRoutes: () => cachedRoutes,
     proxyPort,
@@ -890,6 +1296,7 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, strict) {
     fs3.writeFileSync(store.portFilePath, proxyPort.toString(), { mode: FILE_MODE });
     writeTlsMarker(store.dir, isTls);
     writeTldFile(store.dir, tld);
+    writeLanMarker(store.dir, activeLanIp);
     fixOwnership(store.dir, store.pidPath, store.portFilePath);
     const proto = isTls ? "HTTPS/2" : "HTTP";
     const tldLabel = tld !== DEFAULT_TLD ? ` (TLD: .${tld})` : "";
@@ -897,6 +1304,24 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, strict) {
     console.log(
       colors_default.green(`${proto} proxy listening on port ${proxyPort}${tldLabel}${modeLabel}`)
     );
+    if (activeLanIp) {
+      console.log(chalk.green(`LAN mode: ${activeLanIp}`));
+      console.log(chalk.gray("Services are discoverable as <name>.local on your network"));
+      if (isTls) {
+        console.log(chalk.yellow("For HTTPS on devices, install the CA certificate:"));
+        console.log(chalk.gray(`  ${path3.join(store.dir, "ca.pem")}`));
+      }
+      if (!lanIpPinned) {
+        lanMonitor = startLanIpMonitor({
+          initialIp: activeLanIp,
+          onChange: (nextIp, previousIp) => updateLanIp(nextIp, previousIp),
+          onError: (error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(chalk.yellow(`Failed to refresh LAN IP: ${message}`));
+          }
+        });
+      }
+    }
     if (redirectServer) {
       console.log(colors_default.green("HTTP-to-HTTPS redirect listening on port 80"));
     }
@@ -907,9 +1332,11 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, strict) {
     exiting = true;
     if (debounceTimer) clearTimeout(debounceTimer);
     if (pollingInterval) clearInterval(pollingInterval);
+    if (lanMonitor) lanMonitor.stop();
     if (watcher) {
       watcher.close();
     }
+    if (activeLanIp) cleanupAll();
     if (redirectServer) {
       redirectServer.close();
     }
@@ -1060,8 +1487,11 @@ function listRoutes(store, proxyPort, tls2) {
   }
   console.log();
 }
-async function runApp(initialStore, proxyPort, stateDir, name, commandArgs, tls2, tld, force, autoInfo, desiredPort) {
+async function runApp(initialStore, proxyPort, stateDir, name, commandArgs, tls2, tld, force, autoInfo, desiredPort, lanMode = false, lanIp) {
   let store = initialStore;
+  console.log(chalk.blue.bold(`
+portless
+`));
   let envTld;
   try {
     envTld = getDefaultTld();
@@ -1069,38 +1499,44 @@ async function runApp(initialStore, proxyPort, stateDir, name, commandArgs, tls2
     console.error(colors_default.red(`Error: ${err.message}`));
     process.exit(1);
   }
-  if (envTld !== DEFAULT_TLD && envTld !== tld) {
-    console.warn(
-      colors_default.yellow(
-        `Warning: PORTLESS_TLD=${envTld} but the running proxy uses .${tld}. Using .${tld}.`
-      )
-    );
-  }
-  console.log(colors_default.blue.bold(`
-portless
-`));
-  console.log(colors_default.gray(`-- ${parseHostname(name, tld)} (auto-resolves to 127.0.0.1)`));
-  if (autoInfo) {
-    const baseName = autoInfo.prefix ? name.slice(autoInfo.prefix.length + 1) : name;
-    console.log(colors_default.gray(`-- Name "${baseName}" (from ${autoInfo.nameSource})`));
-    if (autoInfo.prefix) {
-      console.log(colors_default.gray(`-- Prefix "${autoInfo.prefix}" (from ${autoInfo.prefixSource})`));
-    }
-  }
-  if (!await isProxyRunning(proxyPort, tls2)) {
-    const wantTls = !isHttpsEnvDisabled();
-    const defaultPort = getDefaultPort(wantTls);
+  const explicit = {
+    useHttps: process.env.PORTLESS_HTTPS !== void 0,
+    customCert: false,
+    lanMode: process.env.PORTLESS_LAN !== void 0,
+    lanIp: process.env.PORTLESS_LAN_IP !== void 0,
+    tld: process.env.PORTLESS_TLD !== void 0,
+    useWildcard: process.env.PORTLESS_WILDCARD !== void 0
+  };
+  const desiredConfig = resolveProxyConfig({
+    persistedLanMode: lanMode,
+    explicit,
+    defaultTld: envTld,
+    useHttps: !isHttpsEnvDisabled(),
+    customCertPath: null,
+    customKeyPath: null,
+    lanMode: isLanEnvEnabled(),
+    lanIp: process.env.PORTLESS_LAN_IP || null,
+    tld: envTld,
+    useWildcard: isWildcardEnvEnabled()
+  });
+  parseHostname(name, tld);
+  const proxyResponsive = await isProxyRunning(proxyPort, tls2);
+  const proxyListeningFromStateDir = !!process.env.PORTLESS_STATE_DIR && await isPortListening(proxyPort);
+  if (!proxyResponsive && !proxyListeningFromStateDir) {
+    const defaultPort = getDefaultPort(desiredConfig.useHttps);
     const needsSudo = !isWindows && defaultPort < PRIVILEGED_PORT_THRESHOLD;
+    const manualStartCommand = formatProxyStartCommand(defaultPort, desiredConfig);
+    const fallbackStartCommand = formatProxyStartCommand(FALLBACK_PROXY_PORT, desiredConfig);
     if (needsSudo && !process.stdin.isTTY) {
       console.error(colors_default.red("Proxy is not running and no TTY is available for sudo."));
       console.error(colors_default.blue("Option 1: start the proxy in a terminal (will prompt for sudo):"));
-      console.error(colors_default.cyan("  portless proxy start"));
+      console.error(colors_default.cyan(`  ${manualStartCommand}`));
       console.error(
         colors_default.blue(
           `Option 2: use an unprivileged port (no sudo needed, URLs will include :${FALLBACK_PROXY_PORT}):`
         )
       );
-      console.error(colors_default.cyan(`  portless proxy start -p ${FALLBACK_PROXY_PORT}`));
+      console.error(colors_default.cyan(`  ${fallbackStartCommand}`));
       process.exit(1);
     }
     if (needsSudo && process.stdin.isTTY) {
@@ -1116,15 +1552,23 @@ portless
       }
     }
     console.log(colors_default.yellow("Starting proxy..."));
-    const startArgs = [getEntryScript(), "proxy", "start"];
-    if (!wantTls) startArgs.push("--no-tls");
-    if (tld !== DEFAULT_TLD) startArgs.push("--tld", tld);
-    const result = spawnSync(process.execPath, startArgs, {
+    const proxyStartConfig = buildProxyStartConfig({
+      useHttps: desiredConfig.useHttps,
+      customCertPath: desiredConfig.customCertPath,
+      customKeyPath: desiredConfig.customKeyPath,
+      lanMode: desiredConfig.lanMode,
+      lanIp: desiredConfig.lanIpExplicit ? desiredConfig.lanIp : null,
+      lanIpExplicit: desiredConfig.lanIpExplicit,
+      tld: desiredConfig.tld,
+      useWildcard: desiredConfig.useWildcard
+    });
+    const startArgs = [getEntryScript(), "proxy", "start", ...proxyStartConfig.args];
+    const result = spawnSync2(process.execPath, startArgs, {
       stdio: "inherit",
       timeout: SUDO_SPAWN_TIMEOUT_MS
     });
     let discovered = null;
-    if (result.status === 0) {
+    if (!result.signal) {
       for (let i = 0; i < WAIT_FOR_PROXY_MAX_ATTEMPTS; i++) {
         await new Promise((r) => setTimeout(r, WAIT_FOR_PROXY_INTERVAL_MS));
         const state = await discoverState();
@@ -1136,10 +1580,10 @@ portless
     }
     if (!discovered) {
       console.error(colors_default.red("Failed to start proxy."));
-      const fallbackDir = resolveStateDir(getDefaultPort(wantTls));
+      const fallbackDir = resolveStateDir(getDefaultPort(desiredConfig.useHttps));
       const logPath = path3.join(fallbackDir, "proxy.log");
       console.error(colors_default.blue("Try starting it manually:"));
-      console.error(colors_default.cyan("  portless proxy start"));
+      console.error(colors_default.cyan(`  ${manualStartCommand}`));
       if (fs3.existsSync(logPath)) {
         console.error(colors_default.gray(`Logs: ${logPath}`));
       }
@@ -1150,14 +1594,42 @@ portless
     stateDir = discovered.dir;
     tld = discovered.tld;
     tls2 = discovered.tls;
+    lanMode = discovered.lanMode;
+    lanIp = discovered.lanIp;
     store = new RouteStore(stateDir, {
       onWarning: (msg) => console.warn(colors_default.yellow(msg))
     });
     console.log(colors_default.green("Proxy started in background"));
   } else {
-    console.log(colors_default.gray("-- Proxy is running"));
+    const runningConfig = readCurrentProxyConfig(stateDir);
+    const mismatchMessages = getProxyConfigMismatchMessages(desiredConfig, runningConfig, explicit);
+    if (mismatchMessages.length > 0) {
+      printProxyConfigMismatch(proxyPort, desiredConfig, mismatchMessages);
+    }
+    lanMode = runningConfig.lanMode;
+    lanIp = runningConfig.lanIp;
+    console.log(chalk.gray("-- Proxy is running"));
   }
   const hostname = parseHostname(name, tld);
+  if (envTld !== DEFAULT_TLD && envTld !== tld) {
+    console.warn(
+      chalk.yellow(
+        `Warning: PORTLESS_TLD=${envTld} but the running proxy uses .${tld}. Using .${tld}.`
+      )
+    );
+  }
+  if (lanIp) {
+    console.log(chalk.gray(`-- ${hostname} (LAN: ${lanIp})`));
+  } else {
+    console.log(chalk.gray(`-- ${hostname} (auto-resolves to 127.0.0.1)`));
+  }
+  if (autoInfo) {
+    const baseName = autoInfo.prefix ? name.slice(autoInfo.prefix.length + 1) : name;
+    console.log(chalk.gray(`-- Name "${baseName}" (from ${autoInfo.nameSource})`));
+    if (autoInfo.prefix) {
+      console.log(chalk.gray(`-- Prefix "${autoInfo.prefix}" (from ${autoInfo.prefixSource})`));
+    }
+  }
   const port = desiredPort ?? await findFreePort();
   if (desiredPort) {
     console.log(colors_default.green(`-- Using port ${port} (fixed)`));
@@ -1178,13 +1650,24 @@ portless
     console.log(colors_default.yellow(`Killed existing process (PID ${killedPid})`));
   }
   const finalUrl = formatUrl(hostname, proxyPort, tls2);
-  console.log(colors_default.cyan.bold(`
+  console.log(chalk.cyan.bold(`
   -> ${finalUrl}
 `));
+  if (lanIp) {
+    console.log(chalk.green(`  LAN -> ${finalUrl}`));
+    console.log(chalk.gray("  (accessible from other devices on the same WiFi network)\n"));
+  }
+  const basename3 = path3.basename(commandArgs[0]);
+  const isExpo = basename3 === "expo";
+  const isExpoLan = isExpo && (lanMode || isLanEnvEnabled());
+  const hostBind = isExpoLan ? void 0 : "127.0.0.1";
+  if (lanMode && !process.env.PORTLESS_LAN) {
+    process.env.PORTLESS_LAN = "1";
+  }
   injectFrameworkFlags(commandArgs, port);
   console.log(
-    colors_default.gray(
-      `Running: PORT=${port} HOST=127.0.0.1 PORTLESS_URL=${finalUrl} ${commandArgs.join(" ")}
+    chalk.gray(
+      `Running: PORT=${port}${hostBind ? ` HOST=${hostBind}` : ""} PORTLESS_URL=${finalUrl} ${commandArgs.join(" ")}
 `
     )
   );
@@ -1192,9 +1675,13 @@ portless
     env: {
       ...process.env,
       PORT: port.toString(),
-      HOST: "127.0.0.1",
+      ...hostBind ? { HOST: hostBind } : {},
       PORTLESS_URL: finalUrl,
-      __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS: `.${tld}`
+      __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS: `.${tld}`,
+      // Note: EXPO_PACKAGER_PROXY_URL is not used — expo-dev-client removed
+      // baked-in pinging, making this env var ineffective. Expo handles its
+      // own LAN discovery natively.
+      ...lanMode ? { PORTLESS_LAN: "1" } : {}
     },
     onCleanup: () => {
       try {
@@ -1342,6 +1829,7 @@ ${colors_default.bold("Install:")}
 ${colors_default.bold("Usage:")}
   ${colors_default.cyan("portless proxy start")}             Start the proxy (HTTPS on port 443, daemon)
   ${colors_default.cyan("portless proxy start --no-tls")}    Start without HTTPS (port 80)
+  ${colors_default.cyan("portless proxy start --lan")}       Start in LAN mode (mDNS for real device testing)
   ${colors_default.cyan("portless proxy start -p 1355")}     Start on a custom port (no sudo)
   ${colors_default.cyan("portless proxy stop")}              Stop the proxy
   ${colors_default.cyan("portless <name> <cmd>")}            Run your app through the proxy
@@ -1378,14 +1866,30 @@ ${colors_default.bold("How it works:")}
      (apps get a random port in the 4000-4999 range via PORT)
   3. Access via https://<name>.localhost
   4. .localhost domains auto-resolve to 127.0.0.1
-  5. Frameworks that ignore PORT (Vite, Astro, React Router, Angular,
-     Expo, React Native) get --port and --host flags injected automatically
+  5. Frameworks that ignore PORT (Vite, VitePlus, Astro, React Router, Angular,
+     Expo, React Native) get --port and, when needed, --host flags
+     injected automatically
 
 ${colors_default.bold("HTTP/2 + HTTPS (default):")}
   HTTPS with HTTP/2 multiplexing is enabled by default (faster page loads).
   On first use, portless generates a local CA and adds it to your
   system trust store. No browser warnings. Disable with --no-tls.
 
+${colors_default.bold("LAN mode:")}
+  Use --lan to make services accessible from other devices (phones,
+  tablets) on the same WiFi network via mDNS (.local domains).
+  Useful for testing React Native / Expo apps on real devices.
+  Expo keeps Metro's default LAN host behavior in this mode.
+  Auto-detected LAN IPs follow network changes automatically.
+  Stopped LAN proxies keep LAN mode for the next start via proxy.lan.
+  Other proxy settings still follow the current flags and env vars.
+  Use PORTLESS_LAN=0 for one start to switch back to .localhost mode.
+  If a proxy is already running with different explicit LAN/TLS/TLD settings,
+  stop it first.
+  ${colors_default.cyan("portless proxy start --lan")}
+  ${colors_default.cyan("portless proxy start --lan --https")}
+  ${colors_default.cyan("portless proxy start --lan --ip 192.168.1.42")}
+
 ${colors_default.bold("Options:")}
   run [--name <name>] <cmd>      Infer project name (or override with --name)
                                 Adds worktree prefix in git worktrees
@@ -1393,6 +1897,8 @@ ${colors_default.bold("Options:")}
                                 Standard ports auto-elevate with sudo on macOS/Linux
   --no-tls                      Disable HTTPS (use plain HTTP on port 80)
   --https                       Enable HTTPS (default, accepted for compatibility)
+  --lan                         Enable LAN mode (mDNS .local, for real device testing)
+  --ip <address>                Pin a specific LAN IP (disables auto-follow; use with --lan)
   --cert <path>                 Use a custom TLS certificate
   --key <path>                  Use a custom TLS private key
   --foreground                  Run proxy in foreground (for debugging)
@@ -1406,7 +1912,8 @@ ${colors_default.bold("Options:")}
 ${colors_default.bold("Environment variables:")}
   PORTLESS_PORT=<number>        Override the default proxy port (e.g. in .bashrc)
   PORTLESS_APP_PORT=<number>    Use a fixed port for the app (same as --app-port)
-  PORTLESS_HTTPS                HTTPS on by default; set to 0 to disable (same as --no-tls)
+  PORTLESS_HTTPS=0              Disable HTTPS (same as --no-tls)
+  PORTLESS_LAN=1                Enable LAN mode when set to 1 (set in .bashrc / .zshrc)
   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=1         Auto-sync ${HOSTS_DISPLAY} (auto-enabled for custom TLDs)
@@ -1415,8 +1922,9 @@ ${colors_default.bold("Environment variables:")}
 
 ${colors_default.bold("Child process environment:")}
   PORT                          Ephemeral port the child should listen on
-  HOST                          Always 127.0.0.1
+  HOST                          Usually 127.0.0.1 (omitted for Expo in LAN mode)
   PORTLESS_URL                  Public URL of the app (e.g. https://myapp.localhost)
+  PORTLESS_LAN                  Set to 1 when proxy is in LAN mode
 
 ${colors_default.bold("Safari / DNS:")}
   .localhost subdomains auto-resolve in Chrome, Firefox, and Edge.
@@ -1438,7 +1946,7 @@ ${colors_default.bold("Reserved names:")}
   process.exit(0);
 }
 function printVersion() {
-  console.log("0.9.5");
+  console.log("0.10.0");
   process.exit(0);
 }
 async function handleTrust() {
@@ -1459,7 +1967,7 @@ async function handleTrust() {
   const isPermissionError = result.error?.includes("Permission denied") || result.error?.includes("EACCES");
   if (isPermissionError && !isWindows && process.getuid?.() !== 0) {
     console.log(colors_default.yellow("Trusting the CA requires elevated privileges. Requesting sudo..."));
-    const sudoResult = spawnSync(
+    const sudoResult = spawnSync2(
       "sudo",
       [
         "env",
@@ -1630,7 +2138,7 @@ ${colors_default.bold("Auto-sync:")}
           `Writing to ${HOSTS_DISPLAY} requires elevated privileges. Requesting sudo...`
         )
       );
-      const result = spawnSync(
+      const result = spawnSync2(
         "sudo",
         ["env", ...collectPortlessEnvArgs(), process.execPath, getEntryScript(), "hosts", "clean"],
         {
@@ -1683,7 +2191,7 @@ ${colors_default.bold("Usage: portless hosts <command>")}
     console.log(
       colors_default.yellow(`Writing to ${HOSTS_DISPLAY} requires elevated privileges. Requesting sudo...`)
     );
-    const result = spawnSync(
+    const result = spawnSync2(
       "sudo",
       ["env", ...collectPortlessEnvArgs(), process.execPath, getEntryScript(), "hosts", "sync"],
       {
@@ -1734,15 +2242,25 @@ ${colors_default.bold("portless proxy")} - Manage the portless proxy server.
 ${colors_default.bold("Usage:")}
   ${colors_default.cyan("portless proxy start")}                Start the HTTPS proxy on port 443 (daemon)
   ${colors_default.cyan("portless proxy start --no-tls")}       Start without HTTPS (port 80)
+  ${colors_default.cyan("portless proxy start --lan")}          Enable LAN mode (mDNS, .local TLD)
   ${colors_default.cyan("portless proxy start --foreground")}   Start in foreground (for debugging)
   ${colors_default.cyan("portless proxy start -p 1355")}        Start on a custom port (no sudo)
   ${colors_default.cyan("portless proxy start --tld test")}     Use .test instead of .localhost
   ${colors_default.cyan("portless proxy start --wildcard")}     Allow unregistered subdomains to fall back to parent
   ${colors_default.cyan("portless proxy stop")}                 Stop the proxy
+
+${colors_default.bold("LAN mode (--lan):")}
+  Makes services accessible from other devices on the same WiFi network
+  via mDNS (.local domains). Useful for testing on real mobile devices.
+  Auto-detects your LAN IP and follows changes automatically, or use
+  --ip to pin one.
+  Stopped LAN proxies keep LAN mode for the next start via proxy.lan.
+  Use PORTLESS_LAN=0 for one start to switch back to .localhost mode.
 `);
     process.exit(isProxyHelp || !args[1] ? 0 : 1);
   }
   const isForeground = args.includes("--foreground");
+  const hasHttpsFlag = args.includes("--https");
   const hasNoTls = args.includes("--no-tls") || isHttpsEnvDisabled();
   const wantHttps = !hasNoTls;
   let customCertPath = null;
@@ -1767,7 +2285,7 @@ ${colors_default.bold("Usage:")}
     console.error(colors_default.red("Error: --cert and --key must be used together."));
     process.exit(1);
   }
-  const useHttps = wantHttps || !!(customCertPath && customKeyPath);
+  let useHttps = wantHttps || !!(customCertPath && customKeyPath);
   let hasExplicitPort = false;
   let proxyPort = getDefaultPort(useHttps);
   let portFlagIndex = args.indexOf("--port");
@@ -1809,12 +2327,66 @@ ${colors_default.bold("Usage:")}
       process.exit(1);
     }
   }
+  const useWildcard = args.includes("--wildcard") || isWildcardEnvEnabled();
+  const explicit = {
+    useHttps: hasHttpsFlag || hasNoTls || customCertPath !== null || customKeyPath !== null || process.env.PORTLESS_HTTPS !== void 0,
+    customCert: customCertPath !== null || customKeyPath !== null,
+    lanMode: process.env.PORTLESS_LAN !== void 0,
+    lanIp: process.env.PORTLESS_LAN_IP !== void 0,
+    tld: tldIdx !== -1 || process.env.PORTLESS_TLD !== void 0,
+    useWildcard: args.includes("--wildcard") || process.env.PORTLESS_WILDCARD !== void 0
+  };
+  let stateDir = resolveStateDir(proxyPort);
+  let persistedLanMode = readLanMarker(stateDir) !== null;
+  let runningPort = null;
+  if (!hasExplicitPort) {
+    const currentState = await discoverState();
+    persistedLanMode = currentState.lanMode;
+    if (await isProxyRunning(currentState.port) || !!process.env.PORTLESS_STATE_DIR && await isPortListening(currentState.port)) {
+      runningPort = currentState.port;
+      proxyPort = currentState.port;
+      stateDir = currentState.dir;
+    }
+  }
+  const desiredConfig = resolveProxyConfig({
+    persistedLanMode,
+    explicit,
+    defaultTld: getDefaultTld(),
+    useHttps: wantHttps || !!(customCertPath && customKeyPath),
+    customCertPath,
+    customKeyPath,
+    lanMode: isLanEnvEnabled(),
+    lanIp: process.env.PORTLESS_LAN_IP || null,
+    tld,
+    useWildcard
+  });
+  const lanMode = desiredConfig.lanMode;
+  useHttps = desiredConfig.useHttps;
+  customCertPath = desiredConfig.customCertPath;
+  customKeyPath = desiredConfig.customKeyPath;
+  tld = desiredConfig.tld;
+  const desiredWildcard = desiredConfig.useWildcard;
+  let lanIp = desiredConfig.lanIpExplicit ? desiredConfig.lanIp : null;
+  if (!hasExplicitPort && runningPort === null) {
+    proxyPort = getDefaultPort(useHttps);
+    stateDir = resolveStateDir(proxyPort);
+  }
+  if (lanMode && tldIdx !== -1) {
+    const userTld = args[tldIdx + 1];
+    if (userTld && userTld !== "local") {
+      console.warn(
+        chalk.yellow(
+          `Warning: --lan forces .local TLD (mDNS requirement). Ignoring --tld ${userTld}.`
+        )
+      );
+    }
+  }
   const riskyReason = RISKY_TLDS.get(tld);
-  if (riskyReason) {
+  if (riskyReason && !lanMode) {
     console.warn(colors_default.yellow(`Warning: .${tld}: ${riskyReason}`));
   }
   const syncDisabled = process.env.PORTLESS_SYNC_HOSTS === "0" || process.env.PORTLESS_SYNC_HOSTS === "false";
-  if (tld !== DEFAULT_TLD && syncDisabled) {
+  if (tld !== DEFAULT_TLD && !lanMode && syncDisabled) {
     console.warn(
       colors_default.yellow(
         `Warning: .${tld} domains require ${HOSTS_DISPLAY} entries to resolve to 127.0.0.1.`
@@ -1823,51 +2395,93 @@ ${colors_default.bold("Usage:")}
     console.warn(colors_default.yellow("Hosts sync is disabled. To add entries manually, run:"));
     console.warn(colors_default.cyan("  portless hosts sync"));
   }
-  const useWildcard = args.includes("--wildcard") || isWildcardEnvEnabled();
-  let stateDir = resolveStateDir(proxyPort);
   let store = new RouteStore(stateDir, {
     onWarning: (msg) => console.warn(colors_default.yellow(msg))
   });
-  if (await isProxyRunning(proxyPort)) {
+  const proxyRunning = runningPort !== null || await isProxyRunning(proxyPort);
+  if (proxyRunning) {
+    const runningConfig = readCurrentProxyConfig(stateDir);
+    const mismatchMessages = getProxyConfigMismatchMessages(desiredConfig, runningConfig, explicit);
+    if (mismatchMessages.length > 0) {
+      printProxyConfigMismatch(proxyPort, desiredConfig, mismatchMessages);
+    }
     if (isForeground) {
       return;
     }
-    const portFlag = proxyPort !== getProtocolPort(useHttps) ? ` -p ${proxyPort}` : "";
+    const portFlag = proxyPort !== getDefaultPort(useHttps) ? ` -p ${proxyPort}` : "";
     console.log(colors_default.yellow(`Proxy is already running on port ${proxyPort}.`));
     console.log(
       colors_default.blue(`To restart: portless proxy stop${portFlag} && portless proxy start${portFlag}`)
     );
     return;
   }
+  if (lanMode) {
+    const mdnsSupport = isMdnsSupported();
+    if (!mdnsSupport.supported) {
+      console.error(
+        colors_default.red(
+          "Error: LAN mode requires mDNS publishing, which is not supported on this platform."
+        )
+      );
+      if (mdnsSupport.reason) {
+        console.error(colors_default.gray(mdnsSupport.reason));
+      }
+      process.exit(1);
+    }
+    const inheritedLanIp = process.env[INTERNAL_LAN_IP_ENV] || null;
+    delete process.env[INTERNAL_LAN_IP_ENV];
+    if (!lanIp) {
+      lanIp = inheritedLanIp || await getLocalNetworkIp();
+    }
+    if (!lanIp) {
+      console.error(colors_default.red("Error: Could not detect LAN IP. Are you connected to a network?"));
+      console.error(colors_default.blue("Specify manually:"));
+      console.error(colors_default.cyan("  portless proxy start --lan --ip 192.168.1.42"));
+      process.exit(1);
+    }
+  } else {
+    delete process.env[INTERNAL_LAN_IP_ENV];
+  }
+  const resolvedConfig = {
+    ...desiredConfig,
+    useHttps,
+    customCertPath,
+    customKeyPath,
+    lanMode,
+    lanIp: desiredConfig.lanIpExplicit ? lanIp : null,
+    lanIpExplicit: desiredConfig.lanIpExplicit,
+    tld,
+    useWildcard: desiredWildcard
+  };
   if (!isWindows && proxyPort < PRIVILEGED_PORT_THRESHOLD && (process.getuid?.() ?? -1) !== 0) {
-    const baseArgs = [
+    const startArgs = [
       process.execPath,
       getEntryScript(),
       "proxy",
       "start",
-      "-p",
-      String(proxyPort)
+      ...buildProxyStartConfig({
+        useHttps,
+        customCertPath,
+        customKeyPath,
+        lanMode,
+        lanIp: desiredConfig.lanIpExplicit ? lanIp : null,
+        lanIpExplicit: desiredConfig.lanIpExplicit,
+        tld,
+        useWildcard: desiredWildcard,
+        foreground: isForeground,
+        includePort: true,
+        proxyPort
+      }).args
     ];
-    const optionalFlags = [];
-    if (hasNoTls) optionalFlags.push("--no-tls");
-    if (tld !== DEFAULT_TLD) optionalFlags.push("--tld", tld);
-    if (useWildcard) optionalFlags.push("--wildcard");
-    if (isForeground) optionalFlags.push("--foreground");
-    if (customCertPath && customKeyPath)
-      optionalFlags.push("--cert", customCertPath, "--key", customKeyPath);
-    const startArgs = [...baseArgs, ...optionalFlags];
-    const extraFlags = optionalFlags.map((a) => ` ${a}`).join("");
+    const fallbackCommand = formatProxyStartCommand(FALLBACK_PROXY_PORT, resolvedConfig);
+    const currentCommand = formatProxyStartCommand(proxyPort, resolvedConfig);
     console.log(
       colors_default.yellow(`Port ${proxyPort} requires elevated privileges. Requesting sudo...`)
     );
     if (!hasExplicitPort) {
-      console.log(
-        colors_default.gray(
-          `(To skip sudo, use an unprivileged port: portless proxy start -p ${FALLBACK_PROXY_PORT}${extraFlags})`
-        )
-      );
+      console.log(colors_default.gray(`(To skip sudo, use an unprivileged port: ${fallbackCommand})`));
     }
-    const result = spawnSync("sudo", ["env", ...collectPortlessEnvArgs(), ...startArgs], {
+    const result = spawnSync2("sudo", ["env", ...collectPortlessEnvArgs(), ...startArgs], {
       stdio: "inherit",
       timeout: SUDO_SPAWN_TIMEOUT_MS
     });
@@ -1894,7 +2508,7 @@ ${colors_default.bold("Usage:")}
       console.log(
         colors_default.blue(`For clean URLs without port numbers, re-run and accept the sudo prompt:`)
       );
-      console.log(colors_default.cyan(`  portless proxy start${extraFlags}`));
+      console.log(colors_default.cyan(`  ${fallbackCommand}`));
       if (await isProxyRunning(proxyPort)) {
         console.log(colors_default.yellow(`Proxy is already running on port ${proxyPort}.`));
         return;
@@ -1908,7 +2522,7 @@ ${colors_default.bold("Usage:")}
         colors_default.red(`Error: Port ${proxyPort} requires elevated privileges and sudo failed.`)
       );
       console.error(colors_default.blue("Try again (portless will prompt for sudo):"));
-      console.error(colors_default.cyan(`  portless proxy start -p ${proxyPort}${extraFlags}`));
+      console.error(colors_default.cyan(`  ${currentCommand}`));
       process.exit(1);
     }
   }
@@ -1975,8 +2589,8 @@ ${colors_default.bold("Usage:")}
     }
   }
   if (isForeground) {
-    console.log(colors_default.blue.bold("\nportless proxy\n"));
-    startProxyServer(store, proxyPort, tld, tlsOptions, useWildcard ? false : void 0);
+    console.log(chalk.blue.bold("\nportless proxy\n"));
+    startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, desiredWildcard ? false : void 0);
     return;
   }
   store.ensureDir();
@@ -1992,26 +2606,21 @@ ${colors_default.bold("Usage:")}
       getEntryScript(),
       "proxy",
       "start",
-      "--foreground",
-      "--port",
-      proxyPort.toString()
+      ...buildProxyStartConfig({
+        useHttps,
+        customCertPath,
+        customKeyPath,
+        lanMode,
+        lanIp: desiredConfig.lanIpExplicit ? lanIp : null,
+        lanIpExplicit: desiredConfig.lanIpExplicit,
+        tld,
+        useWildcard: desiredWildcard,
+        foreground: true,
+        includePort: true,
+        proxyPort
+      }).args
     ];
-    if (useHttps) {
-      if (customCertPath && customKeyPath) {
-        daemonArgs.push("--cert", customCertPath, "--key", customKeyPath);
-      } else {
-        daemonArgs.push("--https");
-      }
-    } else {
-      daemonArgs.push("--no-tls");
-    }
-    if (tld !== DEFAULT_TLD) {
-      daemonArgs.push("--tld", tld);
-    }
-    if (useWildcard) {
-      daemonArgs.push("--wildcard");
-    }
-    const child = spawn(process.execPath, daemonArgs, {
+    const child = spawn2(process.execPath, daemonArgs, {
       detached: true,
       stdio: ["ignore", logFd, logFd],
       env: process.env,
@@ -2031,7 +2640,11 @@ ${colors_default.bold("Usage:")}
     process.exit(1);
   }
   const proto = useHttps ? "HTTPS/2" : "HTTP";
-  console.log(colors_default.green(`${proto} proxy started on port ${proxyPort}`));
+  console.log(chalk.green(`${proto} proxy started on port ${proxyPort}`));
+  if (lanMode && lanIp) {
+    console.log(chalk.green(`LAN mode active. IP: ${lanIp}`));
+    console.log(chalk.gray("Services will be discoverable as <name>.local on your network."));
+  }
 }
 async function handleRunMode(args) {
   const parsed = parseRunArgs(args);
@@ -2055,7 +2668,7 @@ async function handleRunMode(args) {
   }
   const worktree = detectWorktreePrefix();
   const effectiveName = worktree ? `${worktree.prefix}.${baseName}` : baseName;
-  const { dir, port, tls: tls2, tld } = await discoverState();
+  const { dir, port, tls: tls2, tld, lanMode, lanIp } = await discoverState();
   const store = new RouteStore(dir, {
     onWarning: (msg) => console.warn(colors_default.yellow(msg))
   });
@@ -2069,7 +2682,9 @@ async function handleRunMode(args) {
     tld,
     parsed.force,
     { nameSource, prefix: worktree?.prefix, prefixSource: worktree?.source },
-    parsed.appPort
+    parsed.appPort,
+    lanMode,
+    lanIp
   );
 }
 async function handleNamedMode(args) {
@@ -2083,7 +2698,7 @@ async function handleNamedMode(args) {
     process.exit(1);
   }
   const safeName = parsed.name.split(".").map((label) => truncateLabel(label)).join(".");
-  const { dir, port, tls: tls2, tld } = await discoverState();
+  const { dir, port, tls: tls2, tld, lanMode, lanIp } = await discoverState();
   const store = new RouteStore(dir, {
     onWarning: (msg) => console.warn(colors_default.yellow(msg))
   });
@@ -2097,7 +2712,9 @@ async function handleNamedMode(args) {
     tld,
     parsed.force,
     void 0,
-    parsed.appPort
+    parsed.appPort,
+    lanMode,
+    lanIp
   );
 }
 async function main() {
@@ -2119,6 +2736,40 @@ async function main() {
     console.error(colors_default.cyan("  npm install -D portless"));
     process.exit(1);
   }
+  const stripGlobalFlag = (flag, hasValue) => {
+    const sep = args.indexOf("--");
+    const end = sep === -1 ? args.length : sep;
+    const idx = args.indexOf(flag);
+    if (idx === -1 || idx >= end) return null;
+    if (!hasValue) {
+      args.splice(idx, 1);
+      return true;
+    }
+    const value = args[idx + 1];
+    if (!value || value.startsWith("-")) return false;
+    args.splice(idx, 2);
+    return value;
+  };
+  if (stripGlobalFlag("--lan", false)) {
+    process.env.PORTLESS_LAN = "1";
+  }
+  const ipResult = stripGlobalFlag("--ip", true);
+  if (ipResult === false) {
+    console.error(chalk.red("Error: --ip requires an IP address."));
+    console.error(chalk.cyan("  portless --lan --ip 192.168.1.42 run <command>"));
+    process.exit(1);
+  } else if (typeof ipResult === "string") {
+    process.env.PORTLESS_LAN_IP = ipResult;
+    process.env.PORTLESS_LAN = "1";
+  }
+  const autoIpResult = stripGlobalFlag(INTERNAL_LAN_IP_FLAG, true);
+  if (autoIpResult === false) {
+    console.error(chalk.red(`Error: ${INTERNAL_LAN_IP_FLAG} requires an IP address.`));
+    process.exit(1);
+  } else if (typeof autoIpResult === "string") {
+    process.env[INTERNAL_LAN_IP_ENV] = autoIpResult;
+    process.env.PORTLESS_LAN = "1";
+  }
   if (args[0] === "--name") {
     args.shift();
     if (!args[0]) {