portless 0.10.0 → 0.10.2

package/README.md

@@ -32,7 +32,11 @@ portless myapp next dev
 
 HTTPS with HTTP/2 is enabled by default. On first run, portless generates a local CA, trusts it, and binds port 443 (auto-elevates with sudo on macOS/Linux). Use `--no-tls` for plain HTTP.
 
-The proxy auto-starts when you run an app. A random port (4000--4999) is assigned via the `PORT` environment variable. Most frameworks (Next.js, Express, Nuxt, etc.) respect this automatically. For frameworks that ignore `PORT` (Vite, VitePlus, Astro, React Router, Angular, Expo, React Native), portless auto-injects the right `--port` flag and, when needed, a matching `--host` flag.
+The proxy auto-starts when you run an app. A random port (4000-4999) is assigned via the `PORT` environment variable. Most frameworks (Next.js, Express, Nuxt, etc.) respect this automatically. For frameworks that ignore `PORT` (Vite, VitePlus, Astro, React Router, Angular, Expo, React Native), portless auto-injects the right `--port` flag and, when needed, a matching `--host` flag.
+
+When auto-starting, portless reuses the configuration (port, TLS, TLD) from the most recent proxy run, so a restart or reboot does not silently revert to defaults. Explicit env vars (`PORTLESS_PORT`, `PORTLESS_HTTPS`, etc.) always take priority.
+
+In non-interactive environments (no TTY, or `CI=1`), portless exits with a descriptive error instead of prompting, so task runners like turborepo and CI scripts fail early with a clear message.
 
 ## Use in package.json
 
@@ -88,7 +92,7 @@ portless myapp next dev
 # -> https://myapp.test
 ```
 
-The proxy auto-syncs `/etc/hosts` for custom TLDs, so `.test` domains resolve correctly.
+The proxy auto-syncs `/etc/hosts` for route hostnames (including `.test`), so those domains resolve on your machine.
 
 Recommended: `.test` (IANA-reserved, no collision risk). Avoid `.local` (conflicts with mDNS/Bonjour) and `.dev` (Google-owned, forces HTTPS via HSTS).
 
@@ -139,7 +143,7 @@ portless proxy start --lan --ip 192.168.1.42
 
 `--lan` switches the proxy to mDNS discovery: services are advertised as `<name>.local` and reachable from any device on the same network. Portless auto-detects your LAN IP and follows Wi-Fi/IP changes automatically, but you can pin another address with `--ip <address>` or by exporting `PORTLESS_LAN_IP`. Set `PORTLESS_LAN=1` in your shell (0/1 boolean) to make LAN mode the default whenever the proxy starts.
 
-Portless remembers LAN mode via `proxy.lan`, so if you stop a LAN proxy and start it again, it stays in LAN mode. 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, portless warns and asks you to stop it first.
+Portless remembers LAN mode via `proxy.lan`, so if you stop a LAN proxy and start it again, it stays in LAN mode. All proxy settings (port, TLS, TLD, LAN) are persisted and reused on auto-start unless overridden by explicit flags or 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, portless warns and asks you to stop it first.
 
 LAN mode depends on the system mDNS tools that portless already spawns: macOS ships with `dns-sd`, while Linux uses `avahi-publish-address` from `avahi-utils` (install via `sudo apt install avahi-utils` or your distro’s equivalent). If the command is missing or your network isn’t reachable, `portless proxy start --lan` prints the relevant error and exits.
 
@@ -166,6 +170,7 @@ portless alias <name> <port> --force  # Overwrite an existing route
 portless alias --remove <name>   # Remove a static route
 portless list                    # Show active routes
 portless trust                   # Add local CA to system trust store
+portless clean                   # Remove state, CA trust entry, and hosts block
 portless hosts sync              # Add routes to /etc/hosts (fixes Safari)
 portless hosts clean             # Remove portless entries from /etc/hosts
 
@@ -210,16 +215,27 @@ PORTLESS_HTTPS=0                 Disable HTTPS (same as --no-tls)
 PORTLESS_LAN=1                   Enable LAN mode when set to 1 (auto-detects LAN IP)
 PORTLESS_TLD=<tld>               Use a custom TLD (e.g. test; default: localhost)
 PORTLESS_WILDCARD=1              Allow unregistered subdomains to fall back to parent route
-PORTLESS_SYNC_HOSTS=1            Auto-sync /etc/hosts (auto-enabled for custom TLDs)
+PORTLESS_SYNC_HOSTS=0            Disable auto-sync of /etc/hosts (on by default)
 PORTLESS_STATE_DIR=<path>        Override the state directory
 
 # Injected into child processes
 PORT                             Ephemeral port the child should listen on
 HOST                             Usually 127.0.0.1 (omitted for Expo in LAN mode)
 PORTLESS_URL                     Public URL (e.g. https://myapp.localhost)
+NODE_EXTRA_CA_CERTS              Path to the portless CA (when HTTPS is active)
+```
+
+> **Reserved names:** `run`, `get`, `alias`, `hosts`, `list`, `trust`, `clean`, and `proxy` are subcommands and cannot be used as app names directly. Use `portless run <cmd>` to infer the name from your project, or `portless --name <name> <cmd>` to force any name including reserved ones.
+
+## Uninstall / reset
+
+To remove portless data from your machine (proxy state under `~/.portless` and the system state directory, the local CA from the OS trust store when portless installed it, and the portless block in `/etc/hosts`):
+
+```bash
+portless clean
 ```
 
