@cloudless-ai/node-agent 0.0.24 → 0.0.26

package/README.md

@@ -12,8 +12,9 @@ During install, the script:
 
 1. Detects your OS/CPU architecture.
 2. Installs the matching precompiled binary bundled in this package, including the embedded llama.cpp backend.
-3. On macOS, also installs `CloudlessMenuBar`.
-4. Prompts for your router API key and writes `~/.cloudless/agent.yaml`.
+3. On macOS and Windows, also installs the `CloudlessMenuBar` menu bar / system tray app and registers it to **start at login** (macOS LaunchAgent `app.cloudless.node-agent`; Windows `HKCU\Software\Microsoft\Windows\CurrentVersion\Run\CloudlessAINodeTray`). Turn it off later from the app's "Start on Login" item or `cloudless-node autostart off`, or skip it at install with `CLOUDLESS_NO_START_ON_LOGIN=1`.
+4. Points `~/.cloudless/agent.yaml` at the production router (`https://api.cloudless-ai.app`). An existing token is kept only if it was already for production; otherwise it is cleared and the node links itself via browser sign-in on first start (or from the tray's "Connect" item).
+5. On macOS and Windows, stops any running menu bar app/tray and agent from a previous install, then **starts the menu bar app / tray** right away. It runs the node agent, restarts it if it exits (with backoff if it keeps crashing), and stops it when it quits or is closed for any reason. On a fresh install your browser opens so you can sign in and link the node to Cloudless AI. Set `CLOUDLESS_NO_LAUNCH=1` to skip starting it (it is also skipped when `CI` is set, and on macOS when installing as root, e.g. with `sudo`).
 
 ## Commands
 
@@ -24,19 +25,36 @@ cloudless-node menubar
 cloudless-node stop
 cloudless-node set-api-key
 cloudless-node configure
+cloudless-node autostart on|off
 ```
 
+## Uninstall
+
+npm has no uninstall hook, so stop the node and remove the start-at-login registration first:
+
+```bash
+cloudless-node stop          # stops the node (on macOS/Windows, the menu bar app/tray and its agent)
+cloudless-node autostart off
+npm uninstall -g @cloudless-ai/node-agent
+```
+
+Binaries, models and config under `~/.cloudless` are left in place; delete that directory to remove them.
+
 ## Non-interactive install
 
 ```bash
-CLOUDLESS_NODE_API_KEY=your_key CLOUDLESS_ROUTER_URL=http://router-host:8080 npm install -g @cloudless-ai/node-agent
+CLOUDLESS_NODE_API_KEY=your_node_key npm install -g @cloudless-ai/node-agent
 ```
 
+Install always targets the production router. To point a node at a different router (for example local development), run `cloudless-node configure` after install.
+
 ## Notes
 
+- Run the installer/launcher tests with `npm test` (Node's built-in test runner, no dependencies).
 - By default binaries are installed to `~/.cloudless/bin`.
 - Configuration is written to `~/.cloudless/agent.yaml`.
-- `cloudless-node start` launches the node + menubar in the background by default.
-- Use `cloudless-node start --interactive` to keep it attached to your terminal.
+- `cloudless-node start` launches the node in the background by default. On macOS and Windows it starts the menu bar app / tray, which owns the agent (only one runs per user session).
+- Use `cloudless-node start --interactive` to keep it attached to your terminal (this runs the agent alone, without the menu bar app / tray).
 - Installation has no GitHub release dependency; binaries are bundled in the npm tarball with the embedded backend.
+- Upgrading stops the running menu bar app/tray and agent, installs the new binaries and starts the new menu bar app/tray. On Windows any still-locked binary is moved aside as `*.old-<timestamp>` and cleaned up on the next install; on macOS the old file is unlinked first so the new signed binary isn't killed by the code-signature cache.
 - For internet demos, set `router.advertise_address` in `~/.cloudless/agent.yaml` (or `CLOUDLESS_AGENT_ADVERTISE_ADDRESS`) to a public tunnel URL so router/dashboard can reach this node.

package/bin/cloudless-node.js

@@ -8,10 +8,16 @@ const {
   MENUBAR_BINARY_NAME,
   BIN_DIR,
   CLOUDLESS_ROOT,
+  HOME,
   promptSecret,
   promptLine,
   writeOrUpdateConfig,
   CONFIG_PATH,
+  PRODUCTION_ROUTER_URL,
+  enableStartOnLogin,
+  disableStartOnLogin,
+  launchTray,
+  stopTrayApp,
 } = require("../scripts/common");
 
 const agentBin = path.join(BIN_DIR, AGENT_BINARY_NAME);
@@ -89,21 +95,14 @@ function clearSupervisorPid() {
   } catch {}
 }
 
+// runSupervisor runs the agent in the foreground (`start --interactive`) or
+// for a detached `start` with custom agent args / on platforms without a
+// tray. The tray/menu bar app supervises its own agent, so it isn't started
+// here to avoid two competing supervisors.
 function runSupervisor(agentArgs) {
   checkBinary(agentBin);
 
-  const supportsMenuBar = process.platform === "darwin" || process.platform === "win32";
-  const startTime = Date.now();
-
   const agent = spawn(agentBin, withDefaultConfig(agentArgs), { stdio: "inherit" });
-
-  let menubar = null;
-  if (supportsMenuBar) {
-    if (fs.existsSync(menubarBin)) {
-      menubar = spawn(menubarBin, [], { stdio: "ignore" });
-    }
-  }
-
   writeSupervisorPid();
 
   let shuttingDown = false;
@@ -113,7 +112,6 @@ function runSupervisor(agentArgs) {
     }
     shuttingDown = true;
     agent.kill();
-    if (menubar) menubar.kill();
   }
 
   process.on("SIGINT", shutdown);
@@ -121,29 +119,9 @@ function runSupervisor(agentArgs) {
   process.on("exit", clearSupervisorPid);
 
   agent.on("exit", (code) => {
-    const exitedQuickly = Date.now() - startTime < 5000;
-    if (code !== 0 && code !== null && exitedQuickly) {
-      process.stderr.write(
-        "cloudless-node: agent failed to start, keeping menubar attached to existing local agent if available\n"
-      );
-      return;
-    }
     clearSupervisorPid();
     process.exit(code ?? 0);
   });
-
-  if (menubar) {
-    menubar.on("exit", () => {
-      agent.kill();
-      clearSupervisorPid();
-      process.exit(0);
-    });
-    menubar.on("exit", (code) => {
-      if (code !== 0 && code !== null) {
-        process.stderr.write(`cloudless-node: menubar exited with code ${code}\n`);
-      }
-    });
-  }
 }
 
 function parseStartArgs(args) {
@@ -159,13 +137,27 @@ function parseStartArgs(args) {
   return { interactive, agentArgs };
 }
 
+const hasTrayApp = process.platform === "win32" || process.platform === "darwin";
+const trayLabel = process.platform === "darwin" ? "menu bar app" : "tray";
+
 function startDetached(agentArgs) {
+  // The tray/menu bar app starts the agent, restarts it if it dies and stops
+  // it when it quits, so `start` just launches it (a second copy exits
+  // immediately if one is already running).
+  if (hasTrayApp && fs.existsSync(menubarBin) && agentArgs.length === 0) {
+    launchTray(menubarBin);
+    process.stdout.write(
+      `cloudless-node: started the Cloudless AI ${trayLabel}; it runs the node agent. Quit the ${trayLabel} (or run \`cloudless-node stop\`) to stop it.\n`,
+    );
+    return;
+  }
   const existing = readSupervisorPid();
   if (existing) {
     process.stdout.write(`cloudless-node: already running (supervisor pid ${existing})\n`);
     return;
   }
   const child = spawn(process.execPath, [__filename, "run-supervised", ...agentArgs], {
+    cwd: HOME,
     detached: true,
     stdio: "ignore",
   });
