feat: unify Electron and CLI with shared oRPC API server

Electron now runs an HTTP/WS API server on 127.0.0.1 alongside the
existing MessagePort transport. Both transports share the same oRPC
router instance with auth middleware.

- Add ServerLockfile to manage ~/.mux/server.lock for discovery
- Extend ServerService with startServer/stopServer lifecycle
- Move orpcServer.ts to src/node/orpc/server.ts (shared module)
- Electron generates auth token, injects into both transports
- CLI server checks lockfile to prevent conflicts
- CLI api auto-discovers running server via lockfile

Env vars:
- MUX_SERVER_AUTH_TOKEN: Override auth token
- MUX_SERVER_PORT: Fixed port (default: random)
- MUX_NO_API_SERVER=1: Disable API server in Electron

Author: ThomasK33

src/cli/api.ts

@@ -3,19 +3,63 @@
  *
  * This module is loaded lazily to avoid pulling in ESM-only dependencies
  * (trpc-cli) when running other commands like the desktop app.
+ *
+ * Server discovery priority:
+ * 1. MUX_SERVER_URL env var (explicit override)
+ * 2. Lockfile at ~/.mux/server.lock (running Electron or mux server)
+ * 3. Fallback to http://localhost:3000
  */
 
 import { createCli } from "trpc-cli";
 import { router } from "@/node/orpc/router";
 import { proxifyOrpc } from "./proxifyOrpc";
+import { ServerLockfile } from "@/node/services/serverLockfile";
+import { getMuxHome } from "@/common/constants/paths";
 import type { Command } from "commander";
 
-const baseUrl = process.env.MUX_SERVER_URL ?? "http://localhost:3000";
-const authToken = process.env.MUX_SERVER_AUTH_TOKEN;
+interface ServerDiscovery {
+  baseUrl: string;
+  authToken: string | undefined;
+}
+
+async function discoverServer(): Promise<ServerDiscovery> {
+  // Priority 1: Explicit env vars override everything
+  if (process.env.MUX_SERVER_URL) {
+    return {
+      baseUrl: process.env.MUX_SERVER_URL,
+      authToken: process.env.MUX_SERVER_AUTH_TOKEN,
+    };
+  }
+
+  // Priority 2: Try lockfile discovery (running Electron or mux server)
+  try {
+    const lockfile = new ServerLockfile(getMuxHome());
+    const data = await lockfile.read();
+    if (data) {
+      return {
+        baseUrl: `http://127.0.0.1:${data.port}`,
+        authToken: data.token,
+      };
+    }
+  } catch {
+    // Ignore lockfile errors
+  }
+
+  // Priority 3: Default fallback (standalone server on default port)
+  return {
+    baseUrl: "http://localhost:3000",
+    authToken: process.env.MUX_SERVER_AUTH_TOKEN,
+  };
+}
+
+// Run async discovery then start CLI
+(async () => {
+  const { baseUrl, authToken } = await discoverServer();
 
-const proxiedRouter = proxifyOrpc(router(), { baseUrl, authToken });
-const cli = createCli({ router: proxiedRouter }).buildProgram() as Command;
+  const proxiedRouter = proxifyOrpc(router(), { baseUrl, authToken });
+  const cli = createCli({ router: proxiedRouter }).buildProgram() as Command;
 
-cli.name("mux api");
-cli.description("Interact with the mux API via a running server");
-cli.parse();
+  cli.name("mux api");
+  cli.description("Interact with the mux API via a running server");
+  cli.parse();
+})();

src/cli/index.ts

