Desktop app
The Overdeck desktop app runs its own dashboard server and opens the dashboard in a window, so you don’t need a terminal or a browser tab. It uses the same projects, conversations and agents aspan up, so nothing about your setup changes by switching to the app. Instead of running its own server, the app can also show another machine’s dashboard; see Open another machine.
Download and install
Download the installer for your system from GitHub Releases.
There is no build for Intel Macs, Linux on ARM or Windows on ARM. On those systems, install
@overdeck/core and use the dashboard in a browser with pan up.
Linux
Make the AppImage executable and move it to~/Applications/ so pan up can find it later:
macOS
Open the.dmg and drag Overdeck into Applications.
macOS blocks the first launch because the app is not notarized yet. Run xattr -dr com.apple.quarantine /Applications/Overdeck.app, then open it again.
Windows
RunOverdeck.Setup.<version>.exe. Keep the default installation folder so pan up can find the app later.
Run it from npm
Prefer npm to a standalone installer? Run the app directly, or install it as a command:[overdeck] Node.js 22 or later is required (found <version>). A global install adds the overdeck-desktop command. The npm package does not include the pan command; install @overdeck/core for that.
pan up does not look for the npm package; it only finds the app at the install locations above.
To update, run npm install -g @overdeck/desktop@latest, or just run npx @overdeck/desktop@latest again.
Launch it with pan up
If you already installed the app,pan up finds and launches it instead of starting its own dashboard server: it prints Launching Overdeck desktop app... and ✓ Desktop app launched, starts the background sidecars, and returns. If the launch fails, it prints ⚠ Could not launch desktop app: <message> and falls back to the normal dashboard. Run pan up --no-open to skip the app and always start the normal dashboard.
pan up looks for the app at:
- Linux:
~/Applications/Overdeck*.AppImage, or/opt/overdeck/overdeck - macOS:
/Applications/Overdeck.appor~/Applications/Overdeck.app - Windows:
%LOCALAPPDATA%\Programs\Overdeck\Overdeck.exe
pan up also treats ~/.local/bin/overdeck, ~/.local/share/applications/overdeck and /usr/local/bin/overdeck as the app, and checks them before ~/Applications/. The install script puts the overdeck command in ~/.local/bin, so pan up reports Desktop app launched and opens the dashboard in your browser instead (#5557).
What runs where
The app’s embedded server listens on port7825 (it is not the pan up dashboard’s port); while it restarts after crashes, the port is 7825 plus the number of consecutive restarts since the last healthy start, at most 7833. pan open always talks to the pan up dashboard; see The desktop app for how it reaches the app’s own window. pan down stops the pan up dashboard only; it does not quit the app, which you quit from its tray or menu.
Only one copy of the app runs at a time: launching it again focuses the existing window, and launching it with --open <path> opens that path in the running window. Closing the window keeps the app running in the background on macOS; on Linux and Windows, closing the last window quits the app and stops its embedded server.
The tray and the app menu
Clicking the tray icon opens the dashboard window. Its menu has:- Show Dashboard
- Connect to a Machine…
- Use This Computer (enabled only while another machine’s dashboard is shown)
- Start Cloister
- Stop Cloister
- Emergency Stop All
- Settings
- Quit
Notifications
The app shows the dashboard’s own notifications as native system notifications, the same ones a browser tab would show:- an agent or conversation is waiting on a decision from you;
- a plan is waiting for your approval;
- a conversation hit a permission prompt: Permission needed, repeated 5 and 30 minutes later if it is still waiting;
- memory or disk pressure warnings.
Start at login
Settings → Desktop App → Auto-start → Launch at login starts the app automatically when you log in. It works on macOS and Windows; on Linux it has no effect yet (#5556). On the first launch, a dialog asks whether to start Overdeck automatically, with an option to enable it or skip for now. If you skip it, a reminder toast appears on the next few launches with a button to enable it. The toasts count up to “Reminder 5 of 5” (four toasts after the first dialog). After that, or once you enable it, the reminders stop. Reset reminder in the Auto-start card starts that sequence again. Desktop settings, including this one, save todesktop-settings.json in the app’s user data folder: ~/.config/Overdeck/ on Linux, ~/Library/Application Support/Overdeck/ on macOS, and %APPDATA%\Overdeck\ on Windows.
Updates
The app checks GitHub Releases 5 seconds after launch and every 4 hours after that, but it never downloads an update on its own. Use Help → Check for Updates…, or click the version number at the bottom of the left column, to open the updater, download the update, and restart into it. Once a download finishes, Install Update and Restart appears in the Help menu too. A canary build (a version containing-canary, such as 1.2.3-canary.1) only offers canary releases; a stable build only offers stable releases.
If an update cannot install, download the new installer from GitHub Releases and install it over the old one. This is the only way to update on macOS today, since the app is not notarized (see Download and install).
Installed the app through npm instead? See Run it from npm to update it with npm.
Open another machine
Instead of running its own embedded server, the app can show one other machine’s dashboard. It stores at most one chosen machine, and while it shows one, no local server runs. See Remote access for pairing in general and Tailscale for setting up a tailnet.Pair with a machine
- On the other machine, create a pairing link: Settings → Anywhere → Pair a device, or
pan pair --url <its Tailscale address>. - In the app, choose Connect to a Machine… from the tray or the Overdeck menu.
- Paste the whole link into the Open another machine window and click Connect.
Overdeck desktop on <hostname>; manage it from there with pan devices list and pan devices revoke <id>.
Which addresses work
The app only sends this computer’s credential to:- any
https:address; http:to loopback (localhost,127.0.0.0/8,::1);http:to a Tailscale address (100.64.0.0/10,fd7a:115c:a1e0::/48, or a name ending in.ts.net, or that resolves only to such addresses).
Where the credential is kept
The chosen machine’s record is saved toremote-machine.json in the app’s user data folder, with its device credential encrypted by the operating system’s secure store (Keychain on macOS, Windows credential protection on Windows, GNOME Keyring or KWallet on Linux). Without one of those stores available, the app will not save a machine credential and refuses to pair. The remote dashboard window keeps its session in memory only, so its draft text and UI preferences reset on every launch.
When the machine cannot be opened
In every case, the Open another machine window opens with the reason and offers Open
<label>, Use this computer and Forget <label>. The app never falls back to this computer on its own.
Switch back or forget the machine
Use this computer keeps the pairing on record but starts the embedded server and shows it instead. Forget<label> revokes this computer’s access on that machine, then removes the local record either way; if the machine cannot be reached, revoke the device from that machine’s Settings → Anywhere → Paired devices instead. While a chosen machine is shown, links to other origins open in your regular browser, and restarting the dashboard from the app is refused: restart it on the machine that is showing it.
Get help
- Ask questions on the Overdeck Discord.
- Report bugs and request features in GitHub Issues.
- From the app, use Help → Report an Issue.