-> **Reserved names:** `run`, `get`, `alias`, `hosts`, `list`, `trust`, and `proxy` are subcommands and cannot be used as app names directly. Use `portless run <cmd>` to infer the name from your project, or `portless --name <name> <cmd>` to force any name including reserved ones.
+macOS/Linux may prompt for `sudo`. Custom certificate paths passed with `--cert` and `--key` are not deleted.
 
 ## Safari / DNS
 
@@ -232,7 +248,7 @@ portless hosts sync    # Add current routes to /etc/hosts
 portless hosts clean   # Clean up later
 ```
 
-Auto-syncs `/etc/hosts` for custom TLDs (e.g. `--tld test`). For `.localhost`, set `PORTLESS_SYNC_HOSTS=1` to enable. Disable with `PORTLESS_SYNC_HOSTS=0`.
+Auto-syncs `/etc/hosts` for route hostnames by default (`.localhost`, custom TLDs, LAN `.local`). Set `PORTLESS_SYNC_HOSTS=0` to disable.
 
 ## Proxying Between Portless Apps
 
@@ -264,7 +280,7 @@ devServer: {
 }
 ```
 
-If your tooling doesn't trust the portless CA, point Node.js at it: `NODE_EXTRA_CA_CERTS=/tmp/portless/ca.pem` (or `~/.portless/ca.pem` when the proxy runs on a non-privileged port like 1355). Alternatively, use `--no-tls` for plain HTTP.
+Portless automatically sets `NODE_EXTRA_CA_CERTS` in child processes so Node.js trusts the portless CA. If you run a separate Node.js process outside portless, point it at the CA manually: `NODE_EXTRA_CA_CERTS=/tmp/portless/ca.pem` (or `~/.portless/ca.pem` when the proxy runs on a non-privileged port like 1355). Alternatively, use `--no-tls` for plain HTTP.
 
 Portless detects this misconfiguration and responds with `508 Loop Detected` along with a message pointing to this fix.
 

package/dist/{chunk-WXEE5QH6.js → chunk-EZJWUTUA.js}

@@ -392,8 +392,10 @@ function createProxyServer(options) {
         proxyRes.on("error", () => {
           if (!res.headersSent) {
             res.writeHead(502, { "Content-Type": "text/plain" });
+            res.end();
+          } else {
+            res.destroy();
           }
-          res.end();
         });
         proxyRes.pipe(res);
       }
@@ -516,9 +518,19 @@ function createProxyServer(options) {
       cert: tls.ca ? Buffer.concat([tls.cert, tls.ca]) : tls.cert,
       key: tls.key,
       allowHTTP1: true,
+      // Tolerate high rates of RST_STREAM from browsers during HMR and
+      // page navigations. Without this, Node sends GOAWAY INTERNAL_ERROR
+      // after ~1000 cumulative stream resets and kills the session,
+      // surfacing as ERR_HTTP2_PROTOCOL_ERROR in Chrome. Available in
+      // Node 22.11+; silently ignored on older versions.
+      ...{ streamResetBurst: 1e4, streamResetRate: 100 },
       ...tls.SNICallback ? { SNICallback: tls.SNICallback } : {}
     });