@@ -42,7 +42,10 @@ if (subcommand === "run") {
   process.argv.splice(2, 1);
   // eslint-disable-next-line @typescript-eslint/no-require-imports
   require("./api");
-} else if (subcommand === "desktop" || (isElectron && (subcommand === undefined || isElectronLaunchArg))) {
+} else if (
+  subcommand === "desktop" ||
+  (isElectron && (subcommand === undefined || isElectronLaunchArg))
+) {
   // Explicit `mux desktop`, or Electron runtime with no subcommand / Electron launch args
   launchDesktop();
 } else {

src/cli/server.test.ts

@@ -24,7 +24,7 @@ import type { ORPCContext } from "@/node/orpc/context";
 import { Config } from "@/node/config";
 import { ServiceContainer } from "@/node/services/serviceContainer";
 import type { RouterClient } from "@orpc/server";
-import { createOrpcServer, type OrpcServer } from "./orpcServer";
+import { createOrpcServer, type OrpcServer } from "@/node/orpc/server";
 
 // --- Test Server Factory ---
 

src/cli/server.ts

@@ -4,11 +4,12 @@
  */
 import { Config } from "@/node/config";
 import { ServiceContainer } from "@/node/services/serviceContainer";
-import { migrateLegacyMuxHome } from "@/common/constants/paths";
+import { ServerLockfile } from "@/node/services/serverLockfile";
+import { getMuxHome, migrateLegacyMuxHome } from "@/common/constants/paths";
 import type { BrowserWindow } from "electron";
 import { Command } from "commander";
 import { validateProjectPath } from "@/node/utils/pathUtils";
-import { createOrpcServer } from "./orpcServer";
+import { createOrpcServer } from "@/node/orpc/server";
 import type { ORPCContext } from "@/node/orpc/context";
 
 const program = new Command();
@@ -44,6 +45,15 @@ const mockWindow: BrowserWindow = {
 (async () => {
   migrateLegacyMuxHome();
 
+  // Check for existing server (Electron or another mux server instance)
+  const lockfile = new ServerLockfile(getMuxHome());
+  const existing = await lockfile.read();
+  if (existing) {
+    console.error(`Error: mux API server is already running on port ${existing.port}`);
+    console.error(`Use 'mux api' commands to interact with the running instance.`);
+    process.exit(1);
+  }
+
   const config = new Config();
   const serviceContainer = new ServiceContainer(config);
   await serviceContainer.initialize();
@@ -78,7 +88,22 @@ const mockWindow: BrowserWindow = {
     serveStatic: true,
   });
 
+  // Acquire lockfile so other instances know we're running
+  await lockfile.acquire(server.port, AUTH_TOKEN ?? "");
+
   console.log(`Server is running on ${server.baseUrl}`);
+
+  // Cleanup on shutdown
+  const cleanup = () => {
+    console.log("Shutting down server...");
+    void lockfile
+      .release()
+      .then(() => server.close())
+      .then(() => process.exit(0));
+  };
+
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
 })().catch((error) => {
   console.error("Failed to initialize server:", error);
   process.exit(1);

src/desktop/main.ts

@@ -1,8 +1,10 @@
 // Enable source map support for better error stack traces in production
 import "source-map-support/register";
+import { randomBytes } from "crypto";
 import { RPCHandler } from "@orpc/server/message-port";
 import { onError } from "@orpc/server";
 import { router } from "@/node/orpc/router";
+import { ServerLockfile } from "@/node/services/serverLockfile";
 import "disposablestack/auto";
 
 import type { MenuItemConstructorOptions } from "electron";
@@ -304,33 +306,71 @@ async function loadServices(): Promise<void> {
   services = new ServiceContainerClass(config);
   await services.initialize();
 
-  const orpcHandler = new RPCHandler(router(), {
+  // Generate auth token (use env var or random per-session)
+  const authToken = process.env.MUX_SERVER_AUTH_TOKEN ?? randomBytes(32).toString("hex");
+
+  // Single router instance with auth middleware - used for both MessagePort and HTTP/WS
+  const orpcRouter = router(authToken);
+
+  const orpcHandler = new RPCHandler(orpcRouter, {
     interceptors: [
       onError((error) => {
         console.error("ORPC Error:", error);
       }),
     ],
   });
 
+  // Build the oRPC context with all services
+  const orpcContext = {
+    projectService: services.projectService,
+    workspaceService: services.workspaceService,
+    providerService: services.providerService,
+    terminalService: services.terminalService,
+    windowService: services.windowService,
+    updateService: services.updateService,
+    tokenizerService: services.tokenizerService,
+    serverService: services.serverService,
+    menuEventService: services.menuEventService,
+    voiceService: services.voiceService,
+  };
+
   electronIpcMain.on("start-orpc-server", (event) => {
     const [serverPort] = event.ports;
     orpcHandler.upgrade(serverPort, {
       context: {
-        projectService: services!.projectService,
-        workspaceService: services!.workspaceService,
-        providerService: services!.providerService,
-        terminalService: services!.terminalService,
-        windowService: services!.windowService,
-        updateService: services!.updateService,
-        tokenizerService: services!.tokenizerService,
-        serverService: services!.serverService,
-        menuEventService: services!.menuEventService,
-        voiceService: services!.voiceService,
+        ...orpcContext,
+        // Inject synthetic auth header so auth middleware passes
+        headers: { authorization: `Bearer ${authToken}` },
       },
     });
     serverPort.start();
   });
 
+  // Start HTTP/WS API server for CLI access (unless explicitly disabled)
+  if (process.env.MUX_NO_API_SERVER !== "1") {
+    const lockfile = new ServerLockfile(config.rootDir);
+    const existing = await lockfile.read();
+
+    if (existing) {
+      console.log(`[${timestamp()}] API server already running on port ${existing.port}, skipping`);
+    } else {
+      try {
+        const port = process.env.MUX_SERVER_PORT ? parseInt(process.env.MUX_SERVER_PORT, 10) : 0;
+        const serverInfo = await services.serverService.startServer({
+          muxHome: config.rootDir,
+          context: orpcContext,
+          router: orpcRouter,
+          authToken,
+          port,
+        });
+        console.log(`[${timestamp()}] API server started on port ${serverInfo.port}`);
+      } catch (error) {
+        console.error(`[${timestamp()}] Failed to start API server:`, error);
+        // Non-fatal - continue without API server
+      }
+    }
+  }
+
   // Set TerminalWindowManager for desktop mode (pop-out terminal windows)
   const terminalWindowManager = new TerminalWindowManagerClass(config);
   services.setProjectDirectoryPicker(async () => {
@@ -527,6 +567,13 @@ if (gotTheLock) {
     }
   });
 
+  app.on("before-quit", () => {
+    console.log(`[${timestamp()}] App before-quit - cleaning up API server...`);
+    if (services) {
+      void services.serverService.stopServer();
+    }
+  });
+
   app.on("activate", () => {
     // Skip splash on reactivation - services already loaded, window creation is fast
     if (app.isReady() && mainWindow === null) {

src/cli/orpcServer.ts src/node/orpc/server.tssrc/cli/orpcServer.ts renamed to src/node/orpc/server.ts

@@ -13,7 +13,7 @@ import { WebSocketServer } from "ws";
 import { RPCHandler } from "@orpc/server/node";
 import { RPCHandler as ORPCWebSocketServerHandler } from "@orpc/server/ws";
 import { onError } from "@orpc/server";
-import { router } from "@/node/orpc/router";
+import { router, type AppRouter } from "@/node/orpc/router";
 import type { ORPCContext } from "@/node/orpc/context";
 import { extractWsHeaders } from "@/node/orpc/authMiddleware";
 import { VERSION } from "@/version";
@@ -30,12 +30,14 @@ export interface OrpcServerOptions {
   context: ORPCContext;
   /** Whether to serve static files and SPA fallback (default: false) */
   serveStatic?: boolean;
-  /** Directory to serve static files from (default: __dirname/..) */
+  /** Directory to serve static files from (default: dist/ relative to dist/node/orpc/) */
   staticDir?: string;
   /** Custom error handler for oRPC errors */
   onOrpcError?: (error: unknown) => void;
-  /** Optional bearer token for HTTP auth */
+  /** Optional bearer token for HTTP auth (used if router not provided) */
   authToken?: string;
+  /** Optional pre-created router (if not provided, creates router(authToken)) */
+  router?: AppRouter;
 }
 
 export interface OrpcServer {
@@ -71,8 +73,10 @@ export async function createOrpcServer({
   authToken,
   context,
   serveStatic = false,
-  staticDir = path.join(__dirname, ".."),
+  // From dist/node/orpc/, go up 2 levels to reach dist/ where index.html lives
+  staticDir = path.join(__dirname, "../.."),
   onOrpcError = (error) => log.error("ORPC Error:", error),
+  router: existingRouter,
 }: OrpcServerOptions): Promise<OrpcServer> {
   // Express app setup
   const app = express();
@@ -94,7 +98,7 @@ export async function createOrpcServer({
     res.json({ ...VERSION, mode: "server" });
   });
 
-  const orpcRouter = router(authToken);
+  const orpcRouter = existingRouter ?? router(authToken);
 
   // oRPC HTTP handler
   const orpcHandler = new RPCHandler(orpcRouter, {