feat: load global config env from ~/.config/webmux/.env (#295)

* feat: load global config env from ~/.config/webmux/.env at startup

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat: add webmux service restart command

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor: static-import webmux-paths in cli entry

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: hugocasa

README.md

@@ -52,6 +52,17 @@ Each issue is processed once while it stays in Todo + labeled. Remove the label
 
 When the auto-create watcher picks up a `webmux_oneshot` issue, it posts a structured comment on the Linear issue (prefix `` **Webmux pickup — branch `<branch>`** ``) so external automation can track when the autonomous run starts. (Regular `webmux` pickups are user-driven and skip the comment.)
 
+**Setup — `LINEAR_API_KEY`.** Everything above needs a [Linear API key](https://linear.app/settings/account/security) in the server's environment. webmux runs as a single machine-wide service started from your home directory, so put the key in `~/.config/webmux/.env` — a `KEY=value` file the server loads at startup regardless of which directory it runs from, so it survives `webmux update`:
+
+```bash
+mkdir -p ~/.config/webmux
+echo 'LINEAR_API_KEY=lin_api_...' >> ~/.config/webmux/.env
+chmod 600 ~/.config/webmux/.env
+webmux service restart
+```
+
+Your assigned issues appear in the dashboard once the service restarts.
+
 ## Quick Start
 
 ```bash

backend/src/__tests__/webmux-paths.test.ts

@@ -0,0 +1,28 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { webmuxConfigDir, webmuxConfigEnvPath } from "../adapters/webmux-paths";
+
+const originalHome = Bun.env.HOME;
+
+afterEach(() => {
+  if (originalHome === undefined) delete Bun.env.HOME;
+  else Bun.env.HOME = originalHome;
+});
+
+describe("webmuxConfigDir", () => {
+  it("resolves the XDG config dir under $HOME", () => {
+    Bun.env.HOME = "/home/alice";
+    expect(webmuxConfigDir()).toBe("/home/alice/.config/webmux");
+  });
+
+  it("falls back to /root when HOME is unset", () => {
+    delete Bun.env.HOME;
+    expect(webmuxConfigDir()).toBe("/root/.config/webmux");
+  });
+});
+
+describe("webmuxConfigEnvPath", () => {
+  it("points at .env inside the config dir", () => {
+    Bun.env.HOME = "/home/alice";
+    expect(webmuxConfigEnvPath()).toBe("/home/alice/.config/webmux/.env");
+  });
+});

backend/src/adapters/control-token.ts

@@ -1,7 +1,8 @@
 import { chmod, mkdir } from "node:fs/promises";
-import { dirname } from "node:path";
+import { dirname, join } from "node:path";
+import { webmuxConfigDir } from "./webmux-paths";
 
-const CONTROL_TOKEN_PATH = `${Bun.env.HOME ?? "/root"}/.config/webmux/control-token`;
+const CONTROL_TOKEN_PATH = join(webmuxConfigDir(), "control-token");
 
 let cachedToken: string | null = null;
 

backend/src/adapters/webmux-paths.ts

@@ -0,0 +1,16 @@
+import { join } from "node:path";
+
+/** webmux's XDG-style config directory (`~/.config/webmux`). Home to the
+ *  control token and the optional global env file. Distinct from the
+ *  `~/.webmux` runtime-state dir (projects registry, live-instance registry),
+ *  which holds transient state rather than user config. */
+export function webmuxConfigDir(): string {
+  return join(Bun.env.HOME ?? "/root", ".config", "webmux");
+}
+
+/** Optional global env file webmux reads at server startup for machine-wide
+ *  secrets (e.g. `LINEAR_API_KEY`). Loaded after the launch project's `.env`
+ *  so a project can still override a machine-wide default. */
+export function webmuxConfigEnvPath(): string {
+  return join(webmuxConfigDir(), ".env");
+}

bin/src/service.test.ts

@@ -6,6 +6,7 @@ import {
   parseInstalledServiceConfig,
   readEnvVarsFromUnit,
   readPortFromUnit,
+  restartCommands,
   resolveConfirmDecision,
   resolveEnvVars,
   shouldPersistProject,
@@ -59,6 +60,29 @@ describe("resolveConfirmDecision", () => {
   });
 });
 
+describe("restartCommands", () => {
+  const base: ServiceConfig = {
+    platform: "linux",
+    serviceName: "webmux",
+    webmuxPath: "/usr/bin/webmux",
+    port: 5111,
+    envVars: {},
+  };
+
+  it("restarts the user unit on linux", () => {
+    expect(restartCommands(base)).toEqual([
+      ["systemctl", ["--user", "restart", "webmux"]],
+    ]);
+  });
+
+  it("kickstarts the labeled agent on darwin", () => {
+    const [[bin, args]] = restartCommands({ ...base, platform: "darwin" });
+    expect(bin).toBe("launchctl");
+    expect(args.slice(0, 2)).toEqual(["kickstart", "-k"]);
+    expect(args[2]).toMatch(/^gui\/\d+\/com\.webmux\.webmux$/);
+  });
+});
+
 describe("shouldPersistProject", () => {
   it("persists a webmux repo that isn't registered yet", () => {
     expect(shouldPersistProject("/some/repo", true, ["/other/repo"])).toBe(true);

bin/src/service.ts

@@ -339,6 +339,14 @@ function uninstallCommands(config: ServiceConfig): Command[] {
   ];
 }
 
+export function restartCommands(config: ServiceConfig): Command[] {
+  if (config.platform === "linux") {
+    return [["systemctl", ["--user", "restart", config.serviceName]]];
+  }
+  const uid = typeof process.getuid === "function" ? process.getuid() : 0;
+  return [["launchctl", ["kickstart", "-k", `gui/${uid}/com.webmux.${config.serviceName}`]]];
+}
+
 // ── Check if service exists ─────────────────────────────────────────────────
 
 function isInstalled(config: ServiceConfig): boolean {
@@ -650,6 +658,22 @@ async function uninstall(config: ServiceConfig): Promise<void> {
   p.log.success("Service uninstalled.");
 }
 
+function restart(config: ServiceConfig): void {
+  if (!isInstalled(config)) {
+    p.log.error("Service is not installed.");
+    return;
+  }
+
+  for (const cmd of restartCommands(config)) {
+    const result = runCommand(cmd);
+    if (!result.success) {
+      p.log.error(`Command failed: ${formatCommand(cmd)}\n${result.stderr.toString()}`);
+      return;
+    }
+  }
+  p.log.success("Service restarted.");
+}
+
 function status(config: ServiceConfig): void {
   if (!isInstalled(config)) {
     p.log.error("Service is not installed.");
@@ -702,6 +726,7 @@ add more projects from the dashboard or with \`webmux project add\`.
 Usage:
   webmux service install     Install, enable, and start the service
   webmux service uninstall   Stop, disable, and remove the service
+  webmux service restart     Restart the service (e.g. to reload config env)
   webmux service status      Show service status
   webmux service logs        Tail service logs
 
@@ -721,6 +746,10 @@ Options:
 
   When any env var is set, the unit file is written with mode 0600 so
   secrets are readable only by the installing user.
+
+  Alternatively, put machine-wide secrets (e.g. LINEAR_API_KEY) in
+  ~/.config/webmux/.env — the server loads it at startup regardless of which
+  directory it runs from, so they survive updates without re-baking the unit.
 `);
 }
 
