portless 0.12.0 → 0.13.1

package/dist/cli.js

@@ -39,9 +39,9 @@ var gray = dim;
 var colors_default = { bold, dim, red, green, yellow, blue, cyan, white, gray };
 
 // src/cli.ts
-import * as fs8 from "fs";
-import * as path8 from "path";
-import { spawn as spawn3, spawnSync as spawnSync3 } from "child_process";
+import * as fs9 from "fs";
+import * as path9 from "path";
+import { spawn as spawn3, spawnSync as spawnSync4 } from "child_process";
 import { StringDecoder } from "string_decoder";
 
 // src/certs.ts
@@ -757,10 +757,15 @@ function untrustCAWindows(caCertPath) {
 // src/tailscale.ts
 import { spawnSync } from "child_process";
 var TAILSCALE_BINARY = "tailscale";
+var TAILSCALE_COMMAND_TIMEOUT_MS = 3e4;
 var PREFERRED_SERVE_PORTS = [443, 8443, 8444, 8445, 8446, 8447, 8448, 8449, 8450];
 var FUNNEL_PORTS = [443, 8443, 1e4];
 function defaultRunner(args) {
-  const result = spawnSync(TAILSCALE_BINARY, args, { encoding: "utf-8" });
+  const result = spawnSync(TAILSCALE_BINARY, args, {
+    encoding: "utf-8",
+    killSignal: "SIGKILL",
+    timeout: TAILSCALE_COMMAND_TIMEOUT_MS
+  });
   return {
     status: result.status,
     stdout: result.stdout ?? "",
@@ -812,11 +817,52 @@ function statusToDnsName(status) {
     "Could not determine Tailscale node DNS name from `tailscale status --json`. Is Tailscale connected?"
   );
 }
-function ensureTailscaleReady(runner = defaultRunner) {
+function isFunnelCapability(value) {
+  const normalized = value.toLowerCase();
+  return normalized === "funnel" || normalized.endsWith("/funnel");
+}
+function isHttpsCapability(value) {
+  const normalized = value.toLowerCase();
+  return normalized === "https" || normalized.endsWith("/https");
+}
+function hasCapability(status, predicate) {
+  const capabilities = status.Self?.Capabilities;
+  if (Array.isArray(capabilities) && capabilities.some(predicate)) {
+    return true;
+  }
+  const capMap = status.Self?.CapMap;
+  return Boolean(capMap && Object.keys(capMap).some(predicate));
+}
+function hasHttpsCapability(status) {
+  return hasCapability(status, isHttpsCapability);
+}
+function hasFunnelCapability(status) {
+  return hasCapability(status, isFunnelCapability);
+}
+function throwHttpsNotEnabled() {
+  throw new Error(
+    "Tailscale HTTPS is not enabled on your tailnet. Enable HTTPS certificates in Tailscale DNS settings, then run portless again."
+  );
+}
+function throwFunnelNotEnabled(status) {
+  const nodeId = status.Self?.ID;
+  const enableUrl = typeof nodeId === "string" && nodeId.length > 0 ? ` Visit https://login.tailscale.com/f/funnel?node=${nodeId} to enable it.` : "";
+  throw new Error(
+    "Tailscale Funnel is not enabled on your tailnet. Enable Funnel for this node, then run portless again." + enableUrl
+  );
+}
+function ensureTailscaleReady(options = {}) {
+  const runner = options.runner ?? defaultRunner;
   runOrThrow(["version"], "check tailscale version", runner);
   const statusResult = runOrThrow(["status", "--json"], "read tailscale status", runner);
   const status = parseStatusJson(statusResult.stdout);
   const dnsName = statusToDnsName(status);
+  if (options.requireHttps && !hasHttpsCapability(status)) {
+    throwHttpsNotEnabled();
+  }
+  if (options.requireFunnel && !hasFunnelCapability(status)) {
+    throwFunnelNotEnabled(status);
+  }
   return {
     dnsName,
     baseUrl: `https://${dnsName}`
@@ -868,6 +914,16 @@ function isConflictError(stderr, stdout) {
 ${stdout}`.toLowerCase();
   return text.includes("already in use") || text.includes("already exists") || text.includes("port conflict") || text.includes("address already");
 }
+function isFunnelNotEnabledError(stderr, stdout) {
+  const text = `${stderr}
+${stdout}`.toLowerCase();
+  return text.includes("funnel is not enabled on your tailnet");
+}
+function formatFunnelNotEnabledError(stderr, stdout) {
+  const details = normalizeSpace(`${stderr}
+${stdout}`);
+  return "Tailscale Funnel is not enabled on your tailnet. Enable Funnel for this node, then run portless again." + (details ? ` Tailscale said: ${details}` : "");
+}
 var CONFLICT_MESSAGES = {
   serve: "Stop the existing serve or let portless auto-assign a different port.",
   funnel: "Tailscale Funnel supports ports 443, 8443, and 10000."
@@ -882,9 +938,20 @@ function register(mode, localPort, httpsPort, runner) {
         "Tailscale CLI not found. Install Tailscale (https://tailscale.com/download) and ensure `tailscale` is on PATH."
       );
     }
+    if (mode === "funnel" && isFunnelNotEnabledError(result.stderr, result.stdout)) {
+      throw new Error(formatFunnelNotEnabledError(result.stderr, result.stdout));
+    }
+    if (mode === "funnel" && errno.code === "ETIMEDOUT") {
+      throw new Error(
+        "Tailscale Funnel registration timed out. Make sure Funnel is enabled on your tailnet, then run portless again."
+      );
+    }
     throw new Error(`Failed to register tailscale ${mode}: ${result.error.message}`);
   }
   if (result.status !== 0) {
+    if (mode === "funnel" && isFunnelNotEnabledError(result.stderr, result.stdout)) {
+      throw new Error(formatFunnelNotEnabledError(result.stderr, result.stdout));
+    }
     if (isConflictError(result.stderr, result.stdout)) {
       throw new Error(
         `Tailscale ${mode === "funnel" ? "Funnel " : ""}HTTPS port ${httpsPort} is already in use. ` + CONFLICT_MESSAGES[mode]
@@ -1489,12 +1556,12 @@ async function findFreePort(minPort = MIN_APP_PORT, maxPort = MAX_APP_PORT) {
     throw new Error(`minPort (${minPort}) must be <= maxPort (${maxPort})`);
   }
   const tryPort = (port) => {
-    return new Promise((resolve3) => {
+    return new Promise((resolve4) => {
       const server = net.createServer();
       server.listen(port, () => {
-        server.close(() => resolve3(true));
+        server.close(() => resolve4(true));
       });
-      server.on("error", () => resolve3(false));
+      server.on("error", () => resolve4(false));
     });
   };
   for (let i = 0; i < RANDOM_PORT_ATTEMPTS; i++) {
@@ -1511,7 +1578,7 @@ async function findFreePort(minPort = MIN_APP_PORT, maxPort = MAX_APP_PORT) {
   throw new Error(`No free port found in range ${minPort}-${maxPort}`);
 }
 function isProxyRunning(port, tls2 = false) {
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     const requestFn = tls2 ? https.request : http.request;
     const req = requestFn(
       {
@@ -1524,26 +1591,26 @@ function isProxyRunning(port, tls2 = false) {
       },
       (res) => {
         res.resume();
-        resolve3(res.headers[PORTLESS_HEADER.toLowerCase()] === "1");
+        resolve4(res.headers[PORTLESS_HEADER.toLowerCase()] === "1");
       }
     );
-    req.on("error", () => resolve3(false));
+    req.on("error", () => resolve4(false));
     req.on("timeout", () => {
       req.destroy();
-      resolve3(false);
+      resolve4(false);
     });
     req.end();
   });
 }
 function isPortListening(port) {
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     const socket = net.createConnection({ host: "127.0.0.1", port });
     let settled = false;
     const finish = (result) => {
       if (settled) return;
       settled = true;
       socket.destroy();
-      resolve3(result);
+      resolve4(result);
     };
     socket.setTimeout(SOCKET_TIMEOUT_MS);
     socket.once("connect", () => finish(true));
@@ -1607,7 +1674,7 @@ function findPidOnPort(port) {
 }
 async function waitForProxy(port, maxAttempts = WAIT_FOR_PROXY_MAX_ATTEMPTS, intervalMs = WAIT_FOR_PROXY_INTERVAL_MS, tls2 = false) {
   for (let i = 0; i < maxAttempts; i++) {
-    await new Promise((resolve3) => setTimeout(resolve3, intervalMs));
+    await new Promise((resolve4) => setTimeout(resolve4, intervalMs));
     if (await isProxyRunning(port, tls2)) {
       return true;
     }
@@ -1831,7 +1898,7 @@ function isInternalInterface(iname, macStr, internal) {
   return false;
 }
 function probeDefaultRouteIPv4() {
-  return new Promise((resolve3, reject) => {
+  return new Promise((resolve4, reject) => {
     const socket = createSocket({ type: "udp4", reuseAddr: true });
     socket.on("error", (error) => {
       socket.close();
@@ -1843,7 +1910,7 @@ function probeDefaultRouteIPv4() {
       socket.close();
       socket.unref();
       if (addr && "address" in addr && addr.address && addr.address !== NO_ROUTE_IP) {
-        resolve3(addr.address);
+        resolve4(addr.address);
       } else {
         reject(new Error("No route to host"));
       }
@@ -2524,6 +2591,908 @@ function hasTurboConfig(wsRoot) {
   }
 }
 
+// src/service.ts
+import * as fs8 from "fs";
+import * as os2 from "os";
+import * as path8 from "path";
+import { spawnSync as spawnSync3 } from "child_process";
+var DEFAULT_SERVICE_PORT = getProtocolPort(true);
+var SERVICE_LABEL = "sh.portless.proxy";
+var SYSTEMD_SERVICE = "portless.service";
+var WINDOWS_TASK_NAME = "Portless Proxy";
+var INTERNAL_ELEVATED_ENV = "PORTLESS_INTERNAL_SERVICE_ELEVATED";
+var SERVICE_ENV_KEYS = /* @__PURE__ */ new Set(["PORTLESS_SYNC_HOSTS"]);
+var DEFAULT_SERVICE_CONFIG = {
+  proxyPort: DEFAULT_SERVICE_PORT,
+  useHttps: true,
+  customCertPath: null,
+  customKeyPath: null,
+  lanMode: false,
+  lanIp: null,
+  lanIpExplicit: false,
+  tld: DEFAULT_TLD,
+  useWildcard: false,
+  extraEnv: {}
+};
+function defaultRunner2(command, args, options) {
+  return spawnSync3(command, args, {
+    encoding: "utf-8",
+    stdio: options?.stdio ?? "pipe"
+  });
+}
+function isSupportedPlatform(platform) {
+  return platform === "darwin" || platform === "linux" || platform === "win32";
+}
+function xmlEscape(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+function systemdEscape(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function windowsQuote(value) {
+  return `"${value.replace(/"/g, '\\"')}"`;
+}
+function xmlUnescape(value) {
+  return value.replace(/&apos;/g, "'").replace(/&quot;/g, '"').replace(/&gt;/g, ">").replace(/&lt;/g, "<").replace(/&amp;/g, "&");
+}
+function parseBooleanEnv(value) {
+  if (value === void 0) return null;
+  if (value === "1" || value === "true") return true;
+  if (value === "0" || value === "false") return false;
+  return null;
+}
+function parsePortValue(value, source) {
+  const port = parseInt(value, 10);
+  if (isNaN(port) || port < 1 || port > 65535) {
+    throw new Error(`${source} must be a number between 1 and 65535.`);
+  }
+  return port;
+}
+function getFlagValue(args, index, flag) {
+  const value = args[index + 1];
+  if (!value || value.startsWith("-")) {
+    throw new Error(`${flag} requires a value.`);
+  }
+  return value;
+}
+function resolveServicePath(value) {
+  const expanded = value === "~" ? os2.homedir() : value.startsWith("~/") || value.startsWith("~\\") ? path8.join(os2.homedir(), value.slice(2)) : value;
+  return path8.resolve(expanded);
+}
+function normalizeServiceInstallPaths(config) {
+  return {
+    ...config,
+    stateDir: config.stateDir ? resolveServicePath(config.stateDir) : void 0,
+    customCertPath: config.customCertPath ? resolveServicePath(config.customCertPath) : null,
+    customKeyPath: config.customKeyPath ? resolveServicePath(config.customKeyPath) : null
+  };
+}
+function collectServiceExtraEnv(env) {
+  const extraEnv = {};
+  for (const key of SERVICE_ENV_KEYS) {
+    const value = env[key];
+    if (value) extraEnv[key] = value;
+  }
+  return extraEnv;
+}
+function parseServiceInstallConfig(args, env = process.env, options = {}) {
+  const config = {
+    ...DEFAULT_SERVICE_CONFIG,
+    extraEnv: collectServiceExtraEnv(env)
+  };
+  if (env.PORTLESS_STATE_DIR) {
+    config.stateDir = env.PORTLESS_STATE_DIR;
+  }
+  const envHttps = parseBooleanEnv(env.PORTLESS_HTTPS);
+  if (envHttps !== null) {
+    config.useHttps = envHttps;
+  }
+  const envLan = parseBooleanEnv(env.PORTLESS_LAN);
+  if (envLan !== null) {
+    config.lanMode = envLan;
+  }
+  if (env.PORTLESS_LAN_IP) {
+    config.lanMode = true;
+    config.lanIp = env.PORTLESS_LAN_IP;
+    config.lanIpExplicit = true;
+  }
+  if (env.PORTLESS_TLD) {
+    const tld = env.PORTLESS_TLD.trim().toLowerCase();
+    const err = validateTld(tld);
+    if (err) throw new Error(`PORTLESS_TLD: ${err}`);
+    config.tld = tld;
+  }
+  const envWildcard = parseBooleanEnv(env.PORTLESS_WILDCARD);
+  if (envWildcard !== null) {
+    config.useWildcard = envWildcard;
+  }
+  if (env.PORTLESS_PORT) {
+    config.proxyPort = parsePortValue(env.PORTLESS_PORT, "PORTLESS_PORT");
+  } else {
+    config.proxyPort = getProtocolPort(config.useHttps);
+  }
+  const tokens = args[0] === "service" ? args.slice(2) : args;
+  for (let i = 0; i < tokens.length; i += 1) {
+    const token = tokens[i];
+    switch (token) {
+      case "-p":
+      case "--port":
+        config.proxyPort = parsePortValue(getFlagValue(tokens, i, token), token);
+        i += 1;
+        break;
+      case "--https":
+        config.useHttps = true;
+        break;
+      case "--no-tls":
+        config.useHttps = false;
+        break;
+      case "--lan":
+        config.lanMode = true;
+        break;
+      case "--ip":
+        config.lanMode = true;
+        config.lanIp = getFlagValue(tokens, i, token);
+        config.lanIpExplicit = true;
+        i += 1;
+        break;
+      case "--tld": {
+        const tld = getFlagValue(tokens, i, token).trim().toLowerCase();
+        const err = validateTld(tld);
+        if (err) throw new Error(err);
+        config.tld = tld;
+        i += 1;
+        break;
+      }
+      case "--wildcard":
+        config.useWildcard = true;
+        break;
+      case "--cert":
+        config.customCertPath = getFlagValue(tokens, i, token);
+        config.useHttps = true;
+        i += 1;
+        break;
+      case "--key":
+        config.customKeyPath = getFlagValue(tokens, i, token);
+        config.useHttps = true;
+        i += 1;
+        break;
+      case "--state-dir":
+        config.stateDir = getFlagValue(tokens, i, token);
+        i += 1;
+        break;
+      case "--foreground":
+      case "--skip-trust":
+        if (!options.allowRuntimeFlags) {
+          throw new Error(`Unknown service install option "${token}".`);
+        }
+        break;
+      default:
+        throw new Error(`Unknown service install option "${token}".`);
+    }
+  }
+  if (config.customCertPath && !config.customKeyPath || !config.customCertPath && config.customKeyPath) {
+    throw new Error("--cert and --key must be used together.");
+  }
+  if (!env.PORTLESS_PORT && !tokens.includes("--port") && !tokens.includes("-p")) {
+    config.proxyPort = getProtocolPort(config.useHttps);
+  }
+  if (!config.lanMode) {
+    config.lanIp = null;
+    config.lanIpExplicit = false;
+  }
+  return config;
+}
+function readPasswdHome(username) {
+  try {
+    const passwd = fs8.readFileSync("/etc/passwd", "utf-8");
+    for (const line of passwd.split("\n")) {
+      const fields = line.split(":");
+      if (fields[0] === username && fields[5]) {
+        return fields[5];
+      }
+    }
+  } catch {
+  }
+  return null;
+}
+function resolveUserContext(platform) {
+  if (platform === "win32") {
+    const home = process.env.USERPROFILE || os2.homedir();
+    return { home, username: process.env.USERNAME };
+  }
+  const sudoUser = process.env.SUDO_USER;
+  const sudoUid = process.env.SUDO_UID;
+  const sudoGid = process.env.SUDO_GID;
+  if (sudoUser && sudoUser !== "root") {
+    const home = process.env.HOME && process.env.HOME !== "/var/root" && process.env.HOME !== "/root" ? process.env.HOME : readPasswdHome(sudoUser) || (platform === "darwin" ? path8.posix.join("/Users", sudoUser) : path8.posix.join("/home", sudoUser));
+    return { home, uid: sudoUid, gid: sudoGid, username: sudoUser };
+  }
+  const userInfo2 = os2.userInfo();
+  return {
+    home: os2.homedir(),
+    uid: process.getuid?.()?.toString(),
+    gid: process.getgid?.()?.toString(),
+    username: userInfo2.username
+  };
+}
+function buildProxyCommand(entryScript, serviceConfig) {
+  const proxyConfig = buildProxyStartConfig({
+    useHttps: serviceConfig.useHttps,
+    customCertPath: serviceConfig.customCertPath,
+    customKeyPath: serviceConfig.customKeyPath,
+    lanMode: serviceConfig.lanMode,
+    lanIp: serviceConfig.lanIp,
+    lanIpExplicit: serviceConfig.lanIpExplicit,
+    tld: serviceConfig.tld,
+    useWildcard: serviceConfig.useWildcard,
+    foreground: true,
+    includePort: true,
+    proxyPort: serviceConfig.proxyPort,
+    skipTrust: true
+  });
+  return [entryScript, "proxy", "start", ...proxyConfig.args];
+}
+function buildServiceEnv(ctx) {
+  const env = {
+    PORTLESS_STATE_DIR: ctx.stateDir,
+    PORTLESS_PORT: ctx.config.proxyPort.toString(),
+    PORTLESS_HTTPS: ctx.config.useHttps ? "1" : "0",
+    PORTLESS_LAN: ctx.config.lanMode ? "1" : "0",
+    PORTLESS_WILDCARD: ctx.config.useWildcard ? "1" : "0",
+    ...ctx.config.extraEnv
+  };
+  if (ctx.config.lanMode && ctx.config.lanIpExplicit && ctx.config.lanIp) {
+    env.PORTLESS_LAN_IP = ctx.config.lanIp;
+  }
+  if (ctx.config.lanMode) {
+    env.PORTLESS_TLD = "local";
+  } else if (ctx.config.tld !== DEFAULT_TLD) {
+    env.PORTLESS_TLD = ctx.config.tld;
+  }
+  if (ctx.platform === "win32") {
+    env.USERPROFILE = ctx.user.home;
+    env.PATH = ctx.pathEnv;
+  } else {
+    env.HOME = ctx.user.home;
+    if (ctx.user.uid) env.SUDO_UID = ctx.user.uid;
+    if (ctx.user.gid) env.SUDO_GID = ctx.user.gid;
+  }
+  return env;
+}
+function defaultStateDir(platform, userHome) {
+  return platform === "win32" ? path8.win32.join(userHome, ".portless") : path8.posix.join(userHome, ".portless");
+}
+function buildLaunchdPlist(ctx, programArguments) {
+  const env = buildServiceEnv(ctx);
+  const envEntries = Object.entries(env).map(
+    ([key, value]) => `    <key>${xmlEscape(key)}</key>
+    <string>${xmlEscape(value)}</string>`
+  ).join("\n");
+  const args = programArguments.map((arg) => `    <string>${xmlEscape(arg)}</string>`).join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${SERVICE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+${envEntries}
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(path8.posix.join(ctx.stateDir, "service.log"))}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(path8.posix.join(ctx.stateDir, "service.log"))}</string>
+</dict>
+</plist>
+`;
+}
+function buildSystemdUnit(ctx, execStart) {
+  const env = buildServiceEnv(ctx);
+  const envLines = Object.entries(env).map(([key, value]) => `Environment=${key}=${systemdEscape(value)}`).join("\n");
+  return `[Unit]
+Description=Portless HTTPS proxy
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+${envLines}
+Environment=PATH=${systemdEscape(ctx.pathEnv)}
+ExecStart=${execStart.map(systemdEscape).join(" ")}
+Restart=on-failure
+RestartSec=2
+KillSignal=SIGTERM
+TimeoutStopSec=5
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+function buildWindowsScript(ctx, command) {
+  const env = buildServiceEnv(ctx);
+  const setEnv = Object.entries(env).map(([key, value]) => `set "${key}=${value.replace(/"/g, "").replace(/%/g, "%%")}"`).join("\r\n");
+  const proxyCommand = [windowsQuote(ctx.nodePath), ...command.map(windowsQuote)].join(" ");
+  return `@echo off\r
+${setEnv}\r
+${proxyCommand}\r
+`;
+}
+function buildServiceSpec(options) {
+  const installConfig = {
+    ...DEFAULT_SERVICE_CONFIG,
+    ...options.installConfig,
+    extraEnv: options.installConfig?.extraEnv ?? {}
+  };
+  const stateDir = options.stateDir || installConfig.stateDir || defaultStateDir(options.platform, options.userHome);
+  const normalizedConfig = {
+    ...installConfig,
+    stateDir
+  };
+  const ctx = {
+    platform: options.platform,
+    nodePath: options.nodePath,
+    entryScript: options.entryScript,
+    stateDir,
+    user: {
+      home: options.userHome,
+      uid: options.uid,
+      gid: options.gid,
+      username: options.username
+    },
+    pathEnv: options.pathEnv || "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
+    programData: options.programData || "C:\\ProgramData",
+    config: normalizedConfig
+  };
+  const proxyCommand = buildProxyCommand(ctx.entryScript, ctx.config);
+  if (ctx.platform === "darwin") {
+    const programArguments = [ctx.nodePath, ...proxyCommand];
+    return {
+      platform: "darwin",
+      label: SERVICE_LABEL,
+      plistPath: `/Library/LaunchDaemons/${SERVICE_LABEL}.plist`,
+      plist: buildLaunchdPlist(ctx, programArguments),
+      stateDir: ctx.stateDir,
+      config: ctx.config,
+      programArguments
+    };
+  }
+  if (ctx.platform === "linux") {
+    const execStart = [ctx.nodePath, ...proxyCommand];
+    return {
+      platform: "linux",
+      serviceName: SYSTEMD_SERVICE,
+      unitPath: `/etc/systemd/system/${SYSTEMD_SERVICE}`,
+      unit: buildSystemdUnit(ctx, execStart),
+      stateDir: ctx.stateDir,
+      config: ctx.config,
+      execStart
+    };
+  }
+  const scriptDir = path8.win32.join(ctx.programData, "portless", "service");
+  const scriptPath = path8.win32.join(scriptDir, "portless-service.cmd");
+  const script = buildWindowsScript(ctx, proxyCommand);
+  const taskRun = windowsQuote(scriptPath);
+  return {
+    platform: "win32",
+    taskName: WINDOWS_TASK_NAME,
+    stateDir: ctx.stateDir,
+    config: ctx.config,
+    scriptDir,
+    scriptPath,
+    script,
+    taskRun,
+    createArgs: [
+      "/Create",
+      "/TN",
+      WINDOWS_TASK_NAME,
+      "/SC",
+      "ONSTART",
+      "/RU",
+      "SYSTEM",
+      "/RL",
+      "HIGHEST",
+      "/TR",
+      taskRun,
+      "/F"
+    ],
+    runArgs: ["/Run", "/TN", WINDOWS_TASK_NAME],
+    deleteArgs: ["/Delete", "/TN", WINDOWS_TASK_NAME, "/F"],
+    queryArgs: ["/Query", "/TN", WINDOWS_TASK_NAME, "/FO", "LIST", "/V"]
+  };
+}
+function currentServiceSpec(entryScript, installConfig) {
+  if (!isSupportedPlatform(process.platform)) {
+    throw new Error(`Unsupported platform: ${process.platform}`);
+  }
+  const user = resolveUserContext(process.platform);
+  const stateDir = installConfig?.stateDir || process.env.PORTLESS_STATE_DIR || defaultStateDir(process.platform, user.home);
+  const config = installConfig ?? {
+    ...DEFAULT_SERVICE_CONFIG,
+    stateDir,
+    extraEnv: collectServiceExtraEnv(process.env)
+  };
+  return buildServiceSpec({
+    platform: process.platform,
+    nodePath: process.execPath,
+    entryScript,
+    userHome: user.home,
+    uid: user.uid,
+    gid: user.gid,
+    username: user.username,
+    stateDir,
+    pathEnv: process.env.PATH,
+    programData: process.env.ProgramData,
+    installConfig: config
+  });
+}
+function parseQuotedWords(input, options = {}) {
+  const words = [];
+  let current = "";
+  let inQuote = false;
+  let inWord = false;
+  const unescapeBackslash = options.unescapeBackslash ?? true;
+  for (let i = 0; i < input.length; i += 1) {
+    const char = input[i];
+    if (char === '"') {
+      inQuote = !inQuote;
+      inWord = true;
+      continue;
+    }
+    if (char === "\\" && i + 1 < input.length && (input[i + 1] === '"' || unescapeBackslash && input[i + 1] === "\\")) {
+      current += input[i + 1];
+      inWord = true;
+      i += 1;
+      continue;
+    }
+    if (/\s/.test(char) && !inQuote) {
+      if (inWord) {
+        words.push(current);
+        current = "";
+        inWord = false;
+      }
+      continue;
+    }
+    current += char;
+    inWord = true;
+  }
+  if (inWord) {
+    words.push(current);
+  }
+  return words;
+}
+function parsePlistStrings(block) {
+  return [...block.matchAll(/<string>([\s\S]*?)<\/string>/g)].map((match) => xmlUnescape(match[1]));
+}
+function parsePlistEnv(block) {
+  const env = {};
+  for (const match of block.matchAll(/<key>([\s\S]*?)<\/key>\s*<string>([\s\S]*?)<\/string>/g)) {
+    env[xmlUnescape(match[1])] = xmlUnescape(match[2]);
+  }
+  return env;
+}
+function readInstalledServiceSnapshot(spec) {
+  try {
+    if (spec.platform === "darwin") {
+      if (!fs8.existsSync(spec.plistPath)) return null;
+      const plist = fs8.readFileSync(spec.plistPath, "utf-8");
+      const argsBlock = plist.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/);
+      const envBlock = plist.match(/<key>EnvironmentVariables<\/key>\s*<dict>([\s\S]*?)<\/dict>/);
+      if (!argsBlock) return null;
+      return {
+        command: parsePlistStrings(argsBlock[1]),
+        env: envBlock ? parsePlistEnv(envBlock[1]) : {}
+      };
+    }
+    if (spec.platform === "linux") {
+      if (!fs8.existsSync(spec.unitPath)) return null;
+      const unit = fs8.readFileSync(spec.unitPath, "utf-8");
+      const env2 = {};
+      let command = null;
+      for (const line of unit.split("\n")) {
+        if (line.startsWith("Environment=")) {
+          const entry = line.slice("Environment=".length);
+          const eq = entry.indexOf("=");
+          if (eq > 0) {
+            const key = entry.slice(0, eq);
+            const value = parseQuotedWords(entry.slice(eq + 1))[0] ?? "";
+            env2[key] = value;
+          }
+        } else if (line.startsWith("ExecStart=")) {
+          command = parseQuotedWords(line.slice("ExecStart=".length));
+        }
+      }
+      return command ? { command, env: env2 } : null;
+    }
+    if (!fs8.existsSync(spec.scriptPath)) return null;
+    const script = fs8.readFileSync(spec.scriptPath, "utf-8");
+    const env = {};
+    let commandLine = null;
+    for (const rawLine of script.split(/\r?\n/)) {
+      const line = rawLine.trim();
+      if (!line || line.toLowerCase() === "@echo off") continue;
+      const envMatch = line.match(/^set "([^=]+)=(.*)"$/);
+      if (envMatch) {
+        env[envMatch[1]] = envMatch[2].replace(/%%/g, "%");
+        continue;
+      }
+      commandLine = line;
+    }
+    return commandLine ? { command: parseQuotedWords(commandLine, { unescapeBackslash: false }), env } : null;
+  } catch {
+    return null;
+  }
+}
+function installedConfigFromSnapshot(snapshot, fallback) {
+  const proxyIndex = snapshot.command.findIndex(
+    (arg, index) => arg === "proxy" && snapshot.command[index + 1] === "start"
+  );
+  if (proxyIndex === -1) return null;
+  try {
+    const parsed = parseServiceInstallConfig(
+      ["service", "install", ...snapshot.command.slice(proxyIndex + 2)],
+      snapshot.env,
+      { allowRuntimeFlags: true }
+    );
+    const stateDir = parsed.stateDir || snapshot.env.PORTLESS_STATE_DIR || fallback.stateDir;
+    return { ...parsed, stateDir };
+  } catch {
+    return null;
+  }
+}
+function readInstalledServiceConfig(spec) {
+  const snapshot = readInstalledServiceSnapshot(spec);
+  if (!snapshot) return null;
+  return installedConfigFromSnapshot(snapshot, spec.config);
+}
+function collectPortlessEnvArgs(env = process.env, omit = /* @__PURE__ */ new Set()) {
+  const envArgs = [];
+  for (const key of Object.keys(env)) {
+    if (key.startsWith("PORTLESS_") && env[key] && !omit.has(key)) {
+      envArgs.push(`${key}=${env[key]}`);
+    }
+  }
+  return envArgs;
+}
+function buildElevatedEnvArgs(options) {
+  const extraEnv = options.extraEnv ?? {};
+  const overrideKeys = /* @__PURE__ */ new Set(["PORTLESS_STATE_DIR", ...Object.keys(extraEnv)]);
+  return [
+    "env",
+    ...collectPortlessEnvArgs(options.env, overrideKeys),
+    ...Object.entries(extraEnv).map(([key, value]) => `${key}=${value}`),
+    `HOME=${options.home}`,
+    `PORTLESS_STATE_DIR=${options.stateDir}`
+  ];
+}
+function buildServiceUninstallSudoArgs(entryScript, options = {}) {
+  const env = options.env ?? process.env;
+  const home = options.home ?? os2.homedir();
+  const stateDir = options.stateDir ?? env.PORTLESS_STATE_DIR ?? path8.join(home, ".portless");
+  return [
+    ...buildElevatedEnvArgs({ home, stateDir, env }),
+    options.nodePath ?? process.execPath,
+    entryScript,
+    "service",
+    "uninstall"
+  ];
+}
+function requireUnixElevation(args, runner) {
+  if (process.platform !== "darwin" && process.platform !== "linux") return;
+  if ((process.getuid?.() ?? -1) === 0) return;
+  if (process.env[INTERNAL_ELEVATED_ENV] === "1") return;
+  const home = os2.homedir();
+  const stateDir = process.env.PORTLESS_STATE_DIR || path8.join(home, ".portless");
+  const result = runner(
+    "sudo",
+    [
+      ...buildElevatedEnvArgs({
+        home,
+        stateDir,
+        extraEnv: { [INTERNAL_ELEVATED_ENV]: "1" }
+      }),
+      process.execPath,
+      args[0],
+      ...args.slice(1)
+    ],
+    { stdio: "inherit" }
+  );
+  process.exit(result.status ?? 1);
+}
+function runRequired(runner, command, args) {
+  const result = runner(command, args);
+  if (result.status !== 0) {
+    const detail = result.stderr || result.stdout || result.error?.message || `${command} failed`;
+    throw new Error(detail.trim());
+  }
+}
+function runOptional(runner, command, args) {
+  runner(command, args);
+}
+function isPermissionError(err) {
+  const code = err && typeof err === "object" && "code" in err ? String(err.code) : "";
+  const message = err instanceof Error ? err.message : String(err);
+  return code === "EACCES" || code === "EPERM" || /permission denied|operation not permitted|access is denied/i.test(message);
+}
+function stopProxyOnPort(entryScript, runner, proxyPort) {
+  runRequired(runner, process.execPath, [
+    entryScript,
+    "proxy",
+    "stop",
+    "--port",
+    proxyPort.toString()
+  ]);
+}
+async function stopExistingProxy(entryScript, runner, proxyPort) {
+  const ports = /* @__PURE__ */ new Set();
+  try {
+    const currentState = await discoverState();
+    if (currentState.port !== proxyPort && await isProxyRunning(currentState.port)) {
+      ports.add(currentState.port);
+    }
+  } catch {
+  }
+  ports.add(proxyPort);
+  for (const port of ports) {
+    stopProxyOnPort(entryScript, runner, port);
+  }
+}
+function prepareServiceState(stateDir) {
+  fs8.mkdirSync(stateDir, { recursive: true });
+  fixOwnership(stateDir);
+}
+function prepareTrust(stateDir) {
+  try {
+    ensureCerts(stateDir);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `Failed to generate certificates in ${stateDir}. Ensure OpenSSL is installed.
+${detail}`
+    );
+  }
+  if (isCATrusted(stateDir)) return;
+  console.log(colors_default.gray("Trusting portless CA for service startup..."));
+  const trustResult = trustCA(stateDir);
+  if (trustResult.trusted) {
+    console.log(colors_default.green("CA added to the system trust store."));
+    return;
+  }
+  console.warn(colors_default.yellow("Could not add the CA to the system trust store."));
+  if (trustResult.error) {
+    console.warn(colors_default.gray(trustResult.error));
+  }
+  console.warn(colors_default.yellow("Run `portless trust` if browsers show certificate warnings."));
+}
+function ensureServiceConfigSupported(config) {
+  if (!config.lanMode) return;
+  const mdnsSupport = isMdnsSupported();
+  if (mdnsSupport.supported) return;
+  const reason = mdnsSupport.reason ? `
+${mdnsSupport.reason}` : "";
+  throw new Error(
+    `LAN mode requires mDNS publishing, which is not supported on this platform.${reason}`
+  );
+}
+async function installService(entryScript, runner, args) {
+  const installConfig = normalizeServiceInstallPaths(parseServiceInstallConfig(args));
+  ensureServiceConfigSupported(installConfig);
+  requireUnixElevation([entryScript, ...args], runner);
+  const spec = currentServiceSpec(entryScript, installConfig);
+  prepareServiceState(spec.stateDir);
+  if (spec.config.useHttps && !spec.config.customCertPath) {
+    prepareTrust(spec.stateDir);
+  }
+  if (spec.platform === "darwin") {
+    runOptional(runner, "launchctl", ["bootout", "system", spec.plistPath]);
+    await stopExistingProxy(entryScript, runner, spec.config.proxyPort);
+    fs8.writeFileSync(spec.plistPath, spec.plist);
+    fs8.chmodSync(spec.plistPath, 420);
+    runRequired(runner, "chown", ["root:wheel", spec.plistPath]);
+    runRequired(runner, "launchctl", ["bootstrap", "system", spec.plistPath]);
+    runRequired(runner, "launchctl", ["enable", `system/${spec.label}`]);
+    runRequired(runner, "launchctl", ["kickstart", "-k", `system/${spec.label}`]);
+  } else if (spec.platform === "linux") {
+    runOptional(runner, "systemctl", ["disable", "--now", spec.serviceName]);
+    await stopExistingProxy(entryScript, runner, spec.config.proxyPort);
+    fs8.writeFileSync(spec.unitPath, spec.unit);
+    fs8.chmodSync(spec.unitPath, 420);
+    runRequired(runner, "systemctl", ["daemon-reload"]);
+    runRequired(runner, "systemctl", ["enable", spec.serviceName]);
+    runRequired(runner, "systemctl", ["restart", spec.serviceName]);
+  } else {
+    runOptional(runner, "schtasks", ["/End", "/TN", spec.taskName]);
+    await stopExistingProxy(entryScript, runner, spec.config.proxyPort);
+    fs8.mkdirSync(spec.scriptDir, { recursive: true });
+    fs8.writeFileSync(spec.scriptPath, spec.script);
+    runRequired(runner, "schtasks", spec.createArgs);
+    runOptional(runner, "schtasks", spec.runArgs);
+  }
+  console.log(colors_default.green("Portless service installed."));
+  console.log(colors_default.gray(`State directory: ${spec.stateDir}`));
+  console.log(colors_default.gray(`Proxy port: ${spec.config.proxyPort}`));
+}
+async function uninstallService(entryScript, runner) {
+  requireUnixElevation([entryScript, "service", "uninstall"], runner);
+  const spec = currentServiceSpec(entryScript);
+  if (spec.platform === "darwin") {
+    runOptional(runner, "launchctl", ["bootout", "system", spec.plistPath]);
+    fs8.rmSync(spec.plistPath, { force: true });
+  } else if (spec.platform === "linux") {
+    runOptional(runner, "systemctl", ["disable", "--now", spec.serviceName]);
+    fs8.rmSync(spec.unitPath, { force: true });
+    runOptional(runner, "systemctl", ["daemon-reload"]);
+  } else {
+    runOptional(runner, "schtasks", ["/End", "/TN", spec.taskName]);
+    runOptional(runner, "schtasks", spec.deleteArgs);
+    fs8.rmSync(spec.scriptDir, { recursive: true, force: true });
+  }
+  console.log(colors_default.green("Portless service uninstalled."));
+}
+function tryUninstallService(entryScript, runner = defaultRunner2) {
+  let installed = false;
+  try {
+    const spec = currentServiceSpec(entryScript);
+    if (spec.platform === "darwin") {
+      installed = fs8.existsSync(spec.plistPath);
+      if (!installed) return { removed: false, installed: false };
+      runOptional(runner, "launchctl", ["bootout", "system", spec.plistPath]);
+      fs8.rmSync(spec.plistPath, { force: true });
+    } else if (spec.platform === "linux") {
+      installed = fs8.existsSync(spec.unitPath);
+      if (!installed) return { removed: false, installed: false };
+      runOptional(runner, "systemctl", ["disable", "--now", spec.serviceName]);
+      fs8.rmSync(spec.unitPath, { force: true });
+      runOptional(runner, "systemctl", ["daemon-reload"]);
+    } else {
+      const query = runner("schtasks", ["/Query", "/TN", spec.taskName, "/FO", "LIST"]);
+      installed = query.status === 0;
+      if (!installed) return { removed: false, installed: false };
+      runOptional(runner, "schtasks", ["/End", "/TN", spec.taskName]);
+      runRequired(runner, "schtasks", spec.deleteArgs);
+      fs8.rmSync(spec.scriptDir, { recursive: true, force: true });
+    }
+    return { removed: true, installed: true };
+  } catch (err) {
+    return {
+      removed: false,
+      installed,
+      error: err instanceof Error ? err.message : String(err),
+      needsElevation: installed && isPermissionError(err)
+    };
+  }
+}
+async function getServiceStatus(entryScript, runner) {
+  const spec = currentServiceSpec(entryScript);
+  const installedConfig = readInstalledServiceConfig(spec) ?? spec.config;
+  const proxyRunning = await isProxyRunning(installedConfig.proxyPort, installedConfig.useHttps);
+  if (spec.platform === "darwin") {
+    const installed2 = fs8.existsSync(spec.plistPath);
+    const result = runner("launchctl", ["print", `system/${spec.label}`]);
+    const output2 = `${result.stdout || ""}${result.stderr || ""}`;
+    const managerState = result.status === 0 && /state = running|pid = \d+/.test(output2) ? "running" : installed2 ? "installed" : "not installed";
+    return {
+      installed: installed2,
+      managerState,
+      proxyRunning,
+      config: installedConfig,
+      details: spec.plistPath
+    };
+  }
+  if (spec.platform === "linux") {
+    const enabled2 = runner("systemctl", ["is-enabled", spec.serviceName]);
+    const active = runner("systemctl", ["is-active", spec.serviceName]);
+    const installed2 = enabled2.status === 0 || active.status === 0 || fs8.existsSync(spec.unitPath);
+    const activeText = (active.stdout || "").trim();
+    return {
+      installed: installed2,
+      managerState: active.status === 0 ? activeText || "active" : installed2 ? "installed" : "not installed",
+      proxyRunning,
+      config: installedConfig,
+      details: spec.unitPath
+    };
+  }
+  const query = runner("schtasks", spec.queryArgs);
+  const output = `${query.stdout || ""}${query.stderr || ""}`;
+  const installed = query.status === 0;
+  const stateMatch = output.match(/^\s*Status:\s*(.+)$/im);
+  return {
+    installed,
+    managerState: installed ? stateMatch?.[1]?.trim() || "installed" : "not installed",
+    proxyRunning,
+    config: installedConfig,
+    details: spec.taskName
+  };
+}
+async function printServiceStatus(entryScript, runner) {
+  const status = await getServiceStatus(entryScript, runner);
+  const config = status.config;
+  console.log(colors_default.bold("portless service"));
+  console.log(`  Manager state: ${status.managerState}`);
+  console.log(`  Installed: ${status.installed ? "yes" : "no"}`);
+  console.log(
+    `  Proxy on ${config.proxyPort}: ${status.proxyRunning ? "responding" : "not responding"}`
+  );
+  console.log(`  HTTPS: ${config.useHttps ? "yes" : "no"}`);
+  console.log(`  TLD: ${config.lanMode ? "local" : config.tld}`);
+  console.log(`  LAN mode: ${config.lanMode ? "yes" : "no"}`);
+  if (config.lanIpExplicit && config.lanIp) {
+    console.log(`  LAN IP: ${config.lanIp}`);
+  }
+  console.log(`  Wildcard: ${config.useWildcard ? "yes" : "no"}`);
+  console.log(`  State directory: ${config.stateDir}`);
+  if (status.details) {
+    console.log(`  Service entry: ${status.details}`);
+  }
+}
+function printServiceHelp() {
+  console.log(`
+${colors_default.bold("portless service")} - Start portless automatically when the OS starts.
+
+${colors_default.bold("Usage:")}
+  ${colors_default.cyan("portless service install")}             Install and start the HTTPS service on port 443
+  ${colors_default.cyan("portless service install --lan")}       Enable LAN mode for the startup service
+  ${colors_default.cyan("portless service install -p 8443")}     Use a custom proxy port
+  ${colors_default.cyan("portless service uninstall")}           Stop and remove the startup service
+  ${colors_default.cyan("portless service status")}              Show service and proxy status
+
+${colors_default.bold("Install options:")}
+  -p, --port <number>              Port for the proxy service
+  --no-tls                         Disable HTTPS
+  --https                          Enable HTTPS
+  --lan                            Enable LAN mode
+  --ip <address>                   Pin a specific LAN IP
+  --tld <tld>                      Use a custom TLD outside LAN mode
+  --wildcard                       Allow subdomain fallback
+  --cert <path>                    Use a custom TLS certificate
+  --key <path>                     Use a custom TLS private key
+  --state-dir <path>               Use a custom service state directory
+
+${colors_default.bold("Notes:")}
+  The service uses the default clean URL mode unless options or PORTLESS_*
+  environment variables are provided during install.
+  macOS and Linux install a root-owned service so port 443 can bind at boot.
+  Windows installs a Task Scheduler startup task that runs as SYSTEM.
+`);
+}
+async function handleService(args, options) {
+  const action = args[1];
+  const runner = options.runner || defaultRunner2;
+  if (!action || action === "--help" || action === "-h") {
+    printServiceHelp();
+    process.exit(0);
+  }
+  try {
+    if (action === "install") {
+      await installService(options.entryScript, runner, args);
+      return;
+    }
+    if (action === "uninstall") {
+      await uninstallService(options.entryScript, runner);
+      return;
+    }
+    if (action === "status") {
+      await printServiceStatus(options.entryScript, runner);
+      return;
+    }
+    console.error(colors_default.red(`Error: Unknown service command "${action}".`));
+    printServiceHelp();
+    process.exit(1);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(colors_default.red("Error:"), message);
+    process.exit(1);
+  }
+}
+
 // src/cli.ts
 var chalk = colors_default;
 var HOSTS_DISPLAY = isWindows ? "hosts file" : "/etc/hosts";
@@ -2676,16 +3645,16 @@ function getEntryScript() {
 function isLocallyInstalled() {
   let dir = process.cwd();
   for (; ; ) {
-    if (fs8.existsSync(path8.join(dir, "node_modules", "portless", "package.json"))) {
+    if (fs9.existsSync(path9.join(dir, "node_modules", "portless", "package.json"))) {
       return true;
     }
-    const parent = path8.dirname(dir);
+    const parent = path9.dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
   return false;
 }
-function collectPortlessEnvArgs() {
+function collectPortlessEnvArgs2() {
   const envArgs = [];
   for (const key of Object.keys(process.env)) {
     if (key.startsWith("PORTLESS_") && process.env[key]) {
@@ -2697,7 +3666,35 @@ function collectPortlessEnvArgs() {
 function sudoStop(port) {
   const stopArgs = [process.execPath, getEntryScript(), "proxy", "stop", "-p", String(port)];
   console.log(colors_default.yellow("Proxy is running as root. Elevating with sudo to stop it..."));
-  const result = spawnSync3("sudo", ["env", ...collectPortlessEnvArgs(), ...stopArgs], {
+  const result = spawnSync4("sudo", ["env", ...collectPortlessEnvArgs2(), ...stopArgs], {
+    stdio: "inherit",
+    timeout: SUDO_SPAWN_TIMEOUT_MS
+  });
+  return result.status === 0;
+}
+function runCleanWithSudo(reason) {
+  console.log(colors_default.yellow(`${reason} Requesting sudo...`));
+  const home = process.env.HOME;
+  const result = spawnSync4(
+    "sudo",
+    [
+      "env",
+      ...collectPortlessEnvArgs2(),
+      ...home ? [`HOME=${home}`] : [],
+      process.execPath,
+      getEntryScript(),
+      "clean"
+    ],
+    {
+      stdio: "inherit",
+      timeout: SUDO_SPAWN_TIMEOUT_MS
+    }
+  );
+  return result.status === 0;
+}
+function runServiceUninstallWithSudo(reason) {
+  console.log(colors_default.yellow(`${reason} Requesting sudo...`));
+  const result = spawnSync4("sudo", buildServiceUninstallSudoArgs(getEntryScript()), {
     stdio: "inherit",
     timeout: SUDO_SPAWN_TIMEOUT_MS
   });
@@ -2715,11 +3712,11 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict) {
     console.warn(chalk.yellow(`LAN mode disabled: ${reason}`));
   }
   const routesPath = store.getRoutesPath();
-  if (!fs8.existsSync(routesPath)) {
-    fs8.writeFileSync(routesPath, "[]", { mode: FILE_MODE });
+  if (!fs9.existsSync(routesPath)) {
+    fs9.writeFileSync(routesPath, "[]", { mode: FILE_MODE });
   }
   try {
-    fs8.chmodSync(routesPath, FILE_MODE);
+    fs9.chmodSync(routesPath, FILE_MODE);
   } catch {
   }
   fixOwnership(routesPath);
@@ -2779,7 +3776,7 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict) {
     }
   };
   try {
-    watcher = fs8.watch(routesPath, () => {
+    watcher = fs9.watch(routesPath, () => {
       if (debounceTimer) clearTimeout(debounceTimer);
       debounceTimer = setTimeout(reloadRoutes, DEBOUNCE_MS);
     });
@@ -2829,8 +3826,8 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict) {
     redirectServer.listen(80);
   }
   server.listen(proxyPort, () => {
-    fs8.writeFileSync(store.pidPath, process.pid.toString(), { mode: FILE_MODE });
-    fs8.writeFileSync(store.portFilePath, proxyPort.toString(), { mode: FILE_MODE });
+    fs9.writeFileSync(store.pidPath, process.pid.toString(), { mode: FILE_MODE });
+    fs9.writeFileSync(store.portFilePath, proxyPort.toString(), { mode: FILE_MODE });
     writeTlsMarker(store.dir, isTls);
     writeTldFile(store.dir, tld);
     writeLanMarker(store.dir, activeLanIp);
@@ -2846,7 +3843,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(`  ${path8.join(store.dir, "ca.pem")}`));
+        console.log(chalk.gray(`  ${path9.join(store.dir, "ca.pem")}`));
       }
       if (!lanIpPinned) {
         lanMonitor = startLanIpMonitor({
@@ -2878,11 +3875,11 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict) {
       redirectServer.close();
     }
     try {
-      fs8.unlinkSync(store.pidPath);
+      fs9.unlinkSync(store.pidPath);
     } catch {
     }
     try {
-      fs8.unlinkSync(store.portFilePath);
+      fs9.unlinkSync(store.portFilePath);
     } catch {
     }
     writeTlsMarker(store.dir, false);
@@ -2912,7 +3909,7 @@ function sudoStopOrHint(port) {
 }
 async function stopProxy(store, proxyPort, _tls) {
   const pidPath = store.pidPath;
-  if (!fs8.existsSync(pidPath)) {
+  if (!fs9.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);
@@ -2920,7 +3917,7 @@ async function stopProxy(store, proxyPort, _tls) {
         try {
           process.kill(pid, "SIGTERM");
           try {
-            fs8.unlinkSync(store.portFilePath);
+            fs9.unlinkSync(store.portFilePath);
           } catch {
           }
           writeTlsMarker(store.dir, false);
@@ -2958,10 +3955,10 @@ async function stopProxy(store, proxyPort, _tls) {
     return;
   }
   try {
-    const pid = parseInt(fs8.readFileSync(pidPath, "utf-8"), 10);
+    const pid = parseInt(fs9.readFileSync(pidPath, "utf-8"), 10);
     if (isNaN(pid)) {
       console.error(colors_default.red("Corrupted PID file. Removing it."));
-      fs8.unlinkSync(pidPath);
+      fs9.unlinkSync(pidPath);
       writeTlsMarker(store.dir, false);
       writeTldFile(store.dir, DEFAULT_TLD);
       writeLanMarker(store.dir, null);
@@ -2975,9 +3972,9 @@ async function stopProxy(store, proxyPort, _tls) {
         return;
       }
       console.log(colors_default.yellow("Proxy process is no longer running. Cleaning up stale files."));
-      fs8.unlinkSync(pidPath);
+      fs9.unlinkSync(pidPath);
       try {
-        fs8.unlinkSync(store.portFilePath);
+        fs9.unlinkSync(store.portFilePath);
       } catch {
       }
       writeTlsMarker(store.dir, false);
@@ -2992,16 +3989,16 @@ async function stopProxy(store, proxyPort, _tls) {
         )
       );
       console.log(colors_default.yellow("Removing stale PID file."));
-      fs8.unlinkSync(pidPath);
+      fs9.unlinkSync(pidPath);
       writeTlsMarker(store.dir, false);
       writeTldFile(store.dir, DEFAULT_TLD);
       writeLanMarker(store.dir, null);
       return;
     }
     process.kill(pid, "SIGTERM");
-    fs8.unlinkSync(pidPath);
+    fs9.unlinkSync(pidPath);
     try {
-      fs8.unlinkSync(store.portFilePath);
+      fs9.unlinkSync(store.portFilePath);
     } catch {
     }
     writeTlsMarker(store.dir, false);
@@ -3124,7 +4121,7 @@ async function ensureProxyRunning(proxyPort, tls2, desired) {
     proxyPort: startPort
   });
   const startArgs = [getEntryScript(), "proxy", "start", ...proxyStartConfig.args];
-  const result = spawnSync3(process.execPath, startArgs, {
+  const result = spawnSync4(process.execPath, startArgs, {
     stdio: "inherit",
     timeout: SUDO_SPAWN_TIMEOUT_MS
   });
@@ -3142,10 +4139,10 @@ async function ensureProxyRunning(proxyPort, tls2, desired) {
   if (!discovered) {
     console.error(colors_default.red("Failed to start proxy."));
     const fallbackDir = resolveStateDir(effectivePort);
-    const logPath = path8.join(fallbackDir, "proxy.log");
+    const logPath = path9.join(fallbackDir, "proxy.log");
     console.error(colors_default.blue("Try starting it manually:"));
     console.error(colors_default.cyan(`  ${manualStartCommand}`));
-    if (fs8.existsSync(logPath)) {
+    if (fs9.existsSync(logPath)) {
       console.error(colors_default.gray(`Logs: ${logPath}`));
     }
     process.exit(1);
@@ -3163,14 +4160,17 @@ portless
   let tsBaseUrl;
   if (wantsTailscale) {
     try {
-      const tsReady = ensureTailscaleReady();
+      const tsReady = ensureTailscaleReady({
+        requireFunnel: wantsFunnel,
+        requireHttps: true
+      });
       tsBaseUrl = tsReady.baseUrl;
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       console.error(colors_default.red(`Error: ${message}`));
       if (message.includes("not found")) {
         console.error(colors_default.blue("Install Tailscale: https://tailscale.com/download"));
-      } else {
+      } else if (!message.includes("not enabled on your tailnet")) {
         console.error(colors_default.blue("Make sure Tailscale is connected:"));
         console.error(colors_default.cyan("  tailscale up"));
       }
@@ -3299,7 +4299,7 @@ portless
     } catch {
     }
   }
-  const basename5 = path8.basename(commandArgs[0]);
+  const basename5 = path9.basename(commandArgs[0]);
   const isExpo = basename5 === "expo";
   const isExpoLan = isExpo && (lanMode || isLanEnvEnabled());
   const hostBind = isExpoLan ? void 0 : "127.0.0.1";
@@ -3309,8 +4309,8 @@ portless
   injectFrameworkFlags(commandArgs, port);
   const caEnv = {};
   if (tls2 && !process.env.NODE_EXTRA_CA_CERTS) {
-    const caPath = path8.join(stateDir, "ca.pem");
-    if (fs8.existsSync(caPath)) {
+    const caPath = path9.join(stateDir, "ca.pem");
+    if (fs9.existsSync(caPath)) {
       caEnv.NODE_EXTRA_CA_CERTS = caPath;
     }
   }
@@ -3507,6 +4507,9 @@ ${colors_default.bold("Install:")}
   ${colors_default.cyan("npm install -g portless")}          Global (recommended)
   ${colors_default.cyan("npm install -D portless")}          Project dev dependency
 
+${colors_default.bold("Requirements:")}
+  Node.js 24+
+
 ${colors_default.bold("Usage:")}
   ${colors_default.cyan("portless")}                         Run dev script through proxy
   ${colors_default.cyan("portless")}                         From monorepo root: run all workspace packages
@@ -3515,6 +4518,7 @@ ${colors_default.bold("Usage:")}
   ${colors_default.cyan("portless <name> <cmd>")}            Run with an explicit app name
   ${colors_default.cyan("portless proxy start")}             Start the proxy (HTTPS on port 443, daemon)
   ${colors_default.cyan("portless proxy stop")}              Stop the proxy
+  ${colors_default.cyan("portless service install")}         Start proxy automatically when the OS starts
   ${colors_default.cyan("portless get <name>")}              Print URL for a service (for cross-service refs)
   ${colors_default.cyan("portless alias <name> <port>")}     Register a static route (e.g. for Docker)
   ${colors_default.cyan("portless alias --remove <name>")}   Remove a static route
@@ -3532,6 +4536,9 @@ ${colors_default.bold("Examples:")}
   portless myapp next dev             # -> https://myapp.localhost
   portless run next dev               # -> https://<project>.localhost
   portless run next dev               # in worktree -> https://<worktree>.<project>.localhost
+  portless service install            # Start HTTPS proxy on OS startup
+  portless service install --lan      # Persist LAN mode in the startup service
+  portless service install --wildcard # Persist wildcard routing in the startup service
   portless get backend                # -> https://backend.localhost
   portless myapp --tailscale next dev # -> also https://<node>.ts.net (tailnet)
   portless myapp --funnel next dev    # -> also https://<node>.ts.net (public)
@@ -3590,7 +4597,9 @@ ${colors_default.bold("Tailscale sharing:")}
   Each app is root-mounted on its own Tailscale HTTPS port (443, then 8443,
   8444, etc.) so no basePath configuration is needed.
   Use --funnel to expose your dev server to the public internet via
-  Tailscale Funnel. Requires Tailscale CLI to be installed and connected.
+  Tailscale Funnel. Requires Tailscale CLI to be installed and connected,
+  with Tailscale HTTPS certificates enabled. Funnel must also be enabled
+  on your tailnet.
   ${colors_default.cyan("portless myapp --tailscale next dev")}
   ${colors_default.cyan("portless myapp --funnel next dev")}
 
@@ -3609,6 +4618,7 @@ ${colors_default.bold("Options:")}
   --foreground                  Run proxy in foreground (for debugging)
   --tld <tld>                   Use a custom TLD instead of .localhost (e.g. test, dev)
   --wildcard                    Allow unregistered subdomains to fall back to parent route
+  --state-dir <path>            Use a custom state directory with service install
   --app-port <number>           Use a fixed port for the app (skip auto-assignment)
   --tailscale                   Share the app on your Tailscale network (tailnet)
   --funnel                      Share the app publicly via Tailscale Funnel
@@ -3621,6 +4631,7 @@ ${colors_default.bold("Environment variables:")}
   PORTLESS_APP_PORT=<number>    Use a fixed port for the app (same as --app-port)
   PORTLESS_HTTPS=0              Disable HTTPS (same as --no-tls)
   PORTLESS_LAN=1                Enable LAN mode when set to 1 (set in .bashrc / .zshrc)
+  PORTLESS_LAN_IP=<address>     Pin a specific LAN IP for LAN mode
   PORTLESS_TLD=<tld>            Use a custom TLD (e.g. test, dev; default: localhost)
   PORTLESS_WILDCARD=1           Allow unregistered subdomains to fall back to parent route
   PORTLESS_SYNC_HOSTS=0         Disable auto-sync of ${HOSTS_DISPLAY} (on by default)
@@ -3650,20 +4661,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, clean, prune, proxy are subcommands and
+  run, get, alias, hosts, list, trust, clean, prune, proxy, service 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.12.0");
+  console.log("0.13.1");
   process.exit(0);
 }
 async function handleTrust() {
   const { dir } = await discoverState();
-  if (!fs8.existsSync(dir)) {
-    fs8.mkdirSync(dir, { recursive: true });
+  if (!fs9.existsSync(dir)) {
+    fs9.mkdirSync(dir, { recursive: true });
   }
   const { caGenerated } = ensureCerts(dir);
   if (caGenerated) {
@@ -3675,14 +4686,14 @@ async function handleTrust() {
     console.log(colors_default.gray("Browsers will now trust portless HTTPS certificates."));
     return;
   }
-  const isPermissionError = result.error?.includes("Permission denied") || result.error?.includes("EACCES");
-  if (isPermissionError && !isWindows && process.getuid?.() !== 0) {
+  const isPermissionError2 = result.error?.includes("Permission denied") || result.error?.includes("EACCES");
+  if (isPermissionError2 && !isWindows && process.getuid?.() !== 0) {
     console.log(colors_default.yellow("Trusting the CA requires elevated privileges. Requesting sudo..."));
-    const sudoResult = spawnSync3(
+    const sudoResult = spawnSync4(
       "sudo",
       [
         "env",
-        ...collectPortlessEnvArgs(),
+        ...collectPortlessEnvArgs2(),
         `PORTLESS_STATE_DIR=${dir}`,
         process.execPath,
         getEntryScript(),
@@ -3704,10 +4715,11 @@ async function handleClean(args) {
     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}.
+Stops the proxy if it is running, uninstalls the startup service if installed,
+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.
@@ -3728,6 +4740,23 @@ ${colors_default.bold("Options:")}
     console.error(colors_default.cyan("  portless clean --help"));
     process.exit(1);
   }
+  const serviceResult = tryUninstallService(getEntryScript());
+  if (serviceResult.removed) {
+    console.log(colors_default.green("Removed startup service."));
+  } else if (serviceResult.needsElevation && !isWindows && (process.getuid?.() ?? -1) !== 0) {
+    if (!runServiceUninstallWithSudo("Removing the startup service requires elevated privileges.")) {
+      console.error(colors_default.red("Failed to remove startup service with sudo."));
+      process.exit(1);
+    }
+  } else if (serviceResult.error) {
+    const adminHint = isWindows ? " Run as Administrator and try again." : "";
+    const message = `Could not remove startup service: ${serviceResult.error}${adminHint}`;
+    if (serviceResult.installed) {
+      console.error(colors_default.red(message));
+      process.exit(1);
+    }
+    console.warn(colors_default.yellow(message));
+  }
   console.log(colors_default.cyan("Stopping proxy if it is running..."));
   const { dir, port, tls: tls2 } = await discoverState();
   const store = new RouteStore(dir, {
@@ -3746,8 +4775,8 @@ ${colors_default.bold("Options:")}
   }
   const stateDirs = collectStateDirsForCleanup();
   for (const stateDir of stateDirs) {
-    const caPath = path8.join(stateDir, "ca.pem");
-    if (!fs8.existsSync(caPath)) continue;
+    const caPath = path9.join(stateDir, "ca.pem");
+    if (!fs9.existsSync(caPath)) continue;
     const wasTrusted = isCATrusted(stateDir);
     if (!wasTrusted) continue;
     const untrustResult = untrustCA(stateDir);
@@ -3769,18 +4798,7 @@ Try: sudo portless clean (Linux), or delete the certificate manually.`
   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 = spawnSync3(
-      "sudo",
-      ["env", ...collectPortlessEnvArgs(), process.execPath, getEntryScript(), "clean"],
-      {
-        stdio: "inherit",
-        timeout: SUDO_SPAWN_TIMEOUT_MS
-      }
-    );
-    if (result.status !== 0) {
+    if (!runCleanWithSudo(`Updating ${HOSTS_DISPLAY} requires elevated privileges.`)) {
       console.error(colors_default.red(`Failed to update ${HOSTS_DISPLAY}. Run: sudo portless clean`));
       process.exit(1);
     }
@@ -4011,9 +5029,9 @@ ${colors_default.bold("Auto-sync:")}
           `Writing to ${HOSTS_DISPLAY} requires elevated privileges. Requesting sudo...`
         )
       );
-      const result = spawnSync3(
+      const result = spawnSync4(
         "sudo",
-        ["env", ...collectPortlessEnvArgs(), process.execPath, getEntryScript(), "hosts", "clean"],
+        ["env", ...collectPortlessEnvArgs2(), process.execPath, getEntryScript(), "hosts", "clean"],
         {
           stdio: "inherit",
           timeout: SUDO_SPAWN_TIMEOUT_MS
@@ -4064,9 +5082,9 @@ ${colors_default.bold("Usage: portless hosts <command>")}
     console.log(
       colors_default.yellow(`Writing to ${HOSTS_DISPLAY} requires elevated privileges. Requesting sudo...`)
     );
-    const result = spawnSync3(
+    const result = spawnSync4(
       "sudo",
-      ["env", ...collectPortlessEnvArgs(), process.execPath, getEntryScript(), "hosts", "sync"],
+      ["env", ...collectPortlessEnvArgs2(), process.execPath, getEntryScript(), "hosts", "sync"],
       {
         stdio: "inherit",
         timeout: SUDO_SPAWN_TIMEOUT_MS
@@ -4355,7 +5373,7 @@ ${colors_default.bold("LAN mode (--lan):")}
     if (!hasExplicitPort) {
       console.log(colors_default.gray(`(To skip sudo, use an unprivileged port: ${fallbackCommand})`));
     }
-    const result = spawnSync3("sudo", ["env", ...collectPortlessEnvArgs(), ...startArgs], {
+    const result = spawnSync4("sudo", ["env", ...collectPortlessEnvArgs2(), ...startArgs], {
       stdio: "inherit",
       timeout: SUDO_SPAWN_TIMEOUT_MS
     });
@@ -4365,8 +5383,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 = path8.join(resolveStateDir(proxyPort), "proxy.log");
-          if (fs8.existsSync(logPath2)) {
+          const logPath2 = path9.join(resolveStateDir(proxyPort), "proxy.log");
+          if (fs9.existsSync(logPath2)) {
             console.error(colors_default.gray(`Logs: ${logPath2}`));
           }
         }
@@ -4405,8 +5423,8 @@ ${colors_default.bold("LAN mode (--lan):")}
     store.ensureDir();
     if (customCertPath && customKeyPath) {
       try {
-        const cert = fs8.readFileSync(customCertPath);
-        const key = fs8.readFileSync(customKeyPath);
+        const cert = fs9.readFileSync(customCertPath);
+        const key = fs9.readFileSync(customKeyPath);
         const certStr = cert.toString("utf-8");
         const keyStr = key.toString("utf-8");
         if (!certStr.includes("-----BEGIN CERTIFICATE-----")) {
@@ -4451,9 +5469,9 @@ ${colors_default.bold("LAN mode (--lan):")}
           console.warn(colors_default.cyan("  portless trust"));
         }
       }
-      const cert = fs8.readFileSync(certs.certPath);
-      const key = fs8.readFileSync(certs.keyPath);
-      const ca = fs8.readFileSync(certs.caPath);
+      const cert = fs9.readFileSync(certs.certPath);
+      const key = fs9.readFileSync(certs.keyPath);
+      const ca = fs9.readFileSync(certs.caPath);
       tlsOptions = {
         cert,
         key,
@@ -4468,11 +5486,11 @@ ${colors_default.bold("LAN mode (--lan):")}
     return;
   }
   store.ensureDir();
-  const logPath = path8.join(stateDir, "proxy.log");
-  const logFd = fs8.openSync(logPath, "a");
+  const logPath = path9.join(stateDir, "proxy.log");
+  const logFd = fs9.openSync(logPath, "a");
   try {
     try {
-      fs8.chmodSync(logPath, FILE_MODE);
+      fs9.chmodSync(logPath, FILE_MODE);
     } catch {
     }
     fixOwnership(logPath);
@@ -4503,13 +5521,13 @@ ${colors_default.bold("LAN mode (--lan):")}
     });
     child.unref();
   } finally {
-    fs8.closeSync(logFd);
+    fs9.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 (fs8.existsSync(logPath)) {
+    if (fs9.existsSync(logPath)) {
       console.error(colors_default.gray(`Logs: ${logPath}`));
     }
     process.exit(1);
@@ -4661,8 +5679,8 @@ async function spawnProxiedApp(app, stateDir, proxyPort, tls2, tld, exitCodes) {
       PORTLESS_URL: url
     };
     if (tls2) {
-      const caPath = path8.join(stateDir, "ca.pem");
-      if (fs8.existsSync(caPath)) {
+      const caPath = path9.join(stateDir, "ca.pem");
+      if (fs9.existsSync(caPath)) {
         env.NODE_EXTRA_CA_CERTS = caPath;
       }
     }
@@ -4744,7 +5762,7 @@ async function handleDefaultMulti(wsRoot, globalScript, extraArgs = []) {
   }
   const apps = [];
   for (const pkg of packages) {
-    const rel = path8.relative(wsRoot, pkg.dir).replace(/\\/g, "/");
+    const rel = path9.relative(wsRoot, pkg.dir).replace(/\\/g, "/");
     const rootOverride = loaded ? resolveAppConfig(loaded.config, loaded.configDir, pkg.dir) : null;
     let pkgConfig;
     try {
@@ -4852,8 +5870,8 @@ async function runWithTurbo(wsRoot, stateDir, proxyPort, tls2, tld, scriptName,
       PORTLESS_URL: url
     };
     if (tls2) {
-      const caPath = path8.join(stateDir, "ca.pem");
-      if (fs8.existsSync(caPath)) {
+      const caPath = path9.join(stateDir, "ca.pem");
+      if (fs9.existsSync(caPath)) {
         entry.NODE_EXTRA_CA_CERTS = caPath;
       }
     }
@@ -4902,8 +5920,8 @@ async function runWithTurbo(wsRoot, stateDir, proxyPort, tls2, tld, scriptName,
   };
   process.on("SIGINT", cleanup);
   process.on("SIGTERM", cleanup);
-  const exitCode = await new Promise((resolve3) => {
-    turboChild.on("exit", (code) => resolve3(code));
+  const exitCode = await new Promise((resolve4) => {
+    turboChild.on("exit", (code) => resolve4(code));
   });
   cleanup();
   if (exitCode !== 0 && exitCode !== null) {
@@ -4967,8 +5985,8 @@ async function runWithDirectSpawn(stateDir, proxyPort, tls2, tld, proxiedApps, t
   process.on("SIGTERM", cleanup);
   await Promise.all(
     children.map(
-      (child) => new Promise((resolve3) => {
-        child.on("exit", () => resolve3());
+      (child) => new Promise((resolve4) => {
+        child.on("exit", () => resolve4());
       })
     )
   );
@@ -5055,6 +6073,7 @@ async function handleNamedMode(args) {
     }
   }
   const safeName = parsed.name.split(".").map((label) => truncateLabel(label)).join(".");
+  parseHostname(safeName, DEFAULT_TLD);
   const { dir, port, tls: tls2, tld, lanMode, lanIp } = await discoverState();
   const store = new RouteStore(dir, {
     onWarning: (msg) => console.warn(colors_default.yellow(msg))
@@ -5166,7 +6185,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 === 0 || args.length >= 2 && args[0] !== "proxy" && args[0] !== "clean")) {
+  if (skipPortless && (isRunCommand || args.length === 0 || args.length >= 2 && args[0] !== "proxy" && args[0] !== "clean" && args[0] !== "service")) {
     const parsed = isRunCommand ? parseRunArgs(args) : parseAppArgs(args);
     let commandArgs = parsed.commandArgs;
     if (commandArgs.length === 0 && (isRunCommand || args.length === 0)) {
@@ -5230,6 +6249,10 @@ async function main() {
       await handleProxy(args);
       return;
     }
+    if (args[0] === "service") {
+      await handleService(args, { entryScript: getEntryScript() });
+      return;
+    }
   }
   if (isRunCommand) {
     await handleRunMode(args, globalScript);