portless 0.2.2 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@ Replace port numbers with stable, named .localhost URLs. For humans and agents.
 
 ```diff
 - "dev": "next dev"              # http://localhost:3000
-+ "dev": "portless myapp next dev"  # http://myapp.localhost
++ "dev": "portless myapp next dev"  # http://myapp.localhost:1355
 ```
 
 ## Quick Start
@@ -13,29 +13,29 @@ Replace port numbers with stable, named .localhost URLs. For humans and agents.
 # Install
 npm install -g portless
 
-# Start the proxy (once, requires sudo for port 80)
-sudo portless proxy
+# Start the proxy (once, no sudo needed)
+portless proxy start
 
-# Run your app
+# Run your app (auto-starts the proxy if needed)
 portless myapp next dev
-# → http://myapp.localhost
+# -> http://myapp.localhost:1355
 ```
 
-> When run directly in your terminal, portless can auto-start the proxy for you (prompts for sudo once). Via package scripts, start the proxy manually first.
+> The proxy auto-starts when you run an app. You can also start it explicitly with `portless proxy start`.
 
 ## Why
 
 Local dev with port numbers is fragile:
 
-- **Port conflicts** — two projects default to the same port and you get `EADDRINUSE`
-- **Memorizing ports** — was the API on 3001 or 8080?
-- **Refreshing shows the wrong app** — stop one server, start another on the same port, and your open tab now shows something completely different
-- **Monorepo multiplier** — every problem above scales with each service in the repo
-- **Agents test the wrong port** — AI coding agents guess or hardcode the wrong port, especially in monorepos
-- **Cookie and storage clashes** — cookies set on `localhost` bleed across apps on different ports; localStorage is lost when ports shift
-- **Hardcoded ports in config** — CORS allowlists, OAuth redirect URIs, and `.env` files all break when ports change
-- **Sharing URLs with teammates** — "what port is that on?" becomes a Slack question
-- **Browser history is useless** — your history for `localhost:3000` is a jumble of unrelated projects
+- **Port conflicts** -- two projects default to the same port and you get `EADDRINUSE`
+- **Memorizing ports** -- was the API on 3001 or 8080?
+- **Refreshing shows the wrong app** -- stop one server, start another on the same port, and your open tab now shows something completely different
+- **Monorepo multiplier** -- every problem above scales with each service in the repo
+- **Agents test the wrong port** -- AI coding agents guess or hardcode the wrong port, especially in monorepos
+- **Cookie and storage clashes** -- cookies set on `localhost` bleed across apps on different ports; localStorage is lost when ports shift
+- **Hardcoded ports in config** -- CORS allowlists, OAuth redirect URIs, and `.env` files all break when ports change
+- **Sharing URLs with teammates** -- "what port is that on?" becomes a Slack question
+- **Browser history is useless** -- your history for `localhost:3000` is a jumble of unrelated projects
 
 Portless fixes all of this by giving each dev server a stable, named `.localhost` URL that both humans and agents can rely on.
 
@@ -44,14 +44,14 @@ Portless fixes all of this by giving each dev server a stable, named `.localhost
 ```bash
 # Basic
 portless myapp next dev
-# → http://myapp.localhost
+# -> http://myapp.localhost:1355
 
 # Subdomains
 portless api.myapp pnpm start
-# → http://api.myapp.localhost
+# -> http://api.myapp.localhost:1355
 
 portless docs.myapp next dev
-# → http://docs.myapp.localhost
+# -> http://docs.myapp.localhost:1355
 ```
 
 ### In package.json
@@ -64,32 +64,32 @@ portless docs.myapp next dev
 }
 ```
 
-Start the proxy once (`sudo portless proxy`), then just `pnpm dev`.
+The proxy auto-starts when you run an app. Or start it explicitly: `portless proxy start`.
 
 ## How It Works
 
 ```mermaid
 flowchart TD
-    Browser["Browser\nmyapp.localhost"]
-    Proxy["portless proxy\n(port 80)"]
+    Browser["Browser\nmyapp.localhost:1355"]
+    Proxy["portless proxy\n(port 1355)"]
     App1[":4123\nmyapp"]
     App2[":4567\napi"]
 
-    Browser -->|port 80| Proxy
+    Browser -->|port 1355| Proxy
     Proxy --> App1
     Proxy --> App2
 ```
 
-1. **Start the proxy** -- runs on port 80 by default in the background (requires sudo once)
+1. **Start the proxy** -- auto-starts when you run an app, or start explicitly with `portless proxy start`
 2. **Run apps** -- `portless <name> <command>` assigns a free port and registers with the proxy
-3. **Access via URL** -- `http://<name>.localhost` routes through the proxy to your app
+3. **Access via URL** -- `http://<name>.localhost:1355` routes through the proxy to your app
 
 Apps are assigned a random port (4000-4999) via the `PORT` environment variable. Most frameworks (Next.js, Vite, etc.) respect this automatically.
 
 ## Commands
 
 ```bash
-portless <name> <cmd> [args...]  # Run app at http://<name>.localhost
+portless <name> <cmd> [args...]  # Run app at http://<name>.localhost:1355
 portless list                    # Show active routes
 
 # Disable portless (run command directly)
@@ -97,19 +97,34 @@ PORTLESS=0 pnpm dev              # Bypasses proxy, uses default port
 # Also accepts PORTLESS=skip
 
 # Proxy control
-sudo portless proxy              # Start the proxy (port 80)
-sudo portless proxy --port 8080  # Start the proxy on a custom port
-sudo portless proxy stop         # Stop the proxy
+portless proxy start             # Start the proxy (port 1355, daemon)
+portless proxy start -p 80       # Start on port 80 (requires sudo)
+portless proxy start --foreground  # Start in foreground (for debugging)
+portless proxy stop              # Stop the proxy
 
 # Options
---port <number>                  # Port for the proxy (default: 80)
-                                 # Ports >= 1024 do not require sudo
+-p, --port <number>              # Port for the proxy (default: 1355)
+                                 # Ports < 1024 require sudo
+--foreground                     # Run proxy in foreground instead of daemon
+
+# Environment variables
+PORTLESS_PORT=<number>           # Override the default proxy port
+PORTLESS_STATE_DIR=<path>        # Override the state directory
 
 # Info
 portless --help                  # Show help
 portless --version               # Show version
 ```
 
+## State Directory
+
+Portless stores its state (routes, PID file, port file) in a directory that depends on the proxy port:
+
+- **Port < 1024** (sudo required): `/tmp/portless` -- shared between root and user processes
+- **Port >= 1024** (no sudo): `~/.portless` -- user-scoped, no root involvement
+
+Override with the `PORTLESS_STATE_DIR` environment variable if needed.
+
 ## Requirements
 
 - Node.js 20+

package/dist/{chunk-SE7KL62V.js → chunk-Y5OVKUR4.js}

