Add executor service to run the local gateway as an OS-supervised daemon

Registers the existing daemon (`daemon run --foreground`) with the OS service
manager so the local MCP gateway survives app-quit and machine restart:

- launchd LaunchAgent on macOS (RunAtLoad + KeepAlive=SuccessfulExit:false),
  with best-effort systemd --user (Linux) and a guided Task Scheduler scaffold
  (Windows).
- install / uninstall / status / restart subcommands; install refuses to
  fight an already-running local server and polls until the daemon is reachable.
- The Basic-auth password lives in a 0600 service.key the supervised daemon
  reads on start -- never in the unit, so launchctl/systemctl can't expose it.
- The unit bakes the user's PATH (a bare launchd env can't find pyenv/nvm/brew
  tools) and the install version (`service status` flags drift after upgrade).
- Unit tests cover the plist/systemd/Windows generators, backend dispatch, and
  the 0600 service.key round-trip.

Author: RhysSullivan

apps/cli/src/local-server-manifest.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, it } from "@effect/vitest";
 import { BunServices } from "@effect/platform-bun";
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdtempSync, rmSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { Path } from "effect";
@@ -11,10 +11,13 @@ import { normalizeExecutorServerConnection } from "@executor-js/sdk/shared";
 import {
   acquireLocalServerStartLock,
   readLocalServerManifest,
+  readServiceKey,
   releaseLocalServerStartLock,
   removeLocalServerManifestIfOwnedBy,
+  removeServiceKey,
   resolveExecutorDataDir,
   writeLocalServerManifest,
+  writeServiceKey,
 } from "./local-server-manifest";
 
 const previousDataDir = process.env.EXECUTOR_DATA_DIR;
@@ -84,6 +87,30 @@ describe("local server manifest", () => {
     }).pipe(Effect.provide(BunServices.layer)),
   );
 
+  it.effect("round-trips the service key with owner-only permissions", () =>
+    Effect.gen(function* () {
+      const dataDir = mkdtempSync(join(tmpdir(), "executor-service-key-"));
+      process.env.EXECUTOR_DATA_DIR = dataDir;
+
+      try {
+        expect(yield* readServiceKey()).toBeNull();
+
+        yield* writeServiceKey({ password: "s3cret", createdAt: "2026-06-13T00:00:00.000Z" });
+        const key = yield* readServiceKey();
+        expect(key?.password).toBe("s3cret");
+
+        // The secret file must be readable only by its owner.
+        const mode = statSync(join(dataDir, "server-control", "service.key")).mode & 0o777;
+        expect(mode).toBe(0o600);
+
+        yield* removeServiceKey();
+        expect(yield* readServiceKey()).toBeNull();
+      } finally {
+        rmSync(dataDir, { recursive: true, force: true });
+      }
+    }).pipe(Effect.provide(BunServices.layer)),
+  );
+
   it.effect("resolves the data dir from EXECUTOR_DATA_DIR", () =>
     Effect.gen(function* () {
       const dataDir = mkdtempSync(join(tmpdir(), "executor-local-server-dir-"));

apps/cli/src/local-server-manifest.ts

@@ -27,6 +27,9 @@ const localServerManifestPath = (path: Path.Path): string =>
 const localServerStartLockPath = (path: Path.Path): string =>
   path.join(serverControlDir(path), "startup.lock");
 
+const serviceKeyPath = (path: Path.Path): string =>
+  path.join(serverControlDir(path), "service.key");
+
 export const readLocalServerManifest = (): Effect.Effect<
   ExecutorLocalServerManifest | null,
   never,
@@ -128,3 +131,72 @@ export const releaseLocalServerStartLock = (
     const fs = yield* FileSystem.FileSystem;
     yield* fs.remove(lock.path, { force: true });
   });
+
+// ---------------------------------------------------------------------------
+// Service key — the stable Basic-auth password for the OS-supervised daemon.
+//
+// A launchd/systemd-managed daemon needs a password that survives reinstalls
+// and is discoverable across processes. We persist it once at
+// `~/.executor/server-control/service.key` (mode 0600) so `service install`
+// reuses the same value on reinstall rather than minting a new one (which would
+// break every MCP-client config pointing at the old credential). The password
+// itself reaches the running daemon via the service manifest / plist env, and
+// clients discover it from `server.json`; this file is the durable source of
+// truth that backs both.
+// ---------------------------------------------------------------------------
+
+export interface ServiceKey {
+  readonly password: string;
+  readonly createdAt: string;
+}
+
+const ServiceKeyPayload = Schema.Struct({
+  password: Schema.String,
+  createdAt: Schema.String,
+});
+
+const decodeServiceKeyPayload = Schema.decodeUnknownOption(
+  Schema.fromJsonString(ServiceKeyPayload),
+);
+
+export const readServiceKey = (): Effect.Effect<
+  ServiceKey | null,
+  never,
+  FileSystem.FileSystem | Path.Path
+> =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const raw = yield* fs
+      .readFileString(serviceKeyPath(path))
+      .pipe(Effect.catchCause(() => Effect.succeed(null)));
+    if (raw === null) return null;
+    const decoded = decodeServiceKeyPayload(raw);
+    return Option.isSome(decoded) ? decoded.value : null;
+  });
+
+export const writeServiceKey = (
+  key: ServiceKey,
+): Effect.Effect<void, PlatformError, FileSystem.FileSystem | Path.Path> =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    yield* fs.makeDirectory(serverControlDir(path), { recursive: true });
+    yield* fs.writeFileString(
+      serviceKeyPath(path),
+      `${JSON.stringify(key, null, 2)}\n`,
+      // Owner-only: the password is readable only by the user who installed it.
+      { mode: 0o600 },
+    );
+  });
+
+export const removeServiceKey = (): Effect.Effect<
+  void,
+  PlatformError,
+  FileSystem.FileSystem | Path.Path
+> =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    yield* fs.remove(serviceKeyPath(path), { force: true });
+  });

