portless 0.9.6 → 0.10.1

package/dist/cli.js

@@ -3,12 +3,17 @@ import {
   DEFAULT_TLD,
   FALLBACK_PROXY_PORT,
   FILE_MODE,
+  INTERNAL_LAN_IP_ENV,
+  INTERNAL_LAN_IP_FLAG,
   PRIVILEGED_PORT_THRESHOLD,
   RISKY_TLDS,
   RouteConflictError,
   RouteStore,
+  SYSTEM_STATE_DIR,
+  USER_STATE_DIR,
   WAIT_FOR_PROXY_INTERVAL_MS,
   WAIT_FOR_PROXY_MAX_ATTEMPTS,
+  buildProxyStartConfig,
   cleanHostsFile,
   createHttpRedirectServer,
   createProxyServer,
@@ -19,23 +24,29 @@ import {
   formatUrl,
   getDefaultPort,
   getDefaultTld,
-  getProtocolPort,
   injectFrameworkFlags,
   isErrnoException,
   isHttpsEnvDisabled,
+  isLanEnvEnabled,
+  isPortListening,
   isProxyRunning,
   isWildcardEnvEnabled,
   isWindows,
   parseHostname,
   prompt,
+  readLanMarker,
+  readTldFromDir,
+  readTlsMarker,
   resolveStateDir,
+  shouldAutoSyncHosts,
   spawnCommand,
   syncHostsFile,
   validateTld,
   waitForProxy,
+  writeLanMarker,
   writeTldFile,
   writeTlsMarker
-} from "./chunk-OPTRASOS.js";
+} from "./chunk-FM7IA4AF.js";
 
 // src/colors.ts
 function supportsColor() {
@@ -63,9 +74,9 @@ var gray = wrap("90", "39");
 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 * as fs4 from "fs";
+import * as path4 from "path";
+import { spawn as spawn2, spawnSync as spawnSync2 } from "child_process";
 
 // src/certs.ts
 import * as fs from "fs";
@@ -135,6 +146,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 +235,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 +243,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 +293,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 {
@@ -591,6 +611,129 @@ function trustCA(stateDir) {
     return { trusted: false, error: message };
   }
 }
+function untrustCA(stateDir) {
+  const caCertPath = path.join(stateDir, CA_CERT_FILE);
+  if (!fileExists(caCertPath)) {
+    return { removed: true };
+  }
+  if (!isCATrusted(stateDir)) {
+    return { removed: true };
+  }
+  try {
+    if (process.platform === "darwin") {
+      return untrustCAMacOS(caCertPath);
+    }
+    if (process.platform === "linux") {
+      return untrustCALinux(stateDir);
+    }
+    if (process.platform === "win32") {
+      return untrustCAWindows(caCertPath);
+    }
+    return { removed: false, error: `Unsupported platform: ${process.platform}` };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { removed: false, error: message };
+  }
+}
+function untrustCAMacOS(caCertPath) {
+  const errors = [];
+  const tryExec = (args) => {
+    try {
+      execFileSync("security", args, { stdio: "pipe", timeout: 3e4 });
+      return true;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      errors.push(message);
+      return false;
+    }
+  };
+  if (tryExec(["remove-trusted-cert", caCertPath])) {
+    return isCATrustedMacOSAfterAttempt(caCertPath) ? { removed: false, error: errors.join("; ") || "Trust entry may still be present" } : { removed: true };
+  }
+  const login = loginKeychainPath();
+  tryExec(["delete-certificate", "-c", CA_COMMON_NAME, login]);
+  tryExec(["delete-certificate", "-c", CA_COMMON_NAME, "/Library/Keychains/System.keychain"]);
+  return isCATrustedMacOSAfterAttempt(caCertPath) ? { removed: false, error: errors.join("; ") || "Could not remove CA from keychain (try sudo)" } : { removed: true };
+}
+function isCATrustedMacOSAfterAttempt(caCertPath) {
+  try {
+    const isRoot = (process.getuid?.() ?? -1) === 0;
+    const sudoUser = process.env.SUDO_USER;
+    if (isRoot && sudoUser) {
+      execFileSync(
+        "sudo",
+        ["-u", sudoUser, "security", "verify-cert", "-c", caCertPath, "-L", "-p", "ssl"],
+        { stdio: "pipe", timeout: 5e3 }
+      );
+    } else {
+      execFileSync("security", ["verify-cert", "-c", caCertPath, "-L", "-p", "ssl"], {
+        stdio: "pipe",
+        timeout: 5e3
+      });
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+function untrustCALinux(stateDir) {
+  const errors = [];
+  let deletedAny = false;
+  for (const config of Object.values(LINUX_CA_TRUST_CONFIGS)) {
+    const dest = path.join(config.certDir, "portless-ca.crt");
+    try {
+      if (fileExists(dest)) {
+        const ours = fs.readFileSync(path.join(stateDir, CA_CERT_FILE), "utf-8").trim();
+        const installed = fs.readFileSync(dest, "utf-8").trim();
+        if (ours === installed) {
+          fs.unlinkSync(dest);
+          deletedAny = true;
+        }
+      }
+    } catch (err) {
+      errors.push(err instanceof Error ? err.message : String(err));
+    }
+  }
+  if (deletedAny) {
+    try {
+      const config = getLinuxCATrustConfig();
+      execFileSync(config.updateCommand, [], { stdio: "pipe", timeout: 3e4 });
+    } catch (err) {
+      errors.push(err instanceof Error ? err.message : String(err));
+    }
+  }
+  if (isCATrusted(stateDir)) {
+    return {
+      removed: false,
+      error: errors.join("; ") || "CA still trusted (remove portless-ca.crt and run the distro CA update command, often with sudo)"
+    };
+  }
+  return { removed: true };
+}
+function untrustCAWindows(caCertPath) {
+  try {
+    const fingerprint = openssl(["x509", "-in", caCertPath, "-noout", "-fingerprint", "-sha1"]).trim().replace(/^.*=/, "").replace(/:/g, "").toLowerCase();
+    const storeListing = execFileSync("certutil", ["-store", "-user", "Root"], {
+      encoding: "utf-8",
+      timeout: 1e4,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    const normalized = storeListing.replace(/\s/g, "").toLowerCase();
+    if (!normalized.includes(fingerprint)) {
+      return { removed: true };
+    }
+    execFileSync("certutil", ["-delstore", "-user", "Root", "portless Local CA"], {
+      stdio: "pipe",
+      timeout: 3e4
+    });
+    if (isCATrustedWindows(caCertPath)) {
+      return { removed: false, error: "certutil could not remove the portless CA from Root" };
+    }
+    return { removed: true };
+  } catch (err) {
+    return { removed: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
 
 // src/auto.ts
 import { createHash } from "crypto";
@@ -766,12 +909,398 @@ function readBranchFromHead(gitdir) {
   }
 }
 
+// src/clean-utils.ts
+import * as fs3 from "fs";
+import * as path3 from "path";
+var PORTLESS_STATE_FILES = [
+  "routes.json",
+  "routes.lock",
+  "proxy.pid",
+  "proxy.port",
+  "proxy.log",
+  "proxy.tls",
+  "proxy.tld",
+  "proxy.lan",
+  "ca-key.pem",
+  "ca.pem",
+  "server-key.pem",
+  "server.pem",
+  "server.csr",
+  "server-ext.cnf",
+  "ca.srl"
+];
+var HOST_CERTS_DIR2 = "host-certs";
+function collectStateDirsForCleanup() {
+  const dirs = /* @__PURE__ */ new Set();
+  const add = (d) => {
+    const trimmed = d?.trim();
+    if (!trimmed) return;
+    const resolved = path3.resolve(trimmed);
+    if (fs3.existsSync(resolved)) dirs.add(resolved);
+  };
+  add(USER_STATE_DIR);
+  add(SYSTEM_STATE_DIR);
+  add(process.env.PORTLESS_STATE_DIR);
+  return [...dirs];
+}
+function removePortlessStateFiles(dir) {
+  for (const f of PORTLESS_STATE_FILES) {
+    try {
+      fs3.unlinkSync(path3.join(dir, f));
+    } catch {
+    }
+  }
+  try {
+    fs3.rmSync(path3.join(dir, HOST_CERTS_DIR2), { recursive: true, force: true });
+  } catch {
+  }
+}
+
+// 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((resolve3, 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) {
+        resolve3(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) {
@@ -782,10 +1311,10 @@ function getEntryScript() {
 function isLocallyInstalled() {
   let dir = process.cwd();
   for (; ; ) {
-    if (fs3.existsSync(path3.join(dir, "node_modules", "portless", "package.json"))) {
+    if (fs4.existsSync(path4.join(dir, "node_modules", "portless", "package.json"))) {
       return true;
     }
-    const parent = path3.dirname(dir);
+    const parent = path4.dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
@@ -803,21 +1332,29 @@ 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 });
+  if (!fs4.existsSync(routesPath)) {
+    fs4.writeFileSync(routesPath, "[]", { mode: FILE_MODE });
   }
   try {
-    fs3.chmodSync(routesPath, FILE_MODE);
+    fs4.chmodSync(routesPath, FILE_MODE);
   } catch {
   }
   fixOwnership(routesPath);
@@ -825,19 +1362,59 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, strict) {
   let debounceTimer = null;
   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 = shouldAutoSyncHosts(process.env.PORTLESS_SYNC_HOSTS);
+  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 {
     }
   };
   try {
-    watcher = fs3.watch(routesPath, () => {
+    watcher = fs4.watch(routesPath, () => {
       if (debounceTimer) clearTimeout(debounceTimer);
       debounceTimer = setTimeout(reloadRoutes, DEBOUNCE_MS);
     });
@@ -848,6 +1425,7 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, strict) {
   if (autoSyncHosts) {
     syncHostsFile(cachedRoutes.map((r) => r.hostname));
   }
+  publishCachedRoutes();
   const server = createProxyServer({
     getRoutes: () => cachedRoutes,
     proxyPort,
@@ -886,10 +1464,11 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, strict) {
     redirectServer.listen(80);
   }
   server.listen(proxyPort, () => {
-    fs3.writeFileSync(store.pidPath, process.pid.toString(), { mode: FILE_MODE });
-    fs3.writeFileSync(store.portFilePath, proxyPort.toString(), { mode: FILE_MODE });
+    fs4.writeFileSync(store.pidPath, process.pid.toString(), { mode: FILE_MODE });
+    fs4.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 +1476,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(`  ${path4.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,18 +1504,20 @@ 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();
     }
     try {
-      fs3.unlinkSync(store.pidPath);
+      fs4.unlinkSync(store.pidPath);
     } catch {
     }
     try {
-      fs3.unlinkSync(store.portFilePath);
+      fs4.unlinkSync(store.portFilePath);
     } catch {
     }
     writeTlsMarker(store.dir, false);
@@ -947,7 +1546,7 @@ function sudoStopOrHint(port) {
 }
 async function stopProxy(store, proxyPort, _tls) {
   const pidPath = store.pidPath;
-  if (!fs3.existsSync(pidPath)) {
+  if (!fs4.existsSync(pidPath)) {
     if (await isProxyRunning(proxyPort)) {
       console.log(colors_default.yellow(`PID file is missing but port ${proxyPort} is still in use.`));
       const pid = findPidOnPort(proxyPort);
@@ -955,7 +1554,7 @@ async function stopProxy(store, proxyPort, _tls) {
         try {
           process.kill(pid, "SIGTERM");
           try {
-            fs3.unlinkSync(store.portFilePath);
+            fs4.unlinkSync(store.portFilePath);
           } catch {
           }
           console.log(colors_default.green(`Killed process ${pid}. Proxy stopped.`));
@@ -990,10 +1589,10 @@ async function stopProxy(store, proxyPort, _tls) {
     return;
   }
   try {
-    const pid = parseInt(fs3.readFileSync(pidPath, "utf-8"), 10);
+    const pid = parseInt(fs4.readFileSync(pidPath, "utf-8"), 10);
     if (isNaN(pid)) {
       console.error(colors_default.red("Corrupted PID file. Removing it."));
-      fs3.unlinkSync(pidPath);
+      fs4.unlinkSync(pidPath);
       return;
     }
     try {
@@ -1004,9 +1603,9 @@ async function stopProxy(store, proxyPort, _tls) {
         return;
       }
       console.log(colors_default.yellow("Proxy process is no longer running. Cleaning up stale files."));
-      fs3.unlinkSync(pidPath);
+      fs4.unlinkSync(pidPath);
       try {
-        fs3.unlinkSync(store.portFilePath);
+        fs4.unlinkSync(store.portFilePath);
       } catch {
       }
       return;
@@ -1018,13 +1617,13 @@ async function stopProxy(store, proxyPort, _tls) {
         )
       );
       console.log(colors_default.yellow("Removing stale PID file."));
-      fs3.unlinkSync(pidPath);
+      fs4.unlinkSync(pidPath);
       return;
     }
     process.kill(pid, "SIGTERM");
-    fs3.unlinkSync(pidPath);
+    fs4.unlinkSync(pidPath);
     try {
-      fs3.unlinkSync(store.portFilePath);
+      fs4.unlinkSync(store.portFilePath);
     } catch {
     }
     console.log(colors_default.green("Proxy stopped."));
@@ -1060,8 +1659,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 +1671,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 +1724,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,11 +1752,11 @@ portless
     }
     if (!discovered) {
       console.error(colors_default.red("Failed to start proxy."));
-      const fallbackDir = resolveStateDir(getDefaultPort(wantTls));
-      const logPath = path3.join(fallbackDir, "proxy.log");
+      const fallbackDir = resolveStateDir(getDefaultPort(desiredConfig.useHttps));
+      const logPath = path4.join(fallbackDir, "proxy.log");
       console.error(colors_default.blue("Try starting it manually:"));
-      console.error(colors_default.cyan("  portless proxy start"));
-      if (fs3.existsSync(logPath)) {
+      console.error(colors_default.cyan(`  ${manualStartCommand}`));
+      if (fs4.existsSync(logPath)) {
         console.error(colors_default.gray(`Logs: ${logPath}`));
       }
       process.exit(1);
@@ -1150,14 +1766,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 +1822,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 = path4.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 +1847,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 +2001,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
@@ -1351,6 +2011,7 @@ ${colors_default.bold("Usage:")}
   ${colors_default.cyan("portless alias --remove <name>")}   Remove a static route
   ${colors_default.cyan("portless list")}                    Show active routes
   ${colors_default.cyan("portless trust")}                   Add local CA to system trust store
+  ${colors_default.cyan("portless clean")}                   Remove portless state, trust entry, and hosts block
   ${colors_default.cyan("portless hosts sync")}              Add routes to ${HOSTS_DISPLAY} (fixes Safari)
   ${colors_default.cyan("portless hosts clean")}             Remove portless entries from ${HOSTS_DISPLAY}
 
@@ -1378,14 +2039,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 +2070,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,23 +2085,25 @@ ${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)
+  PORTLESS_SYNC_HOSTS=0         Disable auto-sync of ${HOSTS_DISPLAY} (on by default)
   PORTLESS_STATE_DIR=<path>     Override the state directory
   PORTLESS=0                    Run command directly without proxy
 
 ${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.
   Safari relies on the system DNS resolver, which may not handle them.
-  Auto-syncs ${HOSTS_DISPLAY} for custom TLDs (e.g. --tld test). For .localhost,
-  set PORTLESS_SYNC_HOSTS=1 to enable. To manually sync:
+  Auto-syncs ${HOSTS_DISPLAY} for route hostnames by default (including .localhost,
+  custom TLDs, and LAN .local). Set PORTLESS_SYNC_HOSTS=0 to disable. To manually sync:
     ${colors_default.cyan("portless hosts sync")}
   Clean up later with:
     ${colors_default.cyan("portless hosts clean")}
@@ -1431,20 +2112,20 @@ ${colors_default.bold("Skip portless:")}
   PORTLESS=0 pnpm dev           # Runs command directly without proxy
 
 ${colors_default.bold("Reserved names:")}
-  run, get, alias, hosts, list, trust, proxy are subcommands and cannot
+  run, get, alias, hosts, list, trust, clean, proxy are subcommands and cannot
   be used as app names directly. Use "portless run" to infer the name,
   or "portless --name <name>" to force any name including reserved ones.
 `);
   process.exit(0);
 }
 function printVersion() {
-  console.log("0.9.6");
+  console.log("0.10.1");
   process.exit(0);
 }
 async function handleTrust() {
   const { dir } = await discoverState();
-  if (!fs3.existsSync(dir)) {
-    fs3.mkdirSync(dir, { recursive: true });
+  if (!fs4.existsSync(dir)) {
+    fs4.mkdirSync(dir, { recursive: true });
   }
   const { caGenerated } = ensureCerts(dir);
   if (caGenerated) {
@@ -1459,7 +2140,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",
@@ -1480,6 +2161,90 @@ async function handleTrust() {
   console.error(colors_default.red(`Failed to trust CA: ${result.error}`));
   process.exit(1);
 }
+async function handleClean(args) {
+  if (args[1] === "--help" || args[1] === "-h") {
+    console.log(`
+${colors_default.bold("portless clean")} - Remove portless artifacts from this machine.
+
+Stops the proxy if it is running, removes the local CA from the OS trust store
+when it was installed by portless, deletes known files under state directories
+(~/.portless, the system state directory, and PORTLESS_STATE_DIR when set),
+and removes the portless block from ${HOSTS_DISPLAY}.
+
+Only allowlisted filenames under each state directory are deleted. Custom
+certificate paths from --cert and --key are never removed.
+
+macOS/Linux may prompt for sudo when the proxy, trust store, or ${HOSTS_DISPLAY}
+require elevated privileges. On Windows, run as Administrator if needed.
+
+${colors_default.bold("Usage:")}
+  ${colors_default.cyan("portless clean")}
+
+${colors_default.bold("Options:")}
+  --help, -h             Show this help
+`);
+    process.exit(0);
+  }
+  if (args.length > 1) {
+    console.error(colors_default.red(`Error: Unknown argument "${args[1]}".`));
+    console.error(colors_default.cyan("  portless clean --help"));
+    process.exit(1);
+  }
+  console.log(colors_default.cyan("Stopping proxy if it is running..."));
+  const { dir, port, tls: tls2 } = await discoverState();
+  const store = new RouteStore(dir, {
+    onWarning: (msg) => console.warn(colors_default.yellow(msg))
+  });
+  await stopProxy(store, port, tls2);
+  const stateDirs = collectStateDirsForCleanup();
+  for (const stateDir of stateDirs) {
+    const caPath = path4.join(stateDir, "ca.pem");
+    if (!fs4.existsSync(caPath)) continue;
+    const wasTrusted = isCATrusted(stateDir);
+    if (!wasTrusted) continue;
+    const untrustResult = untrustCA(stateDir);
+    if (untrustResult.removed) {
+      console.log(colors_default.green("Removed local CA from the system trust store."));
+    } else if (untrustResult.error) {
+      console.warn(
+        colors_default.yellow(
+          `Could not remove CA from trust store: ${untrustResult.error}
+Try: sudo portless clean (Linux), or delete the certificate manually.`
+        )
+      );
+    }
+  }
+  for (const stateDir of stateDirs) {
+    removePortlessStateFiles(stateDir);
+  }
+  console.log(colors_default.green("Removed portless state files from known state directories."));
+  if (cleanHostsFile()) {
+    console.log(colors_default.green(`Removed portless entries from ${HOSTS_DISPLAY}.`));
+  } else if (!isWindows && process.getuid?.() !== 0) {
+    console.log(
+      colors_default.yellow(`Updating ${HOSTS_DISPLAY} requires elevated privileges. Requesting sudo...`)
+    );
+    const result = spawnSync2(
+      "sudo",
+      ["env", ...collectPortlessEnvArgs(), process.execPath, getEntryScript(), "clean"],
+      {
+        stdio: "inherit",
+        timeout: SUDO_SPAWN_TIMEOUT_MS
+      }
+    );
+    if (result.status !== 0) {
+      console.error(colors_default.red(`Failed to update ${HOSTS_DISPLAY}. Run: sudo portless clean`));
+      process.exit(1);
+    }
+  } else {
+    console.warn(
+      colors_default.yellow(
+        `Could not remove portless entries from ${HOSTS_DISPLAY}${isWindows ? " (run as Administrator)." : "."}`
+      )
+    );
+  }
+  console.log(colors_default.green("Clean finished."));
+}
 async function handleList() {
   const { dir, port, tls: tls2 } = await discoverState();
   const store = new RouteStore(dir, {
@@ -1614,8 +2379,8 @@ ${colors_default.bold("Usage:")}
   ${colors_default.cyan("portless hosts clean")}   Remove portless entries from ${HOSTS_DISPLAY}
 
 ${colors_default.bold("Auto-sync:")}
-  Auto-enabled for custom TLDs (e.g. --tld test). For .localhost, set
-  PORTLESS_SYNC_HOSTS=1 to enable. Disable with PORTLESS_SYNC_HOSTS=0.
+  The proxy updates ${HOSTS_DISPLAY} for route hostnames by default. Disable with
+  PORTLESS_SYNC_HOSTS=0.
 `);
     process.exit(0);
   }
@@ -1630,7 +2395,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 +2448,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 +2499,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 +2542,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 +2584,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 +2652,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
     });
@@ -1877,8 +2748,8 @@ ${colors_default.bold("Usage:")}
           console.log(colors_default.green(`Proxy started on port ${proxyPort}.`));
         } else {
           console.error(colors_default.red("Proxy process started but is not responding."));
-          const logPath2 = path3.join(resolveStateDir(proxyPort), "proxy.log");
-          if (fs3.existsSync(logPath2)) {
+          const logPath2 = path4.join(resolveStateDir(proxyPort), "proxy.log");
+          if (fs4.existsSync(logPath2)) {
             console.error(colors_default.gray(`Logs: ${logPath2}`));
           }
         }
@@ -1894,7 +2765,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 +2779,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);
     }
   }
@@ -1917,8 +2788,8 @@ ${colors_default.bold("Usage:")}
     store.ensureDir();
     if (customCertPath && customKeyPath) {
       try {
-        const cert = fs3.readFileSync(customCertPath);
-        const key = fs3.readFileSync(customKeyPath);
+        const cert = fs4.readFileSync(customCertPath);
+        const key = fs4.readFileSync(customKeyPath);
         const certStr = cert.toString("utf-8");
         const keyStr = key.toString("utf-8");
         if (!certStr.includes("-----BEGIN CERTIFICATE-----")) {
@@ -1963,9 +2834,9 @@ ${colors_default.bold("Usage:")}
           console.warn(colors_default.cyan("  portless trust"));
         }
       }
-      const cert = fs3.readFileSync(certs.certPath);
-      const key = fs3.readFileSync(certs.keyPath);
-      const ca = fs3.readFileSync(certs.caPath);
+      const cert = fs4.readFileSync(certs.certPath);
+      const key = fs4.readFileSync(certs.keyPath);
+      const ca = fs4.readFileSync(certs.caPath);
       tlsOptions = {
         cert,
         key,
@@ -1975,16 +2846,16 @@ ${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();
-  const logPath = path3.join(stateDir, "proxy.log");
-  const logFd = fs3.openSync(logPath, "a");
+  const logPath = path4.join(stateDir, "proxy.log");
+  const logFd = fs4.openSync(logPath, "a");
   try {
     try {
-      fs3.chmodSync(logPath, FILE_MODE);
+      fs4.chmodSync(logPath, FILE_MODE);
     } catch {
     }
     fixOwnership(logPath);
@@ -1992,26 +2863,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,
@@ -2019,19 +2885,23 @@ ${colors_default.bold("Usage:")}
     });
     child.unref();
   } finally {
-    fs3.closeSync(logFd);
+    fs4.closeSync(logFd);
   }
   if (!await waitForProxy(proxyPort, void 0, void 0, useHttps)) {
     console.error(colors_default.red("Proxy failed to start (timed out waiting for it to listen)."));
     console.error(colors_default.blue("Try starting the proxy in the foreground to see the error:"));
     console.error(colors_default.cyan("  portless proxy start --foreground"));
-    if (fs3.existsSync(logPath)) {
+    if (fs4.existsSync(logPath)) {
       console.error(colors_default.gray(`Logs: ${logPath}`));
     }
     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 +2925,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 +2939,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 +2955,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 +2969,9 @@ async function handleNamedMode(args) {
     tld,
     parsed.force,
     void 0,
-    parsed.appPort
+    parsed.appPort,
+    lanMode,
+    lanIp
   );
 }
 async function main() {
@@ -2119,6 +2993,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]) {
@@ -2144,7 +3052,7 @@ async function main() {
     args.shift();
   }
   const skipPortless = process.env.PORTLESS === "0" || process.env.PORTLESS === "false" || process.env.PORTLESS === "skip";
-  if (skipPortless && (isRunCommand || args.length >= 2 && args[0] !== "proxy")) {
+  if (skipPortless && (isRunCommand || args.length >= 2 && args[0] !== "proxy" && args[0] !== "clean")) {
     const { commandArgs } = isRunCommand ? parseRunArgs(args) : parseAppArgs(args);
     if (commandArgs.length === 0) {
       console.error(colors_default.red("Error: No command provided."));
@@ -2166,6 +3074,10 @@ async function main() {
       await handleTrust();
       return;
     }
+    if (args[0] === "clean") {
+      await handleClean(args);
+      return;
+    }
     if (args[0] === "list") {
       await handleList();
       return;