+    h2Server.on("sessionError", () => {
+    });
     h2Server.on("request", (req, res) => {
+      req.stream?.on("error", () => {
+      });
       handleRequest(req, res);
     });
     h2Server.on("upgrade", (req, socket, head) => {
@@ -614,6 +626,9 @@ function buildBlock(hostnames) {
 ${entries}
 ${MARKER_END}`;
 }
+function shouldAutoSyncHosts(syncVal) {
+  return syncVal !== "0" && syncVal !== "false";
+}
 function syncHostsFile(hostnames) {
   try {
     const content = readHostsFile();
@@ -898,6 +913,24 @@ function isLanEnvEnabled() {
   const val = process.env.PORTLESS_LAN;
   return val === "1" || val === "true";
 }
+function readPersistedProxyState() {
+  const dirs = [];
+  if (process.env.PORTLESS_STATE_DIR) {
+    dirs.push(process.env.PORTLESS_STATE_DIR);
+  } else {
+    dirs.push(USER_STATE_DIR, SYSTEM_STATE_DIR);
+  }
+  for (const dir of dirs) {
+    const port = readPortFromDir(dir);
+    if (port !== null) {
+      const tls = readTlsMarker(dir);
+      const tld = readTldFromDir(dir);
+      const lanIp = readLanMarker(dir);
+      return { port, tls, tld, lanMode: lanIp !== null || tld === "local" };
+    }
+  }
+  return null;
+}
 function buildProxyStartConfig(options) {
   const effectiveTld = options.lanMode ? "local" : options.tld;
   const args = [];
@@ -931,6 +964,9 @@ function buildProxyStartConfig(options) {
   if (options.useWildcard) {
     args.push("--wildcard");
   }
+  if (options.skipTrust) {
+    args.push("--skip-trust");
+  }
   return { effectiveTld, args };
 }
 async function discoverState() {
@@ -999,8 +1035,8 @@ async function discoverState() {
   return {
     dir,
     port: configuredPort,
-    tls: false,
-    tld: getDefaultTld(),
+    tls: readTlsMarker(dir),
+    tld: readTldFromDir(dir),
     lanMode: readLanMarker(dir) !== null,
     lanIp: null
   };
@@ -1269,8 +1305,9 @@ function prompt(question) {
 import * as fs4 from "fs";
 import * as path3 from "path";
 var STALE_LOCK_THRESHOLD_MS = 1e4;
-var LOCK_MAX_RETRIES = 20;
-var LOCK_RETRY_DELAY_MS = 50;
+var LOCK_TIMEOUT_MS = 5e3;
+var LOCK_RETRY_BASE_MS = 10;
+var LOCK_RETRY_CAP_MS = 500;
 var FILE_MODE = 420;
 var DIR_MODE = 493;
 var SYSTEM_DIR_MODE = 1023;
@@ -1334,8 +1371,10 @@ var RouteStore = class _RouteStore {
   syncSleep(ms) {
     Atomics.wait(_RouteStore.sleepBuffer, 0, 0, ms);
   }
-  acquireLock(maxRetries = LOCK_MAX_RETRIES, retryDelayMs = LOCK_RETRY_DELAY_MS) {
-    for (let i = 0; i < maxRetries; i++) {
+  acquireLock() {
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    let delay = LOCK_RETRY_BASE_MS;
+    while (Date.now() < deadline) {
       try {
         fs4.mkdirSync(this.lockPath);
         return true;
@@ -1350,7 +1389,9 @@ var RouteStore = class _RouteStore {
           } catch {
             continue;
           }
-          this.syncSleep(retryDelayMs);
+          const jitter = Math.floor(Math.random() * delay);
+          this.syncSleep(delay + jitter);
+          delay = Math.min(delay * 2, LOCK_RETRY_CAP_MS);
         } else {
           return false;
         }
@@ -1475,6 +1516,7 @@ export {
   extractManagedBlock,
   removeBlock,
   buildBlock,
+  shouldAutoSyncHosts,
   syncHostsFile,
   cleanHostsFile,
   getManagedHostnames,
@@ -1484,6 +1526,8 @@ export {
   PRIVILEGED_PORT_THRESHOLD,
   INTERNAL_LAN_IP_ENV,
   INTERNAL_LAN_IP_FLAG,
+  SYSTEM_STATE_DIR,
+  USER_STATE_DIR,
   WAIT_FOR_PROXY_MAX_ATTEMPTS,
   WAIT_FOR_PROXY_INTERVAL_MS,
   getDefaultPort,
@@ -1501,6 +1545,7 @@ export {
   isHttpsEnvDisabled,
   isWildcardEnvEnabled,
   isLanEnvEnabled,
+  readPersistedProxyState,
   buildProxyStartConfig,
   discoverState,
   findFreePort,

package/dist/cli.js

@@ -9,6 +9,8 @@ import {
   RISKY_TLDS,
   RouteConflictError,
   RouteStore,
+  SYSTEM_STATE_DIR,
+  USER_STATE_DIR,
   WAIT_FOR_PROXY_INTERVAL_MS,
   WAIT_FOR_PROXY_MAX_ATTEMPTS,
   buildProxyStartConfig,
@@ -33,9 +35,11 @@ import {
   parseHostname,
   prompt,
   readLanMarker,
+  readPersistedProxyState,
   readTldFromDir,
   readTlsMarker,
   resolveStateDir,
+  shouldAutoSyncHosts,
   spawnCommand,
   syncHostsFile,
   validateTld,
@@ -43,7 +47,7 @@ import {
   writeLanMarker,
   writeTldFile,
   writeTlsMarker
-} from "./chunk-WXEE5QH6.js";
+} from "./chunk-EZJWUTUA.js";
 
 // src/colors.ts
 function supportsColor() {
@@ -71,8 +75,8 @@ 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 * as fs4 from "fs";
+import * as path4 from "path";
 import { spawn as spawn2, spawnSync as spawnSync2 } from "child_process";
 
 // src/certs.ts
@@ -87,6 +91,9 @@ var SERVER_VALIDITY_DAYS = 365;
 var EXPIRY_BUFFER_MS = 7 * 24 * 60 * 60 * 1e3;
 var CA_COMMON_NAME = "portless Local CA";
 var OPENSSL_TIMEOUT_MS = 15e3;
+var MACOS_SECURITY_TIMEOUT_MS = 15e3;
+var MACOS_SECURITY_AUTH_TIMEOUT_MS = 12e4;
+var MACOS_SECURITY_ROOT_TIMEOUT_MS = 6e4;
 var CA_KEY_FILE = "ca-key.pem";
 var CA_CERT_FILE = "ca.pem";
 var SERVER_KEY_FILE = "server-key.pem";
@@ -335,13 +342,13 @@ function isCATrustedMacOS(caCertPath) {
         ["-u", sudoUser, "security", "verify-cert", "-c", caCertPath, "-L", "-p", "ssl"],
         {
           stdio: "pipe",
-          timeout: 5e3
+          timeout: MACOS_SECURITY_TIMEOUT_MS
         }
       );
     } else {
       execFileSync("security", ["verify-cert", "-c", caCertPath, "-L", "-p", "ssl"], {
         stdio: "pipe",
-        timeout: 5e3
+        timeout: MACOS_SECURITY_TIMEOUT_MS
       });
     }
     return true;
@@ -353,7 +360,7 @@ function loginKeychainPath() {
   try {
     const result = execFileSync("security", ["default-keychain"], {
       encoding: "utf-8",
-      timeout: 5e3
+      timeout: MACOS_SECURITY_TIMEOUT_MS
     }).trim();
     const match = result.match(/"(.+)"/);
     if (match) return match[1];
@@ -569,14 +576,14 @@ function trustCA(stateDir) {
             "/Library/Keychains/System.keychain",
             caCertPath
           ],
-          { stdio: "pipe", timeout: 3e4 }
+          { stdio: "pipe", timeout: MACOS_SECURITY_ROOT_TIMEOUT_MS }
         );
       } else {
         const keychain = loginKeychainPath();
         execFileSync(
           "security",
           ["add-trusted-cert", "-r", "trustRoot", "-k", keychain, caCertPath],
-          { stdio: "pipe", timeout: 3e4 }
+          { stdio: "pipe", timeout: MACOS_SECURITY_AUTH_TIMEOUT_MS }
         );
       }
       return { trusted: true };
@@ -599,6 +606,10 @@ function trustCA(stateDir) {
     return { trusted: false, error: `Unsupported platform: ${process.platform}` };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
+    if (message.includes("ETIMEDOUT")) {
+      const hint = process.platform === "darwin" ? "The macOS security command timed out. This can happen when the Keychain Services daemon is unresponsive or a system authorization dialog was not dismissed in time. Try restarting Keychain Access (or run: sudo killall securityd) and then: portless trust" : "The trust command timed out. Try: portless trust";
+      return { trusted: false, error: hint };
+    }
     if (message.includes("authorization") || message.includes("permission") || message.includes("EACCES")) {
       return {
         trusted: false,
@@ -608,6 +619,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: MACOS_SECURITY_ROOT_TIMEOUT_MS });
+      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: MACOS_SECURITY_TIMEOUT_MS }
+      );
+    } else {
+      execFileSync("security", ["verify-cert", "-c", caCertPath, "-L", "-p", "ssl"], {
+        stdio: "pipe",
+        timeout: MACOS_SECURITY_TIMEOUT_MS
+      });
+    }
+    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";
@@ -783,6 +917,53 @@ 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";
 
@@ -815,7 +996,7 @@ function isInternalInterface(iname, macStr, internal) {
   return false;
 }
 function probeDefaultRouteIPv4() {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const socket = createSocket({ type: "udp4", reuseAddr: true });
     socket.on("error", (error) => {
       socket.close();
@@ -827,7 +1008,7 @@ function probeDefaultRouteIPv4() {
       socket.close();
       socket.unref();
       if (addr && "address" in addr && addr.address && addr.address !== NO_ROUTE_IP) {
-        resolve2(addr.address);
+        resolve3(addr.address);
       } else {
         reject(new Error("No route to host"));
       }
@@ -1138,10 +1319,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;
   }
@@ -1177,11 +1358,11 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict) {
     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);
@@ -1189,8 +1370,7 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, 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 && !activeLanIp && 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;
@@ -1242,7 +1422,7 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict) {
     }
   };
   try {
-    watcher = fs3.watch(routesPath, () => {
+    watcher = fs4.watch(routesPath, () => {
       if (debounceTimer) clearTimeout(debounceTimer);
       debounceTimer = setTimeout(reloadRoutes, DEBOUNCE_MS);
     });
@@ -1292,8 +1472,8 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, 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);
@@ -1309,7 +1489,7 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict) {
       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")}`));
+        console.log(chalk.gray(`  ${path4.join(store.dir, "ca.pem")}`));
       }
       if (!lanIpPinned) {
         lanMonitor = startLanIpMonitor({
@@ -1341,11 +1521,11 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict) {
       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);
@@ -1374,7 +1554,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);
@@ -1382,7 +1562,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.`));
@@ -1417,10 +1597,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 {
@@ -1431,9 +1611,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;
@@ -1445,13 +1625,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."));
@@ -1523,11 +1703,30 @@ portless
   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) {
+    const persisted = readPersistedProxyState();
+    const startConfig = { ...desiredConfig };
+    let startPort;
+    if (persisted) {
+      if (!explicit.useHttps && persisted.tls !== desiredConfig.useHttps) {
+        startConfig.useHttps = persisted.tls;
+      }
+      if (!explicit.tld && persisted.tld !== desiredConfig.tld) {
+        startConfig.tld = persisted.tld;
+      }
+      if (!explicit.lanMode && persisted.lanMode !== desiredConfig.lanMode) {
+        startConfig.lanMode = persisted.lanMode;
+      }
+      const envPort = getDefaultPort(startConfig.useHttps);
+      if (persisted.port !== envPort) {
+        startPort = persisted.port;
+      }
+    }
+    const effectivePort = startPort ?? getDefaultPort(startConfig.useHttps);
+    const needsSudo = !isWindows && effectivePort < PRIVILEGED_PORT_THRESHOLD;
+    const manualStartCommand = formatProxyStartCommand(effectivePort, startConfig);
+    const fallbackStartCommand = formatProxyStartCommand(FALLBACK_PROXY_PORT, startConfig);
+    const isInteractive = !!process.stdin.isTTY && !process.env.CI;
+    if (needsSudo && !isInteractive) {
       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(`  ${manualStartCommand}`));
@@ -1539,7 +1738,7 @@ portless
       console.error(colors_default.cyan(`  ${fallbackStartCommand}`));
       process.exit(1);
     }
-    if (needsSudo && process.stdin.isTTY) {
+    if (needsSudo) {
       const answer = await prompt(colors_default.yellow("Proxy not running. Start it? [Y/n/skip] "));
       if (answer === "n" || answer === "no") {
         console.log(colors_default.gray("Cancelled."));
@@ -1551,16 +1750,26 @@ portless
         return;
       }
     }
-    console.log(colors_default.yellow("Starting proxy..."));
+    if (persisted && startPort !== void 0) {
+      console.log(
+        colors_default.yellow(
+          `Starting proxy with previous configuration (port ${startPort}, ${startConfig.useHttps ? "HTTPS" : "HTTP"})...`
+        )
+      );
+    } else {
+      console.log(colors_default.yellow("Starting proxy..."));
+    }
     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
+      useHttps: startConfig.useHttps,
+      customCertPath: startConfig.customCertPath,
+      customKeyPath: startConfig.customKeyPath,
+      lanMode: startConfig.lanMode,
+      lanIp: startConfig.lanIpExplicit ? startConfig.lanIp : null,
+      lanIpExplicit: startConfig.lanIpExplicit,
+      tld: startConfig.tld,
+      useWildcard: startConfig.useWildcard,
+      includePort: startPort !== void 0,
+      proxyPort: startPort
     });
     const startArgs = [getEntryScript(), "proxy", "start", ...proxyStartConfig.args];
     const result = spawnSync2(process.execPath, startArgs, {
@@ -1580,11 +1789,11 @@ portless
     }
     if (!discovered) {
       console.error(colors_default.red("Failed to start proxy."));
-      const fallbackDir = resolveStateDir(getDefaultPort(desiredConfig.useHttps));
-      const logPath = path3.join(fallbackDir, "proxy.log");
+      const fallbackDir = resolveStateDir(effectivePort);
+      const logPath = path4.join(fallbackDir, "proxy.log");
       console.error(colors_default.blue("Try starting it manually:"));
       console.error(colors_default.cyan(`  ${manualStartCommand}`));
-      if (fs3.existsSync(logPath)) {
+      if (fs4.existsSync(logPath)) {
         console.error(colors_default.gray(`Logs: ${logPath}`));
       }
       process.exit(1);
@@ -1657,7 +1866,7 @@ portless
     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 basename3 = path4.basename(commandArgs[0]);
   const isExpo = basename3 === "expo";
   const isExpoLan = isExpo && (lanMode || isLanEnvEnabled());
   const hostBind = isExpoLan ? void 0 : "127.0.0.1";
@@ -1665,9 +1874,17 @@ portless
     process.env.PORTLESS_LAN = "1";
   }
   injectFrameworkFlags(commandArgs, port);
+  const caEnv = {};
+  if (tls2 && !process.env.NODE_EXTRA_CA_CERTS) {
+    const caPath = path4.join(stateDir, "ca.pem");
+    if (fs4.existsSync(caPath)) {
+      caEnv.NODE_EXTRA_CA_CERTS = caPath;
+    }
+  }
+  const caFragment = caEnv.NODE_EXTRA_CA_CERTS ? ` NODE_EXTRA_CA_CERTS="${caEnv.NODE_EXTRA_CA_CERTS}"` : "";
   console.log(
     chalk.gray(
-      `Running: PORT=${port}${hostBind ? ` HOST=${hostBind}` : ""} PORTLESS_URL=${finalUrl} ${commandArgs.join(" ")}
+      `Running: PORT=${port}${hostBind ? ` HOST=${hostBind}` : ""} PORTLESS_URL=${finalUrl}${caFragment} ${commandArgs.join(" ")}
 `
     )
   );