apps/cli/src/main.ts

@@ -2,7 +2,7 @@
 // before any import (e.g. `@executor-js/local` → libSQL) eagerly loads them.
 import "./native-bindings";
 
-import { randomUUID } from "node:crypto";
+import { randomBytes, randomUUID } from "node:crypto";
 import { existsSync, realpathSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 // Make sibling binaries (if any are added later) discoverable on $PATH so
@@ -93,11 +93,15 @@ import {
 import {
   acquireLocalServerStartLock,
   readLocalServerManifest,
+  readServiceKey,
   releaseLocalServerStartLock,
   removeLocalServerManifestIfOwnedBy,
+  removeServiceKey,
   resolveExecutorDataDir,
   writeLocalServerManifest,
+  writeServiceKey,
 } from "./local-server-manifest";
+import { DEFAULT_SERVICE_PORT, getServiceBackend, SERVICE_LABEL } from "./service";
 import {
   defaultCliServerConnectionProfile,
   findCliServerConnectionProfile,
@@ -1993,12 +1997,24 @@ const daemonRunCommand = Command.make(
     Effect.gen(function* () {
       applyScope(scope);
       if (foreground) {
+        // Auth resolution for the foreground daemon (the form OS service
+        // managers run). Flag wins; then EXECUTOR_AUTH_PASSWORD/TOKEN env (how
+        // a dynamically-written launchd/systemd unit injects the secret); then,
+        // only when running supervised, the durable service.key (how the
+        // desktop's static SMAppService plist — which can't carry a per-user
+        // secret — supplies it).
+        const flagPassword = Option.getOrUndefined(authPassword);
+        const envPassword = process.env.EXECUTOR_AUTH_PASSWORD;
+        const keyPassword =
+          process.env.EXECUTOR_SUPERVISED && !flagPassword && !envPassword
+            ? ((yield* readServiceKey())?.password ?? undefined)
+            : undefined;
         yield* runDaemonSession({
           port,
           hostname,
           allowedHosts: allowedHost,
-          authToken: Option.getOrUndefined(authToken),
-          authPassword: Option.getOrUndefined(authPassword),
+          authToken: Option.getOrUndefined(authToken) ?? process.env.EXECUTOR_AUTH_TOKEN,
+          authPassword: flagPassword ?? envPassword ?? keyPassword,
         });
       } else {
         yield* runBackgroundDaemonStart({ port, hostname, allowedHosts: allowedHost });
@@ -2110,6 +2126,185 @@ const mcpCommand = Command.make(
     }),
 ).pipe(Command.withDescription("Start an MCP server over stdio"));
 
+// ---------------------------------------------------------------------------
+// Service — register the daemon with the OS so it survives app-quit + restart
+// ---------------------------------------------------------------------------
+
+const generateServicePassword = (): string => randomBytes(24).toString("base64url");
+
+const supervisedServiceOrigin = (port: number): string => `http://127.0.0.1:${port}`;
+
+const supervisedServiceAuthorization = (
+  password: string | null,
+  port: number,
+): string | undefined =>
+  getExecutorServerAuthorizationHeader(
+    normalizeExecutorServerConnection({
+      origin: supervisedServiceOrigin(port),
+      ...(password
+        ? {
+            auth: {
+              kind: "basic" as const,
+              username: DEFAULT_EXECUTOR_SERVER_USERNAME,
+              password,
+            },
+          }
+        : {}),
+    }),
+  ) ?? undefined;
+
+const serviceInstallCommand = Command.make(
+  "install",
+  {
+    port: Options.integer("port")
+      .pipe(Options.withDefault(DEFAULT_SERVICE_PORT))
+      .pipe(Options.withDescription("Port the supervised daemon binds (loopback only).")),
+    password: Options.string("password")
+      .pipe(Options.optional)
+      .pipe(
+        Options.withDescription(
+          "Basic auth password. Reused from a prior install or generated if omitted.",
+        ),
+      ),
+    noAuth: Options.boolean("no-auth")
+      .pipe(Options.withDefault(false))
+      .pipe(Options.withDescription("Run without Basic auth (loopback trust only).")),
+  },
+  ({ port, password, noAuth }) =>
+    Effect.gen(function* () {
+      if (isDevMode) {
+        return yield* Effect.fail(
+          new Error(
+            [
+              "`service install` requires the compiled `executor` binary so the OS can run it directly.",
+              `In a dev checkout, run \`${cliPrefix} daemon run --foreground\` instead.`,
+            ].join("\n"),
+          ),
+        );
+      }
+
+      const backend = getServiceBackend();
+      if (!backend.automated) {
+        // win32 / unsupported: the backend surfaces manual steps via its error.
+        yield* backend.install({ executablePath: process.execPath, port, version: CLI_VERSION });
+        return;
+      }
+
+      // Don't fight an already-running local server against the same data dir
+      // (a desktop sidecar, a foreground `executor web`, or an existing daemon).
+      const active = yield* readActiveLocalServerManifest();
+      if (active) {
+        const status = yield* backend.status();
+        if (status.registered && status.running && active.kind === "cli-daemon") {
+          console.log(
+            `Executor service already running at ${active.connection.origin} (pid ${active.pid}).`,
+          );
+          return;
+        }
+        return yield* Effect.fail(
+          new Error(
+            [
+              `A local Executor ${active.kind} is already running at ${active.connection.origin} (pid ${active.pid}).`,
+              `Stop it first (quit the desktop app, or \`${cliPrefix} daemon stop\`), then re-run install.`,
+            ].join("\n"),
+          ),
+        );
+      }
+
+      let servicePassword: string | null = null;
+      if (!noAuth) {
+        const explicit = Option.getOrUndefined(password);
+        const existing = yield* readServiceKey();
+        servicePassword = explicit ?? existing?.password ?? generateServicePassword();
+        yield* writeServiceKey({ password: servicePassword, createdAt: new Date().toISOString() });
+      }
+
+      yield* backend.install({ executablePath: process.execPath, port, version: CLI_VERSION });
+
+      const origin = supervisedServiceOrigin(port);
+      const reachable = yield* waitForReachable({
+        check: isServerReachable(origin, supervisedServiceAuthorization(servicePassword, port)),
+        timeoutMs: DAEMON_BOOT_TIMEOUT_MS,
+        intervalMs: DAEMON_BOOT_POLL_MS,
+      });
+      if (!reachable) {
+        return yield* Effect.fail(
+          new Error(
+            [
+              `Installed ${SERVICE_LABEL} but it did not become reachable at ${origin} within ${DAEMON_BOOT_TIMEOUT_MS / 1000}s.`,
+              `Check ~/.executor/logs/daemon.error.log and \`${cliPrefix} service status\`.`,
+            ].join("\n"),
+          ),
+        );
+      }
+
+      console.log(`Executor is now running as a background service at ${origin}.`);
+      console.log("It keeps serving after you quit the app and restarts on login.");
+      if (servicePassword) {
+        console.log(
+          `Basic auth user "${DEFAULT_EXECUTOR_SERVER_USERNAME}"; password saved to ~/.executor/server-control/service.key.`,
+        );
+      }
+    }),
+).pipe(
+  Command.withDescription("Install and start Executor as an OS-supervised background service"),
+);
+
+const serviceUninstallCommand = Command.make("uninstall", {}, () =>
+  Effect.gen(function* () {
+    const backend = getServiceBackend();
+    yield* backend.uninstall();
+    yield* removeServiceKey().pipe(Effect.ignore);
+    console.log("Executor background service uninstalled.");
+  }),
+).pipe(Command.withDescription("Stop and remove the OS-supervised background service"));
+
+const serviceStatusCommand = Command.make("status", {}, () =>
+  Effect.gen(function* () {
+    const backend = getServiceBackend();
+    const status = yield* backend.status();
+    // Tolerate a registered-but-unreachable manifest here — status shouldn't throw.
+    const active = yield* readActiveLocalServerManifest().pipe(
+      Effect.catchCause(() => Effect.succeed(null)),
+    );
+    console.log(`Platform:   ${status.platform}`);
+    console.log(`Registered: ${status.registered ? "yes" : "no"}`);
+    console.log(
+      `Running:    ${status.running ? "yes" : "no"}${status.pid ? ` (pid ${status.pid})` : ""}`,
+    );
+    if (active) {
+      console.log(`Serving:    ${active.connection.origin} (${active.kind}, pid ${active.pid})`);
+      // Version drift: the running daemon was launched by the binary the unit
+      // points at. If that differs from this CLI, an upgrade left the unit
+      // pointing at an older binary — reinstall to repoint + restart.
+      if (active.owner.version && active.owner.version !== CLI_VERSION) {
+        console.log(
+          `Drift:      running ${active.owner.version}, current ${CLI_VERSION} — run \`${cliPrefix} service install\` to upgrade.`,
+        );
+      }
+    }
+    for (const line of status.detail) console.log(line);
+  }),
+).pipe(Command.withDescription("Show the OS-supervised service status"));
+
+const serviceRestartCommand = Command.make("restart", {}, () =>
+  Effect.gen(function* () {
+    const backend = getServiceBackend();
+    yield* backend.restart();
+    console.log("Executor background service restarted.");
+  }),
+).pipe(Command.withDescription("Restart the OS-supervised background service"));
+
+const serviceCommand = Command.make("service").pipe(
+  Command.withSubcommands([
+    serviceInstallCommand,
+    serviceUninstallCommand,
+    serviceStatusCommand,
+    serviceRestartCommand,
+  ] as const),
+  Command.withDescription("Manage the OS-supervised background service"),
+);
+
 // ---------------------------------------------------------------------------
 // Root command
 // ---------------------------------------------------------------------------
@@ -2122,6 +2317,7 @@ const root = Command.make("executor").pipe(
     serverCommand,
     webCommand,
     daemonCommand,
+    serviceCommand,
     mcpCommand,
   ] as const),
   Command.withDescription("Executor local CLI"),