@@ -174,21 +166,17 @@ function startDetached(agentArgs) {
 }
 
 function stopSupervisor() {
+  // Ending the tray/menu bar app also ends its agent (kill-on-close job on
+  // Windows, SIGTERM handler on macOS).
+  const trayStopped = hasTrayApp ? stopTrayApp() : false;
   const pid = readSupervisorPid();
-  if (!pid) {
-    process.stdout.write("cloudless-node: not running\n");
-    return;
-  }
-  if (!stopProcess(pid)) {
-    clearSupervisorPid();
-    process.stdout.write("cloudless-node: not running\n");
-    return;
-  }
-  process.stdout.write("cloudless-node: stop signal sent\n");
+  const supervisorStopped = pid ? stopProcess(pid) : false;
+  if (!supervisorStopped) clearSupervisorPid();
+  process.stdout.write(trayStopped || supervisorStopped ? "cloudless-node: stopped\n" : "cloudless-node: not running\n");
 }
 
 async function configure() {
-  const defaultURL = "http://localhost:8080";
+  const defaultURL = PRODUCTION_ROUTER_URL;
   process.stdout.write("Cloudless AI node configuration\n\n");
 
   const routerURL =
@@ -210,7 +198,36 @@ async function configure() {
 
 const [, , cmd, ...rest] = process.argv;
 
+function autostart(action) {
+  try {
+    switch (action) {
+      case "on": {
+        if (!fs.existsSync(menubarBin)) {
+          process.stderr.write(`cloudless-node: ${menubarBin} not found; start on login needs the tray/menu bar app.\n`);
+          process.exit(1);
+        }
+        const where = enableStartOnLogin(menubarBin);
+        process.stdout.write(where ? `Start on login enabled (${where})\n` : "Start on login is not supported on this platform\n");
+        return;
+      }
+      case "off":
+        process.stdout.write(disableStartOnLogin() ? "Start on login disabled\n" : "Start on login was not enabled\n");
+        return;
+      default:
+        process.stderr.write("Usage: cloudless-node autostart on|off\n");
+        process.exit(2);
+    }
+  } catch (err) {
+    process.stderr.write(`cloudless-node: ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
 switch (cmd) {
+  case "autostart":
+    autostart(rest[0]);
+    break;
+
   case "configure":
   case "set-api-key":
     configure().catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudless-ai/node-agent",
-  "version": "0.0.24",
+  "version": "0.0.26",
   "description": "Cloudless AI node agent installer and launcher",
   "license": "MIT",
   "homepage": "https://cloudless-ai.app",
@@ -12,7 +12,8 @@
     "cloudless-node": "bin/cloudless-node.js"
   },
   "scripts": {
-    "postinstall": "node ./scripts/postinstall.js"
+    "postinstall": "node ./scripts/postinstall.js",
+    "test": "node --test"
   },
   "engines": {
     "node": ">=18"

package/scripts/common.js

@@ -2,6 +2,7 @@ const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
 const readline = require("node:readline");
+const { spawn, spawnSync } = require("node:child_process");
 
 const HOME = os.homedir();
 const CLOUDLESS_ROOT = path.join(HOME, ".cloudless");
@@ -9,6 +10,16 @@ const BIN_DIR = path.join(CLOUDLESS_ROOT, "bin");
 const CONFIG_PATH = path.join(CLOUDLESS_ROOT, "agent.yaml");
 const AGENT_BINARY_NAME = process.platform === "win32" ? "cloudless-agent.exe" : "cloudless-agent";
 const MENUBAR_BINARY_NAME = process.platform === "win32" ? "CloudlessMenuBar.exe" : "CloudlessMenuBar";
+const AGENT_BINARY_NAME_WINDOWS = "cloudless-agent.exe";
+const MENUBAR_BINARY_NAME_WINDOWS = "CloudlessMenuBar.exe";
+const PRODUCTION_ROUTER_URL = "https://api.cloudless-ai.app";
+
+// Must match the names used by the tray/menu bar apps' own "Start on Login"
+// toggles (apps/node-agent/cmd/tray/autostart_windows.go and
+// apps/menubar-macos LaunchAtLoginController) so their checkboxes reflect it.
+const WINDOWS_RUN_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run";
+const WINDOWS_RUN_VALUE = "CloudlessAINodeTray";
+const MACOS_LAUNCH_AGENT_LABEL = "app.cloudless.node-agent";
 
 function detectTarget() {
   const archMap = {
@@ -33,89 +44,393 @@ function ensureDirs() {
   fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
 }
 
-function installBinary(sourcePath, binaryName) {
-  const targetPath = path.join(BIN_DIR, binaryName);
-  fs.copyFileSync(sourcePath, targetPath);
-  fs.chmodSync(targetPath, 0o755);
+// installBinary copies sourcePath into binDir. On Windows a running executable
+// cannot be overwritten (EBUSY/EPERM), but it can be renamed, so an in-use
+// binary (e.g. the tray started at login) is moved aside first. The stale copy
+// is deleted when possible and otherwise cleaned up by a later install.
+// Elsewhere the old file is unlinked first so the copy gets a new inode:
+// overwriting a signed Mach-O in place makes macOS kill the new binary
+// ("Killed: 9") because the kernel's code-signature cache is keyed on it.
+function installBinary(sourcePath, binaryName, { binDir = BIN_DIR, fsImpl = fs, platform = process.platform } = {}) {
+  const targetPath = path.join(binDir, binaryName);
+  removeStaleBinaries(targetPath, fsImpl);
+  if (platform !== "win32") {
+    fsImpl.rmSync(targetPath, { force: true });
+  }
+  try {
+    fsImpl.copyFileSync(sourcePath, targetPath);
+  } catch (error) {
+    if (!["EBUSY", "EPERM", "EACCES"].includes(error.code) || !fsImpl.existsSync(targetPath)) {
+      throw error;
+    }
+    const stale = `${targetPath}.old-${Date.now()}`;
+    fsImpl.renameSync(targetPath, stale);
+    fsImpl.copyFileSync(sourcePath, targetPath);
+    try {
+      fsImpl.rmSync(stale, { force: true });
+    } catch {}
+  }
+  fsImpl.chmodSync(targetPath, 0o755);
   return targetPath;
 }
 
-function updateRouterConfig(content, { routerURL, token }) {
-  const lines = content.split(/\r?\n/);
-  let routerLine = -1;
-  for (let i = 0; i < lines.length; i++) {
-    if (/^\s*router:\s*$/.test(lines[i])) {
-      routerLine = i;
-      break;
+function removeStaleBinaries(targetPath, fsImpl) {
+  const dir = path.dirname(targetPath);
+  const prefix = `${path.basename(targetPath)}.old-`;
+  let entries = [];
+  try {
+    entries = fsImpl.readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    if (name.startsWith(prefix)) {
+      try {
+        fsImpl.rmSync(path.join(dir, name), { force: true });
+      } catch {}
     }
   }
+}
+
+// yamlString renders value as a YAML double-quoted scalar. JSON string
+// escaping is a valid subset of YAML's, and it escapes backslashes, which
+// matters for Windows paths ("C:\Users" would otherwise be a \U escape).
+function yamlString(value) {
+  return JSON.stringify(String(value));
+}
 
-  if (routerLine === -1) {
-    return `${content.trimEnd()}\n\nrouter:\n  address: "${routerURL}"\n  token: "${token}"\n`;
+// parseYAMLScalar decodes a simple scalar value (double-quoted, single-quoted
+// or plain) and drops any trailing comment.
+function parseYAMLScalar(raw) {
+  const value = raw.trim();
+  if (value.startsWith('"')) {
+    for (let i = 1; i < value.length; i++) {
+      if (value[i] === "\\") {
+        i++;
+        continue;
+      }
+      if (value[i] === '"') {
+        try {
+          return JSON.parse(value.slice(0, i + 1));
+        } catch {
+          return value.slice(1, i);
+        }
+      }
+    }
+    return value.slice(1);
+  }
+  if (value.startsWith("'")) {
+    let out = "";
+    for (let i = 1; i < value.length; i++) {
+      if (value[i] === "'") {
+        if (value[i + 1] === "'") {
+          out += "'";
+          i++;
+          continue;
+        }
+        return out;
+      }
+      out += value[i];
+    }
+    return out;
   }
+  return value.replace(/\s+#.*$/, "").trim();
+}
+
+function isTopLevelKey(line) {
+  return /^[^\s#]/.test(line);
+}
 
-  let blockEnd = lines.length;
-  for (let i = routerLine + 1; i < lines.length; i++) {
-    if (/^\S/.test(lines[i])) {
-      blockEnd = i;
+function findRouterBlock(lines) {
+  const start = lines.findIndex((line) => /^router:\s*(#.*)?$/.test(line));
+  if (start === -1) {
+    return { start: -1, end: -1, indent: "  " };
+  }
+  let end = lines.length;
+  let indent = null;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (isTopLevelKey(lines[i])) {
+      end = i;
       break;
     }
+    if (indent === null && /^\s+[^\s#]/.test(lines[i])) {
+      indent = /^(\s+)/.exec(lines[i])[1];
+    }
+  }
+  return { start, end, indent: indent || "  " };
+}
+
+function childKeyPattern(indent, key) {
+  return new RegExp(`^${indent}${key}:(.*)$`);
+}
+
+function updateRouterConfig(content, { routerURL, token }) {
+  const lines = content.split(/\r?\n/);
+  const { start, end, indent } = findRouterBlock(lines);
+  const addressLineText = `${indent}address: ${yamlString(routerURL)}`;
+  const tokenLineText = `${indent}token: ${yamlString(token)}`;
+
+  if (start === -1) {
+    const prefix = content.trim() === "" ? "" : `${content.trimEnd()}\n\n`;
+    return `${prefix}router:\n${addressLineText}\n${tokenLineText}\n`;
   }
 
   let addressLine = -1;
   let tokenLine = -1;
-  for (let i = routerLine + 1; i < blockEnd; i++) {
-    if (/^\s+address:\s*/.test(lines[i])) {
+  for (let i = start + 1; i < end; i++) {
+    if (childKeyPattern(indent, "address").test(lines[i])) {
       addressLine = i;
     }
-    if (/^\s+token:\s*/.test(lines[i])) {
+    if (childKeyPattern(indent, "token").test(lines[i])) {
       tokenLine = i;
     }
   }
 
-  if (addressLine >= 0) {
-    lines[addressLine] = `  address: "${routerURL}"`;
+  if (tokenLine >= 0) {
+    lines[tokenLine] = tokenLineText;
   } else {
-    lines.splice(routerLine + 1, 0, `  address: "${routerURL}"`);
-    blockEnd += 1;
-    if (tokenLine >= 0) {
-      tokenLine += 1;
-    }
+    lines.splice(start + 1, 0, tokenLineText);
+    if (addressLine >= 0) addressLine += 1;
   }
-
-  if (tokenLine >= 0) {
-    lines[tokenLine] = `  token: "${token}"`;
+  if (addressLine >= 0) {
+    lines[addressLine] = addressLineText;
   } else {
-    lines.splice(routerLine + 1, 0, `  token: "${token}"`);
+    lines.splice(start + 1, 0, addressLineText);
   }
 
   return `${lines.join("\n").replace(/\s+$/, "")}\n`;
 }
 
-function writeOrUpdateConfig({ routerURL, token }) {
-  let content = defaultAgentConfig(routerURL, token);
-  if (fs.existsSync(CONFIG_PATH)) {
-    const existing = fs.readFileSync(CONFIG_PATH, "utf8");
+// readRouterConfig extracts router.address and router.token from agent YAML.
+function readRouterConfig(content) {
+  const result = { address: "", token: "" };
+  const lines = content.split(/\r?\n/);
+  const { start, end, indent } = findRouterBlock(lines);
+  if (start === -1) {
+    return result;
+  }
+  for (let i = start + 1; i < end; i++) {
+    for (const key of ["address", "token"]) {
+      const match = childKeyPattern(indent, key).exec(lines[i]);
+      if (match) {
+        result[key] = parseYAMLScalar(match[1]);
+      }
+    }
+  }
+  return result;
+}
+
+function writeOrUpdateConfig({ routerURL, token }, { configPath = CONFIG_PATH, home = HOME } = {}) {
+  let content = defaultAgentConfig(routerURL, token, home);
+  if (fs.existsSync(configPath)) {
+    const existing = fs.readFileSync(configPath, "utf8");
     content = updateRouterConfig(existing, { routerURL, token });
   }
-  fs.writeFileSync(CONFIG_PATH, content, "utf8");
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, content, "utf8");
+}
+
+function normalizeURL(value) {
+  return String(value || "").trim().replace(/\/+$/, "").toLowerCase();
+}
+
+// pointConfigAtRouter makes the agent config target routerURL. A token issued
+// by a different router is useless against this one, so it is only kept when
+// the address is unchanged; otherwise it is cleared and the node re-links via
+// the browser login flow.
+function pointConfigAtRouter(routerURL, { configPath = CONFIG_PATH, home = HOME } = {}) {
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  if (!fs.existsSync(configPath)) {
+    fs.writeFileSync(configPath, defaultAgentConfig(routerURL, "", home), "utf8");
+    return { tokenKept: false };
+  }
+  const existing = fs.readFileSync(configPath, "utf8");
+  const current = readRouterConfig(existing);
+  const keepToken = current.token !== "" && normalizeURL(current.address) === normalizeURL(routerURL);
+  const token = keepToken ? current.token : "";
+  fs.writeFileSync(configPath, updateRouterConfig(existing, { routerURL, token }), "utf8");
+  return { tokenKept: keepToken };
+}
+
+// isOptOutSet treats unset, empty, "0", "false", "no" and "off" as not set.
+function isOptOutSet(value) {
+  if (value === undefined || value === null) return false;
+  return !["", "0", "false", "no", "off"].includes(String(value).trim().toLowerCase());
+}
+
+function escapeXML(value) {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+function macOSLaunchAgentPlist(menubarPath) {
+  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>KeepAlive</key>
+  <false/>
+  <key>Label</key>
+  <string>${MACOS_LAUNCH_AGENT_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${escapeXML(menubarPath)}</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+</dict>
+</plist>
+`;
+}
+
+// enableStartOnLogin registers the tray/menu bar app to launch at login. It
+// returns where the registration was written, null on unsupported platforms,
+// or throws on failure.
+function enableStartOnLogin(menubarPath, { platform = process.platform, home = HOME, run = spawnSync } = {}) {
+  if (platform === "win32") {
+    const result = run(
+      "reg",
+      ["add", WINDOWS_RUN_KEY, "/v", WINDOWS_RUN_VALUE, "/t", "REG_SZ", "/d", `"${menubarPath}"`, "/f"],
+      { stdio: "pipe", windowsHide: true },
+    );
+    if (result.error || result.status !== 0) {
+      const detail = result.error ? result.error.message : String(result.stderr || "").trim();
+      throw new Error(`reg add failed: ${detail}`);
+    }
+    return `${WINDOWS_RUN_KEY}\\${WINDOWS_RUN_VALUE}`;
+  }
+  if (platform === "darwin") {
+    const plistPath = path.join(home, "Library", "LaunchAgents", `${MACOS_LAUNCH_AGENT_LABEL}.plist`);
+    fs.mkdirSync(path.dirname(plistPath), { recursive: true });
+    fs.writeFileSync(plistPath, macOSLaunchAgentPlist(menubarPath), "utf8");
+    return plistPath;
+  }
+  return null;
+}
+
+// disableStartOnLogin removes the login registration written by
+// enableStartOnLogin (or by the tray/menu bar toggle). It returns true when a
+// registration was removed and false when none existed.
+function disableStartOnLogin({ platform = process.platform, home = HOME, run = spawnSync } = {}) {
+  if (platform === "win32") {
+    const query = run("reg", ["query", WINDOWS_RUN_KEY, "/v", WINDOWS_RUN_VALUE], { stdio: "pipe", windowsHide: true });
+    if (query.error) {
+      throw new Error(`reg query failed: ${query.error.message}`);
+    }
+    if (query.status !== 0) {
+      return false;
+    }
+    const result = run("reg", ["delete", WINDOWS_RUN_KEY, "/v", WINDOWS_RUN_VALUE, "/f"], { stdio: "pipe", windowsHide: true });
+    if (result.error || result.status !== 0) {
+      const detail = result.error ? result.error.message : String(result.stderr || "").trim();
+      throw new Error(`reg delete failed: ${detail}`);
+    }
+    return true;
+  }
+  if (platform === "darwin") {
+    const plistPath = path.join(home, "Library", "LaunchAgents", `${MACOS_LAUNCH_AGENT_LABEL}.plist`);
+    if (!fs.existsSync(plistPath)) {
+      return false;
+    }
+    fs.rmSync(plistPath, { force: true });
+    return true;
+  }
+  return false;
+}
+
+// stopTrayApp terminates any running tray/menu bar app and, with includeAgent,
+// any installed cloudless-agent (e.g. one left by an older tray or a
+// supervisor), so an upgrade doesn't leave the previous version running.
+// Returns true when something was stopped.
+//
+// Windows: taskkill exits 128 when no process matches, which is not an error.
+// macOS: the processes are matched by their full path in binDir and sent
+// SIGTERM (the menu bar app stops its agent on SIGTERM), then SIGKILL if they
+// are still running after timeoutMs.
+function stopTrayApp({
+  includeAgent = false,
+  platform = process.platform,
+  run = spawnSync,
+  binDir = BIN_DIR,
+  timeoutMs = 5000,
+  sleep = sleepSync,
+} = {}) {
+  if (platform === "win32") {
+    const images = [MENUBAR_BINARY_NAME_WINDOWS, ...(includeAgent ? [AGENT_BINARY_NAME_WINDOWS] : [])];
+    let stopped = false;
+    for (const image of images) {
+      // /T also ends the tray's agent child; the tray's kill-on-close job
+      // would do that anyway, but older trays didn't have one.
+      const result = run("taskkill", ["/F", "/T", "/IM", image], { stdio: "pipe", windowsHide: true });
+      if (!result.error && result.status === 0) stopped = true;
+    }
+    return stopped;
+  }
+  if (platform === "darwin") {
+    const names = ["CloudlessMenuBar", ...(includeAgent ? ["cloudless-agent"] : [])];
+    const patterns = names.map((name) => `^${escapeRegExp(path.posix.join(binDir.replace(/\\/g, "/"), name))}( |$)`);
+    // pkill/pgrep exit 0 when something matched and 1 when nothing did.
+    const signal = (sig, pattern) => run("pkill", [`-${sig}`, "-f", pattern], { stdio: "pipe" });
+    const running = (pattern) => run("pgrep", ["-f", pattern], { stdio: "pipe" }).status === 0;
+    let stopped = false;
+    for (const pattern of patterns) {
+      const result = signal("TERM", pattern);
+      if (!result.error && result.status === 0) stopped = true;
+    }
+    if (!stopped) return false;
+    const step = 100;
+    for (let waited = 0; waited < timeoutMs && patterns.some(running); waited += step) {
+      sleep(step);
+    }
+    for (const pattern of patterns) {
+      if (running(pattern)) signal("KILL", pattern);
+    }
+    return true;
+  }
+  return false;
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+// launchTray starts the tray/menu bar app detached from this process so it
+// keeps running after npm (or the CLI) exits. The tray owns the agent: it
+// starts it, restarts it if it dies, and stops it when the tray quits.
+// cwd defaults to home: postinstall runs inside the npm package directory, and
+// on Windows a process whose working directory is in there makes npm's next
+// upgrade fail with EBUSY when it renames the package directory.
+function launchTray(menubarPath, { spawnImpl = spawn, cwd = HOME } = {}) {
+  const child = spawnImpl(menubarPath, [], { cwd, detached: true, stdio: "ignore", windowsHide: false });
+  if (typeof child.on === "function") child.on("error", () => {});
+  if (typeof child.unref === "function") child.unref();
+  return child.pid;
 }
 
-function defaultAgentConfig(routerURL, token) {
+function defaultAgentConfig(routerURL, token, home = HOME) {
+  const cloudlessDir = path.join(home, ".cloudless");
   return `router:
-  address: "${routerURL}"
-  token: "${token}"
+  address: ${yamlString(routerURL)}
+  token: ${yamlString(token)}
   heartbeat_interval: "10s"
   system_load_ceiling: 2.5
   mdns: true
   mdns_service: "_cloudless-router._tcp"
   discover_interval: "1m"
-  servers_file: "${HOME}/.cloudless/router-servers.json"
+  servers_file: ${yamlString(path.join(cloudlessDir, "router-servers.json"))}
   manual_servers: []
   # advertise_address: "https://my-node-demo.example.com"
 
 inference:
-  models_dir: "${HOME}/.cloudless/models"
+  models_dir: ${yamlString(path.join(cloudlessDir, "models"))}
   preload_models: []
   max_concurrent_requests: 4
   unload_on_system_load: true
@@ -194,12 +509,25 @@ module.exports = {
   BIN_DIR,
   CONFIG_PATH,
   CLOUDLESS_ROOT,
+  HOME,
+  MACOS_LAUNCH_AGENT_LABEL,
+  PRODUCTION_ROUTER_URL,
+  WINDOWS_RUN_KEY,
+  WINDOWS_RUN_VALUE,
   defaultAgentConfig,
   detectTarget,
+  disableStartOnLogin,
+  enableStartOnLogin,
   ensureDirs,
   installBinary,
+  isOptOutSet,
+  launchTray,
+  parseYAMLScalar,
+  pointConfigAtRouter,
   promptLine,
   promptSecret,
+  readRouterConfig,
+  stopTrayApp,
   updateRouterConfig,
   writeOrUpdateConfig,
 };

package/scripts/postinstall.js

@@ -2,82 +2,176 @@
 const fs = require("node:fs");
 const path = require("node:path");
 
+const common = require("./common");
 const {
   AGENT_BINARY_NAME,
   MENUBAR_BINARY_NAME,
+  BIN_DIR,
   CONFIG_PATH,
+  HOME,
+  PRODUCTION_ROUTER_URL,
   detectTarget,
-  ensureDirs,
   installBinary,
+  isOptOutSet,
+  pointConfigAtRouter,
   promptSecret,
   writeOrUpdateConfig,
-} = require("./common");
+} = common;
 
-function resolveBundledPlatformDir(target) {
+const DEFAULT_PLATFORM_ROOT = path.resolve(__dirname, "..", "platform");
+
+function resolveBundledPlatformDir(target, platformRoot) {
   const key = `${target.goos}/${target.goarch}`;
-  const dirName = `${target.goos}-${target.goarch}`;
-  const platformDir = path.resolve(__dirname, "..", "platform", dirName);
+  const platformDir = path.join(platformRoot, `${target.goos}-${target.goarch}`);
   if (!fs.existsSync(platformDir)) {
     throw new Error(`Unsupported platform/arch: ${key}`);
   }
   return platformDir;
 }
 
-function installFromPlatformPackage(target) {
-  const platformDir = resolveBundledPlatformDir(target);
+function hasMenuBarApp(target) {
+  return target.goos === "darwin" || target.goos === "windows";
+}
+
+function installFromPlatformPackage(target, { platformRoot, binDir }) {
+  const platformDir = resolveBundledPlatformDir(target, platformRoot);
   const agentSource = path.join(platformDir, AGENT_BINARY_NAME);
 
   if (!fs.existsSync(agentSource)) {
     throw new Error(`Bundled binaries are missing ${AGENT_BINARY_NAME} for ${target.goos}/${target.goarch}`);
   }
-  const agentPath = installBinary(agentSource, AGENT_BINARY_NAME);
+  const agentPath = installBinary(agentSource, AGENT_BINARY_NAME, { binDir });
 
   let menubarPath = null;
-  if (target.goos === "darwin") {
+  if (hasMenuBarApp(target)) {
     const menuBarSource = path.join(platformDir, MENUBAR_BINARY_NAME);
     if (!fs.existsSync(menuBarSource)) {
       throw new Error(`Bundled binaries are missing ${MENUBAR_BINARY_NAME} for ${target.goos}/${target.goarch}`);
     }
-    menubarPath = installBinary(menuBarSource, MENUBAR_BINARY_NAME);
+    menubarPath = installBinary(menuBarSource, MENUBAR_BINARY_NAME, { binDir });
   }
 
   return { agentPath, menubarPath };
 }
 
-async function promptConfig() {
-  const routerURL = process.env.CLOUDLESS_ROUTER_URL?.trim() || "http://localhost:8080";
-  let apiKey = process.env.CLOUDLESS_NODE_API_KEY?.trim() || "";
-  if (!apiKey && process.stdin.isTTY && process.stdout.isTTY) {
-    process.stdout.write("\nCloudless AI node setup\n");
-    process.stdout.write(`Router URL: ${routerURL}\n`);
-    apiKey = await promptSecret("Enter Cloudless router API key (hidden): ");
+async function configureProductionRouter({ configPath, home, env, interactive, out, prompt }) {
+  const routerURL = PRODUCTION_ROUTER_URL;
+  let apiKey = env.CLOUDLESS_NODE_API_KEY?.trim() || "";
+  if (!apiKey && interactive) {
+    out("\nCloudless AI node setup\n");
+    out(`Router URL: ${routerURL}\n`);
+    apiKey = await prompt("Enter a node API key, or press Enter to sign in from the browser later (hidden): ");
   }
-  if (!apiKey) {
-    process.stdout.write("\nNo API key provided during install.\n");
-    process.stdout.write("Run `cloudless-node configure` to set up your router URL and API key.\n");
-    return;
+  if (apiKey) {
+    writeOrUpdateConfig({ routerURL, token: apiKey }, { configPath, home });
+    out(`Saved node config for ${routerURL} to ${configPath}\n`);
+    return { tokenKept: true };
   }
-  writeOrUpdateConfig({ routerURL, token: apiKey });
-  process.stdout.write(`Saved node config to ${CONFIG_PATH}\n`);
+  const { tokenKept } = pointConfigAtRouter(routerURL, { configPath, home });
+  out(`Configured ${configPath} to register with ${routerURL}\n`);
+  if (!tokenKept) {
+    out("On first start you'll be asked to sign in from your browser to link this node.\n");
+  }
+  return { tokenKept };
+}
+
+function configureStartOnLogin(menubarPath, { env, out, enableStartOnLogin }) {
+  if (!menubarPath) return false;
+  if (isOptOutSet(env.CLOUDLESS_NO_START_ON_LOGIN)) {
+    out("Skipping start-on-login (CLOUDLESS_NO_START_ON_LOGIN is set).\n");
+    return false;
+  }
+  try {
+    const where = enableStartOnLogin(menubarPath);
+    if (where) {
+      out(`Enabled start on login (${where}).\n`);
+      return true;
+    }
+  } catch (error) {
+    out(`Warning: could not enable start on login: ${error.message}\n`);
+  }
+  return false;
+}
+
+// trayLabel names the tray/menu bar app in installer output.
+function trayLabel(target) {
+  return target.goos === "darwin" ? "menu bar app" : "tray";
 }
 
-async function main() {
-  ensureDirs();
-  const target = detectTarget();
-  process.stdout.write(`Installing Cloudless node agent for ${target.goos}/${target.goarch}...\n`);
-  const result = installFromPlatformPackage(target);
-  process.stdout.write(`Installed ${result.agentPath}\n`);
+// shouldLaunchTray decides whether postinstall starts the tray/menu bar app,
+// which runs the agent itself. CI and headless installs opt out, and a root
+// install on macOS (`sudo npm install -g`) must not start a GUI app as root.
+function shouldLaunchTray(target, menubarPath, env, { isRoot = false } = {}) {
+  if (!menubarPath || !hasMenuBarApp(target)) return false;
+  if (target.goos === "darwin" && isRoot) return false;
+  return !isOptOutSet(env.CLOUDLESS_NO_LAUNCH) && !isOptOutSet(env.CI);
+}
+
+async function main(options = {}) {
+  const {
+    target = detectTarget(),
+    platformRoot = DEFAULT_PLATFORM_ROOT,
+    binDir = BIN_DIR,
+    configPath = CONFIG_PATH,
+    home = HOME,
+    env = process.env,
+    interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    out = (text) => process.stdout.write(text),
+    prompt = promptSecret,
+    enableStartOnLogin = (menubarPath) => common.enableStartOnLogin(menubarPath, { home }),
+    stopRunning = () => common.stopTrayApp({ includeAgent: true, binDir }),
+    launchTray = (menubarPath) => common.launchTray(menubarPath),
+    isRoot = typeof process.getuid === "function" && process.getuid() === 0,
+  } = options;
+  const label = trayLabel(target);
+
+  fs.mkdirSync(binDir, { recursive: true });
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  out(`Installing Cloudless node agent for ${target.goos}/${target.goarch}...\n`);
+  // Stop the previous tray/menu bar app and agent first so the new binaries
+  // are the ones that run (Windows can't overwrite a running .exe, only
+  // rename it).
+  if (hasMenuBarApp(target) && stopRunning()) {
+    out(`Stopped the running Cloudless AI ${label} and node agent.\n`);
+  }
+  const result = installFromPlatformPackage(target, { platformRoot, binDir });
+  out(`Installed ${result.agentPath}\n`);
   if (result.menubarPath) {
-    process.stdout.write(`Installed ${result.menubarPath}\n`);
+    out(`Installed ${result.menubarPath}\n`);
   }
-  await promptConfig();
-  process.stdout.write("Done. Run `cloudless-node start` to launch the node agent.\n");
-  if (target.goos === "darwin") {
-    process.stdout.write("Run `cloudless-node menubar` to start the menu bar app.\n");
+  const config = await configureProductionRouter({ configPath, home, env, interactive, out, prompt });
+  const autostart = configureStartOnLogin(result.menubarPath, { env, out, enableStartOnLogin });
+
+  let launched = false;
+  if (shouldLaunchTray(target, result.menubarPath, env, { isRoot })) {
+    try {
+      launchTray(result.menubarPath);
+      launched = true;
+      out(`Started the Cloudless AI ${label}; it runs the node agent and restarts it if it stops.\n`);
+      if (!config.tokenKept) {
+        out("Your browser will open so you can sign in and link this node to Cloudless AI.\n");
+      }
+    } catch (error) {
+      out(`Warning: could not start the ${label}: ${error.message}\n`);
+    }
   }
+
+  if (!launched) {
+    out("Done. Run `cloudless-node start` to launch the node agent.\n");
+  } else {
+    out(`Done. Quit the ${label} to stop the node agent.\n`);
+  }
+  if (autostart) {
+    out(`The ${label} will start automatically ${launched ? "at every login" : "at your next login"}.\n`);
+  }
+  return { ...result, ...config, autostart, launched };
 }
 
-main().catch((error) => {
-  process.stderr.write(`Installation failed: ${error.message}\n`);
-  process.exit(1);
-});
+module.exports = { main, shouldLaunchTray };
+
+if (require.main === module) {
+  main().catch((error) => {
+    process.stderr.write(`Installation failed: ${error.message}\n`);
+    process.exit(1);
+  });
+}