Desktop App
Install the Owlat desktop app, connect one or more workspaces, switch between them, and use native notifications, tray badges, shortcuts, and deep links.
The Owlat desktop app is a native shell (built with Tauri) that wraps the same web interface you use in the browser. It adds the things a browser tab can't give you: multiple workspaces side by side, a session stored in your operating system's keychain instead of a cookie, native notifications, a tray icon with an unread badge, global shortcuts, and mailto: handling.
The app loads the exact same UI as the web app — every feature you see on the web is available here too. What's different is how you connect and how the app integrates with your operating system.
The desktop app is built and released from this repository, but Owlat does not run a public download or update server. Whoever operates your Owlat instance is responsible for building, signing, and handing out the installer. The steps below assume someone has already given you a build.
Installing the desktop app
The app ships as a standard installer for macOS (universal .dmg/.app), Windows (.exe/.msi), and Linux. Install it the way you'd install any desktop application for your platform.
Code-signing and notarization are optional and depend on the operator providing signing certificates at build time. If your build is unsigned, macOS Gatekeeper or Windows SmartScreen may warn you the first time you open it. That's expected for an internally-distributed build — confirm with whoever gave you the installer before bypassing the warning.
When you launch the app for the first time with no workspaces connected, it opens the Welcome to Owlat screen, where you choose Connect an existing server (which leads to the Connect to your Owlat server form) or Set up a new server.
Connecting a workspace
A "workspace" is a connection to one Owlat instance. The app is built to hold several at once, Slack-style, but you start by adding one. The welcome screen also offers Set up a new server, which provisions a brand-new Owlat instance on a VPS over SSH — in addition to connecting to an existing one.
Enter your instance URL
On the welcome screen, type the web address of your Owlat instance — for example https://your-instance.owlat.app. You only need the web URL; the app probes the instance's /api/instance-info endpoint to discover the rest of its configuration automatically, so you never have to type Convex URLs by hand.
Sign in through your browser
When you click Connect workspace, the app opens that instance's sign-in page in your system browser rather than inside the app window. Sign in there with your email and password as usual.
Return to the app
After you sign in, the browser hands a one-time token back to the app through an owlat://auth deep link. The app redeems that token for a session and drops you into the dashboard for the new workspace. The session is stored in your operating system's keychain (macOS Keychain, Windows Credential Manager, or the Linux secret service) — not in a cookie.
Signing in through the system browser keeps your credentials out of the app's webview and lets the app hold a header-based, cookie-free session per workspace. This is what makes multiple simultaneous workspaces possible. If you're already signed in to that instance in your browser, the handshake completes instantly without asking for your password again.
Switching between workspaces
Once you have more than one workspace connected, a rail of workspace avatars appears at the top of the sidebar. Each avatar shows the workspace's initials and, if it has items waiting for you, a red unread badge (capped at 99+).
- Click an avatar to switch to that workspace. The app reloads into it so the session and data come cleanly from the workspace you picked.
- Click the
+button to add another workspace — it reopens the Welcome to Owlat screen. - From that screen you can also Remove a workspace, which signs out of it on this device and deletes its keychain entry.
You can also add a workspace from the application menu — File > New Workspace (Cmd/Ctrl + N).
Notifications, tray, and badges
The app installs a system tray icon (menu-bar icon on macOS). Right-click it for a small menu:
| Item | What it does |
|---|---|
| Show Owlat | Brings the main window to the front |
| Open Inbox | Opens the team inbox |
| Open Chat | Opens team chat |
| Quit Owlat | Fully quits the app |
Clicking the tray icon itself also shows the window.
When you close the main window, the app hides to the tray instead of quitting — it keeps running in the background so it can keep notifications and badges live. Use Quit Owlat from the tray (or the menu) to exit completely.
The unread badge — the dock badge on macOS, the taskbar overlay on Windows, the Unity badge on Linux — and the tray tooltip (for example, "Owlat (3 unread)") track the count of unread messages in your personal Postbox inbox. When new mail arrives the app fires a native OS notification: a single new message shows the sender and subject with an Archive action, while several show a count.
The Team Inbox review queue is handled separately. When the number of drafts waiting for review goes up, the app fires a native OS notification titled "Drafts ready for review". The review queue does not drive the unread badge — only your personal inbox unread count does.
Each avatar in the multi-workspace rail carries its own live unread badge (folding together the inbox review count and unread chat mentions for that workspace), so you can see at a glance which workspace needs attention — not just the active one. Inactive workspaces are kept current by a lightweight background connection to each instance you have signed into.
Global shortcuts and the quick switcher
The app registers a few system-wide keyboard shortcuts that work even when Owlat isn't the focused window (Cmd on macOS, Ctrl elsewhere):
| Shortcut | Action |
|---|---|
Cmd/Ctrl + Shift + O | Show or hide the Owlat window |
Cmd/Ctrl + Shift + C | Open the compose window |
Cmd/Ctrl + K | Bring Owlat to the front and trigger the quick switcher |
The Cmd/Ctrl + K shortcut brings the window forward and opens the quick switcher: a filterable command palette for jumping between places and running quick actions without the mouse. The same palette also opens from Cmd/Ctrl + K while the window is already focused. Inside Postbox it's the Postbox command palette; everywhere else in the dashboard it's the global search palette — so the shortcut always opens exactly one switcher, wherever you are.
A global shortcut silently does nothing if another app has already claimed that key combination on your system.
The app also provides a full native menu — the macOS menu bar, or a menu attached to the window on Windows and Linux — with File, Edit (Undo/Redo/Cut/Copy/Paste/Select All), View (Reload, Inbox, Chat, full-screen toggle), Window, and Help (Owlat Documentation, Report an Issue). Preferences… (Cmd/Ctrl + ,) opens the desktop settings.
Launch at login and deep links
Launch at login
Open Settings > Desktop in the app (these settings only appear in the desktop app, not the web version) and toggle Launch at login. When enabled, Owlat starts automatically when you log in to your computer, minimized to the tray so it's ready in the background without taking over your screen.
owlat:// deep links
The app registers the owlat:// URL scheme. Beyond the owlat://auth sign-in handshake, links of these shapes open the matching page in the active workspace:
| Deep link | Opens |
|---|---|
owlat://thread/<id> | A team inbox thread |
owlat://chat/<id> | A chat conversation |
owlat://knowledge/<id> | A Knowledge Graph entry |
owlat://file/<id> | A file in Files |
owlat://contact/<id> | A contact |
mailto: handling
The app registers as a handler for mailto: links. When your operating system sends a mailto: to Owlat, the app opens a dedicated compose window seeded with the recipient (and subject, where provided). You can set Owlat as your default mail handler in your operating system's settings.
Auto-update
The app is wired to check for updates on startup and, if one is found, download and install it for the next restart.
The updater is configured with a public key and a GitHub releases endpoint, so the plumbing is in place. Updates only work if your operator publishes signed builds — signed with the matching private key — to that release channel; otherwise new builds are delivered manually. Ask your operator how updates are delivered for your installation.
Next steps
- Team Inbox — the review queue that drives desktop notifications and badges
- Team Chat — real-time team messaging, reachable from the tray menu
- Your Account & Data — manage your sign-in and sessions