@@ -1,10 +1,13 @@
 // src/utils.ts
 function isErrnoException(err) {
-  return err instanceof Error && "code" in err;
+  return err instanceof Error && "code" in err && typeof err.code === "string";
 }
 function escapeHtml(str) {
   return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
+function formatUrl(hostname, proxyPort) {
+  return proxyPort === 80 ? `http://${hostname}` : `http://${hostname}:${proxyPort}`;
+}
 function parseHostname(input) {
   let hostname = input.trim().replace(/^https?:\/\//, "").split("/")[0].toLowerCase();
   if (!hostname || hostname === ".localhost") {
@@ -27,23 +30,22 @@ function parseHostname(input) {
 
 // src/proxy.ts
 import * as http from "http";
-import httpProxy from "http-proxy";
+var PORTLESS_HEADER = "X-Portless";
+function buildForwardedHeaders(req) {
+  const headers = {};
+  const remoteAddress = req.socket.remoteAddress || "127.0.0.1";
+  const proto = "http";
+  const hostHeader = req.headers.host || "";
+  headers["x-forwarded-for"] = req.headers["x-forwarded-for"] ? `${req.headers["x-forwarded-for"]}, ${remoteAddress}` : remoteAddress;
+  headers["x-forwarded-proto"] = req.headers["x-forwarded-proto"] || proto;
+  headers["x-forwarded-host"] = req.headers["x-forwarded-host"] || hostHeader;
+  headers["x-forwarded-port"] = req.headers["x-forwarded-port"] || hostHeader.split(":")[1] || "80";
+  return headers;
+}
 function createProxyServer(options) {
-  const { getRoutes, onError = (msg) => console.error(msg) } = options;
-  const proxy = httpProxy.createProxyServer({});
-  proxy.on("error", (err, req, res) => {
-    onError(`Proxy error for ${req.headers.host}: ${err.message}`);
-    if (res && "writeHead" in res) {
-      const serverRes = res;
-      if (!serverRes.headersSent) {
-        const errWithCode = err;
-        const message = errWithCode.code === "ECONNREFUSED" ? "Bad Gateway: the target app is not responding. It may have crashed." : "Bad Gateway: the target app may not be running.";
-        serverRes.writeHead(502, { "Content-Type": "text/plain" });
-        serverRes.end(message);
-      }
-    }
-  });
+  const { getRoutes, proxyPort, onError = (msg) => console.error(msg) } = options;
   const handleRequest = (req, res) => {
+    res.setHeader(PORTLESS_HEADER, "1");
     const routes = getRoutes();
     const host = (req.headers.host || "").split(":")[0];
     if (!host) {
@@ -64,7 +66,7 @@ function createProxyServer(options) {
             ${routes.length > 0 ? `
               <h2>Active apps:</h2>
               <ul>
-                ${routes.map((r) => `<li><a href="http://${escapeHtml(r.hostname)}">${escapeHtml(r.hostname)}</a> - localhost:${escapeHtml(String(r.port))}</li>`).join("")}
+                ${routes.map((r) => `<li><a href="${escapeHtml(formatUrl(r.hostname, proxyPort))}">${escapeHtml(r.hostname)}</a> - localhost:${escapeHtml(String(r.port))}</li>`).join("")}
               </ul>
             ` : "<p><em>No apps running.</em></p>"}
             <p>Start an app with: <code>portless ${safeHost.replace(".localhost", "")} your-command</code></p>
@@ -73,10 +75,44 @@ function createProxyServer(options) {
       `);
       return;
     }
-    proxy.web(req, res, {
-      target: `http://127.0.0.1:${route.port}`,
-      xfwd: true
+    const forwardedHeaders = buildForwardedHeaders(req);
+    const proxyReqHeaders = { ...req.headers };
+    for (const [key, value] of Object.entries(forwardedHeaders)) {
+      proxyReqHeaders[key] = value;
+    }
+    const proxyReq = http.request(
+      {
+        hostname: "127.0.0.1",
+        port: route.port,
+        path: req.url,
+        method: req.method,
+        headers: proxyReqHeaders
+      },
+      (proxyRes) => {
+        res.writeHead(proxyRes.statusCode || 502, proxyRes.headers);
+        proxyRes.pipe(res);
+      }
+    );
+    proxyReq.on("error", (err) => {
+      onError(`Proxy error for ${req.headers.host}: ${err.message}`);
+      if (!res.headersSent) {
+        const errWithCode = err;
+        const message = errWithCode.code === "ECONNREFUSED" ? "Bad Gateway: the target app is not responding. It may have crashed." : "Bad Gateway: the target app may not be running.";
+        res.writeHead(502, { "Content-Type": "text/plain" });
+        res.end(message);
+      }
+    });
+    res.on("close", () => {
+      if (!proxyReq.destroyed) {
+        proxyReq.destroy();
+      }
     });
+    req.on("error", () => {
+      if (!proxyReq.destroyed) {
+        proxyReq.destroy();
+      }
+    });
+    req.pipe(proxyReq);
   };
   const handleUpgrade = (req, socket, head) => {
     const routes = getRoutes();
@@ -86,10 +122,56 @@ function createProxyServer(options) {
       socket.destroy();
       return;
     }
-    proxy.ws(req, socket, head, {
-      target: `http://127.0.0.1:${route.port}`,
-      xfwd: true
+    const forwardedHeaders = buildForwardedHeaders(req);
+    const proxyReqHeaders = { ...req.headers };
+    for (const [key, value] of Object.entries(forwardedHeaders)) {
+      proxyReqHeaders[key] = value;
+    }
+    const proxyReq = http.request({
+      hostname: "127.0.0.1",
+      port: route.port,
+      path: req.url,
+      method: req.method,
+      headers: proxyReqHeaders
     });
+    proxyReq.on("upgrade", (proxyRes, proxySocket, proxyHead) => {
+      let response = `HTTP/1.1 101 Switching Protocols\r
+`;
+      for (let i = 0; i < proxyRes.rawHeaders.length; i += 2) {
+        response += `${proxyRes.rawHeaders[i]}: ${proxyRes.rawHeaders[i + 1]}\r
+`;
+      }
+      response += "\r\n";
+      socket.write(response);
+      if (proxyHead.length > 0) {
+        socket.write(proxyHead);
+      }
+      proxySocket.pipe(socket);
+      socket.pipe(proxySocket);
+      proxySocket.on("error", () => socket.destroy());
+      socket.on("error", () => proxySocket.destroy());
+    });
+    proxyReq.on("error", (err) => {
+      onError(`WebSocket proxy error for ${req.headers.host}: ${err.message}`);
+      socket.destroy();
+    });
+    proxyReq.on("response", (res) => {
+      if (!socket.destroyed) {
+        let response = `HTTP/1.1 ${res.statusCode} ${res.statusMessage}\r
+`;
+        for (let i = 0; i < res.rawHeaders.length; i += 2) {
+          response += `${res.rawHeaders[i]}: ${res.rawHeaders[i + 1]}\r
+`;
+        }
+        response += "\r\n";
+        socket.write(response);
+        res.pipe(socket);
+      }
+    });
+    if (head.length > 0) {
+      proxyReq.write(head);
+    }
+    proxyReq.end();
   };
   const httpServer = http.createServer(handleRequest);
   httpServer.on("upgrade", handleUpgrade);
@@ -99,6 +181,11 @@ function createProxyServer(options) {
 // src/routes.ts
 import * as fs from "fs";
 import * as path from "path";
+var STALE_LOCK_THRESHOLD_MS = 1e4;
+var LOCK_MAX_RETRIES = 20;
+var LOCK_RETRY_DELAY_MS = 50;
+var FILE_MODE = 420;
+var DIR_MODE = 493;
 function isValidRoute(value) {
   return typeof value === "object" && value !== null && typeof value.hostname === "string" && typeof value.port === "number" && typeof value.pid === "number";
 }
@@ -107,20 +194,22 @@ var RouteStore = class _RouteStore {
   routesPath;
   lockPath;
   pidPath;
+  portFilePath;
   onWarning;
   constructor(dir, options) {
     this.dir = dir;
     this.routesPath = path.join(dir, "routes.json");
     this.lockPath = path.join(dir, "routes.lock");
     this.pidPath = path.join(dir, "proxy.pid");
+    this.portFilePath = path.join(dir, "proxy.port");
     this.onWarning = options?.onWarning;
   }
   ensureDir() {
     if (!fs.existsSync(this.dir)) {
-      fs.mkdirSync(this.dir, { recursive: true, mode: 493 });
+      fs.mkdirSync(this.dir, { recursive: true, mode: DIR_MODE });
     }
     try {
-      fs.chmodSync(this.dir, 493);
+      fs.chmodSync(this.dir, DIR_MODE);
     } catch {
     }
   }
@@ -132,7 +221,7 @@ var RouteStore = class _RouteStore {
   syncSleep(ms) {
     Atomics.wait(_RouteStore.sleepBuffer, 0, 0, ms);
   }
-  acquireLock(maxRetries = 20, retryDelayMs = 50) {
+  acquireLock(maxRetries = LOCK_MAX_RETRIES, retryDelayMs = LOCK_RETRY_DELAY_MS) {
     for (let i = 0; i < maxRetries; i++) {
       try {
         fs.mkdirSync(this.lockPath);
@@ -141,7 +230,7 @@ var RouteStore = class _RouteStore {
         if (isErrnoException(err) && err.code === "EEXIST") {
           try {
             const stat = fs.statSync(this.lockPath);
-            if (Date.now() - stat.mtimeMs > 1e4) {
+            if (Date.now() - stat.mtimeMs > STALE_LOCK_THRESHOLD_MS) {
               fs.rmSync(this.lockPath, { recursive: true });
               continue;
             }
@@ -198,7 +287,7 @@ var RouteStore = class _RouteStore {
       const alive = routes.filter((r) => this.isProcessAlive(r.pid));
       if (persistCleanup && alive.length !== routes.length) {
         try {
-          fs.writeFileSync(this.routesPath, JSON.stringify(alive, null, 2), { mode: 420 });
+          fs.writeFileSync(this.routesPath, JSON.stringify(alive, null, 2), { mode: FILE_MODE });
         } catch {
         }
       }
@@ -208,8 +297,7 @@ var RouteStore = class _RouteStore {
     }
   }
   saveRoutes(routes) {
-    this.ensureDir();
-    fs.writeFileSync(this.routesPath, JSON.stringify(routes, null, 2), { mode: 420 });
+    fs.writeFileSync(this.routesPath, JSON.stringify(routes, null, 2), { mode: FILE_MODE });
   }
   addRoute(hostname, port, pid) {
     this.ensureDir();
@@ -241,7 +329,11 @@ var RouteStore = class _RouteStore {
 export {
   isErrnoException,
   escapeHtml,
+  formatUrl,
   parseHostname,
+  PORTLESS_HEADER,
   createProxyServer,
+  FILE_MODE,
+  DIR_MODE,
   RouteStore
 };

package/dist/cli.js

@@ -1,21 +1,89 @@
 #!/usr/bin/env node
 import {
+  FILE_MODE,
+  PORTLESS_HEADER,
   RouteStore,
   createProxyServer,
+  formatUrl,
   isErrnoException,
   parseHostname
-} from "./chunk-SE7KL62V.js";
+} from "./chunk-Y5OVKUR4.js";
 
 // src/cli.ts
 import chalk from "chalk";
-import * as fs from "fs";
-import * as path from "path";
-import * as readline from "readline";
-import { execSync, spawn, spawnSync } from "child_process";
+import * as fs2 from "fs";
+import * as path2 from "path";
+import { spawn as spawn2, spawnSync } from "child_process";
 
 // src/cli-utils.ts
+import * as fs from "fs";
+import * as http from "http";
 import * as net from "net";
-async function findFreePort(minPort = 4e3, maxPort = 4999) {
+import * as os from "os";
+import * as path from "path";
+import * as readline from "readline";
+import { execSync, spawn } from "child_process";
+var DEFAULT_PROXY_PORT = 1355;
+var PRIVILEGED_PORT_THRESHOLD = 1024;
+var SYSTEM_STATE_DIR = "/tmp/portless";
+var USER_STATE_DIR = path.join(os.homedir(), ".portless");
+var MIN_APP_PORT = 4e3;
+var MAX_APP_PORT = 4999;
+var RANDOM_PORT_ATTEMPTS = 50;
+var SOCKET_TIMEOUT_MS = 500;
+var LSOF_TIMEOUT_MS = 5e3;
+var WAIT_FOR_PROXY_MAX_ATTEMPTS = 20;
+var WAIT_FOR_PROXY_INTERVAL_MS = 250;
+var SIGNAL_CODES = {
+  SIGHUP: 1,
+  SIGINT: 2,
+  SIGQUIT: 3,
+  SIGABRT: 6,
+  SIGKILL: 9,
+  SIGTERM: 15
+};
+function getDefaultPort() {
+  const envPort = process.env.PORTLESS_PORT;
+  if (envPort) {
+    const port = parseInt(envPort, 10);
+    if (!isNaN(port) && port >= 1 && port <= 65535) return port;
+  }
+  return DEFAULT_PROXY_PORT;
+}
+function resolveStateDir(port) {
+  if (process.env.PORTLESS_STATE_DIR) return process.env.PORTLESS_STATE_DIR;
+  return port < PRIVILEGED_PORT_THRESHOLD ? SYSTEM_STATE_DIR : USER_STATE_DIR;
+}
+function readPortFromDir(dir) {
+  try {
+    const raw = fs.readFileSync(path.join(dir, "proxy.port"), "utf-8").trim();
+    const port = parseInt(raw, 10);
+    return isNaN(port) ? null : port;
+  } catch {
+    return null;
+  }
+}
+async function discoverState() {
+  if (process.env.PORTLESS_STATE_DIR) {
+    const dir = process.env.PORTLESS_STATE_DIR;
+    const port = readPortFromDir(dir) ?? getDefaultPort();
+    return { dir, port };
+  }
+  const userPort = readPortFromDir(USER_STATE_DIR);
+  if (userPort !== null && await isProxyRunning(userPort)) {
+    return { dir: USER_STATE_DIR, port: userPort };
+  }
+  const systemPort = readPortFromDir(SYSTEM_STATE_DIR);
+  if (systemPort !== null && await isProxyRunning(systemPort)) {
+    return { dir: SYSTEM_STATE_DIR, port: systemPort };
+  }
+  const defaultPort = getDefaultPort();
+  return { dir: resolveStateDir(defaultPort), port: defaultPort };
+}
+async function findFreePort(minPort = MIN_APP_PORT, maxPort = MAX_APP_PORT) {
+  if (minPort > maxPort) {
+    throw new Error(`minPort (${minPort}) must be <= maxPort (${maxPort})`);
+  }
   const tryPort = (port) => {
     return new Promise((resolve) => {
       const server = net.createServer();
@@ -25,7 +93,7 @@ async function findFreePort(minPort = 4e3, maxPort = 4999) {
       server.on("error", () => resolve(false));
     });
   };
-  for (let i = 0; i < 50; i++) {
+  for (let i = 0; i < RANDOM_PORT_ATTEMPTS; i++) {
     const port = minPort + Math.floor(Math.random() * (maxPort - minPort + 1));
     if (await tryPort(port)) {
       return port;
@@ -38,58 +106,34 @@ async function findFreePort(minPort = 4e3, maxPort = 4999) {
   }
   throw new Error(`No free port found in range ${minPort}-${maxPort}`);
 }
-function isProxyRunning(port = 80) {
+function isProxyRunning(port) {
   return new Promise((resolve) => {
-    const socket = new net.Socket();
-    socket.setTimeout(500);
-    socket.on("connect", () => {
-      socket.destroy();
-      resolve(true);
-    });
-    socket.on("error", () => resolve(false));
-    socket.on("timeout", () => {
-      socket.destroy();
+    const req = http.request(
+      {
+        hostname: "127.0.0.1",
+        port,
+        path: "/",
+        method: "HEAD",
+        timeout: SOCKET_TIMEOUT_MS
+      },
+      (res) => {
+        res.resume();
+        resolve(res.headers[PORTLESS_HEADER.toLowerCase()] === "1");
+      }
+    );
+    req.on("error", () => resolve(false));
+    req.on("timeout", () => {
+      req.destroy();
       resolve(false);
     });
-    socket.connect(port, "127.0.0.1");
+    req.end();
   });
 }
-
-// src/cli.ts
-var SIGNAL_CODES = { SIGINT: 2, SIGTERM: 15 };
-function prompt(question) {
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout
-  });
-  return new Promise((resolve) => {
-    rl.on("close", () => resolve(""));
-    rl.question(question, (answer) => {
-      rl.close();
-      resolve(answer.trim().toLowerCase());
-    });
-  });
-}
-var PORTLESS_DIR = "/tmp/portless";
-var PROXY_PORT_PATH = path.join(PORTLESS_DIR, "proxy.port");
-var DEFAULT_PROXY_PORT = 80;
-var store = new RouteStore(PORTLESS_DIR, {
-  onWarning: (msg) => console.warn(chalk.yellow(msg))
-});
-function readProxyPort() {
-  try {
-    const raw = fs.readFileSync(PROXY_PORT_PATH, "utf-8").trim();
-    const port = parseInt(raw, 10);
-    return isNaN(port) ? DEFAULT_PROXY_PORT : port;
-  } catch {
-    return DEFAULT_PROXY_PORT;
-  }
-}
 function findPidOnPort(port) {
   try {
     const output = execSync(`lsof -ti tcp:${port} -sTCP:LISTEN`, {
       encoding: "utf-8",
-      timeout: 5e3
+      timeout: LSOF_TIMEOUT_MS
     });
     const pid = parseInt(output.trim().split("\n")[0], 10);
     return isNaN(pid) ? null : pid;
@@ -97,8 +141,7 @@ function findPidOnPort(port) {
     return null;
   }
 }
-async function waitForProxy(proxyPort, maxAttempts = 20, intervalMs = 250) {
-  const port = proxyPort ?? readProxyPort();
+async function waitForProxy(port, maxAttempts = WAIT_FOR_PROXY_MAX_ATTEMPTS, intervalMs = WAIT_FOR_PROXY_INTERVAL_MS) {
   for (let i = 0; i < maxAttempts; i++) {
     await new Promise((resolve) => setTimeout(resolve, intervalMs));
     if (await isProxyRunning(port)) {
@@ -113,45 +156,75 @@ function spawnCommand(commandArgs, options) {
     env: options?.env
   });
   let exiting = false;
+  const cleanup = () => {
+    process.removeListener("SIGINT", onSigInt);
+    process.removeListener("SIGTERM", onSigTerm);
+    options?.onCleanup?.();
+  };
   const handleSignal = (signal) => {
     if (exiting) return;
     exiting = true;
     child.kill(signal);
-    options?.onCleanup?.();
+    cleanup();
     process.exit(128 + (SIGNAL_CODES[signal] || 15));
   };
-  process.on("SIGINT", () => handleSignal("SIGINT"));
-  process.on("SIGTERM", () => handleSignal("SIGTERM"));
+  const onSigInt = () => handleSignal("SIGINT");
+  const onSigTerm = () => handleSignal("SIGTERM");
+  process.on("SIGINT", onSigInt);
+  process.on("SIGTERM", onSigTerm);
   child.on("error", (err) => {
     if (exiting) return;
     exiting = true;
-    console.error(chalk.red(`Failed to run command: ${err.message}`));
-    options?.onCleanup?.();
+    console.error(`Failed to run command: ${err.message}`);
+    if (err.code === "ENOENT") {
+      console.error(`Is "${commandArgs[0]}" installed and in your PATH?`);
+    }
+    cleanup();
     process.exit(1);
   });
   child.on("exit", (code, signal) => {
     if (exiting) return;
     exiting = true;
-    options?.onCleanup?.();
+    cleanup();
     if (signal) {
-      process.exit(128 + (SIGNAL_CODES[signal] || 1));
+      process.exit(128 + (SIGNAL_CODES[signal] || 15));
     }
     process.exit(code ?? 1);
   });
 }
-function startProxyServer(proxyPort) {
+function prompt(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  return new Promise((resolve) => {
+    rl.on("close", () => resolve(""));
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+
+// src/cli.ts
+var DEBOUNCE_MS = 100;
+var POLL_INTERVAL_MS = 3e3;
+var EXIT_TIMEOUT_MS = 2e3;
+var SUDO_SPAWN_TIMEOUT_MS = 3e4;
+function startProxyServer(store, proxyPort) {
   store.ensureDir();
   const routesPath = store.getRoutesPath();
-  if (!fs.existsSync(routesPath)) {
-    fs.writeFileSync(routesPath, "[]", { mode: 420 });
+  if (!fs2.existsSync(routesPath)) {
+    fs2.writeFileSync(routesPath, "[]", { mode: FILE_MODE });
   }
   try {
-    fs.chmodSync(routesPath, 420);
+    fs2.chmodSync(routesPath, FILE_MODE);
   } catch {
   }
   let cachedRoutes = store.loadRoutes();
   let debounceTimer = null;
   let watcher = null;
+  let pollingInterval = null;
   const reloadRoutes = () => {
     try {
       cachedRoutes = store.loadRoutes();
@@ -159,60 +232,72 @@ function startProxyServer(proxyPort) {
     }
   };
   try {
-    watcher = fs.watch(routesPath, () => {
+    watcher = fs2.watch(routesPath, () => {
       if (debounceTimer) clearTimeout(debounceTimer);
-      debounceTimer = setTimeout(reloadRoutes, 100);
+      debounceTimer = setTimeout(reloadRoutes, DEBOUNCE_MS);
     });
   } catch {
     console.warn(chalk.yellow("fs.watch unavailable; falling back to polling for route changes"));
-    setInterval(reloadRoutes, 3e3);
+    pollingInterval = setInterval(reloadRoutes, POLL_INTERVAL_MS);
   }
   const server = createProxyServer({
     getRoutes: () => cachedRoutes,
+    proxyPort,
     onError: (msg) => console.error(chalk.red(msg))
   });
   server.on("error", (err) => {
     if (err.code === "EADDRINUSE") {
-      console.error(chalk.red(`Port ${proxyPort} is already in use`));
+      console.error(chalk.red(`Port ${proxyPort} is already in use.`));
+      console.error(chalk.blue("Stop the existing proxy first:"));
+      console.error(chalk.cyan("  portless proxy stop"));
+      console.error(chalk.blue("Or check what is using the port:"));
+      console.error(chalk.cyan(`  lsof -ti tcp:${proxyPort}`));
     } else if (err.code === "EACCES") {
-      console.error(chalk.red("Permission denied. Use: sudo portless proxy"));
+      console.error(chalk.red(`Permission denied for port ${proxyPort}.`));
+      console.error(chalk.blue("Either run with sudo:"));
+      console.error(chalk.cyan("  sudo portless proxy start -p 80"));
+      console.error(chalk.blue("Or use a non-privileged port (no sudo needed):"));
+      console.error(chalk.cyan("  portless proxy start"));
     } else {
       console.error(chalk.red(`Proxy error: ${err.message}`));
     }
     process.exit(1);
   });
   server.listen(proxyPort, () => {
-    fs.writeFileSync(store.pidPath, process.pid.toString(), { mode: 420 });
-    fs.writeFileSync(PROXY_PORT_PATH, proxyPort.toString(), { mode: 420 });
+    fs2.writeFileSync(store.pidPath, process.pid.toString(), { mode: FILE_MODE });
+    fs2.writeFileSync(store.portFilePath, proxyPort.toString(), { mode: FILE_MODE });
     console.log(chalk.green(`HTTP proxy listening on port ${proxyPort}`));
   });
   let exiting = false;
   const cleanup = () => {
     if (exiting) return;
     exiting = true;
+    if (debounceTimer) clearTimeout(debounceTimer);
+    if (pollingInterval) clearInterval(pollingInterval);
     if (watcher) {
       watcher.close();
     }
     try {
-      fs.unlinkSync(store.pidPath);
+      fs2.unlinkSync(store.pidPath);
     } catch {
     }
     try {
-      fs.unlinkSync(PROXY_PORT_PATH);
+      fs2.unlinkSync(store.portFilePath);
     } catch {
     }
     server.close(() => process.exit(0));
-    setTimeout(() => process.exit(0), 2e3).unref();
+    setTimeout(() => process.exit(0), EXIT_TIMEOUT_MS).unref();
   };
   process.on("SIGINT", cleanup);
   process.on("SIGTERM", cleanup);
   console.log(chalk.cyan("\nProxy is running. Press Ctrl+C to stop.\n"));
   console.log(chalk.gray(`Routes file: ${store.getRoutesPath()}`));
 }
-async function stopProxy() {
+async function stopProxy(store, proxyPort) {
   const pidPath = store.pidPath;
-  const proxyPort = readProxyPort();
-  if (!fs.existsSync(pidPath)) {
+  const needsSudo = proxyPort < PRIVILEGED_PORT_THRESHOLD;
+  const sudoHint = needsSudo ? "sudo " : "";
+  if (!fs2.existsSync(pidPath)) {
     if (await isProxyRunning(proxyPort)) {
       console.log(chalk.yellow(`PID file is missing but port ${proxyPort} is still in use.`));
       const pid = findPidOnPort(proxyPort);
@@ -220,25 +305,30 @@ async function stopProxy() {
         try {
           process.kill(pid, "SIGTERM");
           try {
-            fs.unlinkSync(PROXY_PORT_PATH);
+            fs2.unlinkSync(store.portFilePath);
           } catch {
           }
           console.log(chalk.green(`Killed process ${pid}. Proxy stopped.`));
         } catch (err) {
           if (isErrnoException(err) && err.code === "EPERM") {
-            console.error(chalk.red("Permission denied. The proxy runs as root."));
-            console.log(chalk.blue("Use: sudo portless proxy stop"));
+            console.error(chalk.red("Permission denied. The proxy was started with sudo."));
+            console.error(chalk.blue("Stop it with:"));
+            console.error(chalk.cyan("  sudo portless proxy stop"));
           } else {
             const message = err instanceof Error ? err.message : String(err);
-            console.error(chalk.red("Failed to stop proxy:"), message);
+            console.error(chalk.red(`Failed to stop proxy: ${message}`));
+            console.error(chalk.blue("Check if the process is still running:"));
+            console.error(chalk.cyan(`  lsof -ti tcp:${proxyPort}`));
           }
         }
       } else if (process.getuid?.() !== 0) {
-        console.error(chalk.red("Permission denied. The proxy likely runs as root."));
-        console.log(chalk.blue("Use: sudo portless proxy stop"));
+        console.error(chalk.red("Cannot identify the process. It may be running as root."));
+        console.error(chalk.blue("Try stopping with sudo:"));
+        console.error(chalk.cyan("  sudo portless proxy stop"));
       } else {
         console.error(chalk.red(`Could not identify the process on port ${proxyPort}.`));
-        console.log(chalk.blue(`Try: sudo kill "$(lsof -ti tcp:${proxyPort})"`));
+        console.error(chalk.blue("Try manually:"));
+        console.error(chalk.cyan(`  sudo kill "$(lsof -ti tcp:${proxyPort})"`));
       }
     } else {
       console.log(chalk.yellow("Proxy is not running."));
@@ -246,17 +336,21 @@ async function stopProxy() {
     return;
   }
   try {
-    const pid = parseInt(fs.readFileSync(pidPath, "utf-8"), 10);
+    const pid = parseInt(fs2.readFileSync(pidPath, "utf-8"), 10);
     if (isNaN(pid)) {
       console.error(chalk.red("Corrupted PID file. Removing it."));
-      fs.unlinkSync(pidPath);
+      fs2.unlinkSync(pidPath);
       return;
     }
     try {
       process.kill(pid, 0);
     } catch {
-      console.log(chalk.yellow("Proxy process is no longer running. Cleaning up."));
-      fs.unlinkSync(pidPath);
+      console.log(chalk.yellow("Proxy process is no longer running. Cleaning up stale files."));
+      fs2.unlinkSync(pidPath);
+      try {
+        fs2.unlinkSync(store.portFilePath);
+      } catch {
+      }
       return;
     }
     if (!await isProxyRunning(proxyPort)) {
@@ -266,27 +360,30 @@ async function stopProxy() {
         )
       );
       console.log(chalk.yellow("Removing stale PID file."));
-      fs.unlinkSync(pidPath);
+      fs2.unlinkSync(pidPath);
       return;
     }
     process.kill(pid, "SIGTERM");
-    fs.unlinkSync(pidPath);
+    fs2.unlinkSync(pidPath);
     try {
-      fs.unlinkSync(PROXY_PORT_PATH);
+      fs2.unlinkSync(store.portFilePath);
     } catch {
     }
     console.log(chalk.green("Proxy stopped."));
   } catch (err) {
     if (isErrnoException(err) && err.code === "EPERM") {
-      console.error(chalk.red("Permission denied. The proxy runs as root."));
-      console.log(chalk.blue("Use: sudo portless proxy stop"));
+      console.error(chalk.red("Permission denied. The proxy was started with sudo."));
+      console.error(chalk.blue("Stop it with:"));
+      console.error(chalk.cyan(`  ${sudoHint}portless proxy stop`));
     } else {
       const message = err instanceof Error ? err.message : String(err);
-      console.error(chalk.red("Failed to stop proxy:"), message);
+      console.error(chalk.red(`Failed to stop proxy: ${message}`));
+      console.error(chalk.blue("Check if the process is still running:"));
+      console.error(chalk.cyan(`  lsof -ti tcp:${proxyPort}`));
     }
   }
 }
-function listRoutes() {
+function listRoutes(store, proxyPort) {
   const routes = store.loadRoutes();
   if (routes.length === 0) {
     console.log(chalk.yellow("No active routes."));
@@ -295,21 +392,32 @@ function listRoutes() {
   }
   console.log(chalk.blue.bold("\nActive routes:\n"));
   for (const route of routes) {
+    const url = formatUrl(route.hostname, proxyPort);
     console.log(
-      `  ${chalk.cyan(`http://${route.hostname}`)}  ${chalk.gray("->")}  ${chalk.white(`localhost:${route.port}`)}  ${chalk.gray(`(pid ${route.pid})`)}`
+      `  ${chalk.cyan(url)}  ${chalk.gray("->")}  ${chalk.white(`localhost:${route.port}`)}  ${chalk.gray(`(pid ${route.pid})`)}`
     );
   }
   console.log();
 }
-async function runApp(name, commandArgs) {
+async function runApp(store, proxyPort, stateDir, name, commandArgs) {
   const hostname = parseHostname(name);
-  const proxyPort = readProxyPort();
+  const appUrl = formatUrl(hostname, proxyPort);
   console.log(chalk.blue.bold(`
 portless
 `));
   console.log(chalk.gray(`-- ${hostname} (auto-resolves to 127.0.0.1)`));
   if (!await isProxyRunning(proxyPort)) {
-    if (process.stdin.isTTY) {
+    const defaultPort = getDefaultPort();
+    const needsSudo = defaultPort < PRIVILEGED_PORT_THRESHOLD;
+    if (needsSudo) {
+      if (!process.stdin.isTTY) {
+        console.error(chalk.red("Proxy is not running."));
+        console.error(chalk.blue("Start the proxy first (requires sudo for this port):"));
+        console.error(chalk.cyan("  sudo portless proxy start -p 80"));
+        console.error(chalk.blue("Or use the default port (no sudo needed):"));
+        console.error(chalk.cyan("  portless proxy start"));
+        process.exit(1);
+      }
       const answer = await prompt(chalk.yellow("Proxy not running. Start it? [Y/n/skip] "));
       if (answer === "n" || answer === "no") {
         console.log(chalk.gray("Cancelled."));
@@ -321,29 +429,40 @@ portless
         return;
       }
       console.log(chalk.yellow("Starting proxy (requires sudo)..."));
-      const result = spawnSync("sudo", [process.execPath, process.argv[1], "proxy", "--daemon"], {
+      const result = spawnSync("sudo", [process.execPath, process.argv[1], "proxy", "start"], {
         stdio: "inherit",
-        timeout: 3e4
+        timeout: SUDO_SPAWN_TIMEOUT_MS
       });
       if (result.status !== 0) {
-        console.log(chalk.red("\nFailed to start proxy"));
+        console.error(chalk.red("Failed to start proxy."));
+        console.error(chalk.blue("Try starting it manually:"));
+        console.error(chalk.cyan("  sudo portless proxy start"));
         process.exit(1);
       }
-      if (!await waitForProxy()) {
-        console.log(chalk.red("\nProxy failed to start"));
-        const logPath = path.join(PORTLESS_DIR, "proxy.log");
-        if (fs.existsSync(logPath)) {
-          console.log(chalk.gray(`Check logs: ${logPath}`));
-        }
+    } else {
+      console.log(chalk.yellow("Starting proxy..."));
+      const result = spawnSync(process.execPath, [process.argv[1], "proxy", "start"], {
+        stdio: "inherit",
+        timeout: SUDO_SPAWN_TIMEOUT_MS
+      });
+      if (result.status !== 0) {
+        console.error(chalk.red("Failed to start proxy."));
+        console.error(chalk.blue("Try starting it manually:"));
+        console.error(chalk.cyan("  portless proxy start"));
         process.exit(1);
       }
-      console.log(chalk.green("Proxy started in background"));
-    } else {
-      console.log(chalk.red("\nProxy is not running!"));
-      console.log(chalk.blue("\nStart the proxy first (one time):"));
-      console.log(chalk.cyan("  sudo portless proxy\n"));
+    }
+    if (!await waitForProxy(defaultPort)) {
+      console.error(chalk.red("Proxy failed to start (timed out waiting for it to listen)."));
+      const logPath = path2.join(stateDir, "proxy.log");
+      console.error(chalk.blue("Try starting the proxy manually to see the error:"));
+      console.error(chalk.cyan(`  ${needsSudo ? "sudo " : ""}portless proxy start`));
+      if (fs2.existsSync(logPath)) {
+        console.error(chalk.gray(`Logs: ${logPath}`));
+      }
       process.exit(1);
     }
+    console.log(chalk.green("Proxy started in background"));
   } else {
     console.log(chalk.gray("-- Proxy is running"));
   }
@@ -351,7 +470,7 @@ portless
   console.log(chalk.green(`-- Using port ${port}`));
   store.addRoute(hostname, port, process.pid);
   console.log(chalk.cyan.bold(`
-  -> http://${hostname}
+  -> ${appUrl}
 `));
   console.log(chalk.gray(`Running: PORT=${port} ${commandArgs.join(" ")}
 `));
@@ -371,7 +490,8 @@ async function main() {
   const isPnpmDlx = !!process.env.PNPM_SCRIPT_SRC_DIR && !process.env.npm_lifecycle_event;
   if (isNpx || isPnpmDlx) {
     console.error(chalk.red("Error: portless should not be run via npx or pnpm dlx."));
-    console.log(chalk.blue("Install globally: npm install -g portless"));
+    console.error(chalk.blue("Install globally instead:"));
+    console.error(chalk.cyan("  npm install -g portless"));
     process.exit(1);
   }
   const skipPortless = process.env.PORTLESS === "0" || process.env.PORTLESS === "skip";
@@ -391,16 +511,16 @@ ${chalk.bold("Install:")}
   Do NOT add portless as a project dependency.
 
 ${chalk.bold("Usage:")}
-  ${chalk.cyan("sudo portless proxy")}              Start the proxy (run once, keep open)
-  ${chalk.cyan("sudo portless proxy --port 8080")}  Start the proxy on a custom port
-  ${chalk.cyan("sudo portless proxy stop")}         Stop the proxy
+  ${chalk.cyan("portless proxy start")}             Start the proxy (background daemon)
+  ${chalk.cyan("portless proxy start -p 80")}       Start on port 80 (requires sudo)
+  ${chalk.cyan("portless proxy stop")}              Stop the proxy
   ${chalk.cyan("portless <name> <cmd>")}            Run your app through the proxy
   ${chalk.cyan("portless list")}                    Show active routes
 
 ${chalk.bold("Examples:")}
-  sudo portless proxy               # Start proxy in terminal 1
-  portless myapp next dev           # Terminal 2 -> http://myapp.localhost
-  portless api.myapp pnpm start     # Terminal 3 -> http://api.myapp.localhost
+  portless proxy start                # Start proxy on port 1355
+  portless myapp next dev             # -> http://myapp.localhost:1355
+  portless api.myapp pnpm start       # -> http://api.myapp.localhost:1355
 
 ${chalk.bold("In package.json:")}
   {
@@ -410,14 +530,20 @@ ${chalk.bold("In package.json:")}
   }
 
 ${chalk.bold("How it works:")}
-  1. Start the proxy once with sudo (listens on port 80 by default)
-  2. Run your apps - they register automatically  
-  3. Access via http://<name>.localhost
+  1. Start the proxy once (listens on port 1355 by default, no sudo needed)
+  2. Run your apps - they auto-start the proxy and register automatically
+  3. Access via http://<name>.localhost:1355
   4. .localhost domains auto-resolve to 127.0.0.1
 
 ${chalk.bold("Options:")}
-  --port <number>               Port for the proxy to listen on (default: 80)
-                                Ports >= 1024 do not require sudo
+  -p, --port <number>           Port for the proxy to listen on (default: 1355)
+                                Ports < 1024 require sudo
+  --foreground                  Run proxy in foreground (for debugging)
+
+${chalk.bold("Environment variables:")}
+  PORTLESS_PORT=<number>        Override the default proxy port (e.g. in .bashrc)
+  PORTLESS_STATE_DIR=<path>     Override the state directory
+  PORTLESS=0 | PORTLESS=skip    Run command directly without proxy
 
 ${chalk.bold("Skip portless:")}
   PORTLESS=0 pnpm dev           # Runs command directly without proxy
@@ -426,88 +552,134 @@ ${chalk.bold("Skip portless:")}
     process.exit(0);
   }
   if (args[0] === "--version" || args[0] === "-v") {
-    console.log("0.2.2");
+    console.log("0.3.0");
     process.exit(0);
   }
   if (args[0] === "list") {
-    listRoutes();
+    const { dir: dir2, port: port2 } = await discoverState();
+    const store2 = new RouteStore(dir2, {
+      onWarning: (msg) => console.warn(chalk.yellow(msg))
+    });
+    listRoutes(store2, port2);
     return;
   }
   if (args[0] === "proxy") {
     if (args[1] === "stop") {
-      await stopProxy();
+      const { dir: dir2, port: port2 } = await discoverState();
+      const store3 = new RouteStore(dir2, {
+        onWarning: (msg) => console.warn(chalk.yellow(msg))
+      });
+      await stopProxy(store3, port2);
       return;
     }
-    const isDaemon = args.includes("--daemon");
-    let proxyPort = DEFAULT_PROXY_PORT;
-    const portFlagIndex = args.indexOf("--port");
+    if (args[1] !== "start") {
+      console.log(`
+${chalk.bold("Usage: portless proxy <command>")}
+
+  ${chalk.cyan("portless proxy start")}                Start the proxy (daemon)
+  ${chalk.cyan("portless proxy start --foreground")}   Start in foreground (for debugging)
+  ${chalk.cyan("portless proxy start -p 80")}          Start on port 80 (requires sudo)
+  ${chalk.cyan("portless proxy stop")}                 Stop the proxy
+`);
+      process.exit(args[1] ? 1 : 0);
+    }
+    const isForeground = args.includes("--foreground");
+    let proxyPort = getDefaultPort();
+    let portFlagIndex = args.indexOf("--port");
+    if (portFlagIndex === -1) portFlagIndex = args.indexOf("-p");
     if (portFlagIndex !== -1) {
       const portValue = args[portFlagIndex + 1];
       if (!portValue || portValue.startsWith("-")) {
-        console.error(chalk.red("Error: --port requires a port number"));
-        console.log(chalk.blue("Usage: portless proxy --port 8080"));
+        console.error(chalk.red("Error: --port / -p requires a port number."));
+        console.error(chalk.blue("Usage:"));
+        console.error(chalk.cyan("  portless proxy start -p 8080"));
         process.exit(1);
       }
       proxyPort = parseInt(portValue, 10);
       if (isNaN(proxyPort) || proxyPort < 1 || proxyPort > 65535) {
         console.error(chalk.red(`Error: Invalid port number: ${portValue}`));
-        console.log(chalk.blue("Port must be between 1 and 65535"));
+        console.error(chalk.blue("Port must be between 1 and 65535."));
         process.exit(1);
       }
     }
+    const stateDir = resolveStateDir(proxyPort);
+    const store2 = new RouteStore(stateDir, {
+      onWarning: (msg) => console.warn(chalk.yellow(msg))
+    });
     if (await isProxyRunning(proxyPort)) {
-      if (!isDaemon) {
-        console.log(chalk.yellow("Proxy is already running."));
-        console.log(chalk.blue("To restart: portless proxy stop && sudo portless proxy"));
+      if (isForeground) {
+        return;
       }
+      const needsSudo = proxyPort < PRIVILEGED_PORT_THRESHOLD;
+      const sudoPrefix = needsSudo ? "sudo " : "";
+      console.log(chalk.yellow(`Proxy is already running on port ${proxyPort}.`));
+      console.log(
+        chalk.blue(`To restart: portless proxy stop && ${sudoPrefix}portless proxy start`)
+      );
       return;
     }
-    if (proxyPort < 1024 && process.getuid() !== 0) {
-      console.error(chalk.red(`Error: Proxy requires sudo for port ${proxyPort}`));
-      console.log(chalk.blue("Usage: sudo portless proxy"));
+    if (proxyPort < PRIVILEGED_PORT_THRESHOLD && (process.getuid?.() ?? -1) !== 0) {
+      console.error(chalk.red(`Error: Port ${proxyPort} requires sudo.`));
+      console.error(chalk.blue("Either run with sudo:"));
+      console.error(chalk.cyan("  sudo portless proxy start -p 80"));
+      console.error(chalk.blue("Or use the default port (no sudo needed):"));
+      console.error(chalk.cyan("  portless proxy start"));
       process.exit(1);
     }
-    if (isDaemon) {
-      store.ensureDir();
-      const logPath = path.join(PORTLESS_DIR, "proxy.log");
-      const logFd = fs.openSync(logPath, "a");
+    if (isForeground) {
+      console.log(chalk.blue.bold("\nportless proxy\n"));
+      startProxyServer(store2, proxyPort);
+      return;
+    }
+    store2.ensureDir();
+    const logPath = path2.join(stateDir, "proxy.log");
+    const logFd = fs2.openSync(logPath, "a");
+    try {
       try {
-        fs.chmodSync(logPath, 420);
+        fs2.chmodSync(logPath, FILE_MODE);
       } catch {
       }
-      const daemonArgs = [process.argv[1], "proxy"];
+      const daemonArgs = [process.argv[1], "proxy", "start", "--foreground"];
       if (portFlagIndex !== -1) {
         daemonArgs.push("--port", proxyPort.toString());
       }
-      const child = spawn(process.execPath, daemonArgs, {
+      const child = spawn2(process.execPath, daemonArgs, {
         detached: true,
         stdio: ["ignore", logFd, logFd],
         env: process.env
       });
       child.unref();
-      fs.closeSync(logFd);
-      if (!await waitForProxy(proxyPort)) {
-        console.error(chalk.red("Proxy failed to start"));
-        if (fs.existsSync(logPath)) {
-          console.log(chalk.gray(`Check logs: ${logPath}`));
-        }
-        process.exit(1);
+    } finally {
+      fs2.closeSync(logFd);
+    }
+    if (!await waitForProxy(proxyPort)) {
+      console.error(chalk.red("Proxy failed to start (timed out waiting for it to listen)."));
+      console.error(chalk.blue("Try starting the proxy in the foreground to see the error:"));
+      const needsSudo = proxyPort < PRIVILEGED_PORT_THRESHOLD;
+      console.error(chalk.cyan(`  ${needsSudo ? "sudo " : ""}portless proxy start --foreground`));
+      if (fs2.existsSync(logPath)) {
+        console.error(chalk.gray(`Logs: ${logPath}`));
       }
-      return;
+      process.exit(1);
     }
-    console.log(chalk.blue.bold("\nportless proxy\n"));
-    startProxyServer(proxyPort);
+    console.log(chalk.green(`Proxy started on port ${proxyPort}`));
     return;
   }
   const name = args[0];
   const commandArgs = args.slice(1);
   if (commandArgs.length === 0) {
-    console.error(chalk.red("Error: No command provided"));
-    console.log(chalk.blue("Usage: portless <name> <command...>"));
-    console.log(chalk.blue("Example: portless myapp next dev"));
+    console.error(chalk.red("Error: No command provided."));
+    console.error(chalk.blue("Usage:"));
+    console.error(chalk.cyan("  portless <name> <command...>"));
+    console.error(chalk.blue("Example:"));
+    console.error(chalk.cyan("  portless myapp next dev"));
     process.exit(1);
   }
-  await runApp(name, commandArgs);
+  const { dir, port } = await discoverState();
+  const store = new RouteStore(dir, {
+    onWarning: (msg) => console.warn(chalk.yellow(msg))
+  });
+  await runApp(store, port, dir, name, commandArgs);
 }
 main().catch((err) => {
   const message = err instanceof Error ? err.message : String(err);

package/dist/index.d.ts

@@ -8,18 +8,27 @@ interface RouteInfo {
 interface ProxyServerOptions {
     /** Called on each request to get the current route table. */
     getRoutes: () => RouteInfo[];
+    /** The port the proxy is listening on (used to build correct URLs). */
+    proxyPort: number;
     /** Optional error logger; defaults to console.error. */
     onError?: (message: string) => void;
 }
 
+/** Response header used to identify a portless proxy (for health checks). */
+declare const PORTLESS_HEADER = "X-Portless";
 /**
  * Create an HTTP proxy server that routes requests based on the Host header.
  *
+ * Uses Node's built-in http module for proxying (no external dependencies).
  * The `getRoutes` callback is invoked on every request so callers can provide
  * either a static list or a live-updating one.
  */
 declare function createProxyServer(options: ProxyServerOptions): http.Server;
 
+/** File permission mode for route and state files. */
+declare const FILE_MODE = 420;
+/** Directory permission mode for the state directory. */
+declare const DIR_MODE = 493;
 interface RouteMapping extends RouteInfo {
     pid: number;
 }
@@ -32,6 +41,7 @@ declare class RouteStore {
     private readonly routesPath;
     private readonly lockPath;
     readonly pidPath: string;
+    readonly portFilePath: string;
     private readonly onWarning;
     constructor(dir: string, options?: {
         onWarning?: (message: string) => void;
@@ -40,8 +50,8 @@ declare class RouteStore {
     getRoutesPath(): string;
     private static readonly sleepBuffer;
     private syncSleep;
-    acquireLock(maxRetries?: number, retryDelayMs?: number): boolean;
-    releaseLock(): void;
+    private acquireLock;
+    private releaseLock;
     private isProcessAlive;
     /**
      * Load routes from disk, filtering out stale entries whose owning process
@@ -61,10 +71,14 @@ declare function isErrnoException(err: unknown): err is NodeJS.ErrnoException;
  * Escape HTML special characters to prevent XSS.
  */
 declare function escapeHtml(str: string): string;
+/**
+ * Format a .localhost URL, including the port only when it is not 80 (standard HTTP).
+ */
+declare function formatUrl(hostname: string, proxyPort: number): string;
 /**
  * Parse and normalize a hostname input for use as a .localhost subdomain.
  * Strips protocol prefixes, validates characters, and appends .localhost if needed.
  */
 declare function parseHostname(input: string): string;
 
-export { type ProxyServerOptions, type RouteInfo, type RouteMapping, RouteStore, createProxyServer, escapeHtml, isErrnoException, parseHostname };
+export { DIR_MODE, FILE_MODE, PORTLESS_HEADER, type ProxyServerOptions, type RouteInfo, type RouteMapping, RouteStore, createProxyServer, escapeHtml, formatUrl, isErrnoException, parseHostname };

package/dist/index.js

@@ -1,14 +1,22 @@
 import {
+  DIR_MODE,
+  FILE_MODE,
+  PORTLESS_HEADER,
   RouteStore,
   createProxyServer,
   escapeHtml,
+  formatUrl,
   isErrnoException,
   parseHostname
-} from "./chunk-SE7KL62V.js";
+} from "./chunk-Y5OVKUR4.js";
 export {
+  DIR_MODE,
+  FILE_MODE,
+  PORTLESS_HEADER,
   RouteStore,
   createProxyServer,
   escapeHtml,
+  formatUrl,
   isErrnoException,
   parseHostname
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portless",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Replace port numbers with stable, named .localhost URLs. For humans and agents.",
   "type": "module",
   "main": "./dist/index.js",
@@ -57,12 +57,10 @@
     "url": "https://github.com/vercel-labs/portless/issues"
   },
   "dependencies": {
-    "chalk": "^5.3.0",
-    "http-proxy": "^1.18.1"
+    "chalk": "^5.3.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
-    "@types/http-proxy": "^1.17.14",
     "@types/node": "^20.11.0",
     "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^9.39.2",