feat(desktop,cli): support self-hosted desktop installs (#7136)

* feat(desktop,cli): support self-hosted desktop installs

The desktop shell was already origin-agnostic at runtime — navigation, CSP,
cookie partition, and the update feed all derive from the configured origin,
and every deployment already serves /api/desktop/update/download and its
updater manifest. The one thing missing was a way to change that origin:
ConfigStore.setOrigin had no IPC channel, menu item, or UI behind it, so a
self-hoster installing the signed build was stuck on the baked default.

Adds the native server picker (Sim → Server…, plus a "Change server" button on
the offline page, since a shell pointed at an unreachable origin lands there
with nothing else to click). Its IPC family is gated to bundled file: senders:
the surface that repoints the shell must keep working when the current server
cannot be reached, and must never be drivable by a page that server serves.
A confirmed change relaunches rather than swapping in place — the origin keys
the cookie partition, update feed, encrypted per-origin task state, and every
live browser view and PTY.

Adds `sim-setup desktop`, which resolves the installer from the operator's own
deployment, checks that the update feed resolves too, and prints the server URL
to paste in. Documents the whole path under self-hosting, including the
build-your-own escape hatch for organizations with their own Developer ID.

* refactor(desktop,cli): review pass on self-hosted desktop support

Two real defects found while auditing the change for hardcoded assumptions.

`lastRoute` is a single global setting that carries a workspace id, so it
survived an origin change and opened /workspace/<old-id> on the new server.
resolveStartRoute cannot rescue that — it discards a route only on a confirmed
403, and a fresh partition draws a 401. Cleared on change, via a named list
that is now the documented home for deployment-scoped settings; the agent
browser's jar and its known-sites metadata are deliberately kept, together,
since changing deployments does not imply the account changed.

The offline page's "Check status" sent self-hosters to status.sim.ai, which
reports on Sim's deployments and is always green for theirs. Withheld for a
non-sim.ai origin, as is the same link in the Help menu, through one
isSimCloudOrigin predicate. Hiding it needed `button[hidden]{display:none}`:
the page's own `button{display:inline-flex}` is an author rule and outranks the
UA `[hidden]`, so the attribute alone left it rendering. The e2e offline test
now asserts the whole path, which covers the `server:` local-page IPC gate.

Review cleanups: setOrigin no longer rewrites settings when handed the origin
it already stores; the picker window installs a permission handler and pre-
paints its background like every other window, and its page is theme-aware so
that background is not a flash; the CLI reuses httpHealth and the
cross-platform openBrowser instead of reimplementing both, skips Compose/Helm
discovery when --url makes it dead, and folds two parallel switches into one
exhaustive one. Value-flag parsing is now one helper instead of a third copy.

* fix(desktop,cli): scope deployment capabilities to their origin

Changing the server left two device-global stores in place that grant the
INCOMING deployment authority the user only handed the outgoing one: local
filesystem grants (directories its agent may read, plus security-scoped
bookmarks) and the agent browser's cookie jar (live third-party sessions its
agent may drive). Sign-out clears exactly this pair; an origin change is the
same boundary, so it now clears it too — awaited before the relaunch, since a
quit racing an async clear could leave either behind. browserKnownSites goes
with the jar it describes, so Sim is never left believing in sign-ins the
profile no longer has.

The CLI printed the redirect's filename straight to the terminal. It is read
out of a Location the deployment chose, so percent-encoded ANSI or OSC survives
decodeURIComponent as real control bytes and could forge CLI output; control
characters are stripped and the name is bounded before it reaches the spinner.

resolveDeploymentUrl took the first source naming an app URL. A machine with
both a local checkout and a real deployment would be probed, printed, and
opened at whichever enumerated first, silently — so disagreeing sources are now
an error naming each candidate and asking for --url, the way
resolveFeatureSetupDestination already refuses ambiguity.

* fix(desktop,cli): fail closed on origin change, widen terminal sanitizer

The capability teardown could partially fail and still let the shell move.
Sequential awaits meant a filesystem-grant rejection skipped the browser-profile
clear entirely, and the new origin was already persisted by then, so the
incoming deployment inherited whatever survived — and startup restores it.

Now the two stores clear independently via allSettled and report which ones
survived, and the whole teardown runs BEFORE anything is written. A store that
cannot be emptied refuses the change outright and names what it could not
clear. Nothing is persisted at that point, so refusing leaves the shell exactly
where it was rather than half-applying. Validation moved up front for the same
reason: a typo now costs no teardown.

