> ## Documentation Index
> Fetch the complete documentation index at: https://docs.custral.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Desktop app

> The Custral desktop app for macOS: native notifications, workspace tabs, and auto-updates.

## Overview

The desktop app is the full Custral web experience in its own window, with the
things a browser tab can't do: OS-level notifications that arrive whether or
not Custral is focused, a dock badge with your unread count, and tabs that hold
several workspaces open side by side.

<Info>
  Desktop is **macOS only** today. A Windows build isn't available yet, use
  [app.custral.com](https://app.custral.com) in a browser on Windows and Linux,
  which is feature-equivalent.
</Info>

## Install it

<Steps>
  <Step title="Download">
    Go to [custral.com/download](https://custral.com/download) and choose
    **Download for Mac**. The app ships as a universal binary, so it runs
    natively on both Apple Silicon and Intel Macs.
  </Step>

  <Step title="Open it">
    Open the downloaded `.dmg` and drag **Custral** into Applications. Launch it
    from Applications or Spotlight.
  </Step>

  <Step title="Sign in">
    Sign in with the same credentials you use on the web. If your account
    belongs to more than one workspace, you'll be asked which to open first.
  </Step>

  <Step title="Allow notifications">
    macOS will ask once. Allow it, then choose which categories you want under
    **Settings → Client Settings**.
  </Step>
</Steps>

## Workspace tabs

The desktop app keeps a tab bar across the top. Each tab is a page, a record, a
view, or a whole other workspace. When you have **two or more workspaces open**,
tabs switch from showing a page icon to showing each **workspace's logo**, so
you can tell at a glance which company a tab belongs to.

<Tip>
  `⌘⇧N` opens a new chat window with the assistant, separate from your main
  window. Useful when you want to keep a conversation visible while working
  somewhere else.
</Tip>

## Updates

The app checks for updates on launch and installs them in the background. To
check by hand, open **Settings → Client Settings** and use the **About** card,
which shows the version you're running alongside a manual update control.

## Troubleshooting

| Symptom                                                 | Likely cause                                                     | What to check                                                                                                      |
| ------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| "Custral can't be opened because Apple cannot check it" | The download was interrupted, so the signature didn't verify     | Re-download from [custral.com/download](https://custral.com/download) rather than copying the app between machines |
| No notifications arrive                                 | macOS notification permission was denied, or the category is off | Check **System Settings → Notifications → Custral**, then the toggles under **Settings → Client Settings**         |
| The dock badge is stuck or wrong                        | The badge reflects the focused workspace's unread count          | Switch tabs to refresh it; if it persists, quit and reopen the app                                                 |
| Sign-in loops back to the login screen                  | A stale session cookie                                           | Quit the app fully (`⌘Q`, not just closing the window) and reopen                                                  |
| An update never installs                                | The app couldn't reach the update feed                           | Use the manual control on the **About** card; if that fails, download the latest build directly                    |

## Related

* [Where Custral runs](/start/apps/overview): the surfaces compared.
* [My Account](/start/account/overview): notifications, sounds, and shortcuts.
* [Command palette](/start/command-palette): keyboard-first navigation.


## Related topics

- [Where Custral runs](/start/apps/overview.md)
- [My Account](/start/account/overview.md)
- [Mobile app](/start/apps/mobile.md)
- [Authentication](/dev/auth/overview.md)
- [Real-time updates](/dev/realtime/overview.md)