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 15.0 (Sequoia) 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.

Menu Bar Extra

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

Local File Sync

The desktop app keeps your Stoa teams and projects mirrored on disk at ~/Stoa/. Edit files in the editor of your choice and changes flow back to the live Stoa workspace; edits made in Stoa appear locally within seconds.

Enable sync

1. Open Settings with Cmd+, (or Stoa → Settings) and select the Sync tab.
2. Toggle Sync enabled at the top.
3. All teams and projects sync by default. To limit scope, expand any team under Teams & Projects and turn off the projects you don't want mirrored locally.

Under Sync Enabled, a status line shows whether the sync service is running. Each project shows its own state (Running, Starting, Cloning, and so on) with any error messages inline.

What gets synced

Synced content lives under ~/Stoa/<team>/<project>/. All files in a project (text and binary) sync by default, except anything filtered out by that project's .stoaignore file.

The root directory (~/Stoa/) is fixed; there is no folder picker. Scope is controlled entirely by which teams and projects are enabled in the Sync tab. New projects created in the workspace appear automatically; deleted projects are removed.

How sync works

Sync is bidirectional. Local changes push to Stoa, and remote changes pull down automatically. Concurrent edits to the same file — whether made in Stoa, on another device, or in your editor — merge without conflicts, and full edit history and provenance is preserved across both sides.

A background service runs under launchd to watch your local ~/Stoa/ directory and maintain a live connection to Stoa. If you quit, sleep, or restart your Mac, the service resumes and catches up on any changes made while it was offline.

Disabling sync

Turn off Sync enabled in the Sync tab to stop syncing across all projects. Your local files stay on disk but stop updating until sync is re-enabled. You can also leave global sync on and disable sync for individual projects independently.

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:

What's Next