Desktop App

Sophon Desktop is an Electron-based native wrapper around the Dashboard. You get the same UI as the web app, plus things that only make sense on a real desktop — tray/menu-bar integration, global keyboard shortcuts, native desktop notifications, and auto-update.

Why install the desktop app vs. using the browser?

• Always-on — tray/menu-bar icon keeps Sophon running even when no window is open; click to focus.
• Global push-to-talk — hold a configurable hotkey from anywhere on your desktop; speak; release; the agent responds.
• Native notifications — approvals and completed tasks land as OS-native notifications (not browser notifications that get buried in your tab stack).
• Offline-safe UI — the window stays open and usable even if the Gateway briefly drops; reconnects automatically.
• Window management — proper window controls, dock integration on macOS, taskbar badge on Windows.

For most users it's a quality-of-life upgrade. The browser Dashboard still works if you prefer it.

Installation

macOS

Download Sophon-<version>-arm64.dmg (or -x64.dmg) from https://releases.sophon.dev/desktop. Mount, drag Sophon to Applications, eject.

First launch: macOS will warn "downloaded from the internet." Right-click → Open (once); subsequent launches are automatic.

Windows

Download Sophon-Setup-<version>.exe. Run. Installer places Sophon in %LOCALAPPDATA%\Programs\Sophon and creates Start Menu / Desktop shortcuts.

No admin rights required (per-user install). An optional all-users installer is available for team rollouts.

Linux

AppImage: Sophon-<version>.AppImage — download, chmod +x, run. No install required.

DEB / RPM packages for major distros also available.

First-run setup

On first launch, the app asks for your Gateway URL — http://localhost:8080 for a local dev Gateway, or https://gw.example.com for a deployed one. Paste, click Continue. The app verifies reachability, redirects to sign-in, and remembers the URL.

Change the Gateway URL later from Settings → About → Gateway URL or by deleting ~/.sophon-desktop/config.json.

Tray / menu bar

The tray icon (Windows system tray; macOS menu bar; Linux status notifier) provides:

• Show / Hide window — one-click
• Voice mode — toggle push-to-talk listener
• Pending approvals — count badge + quick actions
• Active tasks — live count of running tasks
• Quit Sophon

On macOS the icon lives in the right-hand menu bar. On Windows it's in the system tray (may be hidden in the tray overflow; pin it to the main tray for visibility).

Global keyboard shortcuts

Configurable in Settings → Desktop → Shortcuts:

Global shortcuts work system-wide — you don't need Sophon focused.

Native notifications

Approvals and task completions deliver as OS-native notifications:

• macOS — Notification Center entries with Approve / Reject action buttons
• Windows — Action Center toasts with inline buttons
• Linux — notify-send notifications (actions depend on DE)

Click a notification to open Sophon to the relevant screen (approval detail, completed task, etc.).

Configure which events fire native notifications in Settings → Notifications.

Auto-update

On startup and once every 24 hours, the app checks for updates. Updates are:

• Differential — only the changed bits are downloaded
• Code-signed — macOS via Apple Developer ID; Windows via Authenticode
• Rollback-safe — if the update fails to start, the app reverts to the previous version

Manual update: Help → Check for updates…

Update channels: stable (default), beta, nightly — change in Settings → About → Update channel.

Multiple accounts

Switch between Gateways (e.g., home, work, personal cloud) with File → Switch account. Each account stores its own session tokens.

macOS-specific

• Dock integration — badge count reflects pending approvals + unread messages
• Dark mode — follows system appearance by default (overridable)
• Menu bar — right-click for quick actions
• Full-screen mode — standard macOS full-screen; voice overlay is available in a detached window if you want it to float

Windows-specific

• Jump list — recent sessions accessible from the Start Menu context menu
• Taskbar badge — notification count
• Snap assist — resizable + snappable like any native window
• Single-instance lock — launching the app a second time focuses the existing window

Linux-specific

• Desktop entry — registered via ~/.local/share/applications/sophon.desktop
• URI handler — registers sophon:// scheme (for deep links from emails / chat)
• Wayland — full support; X11 compatibility layer for older DEs

Uninstall

• macOS — drag Sophon.app to Trash; remove ~/Library/Application Support/Sophon/ to wipe config
• Windows — Apps & Features → Sophon → Uninstall
• Linux — apt remove sophon / rpm -e sophon, or delete the AppImage

Uninstalling doesn't affect the Gateway or your data — those live in ~/.sophon/.

Troubleshooting

"Can't connect to Gateway" — check Gateway URL in Settings → About. Try the URL in a browser; if it works there but not in the app, your system may be blocking WebSockets.

Global shortcut doesn't trigger — another app may own the same shortcut. Change it in Settings → Desktop → Shortcuts.

Native notifications don't appear — grant notification permission on first prompt. If missed, re-enable in OS settings:

• macOS: System Settings → Notifications → Sophon
• Windows: Settings → System → Notifications → Sophon
• Linux: depends on DE; GNOME is Settings → Notifications

macOS "app is damaged" warning after update — Gatekeeper quarantine. Run xattr -d com.apple.quarantine /Applications/Sophon.app once.

Where to go next

• Dashboard — the same UI on the web
• Mobile App — iOS / Android companion
• CLI — scripted access