fix desktop preload build and rename app (#1150)

* fix desktop preload fetch typing

* rename desktop app to Hermes Studio

* rename desktop package to Hermes Studio

* update Hermes Studio desktop icons

* configure desktop signing and app id

* force desktop api calls to local server

* isolate desktop agent bridge ports

* bundle MCP support in desktop Python

* change desktop default port to 8748

* restore webui production port copy

.github/workflows/desktop-release.yml

@@ -89,6 +89,12 @@ jobs:
         run: npm --prefix packages/desktop run prepare:python
 
       - name: Build desktop artifact
+        env:
+          CSC_LINK: ${{ matrix.target_os == 'darwin' && secrets.MAC_CSC_LINK || '' }}
+          CSC_KEY_PASSWORD: ${{ matrix.target_os == 'darwin' && secrets.MAC_CSC_KEY_PASSWORD || '' }}
+          APPLE_ID: ${{ matrix.target_os == 'darwin' && secrets.APPLE_ID || '' }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ matrix.target_os == 'darwin' && secrets.APPLE_APP_SPECIFIC_PASSWORD || '' }}
+          APPLE_TEAM_ID: ${{ matrix.target_os == 'darwin' && secrets.APPLE_TEAM_ID || '' }}
         run: npm --prefix packages/desktop run dist -- ${{ matrix.electron_target }} --publish never
 
       - name: Upload artifacts to release

packages/client/src/api/client.ts

@@ -2,8 +2,14 @@ import router from '@/router'
 
 const DEFAULT_BASE_URL = ''
 
+function isDesktopShell(): boolean {
+  return typeof window !== 'undefined' &&
+    (window as typeof window & { hermesDesktop?: { isDesktop?: boolean } }).hermesDesktop?.isDesktop === true
+}
+
 function getBaseUrl(): string {
   if (import.meta.env.VITE_HERMES_PREVIEW === '1') return DEFAULT_BASE_URL
+  if (isDesktopShell()) return DEFAULT_BASE_URL
   return localStorage.getItem('hermes_server_url') || DEFAULT_BASE_URL
 }
 

packages/desktop/README.md

@@ -1,6 +1,6 @@
-# Hermes Desktop
+# Hermes Studio
 
-Electron desktop distribution for Hermes Web UI.
+Electron desktop distribution for Hermes Studio.
 
 ## Data directories
 

packages/desktop/electron-builder.yml

@@ -1,5 +1,5 @@
-appId: com.hermesagent.desktop
+appId: com.hermeswebui.studio
-productName: Hermes Desktop
+productName: Hermes Studio
 copyright: Copyright © 2026
 
 directories:
@@ -45,9 +45,9 @@ mac:
     - target: dmg
       arch: [arm64, x64]
   category: public.app-category.developer-tools
-  hardenedRuntime: false
+  hardenedRuntime: true
   gatekeeperAssess: false
-  identity: null
+  notarize: true
   artifactName: "${productName}-${version}-${arch}.${ext}"
 
 win:

packages/desktop/package-lock.json

