Desktop App
Install the Owlat desktop app, connect one or more workspaces, switch between them, and use native notifications, the dock/taskbar unread badge, 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 dock/taskbar 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 in alpha, the same status as the rest of Owlat — it works end-to-end, but expect rough edges and breaking changes between releases.
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 will 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.
Opening an unsigned build on macOS
On an unsigned build, macOS shows “Owlat.app” Not Opened — Apple could not verify “Owlat.app” is free of malware, and only offers Move to Trash or Done. On current macOS versions, right-click → Open no longer bypasses this. After confirming with your operator that the build is expected to be unsigned, either:
- Click Done (not Move to Trash), open System Settings → Privacy & Security, scroll down to the message about Owlat.app, and click Open Anyway. Confirm the follow-up prompt once; after that the app opens normally.
- Or remove the quarantine flag from the terminal:
xattr -dr com.apple.quarantine /Applications/Owlat.app
This is a one-time step per downloaded build. If your operator publishes signed and notarized builds, the dialog does not appear at all.
Opening an unsigned build on Windows
SmartScreen shows Windows protected your PC on first run. Click More info, then Run anyway.
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 and badges
Closing the main window quits the app — there is no menu-bar tray icon. Reopen Owlat from your Applications folder (or the taskbar / launcher). While Owlat is still running — for example after you've hidden the window with the global show/hide shortcut — that same shortcut brings it back to the front.
The unread badge — the dock badge on macOS, the taskbar overlay on Windows, the Unity badge on Linux — tracks 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.
Offline mail cache
The desktop app keeps a small, read-only copy of recent mail on the device, so Postbox opens instantly on launch and your recent inbox and already-read messages stay readable when you lose connection. Only sanitized mail is stored, unencrypted, in the app's local database on that machine — never the raw message and never synced anywhere.
This is on by default in the desktop app (and off by default in a plain browser). Turn it off or wipe it from Postbox → Settings → On this device (Store recent mail on this device / Clear local cache). While offline, Postbox shows a quiet banner, serves the cached list and bodies, and pauses actions that need the server. See Postbox → Offline & local cache for details.
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 |
While the Owlat window is focused, Cmd/Ctrl + K opens the quick switcher: a filterable command palette for jumping between places and running quick actions without the mouse. 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. It's an in-app shortcut, not a system-wide one, so pressing Cmd/Ctrl + K in other apps never summons Owlat.
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, so it's ready and its unread badge is live as soon as you sit down.
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 from the link — recipients (including multiple, comma-separated, and to/cc/bcc), the subject, and a plain-text body are all carried across.
To make Owlat the app that opens when you click a mailto: link, set it as your default mail handler in your operating system — there is no reliable way to register this programmatically, so it is a one-time manual step. Settings > Desktop in the app shows the steps for your platform:
- macOS — open Mail > Settings > General and set Default email reader to Owlat.
- Windows — open Settings > Apps > Default apps, find Owlat, and set it as the handler for
mailto. - Linux — set Owlat as your
x-scheme-handler/mailtodefault, e.g.xdg-mime default owlat.desktop x-scheme-handler/mailto, or via your desktop environment's default-applications 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 application menu
- Your Account & Data — manage your sign-in and sessions