# Desktop app OpenSmartRoute Desktop puts your router one keystroke away in every application on your computer. Press **Ctrl+Shift+Space** (**⌘⇧Space** on a Mac) and a small bar opens over whatever you are doing - Word, Outlook, Slack, Teams, VS Code, Notes, a terminal, a browser. Type a request, press Enter, and the router picks the model, answers, and tells you which model it was, how sure it was, what it cost and how long it took. The app also installs the [browser extension](https://opensmartroute.ai/docs/EXTENSION.md) into every browser on the machine and keeps itself up to date. Windows, macOS and Linux. Download from the [product page](https://opensmartroute.ai/desktop) or the [downloads page](https://opensmartroute.ai/downloads); the current build, its size and SHA-256 are listed there. ## Install | System | File | Notes | |---|---|---| | Windows 10/11 (x64, ARM) | `OpenSmartRoute--win-x64.exe` / `-win-arm64.exe` | One-click installer, per user, no administrator rights. `-win-x64-portable.exe` runs without installing (and does not self-update) | | macOS 12+ (Apple silicon, Intel) | `OpenSmartRoute--mac-arm64.dmg` / `-mac-x64.dmg` (or `.zip`) | Drag to Applications. The app lives in the menu bar; it has no Dock icon | | Linux | `.AppImage` (any distribution), `.deb` (Debian, Ubuntu), `.rpm` (Fedora, openSUSE) | The AppImage self-updates; `.deb` and `.rpm` update through your package manager | The first run asks nothing. The app registers itself to start when you sign in, registers the browser extension with every browser on the computer (the way each browser allows - see [Add the extension to every browser](#add-the-extension-to-every-browser)) and opens a short welcome that reports what it did, with one optional button: **Connect** your workspace. Offline, the extension registration waits and completes by itself as soon as the platform is reachable, on this or a later start. Everything can be changed later from Settings. After that the app sits in the system tray (Windows, Linux) or menu bar (macOS) and waits for the shortcut. Signing depends on the release artifact. Windows SmartScreen can warn about unsigned files and signed files without sufficient reputation; a signature does not guarantee a warning-free install. macOS ad-hoc signing is not Developer ID signing or notarization. Gatekeeper and organization policy may still block it. Download only from the official downloads page, compare its SHA-256, and inspect the publisher signature before deciding whether to proceed. A matching hash confirms the download matches that published file; it does not establish publisher identity or prove the software is safe. For a verified file you trust, Windows may offer **More info > Run anyway**, and macOS may offer **Open Anyway** under **System Settings > Privacy & Security**. Do not disable system protections or override an organization's security policy. Distributing a Windows installer directly does not require Microsoft Store enrollment. Trusted code signing is a separate service and may have fees and identity checks. A free Apple developer account supports local development, not public Developer ID signing or notarization. Free browser distribution options and their owner-verification steps are covered in [publisher enrollment](https://opensmartroute.ai/docs/EXTENSION.md#publisher-enrollment-and-automation). ## The command bar - **Open** it with the shortcut from any app, from the tray menu (*Ask*), or by opening an `osr://` link. If another program already holds Ctrl+Shift+Space the app falls back to Ctrl+Alt+Space and says so in Settings. - **Type** a request. While you type, the same checks the browser extension runs happen on this computer: the verdict line says *Looks good to send*, *2 personal details in your draft* or *An API key is in your draft*, with the task, the token count and whether a quick, standard or thinking model is enough. **Redact** swaps personal details for placeholders such as `` before anything is sent. - **Choose what matters** with the four chips: **Balanced** (default), **Cheapest**, **Best**, **Fastest**. They set the router's objective for the next request. - **Enter** sends, **Shift+Enter** adds a line, **Esc** steps back one level at a time (clears the draft, then closes the bar). **New chat** starts a fresh thread; the bar keeps the thread while it is open. - **Every answer** carries the decision under it - *routed to gpt-4.1-mini · 91% sure · $0.0004 · 780 ms* - with **Copy** and thumbs up / down. Your thumbs are outcome feedback: the router learns from them. - The bar follows the light or dark appearance of your system. ## Working inside the app in front When the bar opens it asks the operating system which application is in front and reads the text you have selected there (Settings › *Read what I selected when the bar opens*, on by default). The selection appears as a chip - *240 chars selected in Word* - with one-click actions: **Explain**, **Summarise**, **Rewrite**, **Fix grammar**, **Shorten**, **Translate**. Every answer then offers **Paste into Word** (or whichever app it was), which puts the answer where your cursor was. Pasting is always an explicit click; nothing is typed into another app on its own. | Where | What happens | |---|---| | Word, Outlook, Notes, mail and documents | Selection read, answer pasted back at the cursor | | Slack, Teams | A thread or message turned into a decision or action items, pasted into the composer | | VS Code and other editors | Explain an error or a function, write the test, paste it back | | Terminals (Windows Terminal, PowerShell, iTerm, GNOME Terminal…) | The bar never sends Ctrl+C to a terminal - it would interrupt the running program - so nothing is read there; type or paste the command output instead. Pasting back works | | Browsers | The selection is read like any other app; on the chat sites the browser extension already sits under the composer | *Attach the clipboard when the bar opens* (off by default) offers whatever you copied last as context, on this computer only, until you send. Requirements per system: Windows needs nothing. macOS asks once for the **Accessibility** permission (System Settings › Privacy & Security › Accessibility); Settings shows the prompt when it is missing. Linux on X11 needs `xdotool`; on Wayland it needs `wl-clipboard` (to read the highlighted text - no key is sent) and `wtype` (to paste back), and on KDE `kdotool` names the app in front - elsewhere the chip says *selected text* and the paste button says **Paste back**. Settings names exactly what is missing; the bar itself works everywhere. ## Connect your workspace The on-device checks work without an account. To ask through your router, press **Connect** in the welcome, the bar or Settings › Workspace: the browser opens a sign-in page for this computer, you approve it, and the app receives a workspace key. From then on answers come from your workspace's own models, prices and rules, and every request appears in your [dashboard](https://opensmartroute.ai/docs/PLATFORM.md#13-dashboard) with its trace. *Self-hosted or using a key* (Settings › Workspace) holds the platform address, the API style and the tenant for a self-hosted router, and a field to paste a key directly instead of signing in. **Sign out** removes the key from this computer. The key is stored encrypted with your account's own secret store (Windows DPAPI, the macOS Keychain, the Linux keyring) so a copied file is worthless on another machine or account; where no keyring exists it stays in a file readable by your user only. ## Add the extension to every browser First-run setup, or **Add to my browsers** in Settings › Browser extension or the tray menu, finds browsers that have a profile on this machine - Chrome, Edge, Brave, Chromium, Vivaldi, Arc, Firefox, Safari - and registers the browser extension when a compatible published listing or signed package is available: | Browser | What you will see | |---|---| | Chrome, Edge, Brave, Chromium, Vivaldi, Arc | Registration requires the appropriate published store ID. The browser may ask you to enable it after restart; support and organization policy vary. A successful registration write is not proof that the browser installed it | | Firefox | Requires a Mozilla-signed package. The app attempts a browser policy registration; on Linux it reports the system-wide path an administrator must manage. Organization policy can prevent installation | | Safari | Opens the App Store listing when there is one | Settings lists the outcome per browser. **Remove** undoes everything the app wrote, and so does uninstalling the app on Windows (the uninstaller takes the registrations back before it removes the files; an update leaves them in place). While a store listing is not live yet the row says *not available yet* and links to the [extension page](https://opensmartroute.ai/extension). ## Settings Open Settings from the gear in the bar, the tray menu or `osr://settings`. | Section | What it holds | |---|---| | **Workspace** | Connect / Sign out, the connected workspace; *Self-hosted or using a key* - platform address, API style, tenant, a pasted key | | **Command bar** | The shortcut (press the keys you want; a combination another app holds is refused and the old one stays), *Start when I sign in*, *Read what I selected when the bar opens*, *Attach the clipboard when the bar opens* | | **Browser extension** | Add / Remove, one line per browser with what happened | | **Privacy** | *Send my draft to get prices while I type* - off: only the on-device checks run until you press Enter; on: your workspace prices the draft as you type (the text is not stored) | | **Updates** | The installed version, *Check now*, *Download*, *Restart to update*, *Download updates automatically*, and a *Self-hosted update server* field | | **What's new** | The release notes of the installed version | ## Updates The app checks for a new version 30 seconds after it starts and every six hours. With *Download updates automatically* (default) the new version downloads in the background; a notification and the first line of the tray menu then offer **Restart to update**. Nothing restarts on its own - a downloaded update is applied when you choose to restart or when you quit. Development builds, the Windows portable exe and `.deb` / `.rpm` installs do not self-update; the Updates section says why. The same goes for the macOS build until it is signed with an Apple Developer ID: macOS only lets an app replace itself with one carrying the same signature, so the Updates section reads *not signed with an Apple Developer ID* and the downloads page is the way to a new version. Self-hosted deployments point *Self-hosted update server* at any web folder that holds the installers and the `latest*.yml` files the build produces (see the [deployment guide](https://opensmartroute.ai/docs/INSTALL.md)). ## Code signing without buying a certificate The installers work unsigned; what a signature buys is the absence of the SmartScreen and Gatekeeper prompts described under [Install](#install). None of the paths below needs a traditional code-signing certificate from a commercial CA, and the pipeline (`azure-pipelines/desktop.yml`) takes each one automatically as soon as its variables exist in the `osr-platform-prod` variable group - nothing else changes. | System | Path | What it needs | Pipeline variables | |---|---|---|---| | Windows | **Azure Trusted Signing** (Artifact Signing): Microsoft issues short-lived Public Trust certificates from an identity-validated account and signs through the service; SmartScreen treats the publisher as known from the first download. | An Azure subscription, the Basic tier of the service (a small monthly fee), and identity validation - an organisation in the United States, Canada, the European Union, the United Kingdom, Australia, New Zealand, Japan, South Korea, Singapore, Switzerland, Norway or Israel, or an individual in the United States or Canada (government ID, a few days). The pipeline's service connection gets the *Artifact Signing Certificate Profile Signer* role. | `OSR_DESKTOP_AZURE_SIGN_ENDPOINT` (the region endpoint, e.g. `https://weu.codesigning.azure.net`), `OSR_DESKTOP_AZURE_SIGN_ACCOUNT`, `OSR_DESKTOP_AZURE_SIGN_PROFILE` (naming the certificate profile switches signing on) and `OSR_DESKTOP_AZURE_SIGN_PUBLISHER` = the certificate's subject name so the updater accepts signed updates. The operator steps are in `platform/desktop/README.md`, *Release*. | | Windows | A conventional certificate (`.pfx`) from a CA. | The certificate and its password. | `OSR_DESKTOP_WIN_CSC_LINK` (base64 of the `.pfx`), `OSR_DESKTOP_WIN_CSC_KEY_PASSWORD`. | | macOS | Developer ID signing and notarisation. | An Apple Developer Program membership (yearly fee); there is no free notarisation. | `OSR_DESKTOP_MAC_CSC_LINK`, `OSR_DESKTOP_MAC_CSC_KEY_PASSWORD`, `OSR_DESKTOP_APPLE_ID`, `OSR_DESKTOP_APPLE_APP_PASSWORD`, `OSR_DESKTOP_APPLE_TEAM_ID`. Until then the bundle is ad-hoc signed so Gatekeeper reports it as unverified rather than damaged, and the first launch is *Open Anyway* as described above. | | Linux | Nothing to sign for the AppImage; `.deb` / `.rpm` repositories can carry a GPG key. | - | - | What the unsigned Windows build cannot avoid is the one *More info › Run anyway* on first launch; the SHA-256 on the downloads page is the check that the file is the one the pipeline published. The portable exe carries the same prompt and never self-updates. ## Tray menu The mark in the system tray or menu bar gains a dot while an answer is streaming. Its menu mirrors the app: **Ask**, the connected workspace or **Connect**, the extension's status, **Settings**, **Start when I sign in**, **Dashboard**, **Help**, an update line when one is ready, **Quit**. ## Privacy - Nothing leaves this computer until you press Enter, unless you turn on *Send my draft to get prices while I type*. The personal-data scan, redaction and the model-tier check run on the device. - A request you send goes to your workspace (or, signed out, nowhere - the bar asks you to connect). The platform stores the decision and its trace, not the text, unless your workspace has turned request logging on. - The selection is read by sending Copy to the app in front and reading the clipboard, which is restored immediately afterwards. It is never read in a terminal. - Settings and the workspace key live in the app's own folder - `%APPDATA%\OpenSmartRoute` on Windows, `~/Library/Application Support/OpenSmartRoute` on macOS, `~/.config/OpenSmartRoute` on Linux. Uninstalling keeps the folder so a reinstall finds your settings; delete it to remove everything. - Every request carries an `X-OSR-App: desktop` header so the dashboard can tell the app from the extension and the API. ## Troubleshooting | Symptom | What to do | |---|---| | The shortcut does nothing | Another app holds it. Settings › Command bar shows the active shortcut; press new keys there | | *Selected text is not read* | macOS: grant the Accessibility permission and press the shortcut again. Linux X11: install `xdotool`; Wayland: install `wl-clipboard` and `wtype` (Settings says which is missing). Terminals are never read by design | | *Enable OpenSmartRoute?* never appears in Chrome or Edge | Restart the browser fully (check the tray for a lingering process). Settings › Browser extension shows what was written per browser | | The bar says *connect a workspace* | Press Connect and approve the sign-in in the browser; for a self-hosted router fill in *Self-hosted or using a key* | | No update is offered | Portable, `.deb` and `.rpm` builds, and the macOS build while it is not Developer-ID signed, do not self-update; download the new version from the downloads page. Installed Windows builds and the AppImage: Settings › Updates › Check now | | The Windows installer closes at once, or Windows reports *OpenSmartRoute-…-win-x64.exe has stopped working* | Installers published before the electron-builder 26 upgrade could crash while choosing the install folder (an over-read in the installer runtime); download the current installer from the downloads page | | Windows SmartScreen or macOS Gatekeeper warns about the file | Verify the official source, hash and signature first. Signing, reputation and notarization are separate checks; a warning alone does not establish which failed. Follow organization policy | | macOS says *"OpenSmartRoute.app" is damaged and can't be opened* | Download the current image again from the official page and verify it. If the problem persists, report the version, architecture and exact message to support; do not assume quarantine is the cause or remove it blindly | Building the app from source, the release pipeline and the internals are described in the repository's `platform/desktop/README.md`.