feat: add desktop update controls

Author: Nazmus Samir

lat.md/desktop-updates.md

@@ -0,0 +1,9 @@
+# Desktop Updates
+
+Desktop updates use GitHub releases and expose both a startup upgrade action and a Settings auto-upgrade preference.
+
+The Electron main process configures `electron-updater` against the repository publisher metadata from `electron-builder.yml`, which points at `fathah/hermes-desktop`. [[src/main/index.ts#setupUpdater]] registers update IPC handlers, persists the auto-upgrade preference under Electron `userData`, and applies that preference to `autoUpdater.autoDownload`.
+
+When GitHub reports a newer release, [[src/renderer/src/screens/Layout/Layout.tsx#Layout]] shows an upgrade button in the sidebar footer as soon as the app reaches the main layout. The button downloads the update when needed, shows download progress, and changes into a restart action after the update is ready.
+
+[[src/renderer/src/screens/Settings/Settings.tsx#Settings]] exposes the auto-upgrade desktop app toggle in the Hermes Agent settings section. When enabled, the startup release check downloads the update automatically; when disabled, the startup button remains available but downloading waits for the user's click.

lat.md/lat.md

@@ -5,3 +5,4 @@ This directory defines the high-level concepts, business logic, and architecture
 - [[web-preview]] — the in-app split-screen webview and the `partition`-based gate that lets only it load remote HTTPS while staying sandboxed.
 - [[code-blocks]] — collapsible long code blocks, and why expansion state is keyed on source position to survive react-markdown's streaming remounts.
 - [[window-chrome]] — the browser-style title bar where open-conversation tabs sit on top of the window drag region, clickable while empty space still drags.
+- [[desktop-updates]] — GitHub release checks, startup upgrade button behavior, and the Settings auto-upgrade preference.

src/main/index.ts

@@ -9,8 +9,9 @@ import {
   clipboard,
   session,
 } from "electron";
-import { join, extname } from "path";
+import { dirname, join, extname } from "path";
 import { randomUUID } from "crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { readdir, readFile, stat } from "fs/promises";
 import { electronApp, optimizer, is } from "@electron-toolkit/utils";
 import type { AppUpdater } from "electron-updater";
@@ -2679,9 +2680,42 @@ function buildMenu(): void {
   Menu.setApplicationMenu(menu);
 }
 
+let autoUpdaterInstance: AppUpdater | null = null;
+
+function updatePreferencesPath(): string {
+  return join(app.getPath("userData"), "update-preferences.json");
+}
+
+function getAutoUpgradeEnabled(): boolean {
+  try {
+    const file = updatePreferencesPath();
+    if (!existsSync(file)) return true;
+    const parsed = JSON.parse(readFileSync(file, "utf8")) as {
+      autoUpgrade?: unknown;
+    };
+    return parsed.autoUpgrade !== false;
+  } catch {
+    return true;
+  }
+}
+
+function setAutoUpgradeEnabled(enabled: boolean): void {
+  const file = updatePreferencesPath();
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify({ autoUpgrade: enabled }, null, 2)}\n`);
+}
+
 function setupUpdater(): void {
   // IPC handlers must always be registered to avoid invoke errors
   ipcMain.handle("get-app-version", () => app.getVersion());
+  ipcMain.handle("get-auto-upgrade-enabled", () => getAutoUpgradeEnabled());
+  ipcMain.handle("set-auto-upgrade-enabled", (_event, enabled: boolean) => {
+    setAutoUpgradeEnabled(enabled);
+    if (autoUpdaterInstance) {
+      autoUpdaterInstance.autoDownload = enabled;
+    }
+    return true;
+  });
 
   // Portable Windows builds set PORTABLE_EXECUTABLE_DIR. They have no
   // install location for electron-updater to replace in place, so an
@@ -2703,13 +2737,14 @@ function setupUpdater(): void {
   const { autoUpdater } = require("electron-updater") as {
     autoUpdater: AppUpdater;
   };
+  autoUpdaterInstance = autoUpdater;
 
   // Log the updater's own lifecycle to <userData>/logs/updater.log so a
   // failed update (e.g. issue #271) leaves something to diagnose.
   autoUpdater.logger = updaterLogger;
   // Auto-download as soon as an update is found, then surface a single
   // "Restart to Update" action once it's ready — no manual download step.
-  autoUpdater.autoDownload = true;
+  autoUpdater.autoDownload = getAutoUpgradeEnabled();
   autoUpdater.autoInstallOnAppQuit = true;
 
   autoUpdater.on("update-available", (info) => {

src/preload/index.d.ts

@@ -807,6 +807,8 @@ interface HermesAPI {
   downloadUpdate: () => Promise<boolean>;
   installUpdate: () => Promise<void>;
   getAppVersion: () => Promise<string>;
+  getAutoUpgradeEnabled: () => Promise<boolean>;
+  setAutoUpgradeEnabled: (enabled: boolean) => Promise<boolean>;
   onUpdateAvailable: (
     callback: (info: { version: string; releaseNotes: string }) => void,
   ) => () => void;

src/preload/index.ts

@@ -1052,6 +1052,10 @@ const hermesAPI = {
   downloadUpdate: (): Promise<boolean> => ipcRenderer.invoke("download-update"),
   installUpdate: (): Promise<void> => ipcRenderer.invoke("install-update"),
   getAppVersion: (): Promise<string> => ipcRenderer.invoke("get-app-version"),
+  getAutoUpgradeEnabled: (): Promise<boolean> =>
+    ipcRenderer.invoke("get-auto-upgrade-enabled"),
+  setAutoUpgradeEnabled: (enabled: boolean): Promise<boolean> =>
+    ipcRenderer.invoke("set-auto-upgrade-enabled", enabled),
 
   onUpdateAvailable: (
     callback: (info: { version: string; releaseNotes: string }) => void,

src/renderer/src/screens/Layout/Layout.tsx

@@ -257,20 +257,38 @@ function Layout({
   const [updateState, setUpdateState] = useState<
     "available" | "downloading" | "ready" | "error" | null
   >(null);
+  const [updateVersion, setUpdateVersion] = useState<string | null>(null);
+  const [updatePercent, setUpdatePercent] = useState<number | null>(null);
   const [updateError, setUpdateError] = useState<string | null>(null);
 
   useEffect(() => {
-    // Updates download silently in the background (autoDownload); we don't
-    // surface "available" or progress — only the ready/error end states.
+    // Surface a startup upgrade button as soon as GitHub reports a newer
+    // release. If auto-upgrade is enabled, electron-updater also downloads in
+    // the background and this state advances to downloading/ready.
+    const cleanupAvailable = window.hermesAPI.onUpdateAvailable((info) => {
+      setUpdateState("available");
+      setUpdateVersion(info.version);
+      setUpdateError(null);
+    });
+    const cleanupProgress = window.hermesAPI.onUpdateDownloadProgress(
+      (info) => {
+        setUpdateState("downloading");
+        setUpdatePercent(info.percent);
+        setUpdateError(null);
+      },
+    );
     const cleanupDownloaded = window.hermesAPI.onUpdateDownloaded(() => {
       setUpdateState("ready");
+      setUpdatePercent(null);
       setUpdateError(null);
     });
     const cleanupError = window.hermesAPI.onUpdateError((message) => {
       setUpdateState("error");
       setUpdateError(message);
     });
     return () => {
+      cleanupAvailable();
+      cleanupProgress();
       cleanupDownloaded();
       cleanupError();
     };
@@ -280,10 +298,11 @@ function Layout({
     if (updateState === "ready") {
       // The only user action: restart into the already-downloaded update.
       await window.hermesAPI.installUpdate();
-    } else if (updateState === "error") {
-      // Retry the auto-download that failed.
-      // Set downloading state immediately to prevent re-entrancy (double-click).
+    } else if (updateState === "available" || updateState === "error") {
+      // Download the available update (or retry a failed auto-download).
+      // Set downloading state immediately to prevent re-entrancy.
       setUpdateState("downloading");
+      setUpdatePercent(null);
       setUpdateError(null);
       try {
         const ok = await window.hermesAPI.downloadUpdate();
@@ -298,11 +317,17 @@ function Layout({
 
   const updateButtonTitle =
     updateError ??
-    (updateState === "ready"
-      ? t("common.restartToUpdate")
-      : updateState === "error"
-        ? t("common.updateFailed")
-        : undefined);
+    (updateState === "available" && updateVersion
+      ? t("common.updateAvailable", { version: updateVersion })
+      : updateState === "downloading"
+        ? updatePercent === null
+          ? t("common.downloading", { percent: 0 })
+          : t("common.downloading", { percent: updatePercent })
+        : updateState === "ready"
+          ? t("common.restartToUpdate")
+          : updateState === "error"
+            ? t("common.updateFailed")
+            : undefined);
 
   const handleNewChat = useCallback(() => {
     // Open a fresh run WITHOUT aborting others — any in-flight session keeps
@@ -567,18 +592,31 @@ function Layout({
         </nav>
 
         <div className="sidebar-footer">
-          {/* Downloads happen silently in the background — only surface the
-              button once the update is ready (or if it failed to download). */}
-          {(updateState === "ready" || updateState === "error") && (
+          {/* Show an upgrade affordance at startup when GitHub has a newer
+              release; it becomes a restart action once downloaded. */}
+          {updateState && (
             <button
               className={`sidebar-update-btn ${
                 updateState === "error" ? "error" : ""
               }`}
               onClick={handleUpdate}
+              disabled={updateState === "downloading"}
               title={updateButtonTitle}
               aria-label={updateButtonTitle}
             >
               <Download size={13} />
+              {updateState === "available" && (
+                <span>
+                  {updateVersion
+                    ? t("common.updateAvailable", { version: updateVersion })
+                    : t("common.updateAvailable", { version: "" })}
+                </span>
+              )}
+              {updateState === "downloading" && (
+                <span>
+                  {t("common.downloading", { percent: updatePercent ?? 0 })}
+                </span>
+              )}
               {updateState === "ready" && (
                 <span>{t("common.restartToUpdate")}</span>
               )}

src/renderer/src/screens/Settings/Settings.tsx

@@ -137,6 +137,8 @@ function Settings({ profile }: { profile?: string }): React.JSX.Element {
   const [updateResultType, setUpdateResultType] = useState<
     "success" | "error" | null
   >(null);
+  const [autoUpgradeEnabled, setAutoUpgradeEnabled] = useState(true);
+  const [autoUpgradeSaved, setAutoUpgradeSaved] = useState(false);
 
   // OpenClaw migration — initialize from localStorage cache
   const cachedClaw = getCachedOpenClaw();
@@ -219,10 +221,11 @@ function Settings({ profile }: { profile?: string }): React.JSX.Element {
     setHermesVersion(null);
 
     // Load fast config first (cached in main process)
-    const [aVersion, conn, keyStatus] = await Promise.all([
+    const [aVersion, conn, keyStatus, autoUpgrade] = await Promise.all([
       window.hermesAPI.getAppVersion(),
       window.hermesAPI.getConnectionConfig(),
       window.hermesAPI.getApiServerKeyStatus(profile),
+      window.hermesAPI.getAutoUpgradeEnabled(),
     ]);
 
     if (requestId !== loadConfigRequestRef.current) return;
@@ -245,6 +248,7 @@ function Settings({ profile }: { profile?: string }): React.JSX.Element {
     setSshRemotePort(conn.ssh?.remotePort ? String(conn.ssh.remotePort) : "");
     setSshLocalPort(conn.ssh?.localPort ? String(conn.ssh.localPort) : "");
     setApiServerKeyMissing(!keyStatus.hasKey);
+    setAutoUpgradeEnabled(autoUpgrade);
     connLoaded.current = true;
 
     const homeResult = await Promise.resolve()
@@ -683,6 +687,13 @@ function Settings({ profile }: { profile?: string }): React.JSX.Element {
     }
   }
 
+  async function handleAutoUpgradeChange(enabled: boolean): Promise<void> {
+    setAutoUpgradeEnabled(enabled);
+    await window.hermesAPI.setAutoUpgradeEnabled(enabled);
+    setAutoUpgradeSaved(true);
+    setTimeout(() => setAutoUpgradeSaved(false), 2000);
+  }
+
   // Parse "Hermes Agent v0.7.0 (2026.4.3) Project: ... Python: 3.11.15 OpenAI SDK: 2.30.0 Update available: ..."
   const parsedVersion = (() => {
     if (!hermesVersion) return null;
@@ -819,6 +830,32 @@ function Settings({ profile }: { profile?: string }): React.JSX.Element {
               {dumpRunning ? t("settings.running") : t("settings.debugDump")}
             </button>
           </div>
+          <div className="settings-field" style={{ marginTop: 12 }}>
+            <label className="settings-field-label">
+              {t("settings.autoUpgradeDesktop")}
+              {autoUpgradeSaved && (
+                <span className="settings-saved" style={{ marginLeft: 8 }}>
+                  {t("settings.saved")}
+                </span>
+              )}
+              <label
+                className="tools-toggle"
+                style={{ marginLeft: 12, verticalAlign: "middle" }}
+              >
+                <input
+                  type="checkbox"
+                  checked={autoUpgradeEnabled}
+                  onChange={(e) =>
+                    void handleAutoUpgradeChange(e.target.checked)
+                  }
+                />
+                <span className="tools-toggle-track" />
+              </label>
+            </label>
+            <div className="settings-field-hint">
+              {t("settings.autoUpgradeDesktopHint")}
+            </div>
+          </div>
           {updateResult && (
             <div
               className={`settings-hermes-result ${updateResultType || "error"}`}

src/shared/i18n/locales/en/settings.ts

@@ -94,6 +94,9 @@ export default {
   updating: "Updating...",
   updateEngine: "Update Engine",
   latestVersion: "Already up to date",
+  autoUpgradeDesktop: "Auto-upgrade desktop app",
+  autoUpgradeDesktopHint:
+    "Automatically download new Hermes One releases from GitHub when the app starts. Turn this off to show the startup upgrade button without downloading until you click it.",
   runningDiagnosis: "Running diagnosis...",
   runDiagnosis: "Run Diagnosis",
   running: "Running...",