The desktop app

Member·5 minutes to read

Verified against docs/superpowers/specs/2026-09-15-p5-a-desktop-shippable.md §1.1; re-verified against the code at close-out.

What this does for you

The desktop app puts Botseon in your dock, checks for its own updates on a track you choose, and confirms every link before it opens one.

Before you start

You're signed in on the web.
Your account and appearance settings are shared with the browser — see Your account and settings.
Know which build your operating system needs; the installers are signed for macOS, Windows and Linux separately.

Steps

Install the signed build for your computer — a notarised disk image on macOS, a signed installer on Windows, or a .deb, .rpm or AppImage on Linux — and open it.
Sign in once; the desktop app and the browser share the same account. Signing in opens your system browser, where you approve the app on a page that names it and the account it would act as; the app window then signs itself in once, automatically, and you land in Botseon.
Use the tray icon to reopen the window, check for updates, or quit — three items, in that order.
Open Settings → Updates to choose your Update Track — Stable is the safe default; other tracks ship new builds earlier and more often, and switching checks for updates right away.
The same tab shows your running version and a status sentence — checking, up to date, downloading, or ready — with a Check for Updates button that stays available even while you're current.
When a build is ready, install it: most installs restart the app for you; a .deb or .rpm install instead opens your system's own package manager, which asks you to confirm.
A link that tries to open inside the app — from a web page, a message or another application — asks you to confirm first, with one exception: the link that returns you from the browser after signing in (Step 2) opens directly, without asking. Beyond that one case, the app never shows you the raw link as something to click through blind.

A worked example

A stable-track update that is ready to install reads like this on the Updates tab, before you press the button:

Version 1.4.0
Updates follow the Stable track
An update to 1.4.1 is ready to install
[ Install and Restart ]

What can go wrong

What you see	Why	What to do
`Updates are not available in the browser.`	You opened Botseon in a browser tab rather than the desktop app.	Open the desktop app to check for or install an update.
`This build does not check for updates.`	This particular build carries no update-signing key.	Reinstall from a signed release if you need updates.
`This version is no longer supported. Install the update to continue.`	Your build has aged past what the service still accepts.	Install the update shown; there is no way to postpone it further.
`Could not check for updates. Try again.`	The update check itself failed, usually a network problem.	Try again once you have a connection.
`Could not install the update. Try again.`	The install step failed after a successful check.	Try again; if it keeps failing, reinstall from a fresh download.
`That sign-in did not complete. Try again.`	The app window's automatic sign-in (Step 2) did not go through — most often because it was left more than a minute, or because the same sign-in had already been used once.	Sign in again from the app. Each approval signs the window in exactly once.