The terminal sanitizer matched only C0/DEL/C1 by range, so percent-encoded bidi
overrides and isolates survived decodeURIComponent and could still reorder what
the reader sees without emitting one control byte. Matched by Unicode class
instead — Cc covers the cursor controls, Cf covers the bidi ones.

Configuration discovery compared raw strings, so a trailing slash, a default
port, a host-case difference, or an ignored path read as two different servers
and demanded a --url override to settle an ambiguity that did not exist. Now
compared on the parsed origin, which is what the command ends up using.

* fix(cli): sanitize the installer name by Unicode group, not by escape list

U+2028 and U+2029 are Zl/Zp, so the Cc/Cf filter let them through and a
deployment-controlled redirect filename could still forge a status line.

Enumerating what to strip had cost a patch per class found — C0 and C1, then
the bidi overrides, now the line separators — so this keeps whole groups
instead. `C` removes every control, format, surrogate, private-use, and
unassigned code point, covering ESC and OSC, the bidi overrides and isolates,
zero-width characters, and the BOM; `Z` removes every space, line, and
paragraph separator. Separators become a plain space rather than vanishing so
a name is not run together at the seam, and runs are collapsed so the result
cannot be padded to push text off the line.

The regression table now names each class that reached the terminal in an
earlier round, so a future bypass says which one came back.

* fix(desktop): serialize server changes and report partial teardown honestly

Two problems in the same transaction.

The picker re-enabled Connect whenever the field changed, including while a
request was in flight, so typing and pressing Enter could start a second change
that interleaved its teardown and its write with the first — the later write,
not a single transition, deciding the next server. The transaction is now
serialized in the main process, the way the sign-out coordinator guards its
own teardown, since the IPC boundary is reachable regardless of what the page
does; the page keeps its button disabled for the whole request so it never asks
for something it will only be refused.

The stores clear independently, so one can succeed while the other fails. There
is nothing to roll back to — a revoked cookie jar and deleted security-scoped
bookmarks cannot be un-deleted — and moving anyway would hand the incoming
deployment whatever survived. So the change is still refused, but the message
no longer names only the failed store as though nothing else had happened: it
says some local access may already have been cleared, and that retrying
finishes the job. Clearing an already-empty store succeeds, so a retry is safe.

Author: waleedlatif1

apps/desktop/e2e/smoke.spec.ts

