Installation & Updates
Everything you need to get Orca running on your Mac, keep it up to date, and troubleshoot common issues.
Before you start
You will receive two files from us: a .dmg file (the app) and a .zip file containing the setup assistant. Unzip the .zip first, then follow the steps below in order.
System Requirements
The setup assistant installs dependencies that Orca needs. If you open the app before running setup, some features (particularly WhatsApp notifications) will not work until you go back and run it.
Run the setup assistant
Double-click the setup.command file. macOS will likely block it with a warning saying it cannot verify the file. This is normal for files downloaded outside the App Store.
1. Click Done (not "Move to Bin") on the warning dialog
2. Open System Settings → Privacy & Security
3. Scroll down — you will see a message about the file being blocked
4. Click Open Anyway and enter your Mac password to confirm
Terminal will open and the assistant will install everything automatically. Here is what it does:
If you see a window asking to install Xcode Command Line Tools, click Install and wait for it to finish. This is an Apple system component that the setup assistant needs. It can take a few minutes.
Most steps are skipped if the dependency is already on your Mac. The assistant tells you what it is doing at each stage.
Install the app
Once the setup assistant pauses and asks you to install the app, open the DMG and drag it across.
Double-click the .dmg file to open it
Drag Orca into the Applications folder
Go back to Terminal and press Enter to continue
The assistant will remove the macOS quarantine flag (you will be asked for your Mac password) and open System Settings for the next step.
Grant Full Disk Access
Orca needs Full Disk Access to read and write files in iCloud Drive, OneDrive, and your Documents folder. The setup assistant opens the relevant System Settings pane automatically.
In System Settings > Privacy & Security > Full Disk Access, click the + button
Navigate to /Applications and select Orca
Toggle it on. You may be asked for your password.
Launch Orca and connect your accounts
Open Orca from Applications. A setup wizard walks you through connecting your accounts and services.
Licence Activation
Enter your licence key when prompted. This validates your subscription and unlocks the app. If you are offline, Orca uses a cached validation for up to 7 days.
AI Provider
Enter your Claude API key. If you do not have one, we can provision one as part of your subscription. You can also choose which Claude model to use.
Email & Calendar
Connect your Microsoft 365 or Google Workspace account. Orca uses this for reading your calendar, searching emails, sending messages (always with your approval), and posting to Teams. You can connect up to five accounts in any combination. After your first account, the connect buttons remain visible in Settings so you can add more at any time.
Database (optional)
If your build includes a Supabase database, enter your project URL and keys. This enables persistent storage for contacts, tasks, and meeting data. If you skip this, Orca still works but data persists locally only.
Transcript provider (optional)
Connect Fireflies, Fathom, or Otter.ai for meeting transcript integration. This powers meeting preparation and follow-up features.
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
WhatsApp runs as a separate lightweight service on your Mac. The setup assistant installs this automatically. 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
"setup.command" cannot be opened or does not have access privileges
Make sure you extracted the file from the .zip before double-clicking it. If the problem persists, open Terminal and run:
Then double-click the file again. If macOS shows a security warning, click Done (not "Move to Bin"), then:
- Open System Settings → Privacy & Security
- Scroll down until you see a message about the file being blocked
- Click Open Anyway and enter your Mac password
"Orca can't be opened because Apple cannot check it for malicious software"
The setup assistant should have removed the quarantine flag. If you still see this, open Terminal and run:
Enter your Mac password when asked, then try opening Orca again.
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
Ensure Node.js is installed: open Terminal and type node --version. If not found, run the setup assistant again.
Check that the WhatsApp service is running in Settings > Integrations. Try scanning the QR code again (WhatsApp > Linked Devices > Link a Device).
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.