macOS Desktop App

The Stoa desktop app for macOS wraps the full web experience with native OS integrations like menu bar, native authentication, file sidebar, notifications, and more. Everything you can do in the browser works identically in the desktop app, with additional features that leverage macOS.

Installation

Download the latest .dmg from the Stoa releases page. Drag the app to your Applications folder.

Requirements: macOS 14.0 (Sonoma) or later.

Native Authentication

The desktop app uses macOS-native authentication:

OAuth flow via ASWebAuthenticationSession where the system browser handles sign-in
Keychain storage keeps your authentication tokens stored securely in the macOS Keychain
Automatic token refresh so you stay signed in across app restarts
JWT tokens passed to the web view via secure cookies

You never need to sign in through the web view. Authentication is handled natively before the workspace loads.

A persistent menu bar icon provides quick access without switching to the main window:

What It Shows

Active sessions showing which Spaces have live sessions
Participant count showing how many people are in each session
Live indicators with green dots for active sessions
Unread badges with notification count for share notifications

Quick Actions

Click a session to open it in the main window
See session status at a glance without opening the app
Access the app quickly from anywhere on your Mac

File Sidebar

The desktop app includes a native file sidebar for project navigation:

Project tree to browse all files in the current project
Native rendering using macOS-native UI for smooth scrolling and familiar feel
Quick Open with Cmd+P to open the file finder panel in builds where Quick Open is enabled

Camera and Microphone

The desktop app handles macOS permission prompts natively:

Camera access is prompted when you first enable your camera in a call
Microphone access is prompted when you first join a voice call
Permissions are remembered by macOS after the first grant

Notifications

Session events trigger native macOS notifications:

Notification Center integration
Banner-style alerts
Sound notifications (configurable)
Click a notification to jump to the relevant session

Drag and Drop

Drop files directly from Finder into the workspace:

Images: drag PNG, JPG, GIF, WebP files into the editor to embed them
Documents: drag DOCX and other supported files
Uses native macOS drag-and-drop APIs for a seamless experience

Deep Linking

Stoa URLs open directly in the desktop app when it's installed:

Click a session invite link and it opens in the app instead of the browser
Click a shared file link and it navigates to the file in the workspace
Works with all Stoa URLs

Settings

The desktop app includes a native settings panel:

Tab	Options
General	Launch at login, default workspace behavior
Appearance	Theme (auto, light, dark)
Audio/Video	Default camera, microphone, speaker selection

How It Works

The desktop app is a native Swift/SwiftUI application that hosts the Stoa web app inside a WKWebView. Communication between the native layer and the web app happens via a JavaScript bridge.

Development: Loads from localhost:3000
Production: Loads from the production web URL

The web app detects that it's running inside the native shell via window.isNativeApp and adjusts behavior accordingly (e.g., hiding the browser-based sign-in, using native file pickers).