@@ -113,7 +113,15 @@ test.describe('desktop shell smoke', () => {
     await expect(window.locator('.wordmark')).toBeVisible()
     await expect(window.locator('.wordmark')).toHaveAttribute('aria-label', 'Sim')
     await expect(window.locator('#title')).toHaveText('Can’t connect to Sim')
-    await expect(window.locator('#status')).toHaveText('Check status')
+    // The recovery path for a self-hosted shell pointed at a server it cannot
+    // reach. Exercised end to end here because it is the only coverage of the
+    // `server:` local-page IPC gate: the bundled page reads the configuration
+    // over the real preload bridge, and status.sim.ai is withheld because this
+    // origin is not one of Sim's own. `toBeHidden` is load-bearing — the page's
+    // own `button { display: inline-flex }` outranks the UA `[hidden]` rule, so
+    // the attribute alone does not hide it.
+    await expect(window.locator('#server')).toBeVisible()
+    await expect(window.locator('#status')).toBeHidden()
     await expect
       .poll(() => window.evaluate(() => document.fonts.check('16px "Season Sans"')))
       .toBe(true)

apps/desktop/src/main/config.test.ts

@@ -9,6 +9,7 @@ import {
   createConfigStore,
   DEFAULT_ORIGIN,
   isSafeInternalPath,
+  isSimCloudOrigin,
   partitionForOrigin,
   validateOriginInput,
 } from '@/main/config'
@@ -145,6 +146,26 @@ describe('createConfigStore', () => {
     expect(reloaded.getOrigin()).toBe('https://self-hosted.example')
   })
 
+  // setOrigin writes the whole settings file synchronously on the main thread,
+  // and re-confirming the URL already in the field is the common case in the
+  // server picker.
+  it('does not rewrite settings when setOrigin is given the stored origin', () => {
+    const filePath = tempSettingsPath()
+    const store = createConfigStore(filePath, {})
+    store.setOrigin('https://self-hosted.example')
+    // A sentinel only this test could have written. A rewrite serializes the
+    // in-memory settings over it, so its survival proves no write happened —
+    // unlike an mtime comparison, which two writes a fraction of a millisecond
+    // apart can pass by accident.
+    writeFileSync(filePath, `${readFileSync(filePath, 'utf8')}\n// sentinel\n`)
+
+    expect(store.setOrigin('https://self-hosted.example')).toEqual({
+      ok: true,
+      origin: 'https://self-hosted.example',
+    })
+    expect(readFileSync(filePath, 'utf8')).toContain('// sentinel')
+  })
+
   it('canonicalizes the apex production origin on setOrigin, not just on load', () => {
     // Entering https://sim.ai mid-session must not persist the apex: the
     // running session would use the wrong cookie partition and misclassify
@@ -223,6 +244,25 @@ describe('createConfigStore', () => {
   })
 })
 
+describe('isSimCloudOrigin', () => {
+  it('recognizes Sim-operated origins and nothing else', () => {
+    for (const origin of ['https://sim.ai', 'https://www.sim.ai', 'https://www.staging.sim.ai']) {
+      expect(isSimCloudOrigin(origin)).toBe(true)
+    }
+    // A lookalike host must not pass — the suffix check is on the parsed
+    // hostname, never a prefix or substring of the raw string.
+    for (const origin of [
+      'https://sim.example.com',
+      'https://sim.ai.evil.example',
+      'https://notsim.ai',
+      'http://localhost:3000',
+      'not a url',
+    ]) {
+      expect(isSimCloudOrigin(origin)).toBe(false)
+    }
+  })
+})
+
 describe('channelForOrigin', () => {
   it('maps each environment origin to its channel', () => {
     expect(channelForOrigin('https://sim.ai')).toBe('prod')

apps/desktop/src/main/config.ts

@@ -179,6 +179,22 @@ export function canonicalOrigin(origin: string): string {
   return ORIGIN_REWRITES[origin] ?? origin
 }
 
+/**
+ * Whether an origin is one of Sim's own deployments rather than a self-hosted
+ * one. Sim-operated resources — the public status page above all — describe
+ * only these, so a shell pointed elsewhere must not be offered them: telling a
+ * self-hoster whose server is down to consult a page that is always green
+ * sends the person who most needs an answer to the one place that has none.
+ */
+export function isSimCloudOrigin(origin: string): boolean {
+  try {
+    const host = new URL(origin).hostname.toLowerCase()
+    return host === 'sim.ai' || host.endsWith('.sim.ai')
+  } catch {
+    return false
+  }
+}
+
 /**
  * Maps a server origin to its cookie/storage partition. Each origin gets an
  * isolated persistent partition so sessions never leak across instances.
@@ -339,6 +355,12 @@ export function createConfigStore(
       // only repairs it on the next launch. The canonical origin is also
       // returned so the caller sees what was actually stored.
       const origin = canonicalOrigin(validated.origin)
+      // Re-confirming the origin already stored is the common case in the
+      // server picker, and setOrigin's write is a synchronous mkdir + whole-file
+      // write + rename on the main thread. There is nothing to persist.
+      if (origin === settings.origin) {
+        return { ok: true, origin }
+      }
       settings.origin = origin
       // Not debounced: changing the origin tears the session down and
       // reloads, so a pending write could be lost on the way out — and this

apps/desktop/src/main/index.ts

@@ -51,6 +51,7 @@ import { openExternalSafe } from '@/main/navigation'
 import { createEventLog } from '@/main/observability'
 import { ScopedEventRouter } from '@/main/scoped-event-router'
 import { installGlobalGuards } from '@/main/security-guards'
+import { createServerWindow, relaunchApp } from '@/main/server-window'
 import {
   createSessionLifecycleCoordinator,
   decideStartRoute,
@@ -78,6 +79,7 @@ function reportHandoffFailure(error: unknown): void {
 }
 
 const OFFLINE_PAGE = 'static/offline.html'
+const SERVER_PAGE = 'static/server.html'
 const DOCK_ICON_FOR_CHANNEL = {
   prod: 'dock-icon.png',
   staging: 'dock-icon-staging.png',
@@ -473,6 +475,35 @@ function main(): void {
     },
   })
 
+  const serverWindow = createServerWindow({
+    config,
+    defaultOrigin: DEFAULT_ORIGIN,
+    pagePath: SERVER_PAGE,
+    preloadPath,
+    isPackaged: app.isPackaged,
+    getParentWindow: getMainWindow,
+    clearDeploymentScopedState: async () => {
+      // allSettled, not sequential awaits: these are independent stores, and a
+      // rejection from the first must not skip the second — leaving the store
+      // that would have cleared fine still holding the outgoing deployment's
+      // access. Each failure is named so the picker can say what survived.
+      const stores = [
+        { label: 'local file access', clear: () => localFilesystem.forgetAll() },
+        { label: 'built-in browser sessions', clear: () => clearAgentBrowserProfile() },
+      ]
+      const outcomes = await Promise.allSettled(stores.map((store) => store.clear()))
+      return outcomes.flatMap((outcome, index) => {
+        if (outcome.status === 'fulfilled') return []
+        logger.error('Could not clear deployment-scoped state', {
+          store: stores[index].label,
+          error: getErrorMessage(outcome.reason),
+        })
+        return [stores[index].label]
+      })
+    },
+    relaunch: relaunchApp,
+  })
+
   /**
    * Routes through the coordinator rather than tearing down directly: the
    * coordinator holds the in-progress guard, clears the same handoff and grant
@@ -659,13 +690,19 @@ function main(): void {
         check: () => updater?.check(),
         install: () => updater?.install(),
       },
+      server: {
+        open: () => serverWindow.open(),
+        getConfiguration: () => serverWindow.getConfiguration(),
+        setOrigin: (origin) => serverWindow.setOrigin(origin),
+      },
     })
     await ensureMainWindow()
     installApplicationMenu({
       config,
       getMainWindow,
       allowHttpLocalhost,
       openSettings,
+      openServerSettings: () => serverWindow.open(),
       newWindow: () => void createAndLoadAppWindow(),
       newChat: () => void openMainWindowAt(newChatRoute(config.get('lastRoute'))),
       handleFocusedResourceShortcut: (win, shortcut) =>

apps/desktop/src/main/ipc.test.ts

@@ -316,6 +316,11 @@ describe('registerIpcHandlers', () => {
         check: vi.fn(),
         install: vi.fn(),
       },
+      server: {
+        open: vi.fn(),
+        getConfiguration: vi.fn(() => ({ origin: APP, defaultOrigin: APP, isSimCloud: true })),
+        setOrigin: vi.fn(async () => ({ ok: true as const, origin: APP, unchanged: true })),
+      },
     }
     registerIpcHandlers(deps)
   })

apps/desktop/src/main/ipc.ts

@@ -9,6 +9,8 @@ import {
 } from '@sim/browser-protocol'
 import {
   type DesktopNotificationPayload,
+  type DesktopServerChangeResult,
+  type DesktopServerConfiguration,
   type DesktopUpdateState,
   type DesktopWindowState,
   type DesktopZoomPercent,
@@ -301,6 +303,11 @@ export interface IpcDeps {
     check: () => void
     install: () => void
   }
+  server: {
+    open: () => void
+    getConfiguration: () => DesktopServerConfiguration
+    setOrigin: (origin: string) => Promise<DesktopServerChangeResult>
+  }
 }
 
 /**
@@ -1737,6 +1744,31 @@ export function registerIpcHandlers(deps: IpcDeps): void {
       passSender: true,
       handler: (sender) => deps.retryLoad(sender as WebContents),
     },
+    // The `server:` family is local-page only, and deliberately so: the one
+    // surface that repoints the shell at another deployment must keep working
+    // when the current one is unreachable (the offline page is where a
+    // self-hoster with a typo'd origin actually lands), and must never be
+    // drivable by a page the current server serves.
+    'server:open': {
+      kind: 'send',
+      gate: 'local-page',
+      handler: () => deps.server.open(),
+    },
+    'server:get-configuration': {
+      kind: 'invoke',
+      gate: 'local-page',
+      denied: null,
+      handler: () => deps.server.getConfiguration(),
+    },
+    'server:set-origin': {
+      kind: 'invoke',
+      gate: 'local-page',
+      denied: { ok: false, error: 'The server can only be changed from the Sim app itself.' },
+      handler: (origin) =>
+        typeof origin === 'string'
+          ? deps.server.setOrigin(origin)
+          : { ok: false, error: 'Server URL is required' },
+    },
   }
 
   const senderAllowed = (event: IpcMainEvent | IpcMainInvokeEvent, gate: ChannelGate): boolean => {

apps/desktop/src/main/menu.test.ts

@@ -6,18 +6,19 @@ import { BrowserWindow, type MenuItemConstructorOptions } from 'electron'
 import type { ConfigStore } from '@/main/config'
 import { buildMenuTemplate, type MenuDeps } from '@/main/menu'
 
-function makeDeps(): MenuDeps {
+function makeDeps(origin = 'https://sim.ai'): MenuDeps {
   return {
     config: {
       filePath: '/tmp/settings.json',
-      getOrigin: vi.fn(() => 'https://sim.ai'),
+      getOrigin: vi.fn(() => origin),
       setOrigin: vi.fn(),
       get: vi.fn(() => undefined),
       set: vi.fn(),
     } as unknown as ConfigStore,
     getMainWindow: vi.fn(() => null),
     allowHttpLocalhost: vi.fn(() => false),
     openSettings: vi.fn(),
+    openServerSettings: vi.fn(),
     newWindow: vi.fn(),
     newChat: vi.fn(),
     handleFocusedResourceShortcut: vi.fn(() => false),
@@ -51,6 +52,7 @@ describe('buildMenuTemplate', () => {
     expect(submenu(template, 'Sim').map((item) => item.label ?? item.role ?? item.type)).toEqual([
       'about',
       'Settings…',
+      'Server…',
       'Check for Updates…',
       'Sign Out',
       'separator',
@@ -105,6 +107,13 @@ describe('buildMenuTemplate', () => {
     expect(help.map((item) => item.label)).toEqual(['Sim Documentation', 'Sim Status'])
   })
 
+  // status.sim.ai reports on Sim's deployments only, so it is worse than
+  // useless to an operator whose own server is the one that is down.
+  it('drops Sim status for a self-hosted server', () => {
+    const help = submenu(buildMenuTemplate(makeDeps('https://sim.example.com')), 'Help')
+    expect(help.map((item) => item.label)).toEqual(['Sim Documentation'])
+  })
+
   it('never exposes developer tools in the application menu', () => {
     const view = submenu(buildMenuTemplate(makeDeps()), 'View')
     expect(view.some((item) => item.role === 'toggleDevTools')).toBe(false)

apps/desktop/src/main/menu.ts

@@ -1,6 +1,6 @@
 import type { MenuItemConstructorOptions } from 'electron'
 import { app, BrowserWindow, Menu } from 'electron'
-import type { ConfigStore } from '@/main/config'
+import { type ConfigStore, isSimCloudOrigin } from '@/main/config'
 import { DOCS_URL, STATUS_URL } from '@/main/external-links'
 import { openExternalSafe } from '@/main/navigation'
 import type {
@@ -15,6 +15,8 @@ export interface MenuDeps {
   getMainWindow: () => BrowserWindow | null
   allowHttpLocalhost: () => boolean
   openSettings: () => void
+  /** Opens the native server picker (see main/server-window.ts). */
+  openServerSettings: () => void
   newWindow: () => void
   newChat: () => void
   /**
@@ -155,6 +157,7 @@ export function buildMenuTemplate(deps: MenuDeps): MenuItemConstructorOptions[]
       submenu: [
         { role: 'about' },
         { label: 'Settings…', accelerator: 'CmdOrCtrl+,', click: deps.openSettings },
+        { label: 'Server…', click: deps.openServerSettings },
         { label: 'Check for Updates…', click: deps.checkForUpdates },
         { label: 'Sign Out', click: deps.signOut },
         { type: 'separator' },
@@ -250,10 +253,16 @@ export function buildMenuTemplate(deps: MenuDeps): MenuItemConstructorOptions[]
           label: 'Sim Documentation',
           click: () => void openExternalSafe(DOCS_URL, deps.allowHttpLocalhost()),
         },
-        {
-          label: 'Sim Status',
-          click: () => void openExternalSafe(STATUS_URL, deps.allowHttpLocalhost()),
-        },
+        // Omitted for a self-hosted shell, like the offline page's status
+        // button — see isSimCloudOrigin.
+        ...(isSimCloudOrigin(deps.config.getOrigin())
+          ? [
+              {
+                label: 'Sim Status',
+                click: () => void openExternalSafe(STATUS_URL, deps.allowHttpLocalhost()),
+              },
+            ]
+          : []),
       ],
     },
   ]