@@ -732,7 +761,7 @@ export default async function service(args: string[]): Promise<void> {
     return;
   }
 
-  if (!["install", "uninstall", "status", "logs"].includes(action)) {
+  if (!["install", "uninstall", "restart", "status", "logs"].includes(action)) {
     p.log.error(`Unknown action: ${action}`);
     usage();
     return;
@@ -824,6 +853,9 @@ export default async function service(args: string[]): Promise<void> {
     case "uninstall":
       await uninstall(config);
       break;
+    case "restart":
+      restart(config);
+      break;
     case "status":
       status(config);
       break;

bin/src/webmux.ts

@@ -5,6 +5,7 @@ import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import type { Subprocess } from "bun";
 import pkg from "../../package.json";
+import { webmuxConfigEnvPath } from "../../backend/src/adapters/webmux-paths";
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
@@ -350,6 +351,14 @@ async function main(args: string[] = process.argv.slice(2)): Promise<void> {
   for (const key of await loadEnvFile(resolve(process.cwd(), ".env.local"))) projectEnvKeys.add(key);
   for (const key of await loadEnvFile(resolve(process.cwd(), ".env"))) projectEnvKeys.add(key);
 
+  // webmux's own global config env (`~/.config/webmux/.env`): machine-wide
+  // secrets like LINEAR_API_KEY the single service reads regardless of which
+  // directory it runs from. Loaded last so an already-set value wins — the unit
+  // and the launch project's `.env` both take precedence. Its keys join
+  // projectEnvKeys so they're stripped from the tmux global environment like any
+  // other secret webmux loads, rather than leaking into every session and pane.
+  for (const key of await loadEnvFile(webmuxConfigEnvPath())) projectEnvKeys.add(key);
+
   // When the user didn't pin a port, point CLI commands at the live server for
   // this project rather than the 5111 default. `webmux serve` walks to a free
   // port when 5111 is taken, so the running instance is often elsewhere (e.g.