@@ -1,11 +1,11 @@
 {
-  "name": "hermes-desktop",
+  "name": "hermes-studio",
   "version": "0.6.5",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "hermes-desktop",
+      "name": "hermes-studio",
       "version": "0.6.5",
       "license": "MIT",
       "dependencies": {

packages/desktop/package.json

@@ -1,11 +1,11 @@
 {
-  "name": "hermes-desktop",
+  "name": "hermes-studio",
   "version": "0.6.5",
-  "description": "Desktop distribution for Hermes Web UI with bundled Python runtime and hermes-agent",
+  "description": "Hermes Studio desktop distribution with bundled Python runtime and hermes-agent",
   "homepage": "https://ekkolearnai.com",
   "author": {
-    "name": "Hermes Desktop Contributors",
+    "name": "Hermes Studio Contributors",
-    "email": "noreply@hermes-desktop.local"
+    "email": "noreply@hermes-studio.local"
   },
   "license": "MIT",
   "private": true,

packages/desktop/scripts/install-hermes.mjs

@@ -13,6 +13,7 @@ const ROOT = resolve(__dirname, '..')
 const TARGET_OS = process.env.TARGET_OS || osPlatform()
 const TARGET_ARCH = process.env.TARGET_ARCH || osArch()
 const HERMES_VERSION = process.env.HERMES_VERSION || '0.15.2'
+const HERMES_PACKAGE = process.env.HERMES_PACKAGE || `hermes-agent[mcp]==${HERMES_VERSION}`
 
 const OS_LABEL = TARGET_OS === 'win32' ? 'win' : TARGET_OS === 'darwin' ? 'mac' : TARGET_OS
 const PY_DIR = resolve(ROOT, 'resources', 'python', `${OS_LABEL}-${TARGET_ARCH}`)
@@ -33,23 +34,32 @@ function hasUv() {
 
 let r
 if (hasUv()) {
-  console.log(`→ Installing hermes-agent==${HERMES_VERSION} via uv`)
+  console.log(`→ Installing ${HERMES_PACKAGE} via uv`)
   r = spawnSync('uv', [
     'pip', 'install',
     '--python', pyBin,
-    `hermes-agent==${HERMES_VERSION}`,
+    HERMES_PACKAGE,
   ], { stdio: 'inherit' })
 } else {
-  console.log(`→ Installing hermes-agent==${HERMES_VERSION} via pip`)
+  console.log(`→ Installing ${HERMES_PACKAGE} via pip`)
   r = spawnSync(pyBin, [
     '-m', 'pip', 'install',
-    `hermes-agent==${HERMES_VERSION}`,
+    HERMES_PACKAGE,
     '--no-warn-script-location',
     '--disable-pip-version-check',
   ], { stdio: 'inherit' })
 }
 if (r.status !== 0) process.exit(r.status ?? 1)
 
+r = spawnSync(pyBin, [
+  '-c',
+  'import mcp; import tools.mcp_tool as t; assert t._MCP_AVAILABLE',
+], { stdio: 'inherit' })
+if (r.status !== 0) {
+  console.error('MCP Python SDK sanity check failed')
+  process.exit(r.status ?? 1)
+}
+
 const hermesBin = TARGET_OS === 'win32'
   ? resolve(PY_DIR, 'Scripts', 'hermes.exe')
   : resolve(PY_DIR, 'bin', 'hermes')

packages/desktop/src/main/index.ts

@@ -4,7 +4,7 @@ import { startWebUiServer, stopWebUiServer, getToken } from './webui-server'
 import { hermesBinExists, hermesBin } from './paths'
 import { initAutoUpdater } from './updater'
 
-const PORT = Number(process.env.HERMES_DESKTOP_PORT) || 8648
+const PORT = Number(process.env.HERMES_DESKTOP_PORT) || 8748
 
 let mainWindow: BrowserWindow | null = null
 let serverUrl: string | null = null
@@ -15,7 +15,7 @@ function createWindow() {
     height: 820,
     minWidth: 960,
     minHeight: 600,
-    title: 'Hermes Desktop',
+    title: 'Hermes Studio',
     backgroundColor: '#1a1a1a',
     autoHideMenuBar: true,
     webPreferences: {
@@ -46,7 +46,7 @@ function createWindow() {
 }
 
 function splashHtml(): string {
-  const html = `<!doctype html><html><head><meta charset="utf-8"><title>Hermes Desktop</title>
+  const html = `<!doctype html><html><head><meta charset="utf-8"><title>Hermes Studio</title>
 <style>
   html,body{margin:0;height:100%;background:#1a1a1a;color:#e5e5e5;font-family:-apple-system,BlinkMacSystemFont,Segoe UI,Helvetica,Arial,sans-serif;}
   .wrap{display:flex;flex-direction:column;align-items:center;justify-content:center;height:100%;gap:24px}
@@ -57,7 +57,7 @@ function splashHtml(): string {
   .label{font-size:14px;color:#999}
   h1{font-weight:500;margin:0;font-size:18px}
 </style></head><body><div class="wrap">
-<h1>Hermes Desktop</h1>
+<h1>Hermes Studio</h1>
 <div class="row"><div class="dot"></div><div class="dot"></div><div class="dot"></div></div>
 <div class="label">Starting local services…</div>
 </div></body></html>`

packages/desktop/src/main/updater.ts

@@ -26,7 +26,7 @@ export function initAutoUpdater() {
     const { response } = await dialog.showMessageBox({
       type: 'info',
       title: 'Update ready',
-      message: `Hermes Desktop ${info.version} is ready to install.`,
+      message: `Hermes Studio ${info.version} is ready to install.`,
       detail: 'Restart now to apply the update, or it will be installed on next quit.',
       buttons: ['Restart now', 'Later'],
       defaultId: 0,

packages/desktop/src/main/webui-server.ts

@@ -1,11 +1,12 @@
 import { ChildProcess, spawn } from 'node:child_process'
 import { mkdirSync, readFileSync, writeFileSync, chmodSync, existsSync } from 'node:fs'
+import { createServer } from 'node:net'
 import { dirname, delimiter, join } from 'node:path'
 import { randomBytes } from 'node:crypto'
 import { app } from 'electron'
 import { webuiServerEntry, webuiDir, hermesBin, webUiHome, hermesHome, tokenFile, pythonDir } from './paths'
 
-const DEFAULT_PORT = 8648
+const DEFAULT_PORT = 8748
 const READY_TIMEOUT_MS = 30_000
 
 let serverProc: ChildProcess | null = null
@@ -50,6 +51,43 @@ export function getServerUrl(port = DEFAULT_PORT): string {
   return `http://127.0.0.1:${port}`
 }
 
+async function getFreeTcpPort(): Promise<number> {
+  return await new Promise((resolveFreePort, rejectFreePort) => {
+    const server = createServer()
+    server.unref()
+    server.once('error', rejectFreePort)
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address()
+      server.close(() => {
+        if (typeof address === 'object' && address?.port) {
+          resolveFreePort(address.port)
+        } else {
+          rejectFreePort(new Error('Unable to allocate local TCP port'))
+        }
+      })
+    })
+  })
+}
+
+async function canBindTcpPort(port: number): Promise<boolean> {
+  return await new Promise((resolveCanBind) => {
+    const server = createServer()
+    server.unref()
+    server.once('error', () => resolveCanBind(false))
+    server.listen(port, '127.0.0.1', () => {
+      server.close(() => resolveCanBind(true))
+    })
+  })
+}
+
+async function getFreeTcpPortInRange(min: number, max: number): Promise<number> {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    const port = min + (randomBytes(2).readUInt16BE(0) % (max - min + 1))
+    if (await canBindTcpPort(port)) return port
+  }
+  return getFreeTcpPort()
+}
+
 export async function startWebUiServer(port = DEFAULT_PORT): Promise<string> {
   ensureNativeModules()
   const token = ensureToken()
@@ -71,6 +109,8 @@ export async function startWebUiServer(port = DEFAULT_PORT): Promise<string> {
   const bundledPython = isWin
     ? join(pythonDir(), 'python.exe')
     : join(pythonDir(), 'bin', 'python3')
+  const bridgePort = await getFreeTcpPort()
+  const workerPortBase = await getFreeTcpPortInRange(20000, 59000)
 
   // Run via Electron's "run as Node" mode — Electron binary doubles as Node.
   const env: NodeJS.ProcessEnv = {
@@ -85,10 +125,11 @@ export async function startWebUiServer(port = DEFAULT_PORT): Promise<string> {
     // unix socket is rejected on macOS in some EDR/sandbox setups (silent
     // SIGKILL of the bridge child within ~150ms). TCP on 127.0.0.1 works
     // identically and avoids the issue cross-platform.
-    HERMES_AGENT_BRIDGE_ENDPOINT: 'tcp://127.0.0.1:18765',
+    HERMES_AGENT_BRIDGE_ENDPOINT: `tcp://127.0.0.1:${bridgePort}`,
     // Force TCP for worker endpoints too (upstream #1106). Same EDR/sandbox
     // reason as above — default ipc:// unix sockets in /tmp get killed.
     HERMES_AGENT_BRIDGE_WORKER_TRANSPORT: 'tcp',
+    HERMES_AGENT_BRIDGE_WORKER_PORT_BASE: String(workerPortBase),
     // And for preview-mode bridges spawned by the in-app update controller.
     HERMES_WEB_UI_PREVIEW_AGENT_BRIDGE_TRANSPORT: 'tcp',
     // Suppress the npm-registry update prompt (upstream #1105). hermes-web-ui

packages/desktop/src/preload/index.ts

@@ -56,7 +56,7 @@ function stripCredentialFlag(text: string): string {
 
 function installFetchPatch(): void {
   const origFetch = window.fetch.bind(window)
-  window.fetch = async (input, init) => {
+  const patchedFetch = (async (input, init) => {
     const res = await origFetch(input, init)
     try {
       const url = typeof input === 'string' ? input : (input as Request).url
@@ -73,7 +73,8 @@ function installFetchPatch(): void {
       }
     } catch { /* fall through */ }
     return res
-  }
+  }) as typeof window.fetch
+  window.fetch = patchedFetch
 
   const OrigXHR = window.XMLHttpRequest
   type XHRWithDesktop = XMLHttpRequest & { __hermesDesktopUrl?: string }