@@ -1681,7 +1898,8 @@ portless
       // 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" } : {}
+      ...lanMode ? { PORTLESS_LAN: "1" } : {},
+      ...caEnv
     },
     onCleanup: () => {
       try {
@@ -1839,6 +2057,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}
 
@@ -1882,7 +2101,8 @@ ${colors_default.bold("LAN mode:")}
   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.
+  All proxy settings are persisted and reused on auto-start unless
+  overridden by explicit flags or 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.
@@ -1916,7 +2136,7 @@ ${colors_default.bold("Environment variables:")}
   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
 
@@ -1925,12 +2145,13 @@ ${colors_default.bold("Child process environment:")}
   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
+  NODE_EXTRA_CA_CERTS           Path to the portless CA (set when HTTPS is active)
 
 ${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")}
@@ -1939,20 +2160,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.10.0");
+  console.log("0.10.2");
   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) {
@@ -1988,6 +2209,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, {
@@ -2122,8 +2427,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);
   }
@@ -2260,6 +2565,7 @@ ${colors_default.bold("LAN mode (--lan):")}
     process.exit(isProxyHelp || !args[1] ? 0 : 1);
   }
   const isForeground = args.includes("--foreground");
+  const skipTrust = args.includes("--skip-trust");
   const hasHttpsFlag = args.includes("--https");
   const hasNoTls = args.includes("--no-tls") || isHttpsEnvDisabled();
   const wantHttps = !hasNoTls;
