Installation & Updates
One download, drag it to Applications, and open it. Orca walks you through the rest the first time you launch.
Orca for Mac
Before you start
Installation is a single file. Download the .dmg above, open it, drag Orca to Applications, and open it. There is nothing to unzip and no terminal steps. When you first launch Orca, a setup wizard walks you through connecting your accounts and adding the API keys for the features you want.
System Requirements
Install the app
Open the downloaded Orca.dmg, then drag Orca into your Applications folder.
Double-click the downloaded Orca.dmg file to open it
Drag Orca into the Applications folder
Eject the disk image and open Orca from Applications
Follow the setup wizard
The first time you open Orca, a setup wizard walks you through everything: activating your licence, connecting your accounts, and adding the API keys for the features you want. Work through it at your own pace, and skip anything you do not need for now. You can always come back to it later in Settings.
Connect your accounts
Sign in to your Microsoft 365 or Google Workspace account through a secure OAuth pop-up. Orca uses this for your calendar, email, and Teams, always asking before it sends anything on your behalf. You can connect up to five accounts in any combination, and add more later in Settings.
Add your feature keys
The wizard prompts you for the API keys behind the features you want to use. Paste in whatever you have, skip the rest, and add the others later. Anything optional can stay empty until you need it.
Grant macOS permissions
If a feature needs access to your files, or you want WhatsApp notifications, the wizard guides you through the relevant macOS permission and pairing prompts when you reach that step. Nothing is required up front in Terminal.
All credentials are stored in an encrypted vault on your machine. Nothing is sent anywhere except to the services you are connecting to.
Check it works
Once set up, try these four things to confirm everything is connected.
Calendar
Your today's meetings should appear in the left panel
Chat
Type "What's my calendar look like for tomorrow?" and press Enter. Orca should respond with your schedule.
Command Palette
Press ⌘+K. A search bar should appear.
Ask "What was the most recent email I sent and received?" in the chat
If all four work, you are all set.
Connecting additional services
After the initial setup, connect more services at any time via Settings (⌘+,).
Microsoft 365
Calendar, email, Teams, OneDrive, SharePoint
Google Workspace
Calendar, Gmail, Drive
ClickUp
Task and project management
Fireflies / Fathom / Otter
Meeting transcripts
Message notifications (QR code pairing)
Pushover
Push notifications to your phone
HubSpot
CRM and pipeline data
Companies House
UK company research
WhatsApp setup
Orca can send notifications over WhatsApp. The setup wizard offers to enable this, or you can turn it on later. To pair your phone:
Open Settings > Integrations > WhatsApp in Orca
Scan the QR code with your phone (WhatsApp > Linked Devices > Link a Device)
Once paired, Orca can send you WhatsApp messages as notifications
Updating Orca
When a new version is available, Orca tells you on launch. You do not need to re-enter credentials or reconnect services.
Notification appears
Bottom-right corner shows version number and summary of changes
Click "Install now"
Download takes a few seconds. Click "Later" to be reminded next launch.
App restarts
Orca restarts automatically. Everything is preserved.
What updates preserve
If automatic updates are not available for your build, download the new .dmg, open it, drag the app to Applications, and click Replace. Your data and settings are stored separately from the app.
Keyboard shortcuts
Where your data lives
Orca stores data in several locations on your Mac. All of these are preserved during updates.
| Data | Location |
|---|---|
| Credentials and API keys | Encrypted in the system credential store |
| App settings | ~/.config/orca/settings.json |
| Conversation history | Browser storage within the app |
| Output files | iCloud Drive: Orca/output/ |
| WhatsApp session | ~/.orca/whatsapp/ |
| Database (if configured) | Supabase cloud (not stored locally) |
If you use OneDrive or SharePoint, output files can also be synced to your organisation's shared drive. This is configured in Settings.
Troubleshooting
"Orca can't be opened" on first launch
Orca is signed and notarised by Apple, so this is rare. If macOS still hesitates on the first open, right-click (or Control-click) Orca in Applications and choose Open, then confirm. You only need to do this once.
Blank white screen on launch
Open the app and press ⌘+Option+I to open developer tools. Check the Console tab for error messages. Common causes:
Missing API key (check Settings > AI Provider), or a network issue preventing connection to Claude or Supabase.
Calendar or email not loading
Open Settings with ⌘+,. Check that your Microsoft 365 or Google account shows "Connected".
If it shows "Not configured", click the connect button and sign in again. If the connection has expired, click "Reconnect". If this persists, check that your organisation has not revoked the app's access permissions.
WhatsApp not connecting
Check that WhatsApp is enabled in Settings > Integrations. Try scanning the QR code again (WhatsApp > Linked Devices > Link a Device).
If the code expires before you scan it, reopen the WhatsApp panel to generate a fresh one.
Licence validation failed
Check your internet connection. If you are offline, the app uses a cached validation that lasts up to 7 days.
If your licence has expired, contact us to renew.
Orca cannot access iCloud or Documents folders
Orca needs Full Disk Access. Open System Settings > Privacy & Security > Full Disk Access and make sure Orca is in the list and toggled on.
If it is not in the list, click +, navigate to /Applications, select Orca, and toggle it on.
App feels slow or unresponsive
Check your internet connection. Orca relies on API calls for most operations.
Try clearing the conversation history (Settings > Clear Messages) and restarting the app.
Uninstalling
To remove Orca from your Mac:
Quit Orca if it is running
Drag Orca from Applications to the Bin
Optionally, remove data folders:
~/.config/orca/
Settings
~/.orca/
WhatsApp data
Orca/
Output files
Your Supabase data (if configured) lives in the cloud and is not affected by uninstalling the app.
Need help?
If you run into an issue not covered here, get in touch. You can also ask Orca itself for help, as it can often troubleshoot its own configuration.