portless 0.12.0 → 0.13.0

package/README.md

@@ -249,6 +249,18 @@ portless trust
 
 On Linux, `portless trust` supports Debian/Ubuntu, Arch, Fedora/RHEL/CentOS, and openSUSE (via `update-ca-certificates` or `update-ca-trust`). On Windows, it uses `certutil` to add the CA to the system trust store.
 
+## Start at OS startup
+
+Install the proxy as an OS startup service so clean HTTPS URLs are available after reboot without starting the proxy from a terminal:
+
+```bash
+portless service install
+portless service status
+portless service uninstall
+```
+
+The service uses portless defaults: HTTPS on port 443 with `.localhost` names. 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. Installation and removal may require administrator privileges. `portless clean` automatically removes the service.
+
 ## LAN mode
 
 ```bash
@@ -300,9 +312,11 @@ portless myapp --funnel next dev
 # -> https://devbox.yourteam.ts.net    (public)
 ```
 
+Tailscale HTTPS certificates must be enabled before `--tailscale` or `--funnel` can register HTTPS URLs. Funnel must also be enabled for the tailnet and node before `--funnel` can register the public URL. If either setting is missing, portless exits before starting the child process.
+
 Set `PORTLESS_TAILSCALE=1` in your shell profile or `.env` to share every app by default. `portless list` shows both local and tailnet URLs. Tailscale serve registrations are cleaned up automatically when the app exits.
 
-Requires the Tailscale CLI to be installed and connected (`tailscale up`).
+Requires the Tailscale CLI to be installed and connected (`tailscale up`), with Tailscale HTTPS certificates enabled.
 
 ## Commands
 
@@ -332,6 +346,11 @@ portless proxy start -p 1355     # Start on a custom port (no sudo)
 portless proxy start --foreground  # Start in foreground (for debugging)
 portless proxy start --wildcard  # Allow unregistered subdomains to fall back to parent
 portless proxy stop              # Stop the proxy
+
+# OS startup service
+portless service install         # Start HTTPS proxy when the OS starts
+portless service status          # Show service and proxy status
+portless service uninstall       # Remove the startup service
 ```
 
 ### Options
@@ -378,7 +397,7 @@ PORTLESS_TAILSCALE_URL           Tailscale URL of the app (when --tailscale is a
 NODE_EXTRA_CA_CERTS              Path to the portless CA (when HTTPS is active)
 ```
 
-> **Reserved names:** `run`, `get`, `alias`, `hosts`, `list`, `trust`, `clean`, `prune`, and `proxy` are subcommands and cannot be used as app names directly. Use `portless run <cmd>` to infer the name from your project, or `portless --name <name> <cmd>` to force any name including reserved ones.
+> **Reserved names:** `run`, `get`, `alias`, `hosts`, `list`, `trust`, `clean`, `prune`, `proxy`, and `service` are subcommands and cannot be used as app names directly. Use `portless run <cmd>` to infer the name from your project, or `portless --name <name> <cmd>` to force any name including reserved ones.
 
 ## Uninstall / reset
 

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]
@@ -2524,6 +2591,522 @@ 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 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";
+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 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) {
+  const config = buildProxyStartConfig({
+    useHttps: true,
+    lanMode: false,
+    tld: DEFAULT_TLD,
+    foreground: true,
+    includePort: true,
+    proxyPort: SERVICE_PORT,
+    skipTrust: true
+  });
+  return [entryScript, "proxy", "start", ...config.args];
+}
+function buildServiceEnv(ctx) {
+  const env = {
+    PORTLESS_STATE_DIR: ctx.stateDir
+  };
+  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 ctx = {
+    platform: options.platform,
+    nodePath: options.nodePath,
+    entryScript: options.entryScript,
+    stateDir: options.stateDir || defaultStateDir(options.platform, options.userHome),
+    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"
+  };
+  const proxyCommand = buildProxyCommand(ctx.entryScript);
+  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,
+      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,
+      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,
+    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) {
+  if (!isSupportedPlatform(process.platform)) {
+    throw new Error(`Unsupported platform: ${process.platform}`);
+  }
+  const user = resolveUserContext(process.platform);
+  return buildServiceSpec({
+    platform: process.platform,
+    nodePath: process.execPath,
+    entryScript,
+    userHome: user.home,
+    uid: user.uid,
+    gid: user.gid,
+    username: user.username,
+    stateDir: process.env.PORTLESS_STATE_DIR || defaultStateDir(process.platform, user.home),
+    pathEnv: process.env.PATH,
+    programData: process.env.ProgramData
+  });
+}
+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 stopExistingProxy(entryScript, runner) {
+  runRequired(runner, process.execPath, [
+    entryScript,
+    "proxy",
+    "stop",
+    "--port",
+    SERVICE_PORT.toString()
+  ]);
+}
+function prepareTrust(stateDir) {
+  fs8.mkdirSync(stateDir, { recursive: true });
+  fixOwnership(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."));
+}
+async function installService(entryScript, runner) {
+  requireUnixElevation([entryScript, "service", "install"], runner);
+  const spec = currentServiceSpec(entryScript);
+  prepareTrust(spec.stateDir);
+  if (spec.platform === "darwin") {
+    runOptional(runner, "launchctl", ["bootout", "system", spec.plistPath]);
+    stopExistingProxy(entryScript, runner);
+    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]);
+    stopExistingProxy(entryScript, runner);
+    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]);
+    stopExistingProxy(entryScript, runner);
+    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}`));
+}
+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 proxyRunning = await isProxyRunning(SERVICE_PORT);
+  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, 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,
+      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,
+    details: spec.taskName
+  };
+}
+async function printServiceStatus(entryScript, runner) {
+  const spec = currentServiceSpec(entryScript);
+  const status = await getServiceStatus(entryScript, runner);
+  console.log(colors_default.bold("portless service"));
+  console.log(`  Manager state: ${status.managerState}`);
+  console.log(`  Installed: ${status.installed ? "yes" : "no"}`);
+  console.log(`  Proxy on 443: ${status.proxyRunning ? "responding" : "not responding"}`);
+  console.log(`  State directory: ${spec.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 uninstall")}    Stop and remove the startup service
+  ${colors_default.cyan("portless service status")}       Show service and proxy status
+
+${colors_default.bold("Notes:")}
+  The service uses the default clean URL mode: HTTPS on port 443.
+  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);
+      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 +3259,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 +3280,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 +3326,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 +3390,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 +3440,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 +3457,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 +3489,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 +3523,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 +3531,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 +3569,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 +3586,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 +3603,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 +3735,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 +3753,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 +3774,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 +3913,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 +3923,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;
     }
   }
@@ -3515,6 +4129,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 +4147,7 @@ ${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 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 +4206,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")}
 
@@ -3650,20 +4268,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.0");
   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 +4293,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 +4322,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 +4347,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 +4382,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 +4405,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 +4636,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 +4689,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 +4980,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 +4990,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 +5030,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 +5076,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 +5093,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 +5128,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 +5286,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 +5369,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 +5477,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;
       }
     }
@@ -5166,7 +5791,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 +5855,10 @@ async function main() {
       await handleProxy(args);
       return;
     }
+    if (args[0] === "service") {
+      await handleService(args, { entryScript: getEntryScript() });
+      return;
+    }
   }
   if (isRunCommand) {
     await handleRunMode(args, globalScript);

package/package.json

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