@@ -2491,8 +2797,8 @@ ${colors_default.bold("LAN mode (--lan):")}
           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}`));
           }
         }
@@ -2531,8 +2837,8 @@ ${colors_default.bold("LAN mode (--lan):")}
     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-----")) {
@@ -2559,7 +2865,7 @@ ${colors_default.bold("LAN mode (--lan):")}
       if (certs.caGenerated) {
         console.log(colors_default.green("Generated local CA certificate."));
       }
-      if (!isCATrusted(stateDir)) {
+      if (!skipTrust && !isCATrusted(stateDir)) {
         console.log(colors_default.yellow("Adding CA to system trust store..."));
         const trustResult = trustCA(stateDir);
         if (trustResult.trusted) {
@@ -2577,9 +2883,9 @@ ${colors_default.bold("LAN mode (--lan):")}
           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,
@@ -2594,11 +2900,11 @@ ${colors_default.bold("LAN mode (--lan):")}
     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);
@@ -2617,7 +2923,8 @@ ${colors_default.bold("LAN mode (--lan):")}
         useWildcard: desiredWildcard,
         foreground: true,
         includePort: true,
-        proxyPort
+        proxyPort,
+        skipTrust: true
       }).args
     ];
     const child = spawn2(process.execPath, daemonArgs, {
@@ -2628,13 +2935,13 @@ ${colors_default.bold("LAN mode (--lan):")}
     });
     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);
@@ -2795,7 +3102,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."));
@@ -2817,6 +3124,10 @@ async function main() {
       await handleTrust();
       return;
     }
+    if (args[0] === "clean") {
+      await handleClean(args);
+      return;
+    }
     if (args[0] === "list") {
       await handleList();
       return;

package/dist/index.d.ts

@@ -157,6 +157,11 @@ declare function removeBlock(content: string): string;
  * Build a portless-managed block for the given hostnames.
  */
 declare function buildBlock(hostnames: string[]): string;
+/**
+ * Whether the proxy should write route hostnames to the hosts file.
+ * Disabled only when `PORTLESS_SYNC_HOSTS` is `0` or `false` (opt-out).
+ */
+declare function shouldAutoSyncHosts(syncVal: string | undefined): boolean;
 /**
  * Sync /etc/hosts to include entries for all given hostnames.
  * Replaces any existing portless-managed block. Requires root access.
@@ -178,4 +183,4 @@ declare function getManagedHostnames(): string[];
  */
 declare function checkHostResolution(hostname: string): Promise<boolean>;
 
-export { DIR_MODE, FILE_MODE, PORTLESS_HEADER, type ProxyServer, type ProxyServerOptions, RouteConflictError, type RouteInfo, type RouteMapping, RouteStore, SYSTEM_DIR_MODE, SYSTEM_FILE_MODE, buildBlock, checkHostResolution, cleanHostsFile, createHttpRedirectServer, createProxyServer, escapeHtml, extractManagedBlock, fixOwnership, formatUrl, getManagedHostnames, isErrnoException, parseHostname, removeBlock, syncHostsFile };
+export { DIR_MODE, FILE_MODE, PORTLESS_HEADER, type ProxyServer, type ProxyServerOptions, RouteConflictError, type RouteInfo, type RouteMapping, RouteStore, SYSTEM_DIR_MODE, SYSTEM_FILE_MODE, buildBlock, checkHostResolution, cleanHostsFile, createHttpRedirectServer, createProxyServer, escapeHtml, extractManagedBlock, fixOwnership, formatUrl, getManagedHostnames, isErrnoException, parseHostname, removeBlock, shouldAutoSyncHosts, syncHostsFile };

package/dist/index.js

@@ -19,8 +19,9 @@ import {
   isErrnoException,
   parseHostname,
   removeBlock,
+  shouldAutoSyncHosts,
   syncHostsFile
-} from "./chunk-WXEE5QH6.js";
+} from "./chunk-EZJWUTUA.js";
 export {
   DIR_MODE,
   FILE_MODE,
@@ -42,5 +43,6 @@ export {
   isErrnoException,
   parseHostname,
   removeBlock,
+  shouldAutoSyncHosts,
   syncHostsFile
 };

package/package.json

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