Orbit documentation

Everything you need to install Orbit, link your WhatsApp accounts, work across them from one native Mac window, and connect your own AI assistant through local MCP with permissions you control.

Overview

Orbit is a native SwiftUI and AppKit application for macOS that brings several WhatsApp Personal and WhatsApp Business app accounts into one workspace. It has no web view, no Electron and no browser UI. Each account runs in its own isolated helper process with its own session and message database on your Mac. No Orbit server sits between you and WhatsApp.

• Multi-account workspace. One window, one sidebar, one unified list across every linked account, with each conversation labelled by the account it belongs to.
• Menu bar inbox. Read and reply to recent conversations from any account without opening the main window.
• Kepler. An assistant (Pro and Studio) in its own panel and in the menu bar that runs your own Claude Code on your chats, with agents you define, and asks you before anything is sent.
• Local MCP server. Twenty-three tools that let a compatible AI assistant search, read, draft and act on the accounts you grant, under ask/allow/deny policies.

Install and update

Requirements

• A Mac with Apple Silicon (M1 or later). Intel builds are not available.
• macOS 14 Sonoma or later. Liquid Glass controls appear on macOS 26 and later; earlier versions use standard materials.
• A phone with WhatsApp or WhatsApp Business for each account you want to link.

There is no Windows, iOS or Linux version. A Windows waitlist on the product page measures interest; it is not a release commitment.

First launch

1. Download the disk image from the product page and drag Orbit into Applications.
2. Open Orbit. The preview build is signed with SabaiDev’s Developer ID but not yet notarized by Apple, so macOS blocks it the first time.
3. Open System Settings › Privacy & Security, scroll to the message about Orbit and click Open Anyway. You only need to do this once.

To check the download, compare its SHA-256 checksum with the one published for the release: run shasum -a 256 ~/Downloads/Orbit-*.dmg in Terminal.

Updates

Once a day, the direct-download build reads the public release catalog on orbit.sabaidev.la and offers a newer version when one exists. The check sends no account or message data. Orbit never installs anything by itself: the download opens in your browser, and you replace the app yourself. Copies installed from the Mac App Store are updated by the App Store.

Link accounts

With a QR code

1. In Orbit, add an account and give it a name (for example “Work” or “Shop”).
2. On your phone, open WhatsApp › Settings › Linked Devices › Link a Device.
3. Scan the QR code shown in Orbit. The account connects and starts syncing recent history.

With a phone number

If scanning is inconvenient, choose Link with phone number instead, enter the number with its country code, then on the phone choose Link a Device › Link with phone number instead and type the 8-character code Orbit shows. The link appears on your phone as “Orbit” in Linked Devices.

Managing accounts

• All configured accounts connect when Orbit opens.
• Rename or remove an account in Settings › Accounts, or by right-clicking it in the sidebar. Removing an account deletes its local data from this Mac; also unlink it on the phone.
• Each account has a badge colour from a theme-aware palette, and can show its WhatsApp profile photo or initials.
• Connection state uses three tones: connected (accent colour), in progress (grey with a spinner) and needs attention (orange). A logged-out account offers Remove and Link Again.
• The number of accounts you can link depends on your plan: one on Free, three on Plus, five on Pro, twenty on Studio.

The workspace

• All Accounts is the first sidebar row (⌘1). It shows one chronological list of conversations from every account, each with its account badge. Selecting it marks nothing as read.
• Account rows follow it (⌘2…⌘9 for the first eight). Above eight accounts, a filter field appears at the top of the sidebar.
• Filter chips narrow any list: Recent, Unread, Pinned, Drafts and Archive.
• Your last account and conversation are restored when Orbit reopens. Cached history loads from disk first, before the network connection.
• Closing the window keeps Orbit running in the menu bar so notifications and scheduled messages continue. ⌘Q quits normally, saving drafts and shutting down helpers.

Messages and media

Composing

• The composer always names the account you are sending from.
• Return sends, ⇧Return inserts a new line, ⌘Return also sends.
• Text drafts and quoted replies are saved per conversation, encrypted with a key in your Mac Keychain, and survive quit and relaunch. Attached files must be selected again after a restart.
• Messages show WhatsApp formatting: *bold*, _italic_, ~strikethrough~ and ```monospace```, so you can use the same markers when you write. A message of only a few emoji is shown large.
• The emoji button opens a native panel with search, recents, favourites and skin tones; its Stickers tab lists stickers sent to you and by you. More symbols… opens the macOS character viewer.
• In groups, type @ to mention a participant; Tab inserts the highlighted name. Mentions are shown highlighted in received messages.
• The attachment menu also sends a Location… (your current position or a pin you place), a Contact… card and a Poll… (a question with two or more options, single or multiple choice). Orbit asks you to confirm before sharing a location or contact.
• Dropped or chosen files open a review sheet: add a caption, add or remove files, then send them together. A local GIF is converted so it plays as a WhatsApp GIF.
• Attachments are limited to 25 MB.
• A send whose outcome is uncertain (for example after a connection drop) is flagged for your review and never replayed automatically.

On this Mac

These helpers use Apple’s frameworks on your Mac. Nothing is sent to Orbit or an AI provider.

• Translate (macOS 26 or later): right-click a message and choose a language to show a translation under it, or translate your draft before sending, with undo. English, French and Thai. Lao isn’t available on device. macOS may download a language model the first time.
• Transcribe (macOS 26 or later): the transcript button on a voice message writes it out in English or French.
• Read Text in Image: right-click an image to read its text (English, French, Thai) and copy it. That text isn’t searchable yet.
• Catch me up (Pro and Studio, with Apple Intelligence): summarises the latest messages of a chat, with a link to each source message. Kepler is used only if you click Ask Kepler to catch me up.

Delivery status

Checks follow WhatsApp’s own evidence: one grey check for sent, two grey for delivered, two blue for read. Pending, unknown and failed messages never claim to be sent. Group message info lists confirmations per participant.

Typing and recording

The conversation header shows when a contact is typing or recording audio. Orbit shares your own typing indicator by default; turn off Settings › Privacy › Share typing indicator to stop. You still see theirs. Online and last-seen status are not shown.

Reactions, replies and actions

• Hover a message for a small toolbar: react, copy, reply, forward and star. Quick reactions offer the common emoji, and More emoji opens the full panel. Reactions show as a pill on the bubble’s edge; click it to see who reacted or remove yours.
• Pin a message for 24 hours, 7 days or 30 days from its menu. Pinned messages appear in a banner at the top of the conversation; unpin them from the same menu.
• When you open a conversation with unread messages, a divider marks where they start, and a button jumps back to the latest message when you scroll up.
• Forwarded messages are labelled as forwarded.
• To copy several messages, choose Conversation actions › Select messages (or right-click a message), tick the messages, then copy with ⌘C.
• Edits and deletions made by contacts or on your phone are reflected in place.

Media

• Photos and stickers in view download once automatically. GIFs play muted and looping, and animated stickers move.
• Videos and video notes play inline in the conversation.
• Click a photo or video to open the media viewer: ←/→ step through the conversation’s media, and you can save to Downloads or show in Finder. Other files open in Finder.
• Link previews show the title, description and image supplied by WhatsApp. Links open in your default browser.

Locations, contacts and polls

• Shared locations show a map snapshot that opens in Maps; live locations are labelled.
• Contact cards show the name and numbers, with Message and Add to Contacts.
• Polls show their options with live vote counts. Vote by clicking an option.

Disappearing and view-once messages

• Messages in a disappearing chat show a timer and are deleted from this Mac, with their media, when they expire. The composer shows the chat’s current setting, and messages you send or forward there carry the same timer.
• View-once photos and videos appear only as a notice. Orbit never downloads or keeps them; open them on your phone.

Voice

• Voice messages play inline, including WhatsApp Ogg/Opus, with a waveform you can click or drag to seek. The playback speed (1×, 1.5×, 2×) is shared by every voice note.
• The microphone button records up to five minutes. Stop prepares the note so you can preview it, then Send or remove it. Recording never sends automatically.
• One-to-one voice calls have a header button and an incoming/active call banner with Answer, Decline, Mute and End. Calling is experimental. Group and video calls are not supported.
• macOS asks for microphone permission the first time you record or call.

Search

⌘K is the single search across Orbit: accounts, conversation names, phone numbers, and text in messages stored on this Mac. Matching ignores case and accents and covers message bodies, file names and link details. Results keep their account label; selecting a message opens nearby context with the hit highlighted.

⌘F searches the current conversation. Loaded results appear immediately, then older stored messages are checked in the background.

Browsing search results never clears unread counts or sends read receipts. Search covers history cached on this Mac, not your full WhatsApp archive.

Menu bar and notifications

Today

The menu bar icon opens Today (⌘1). On Pro and Studio with the assistant enabled, a Kepler tab sits next to it (⌘2). The icon changes while an assistant request waits for your approval, and shows a dot while an agent is running.

• Waiting for you lists chats where the last message is someone else’s, from the last 14 days, not muted or archived. A group appears only when the message mentions you.
• You promised (Pro and Studio) lists commitments found in messages you sent, such as “I’ll send the quote tomorrow”, with the deadline as written. Promises with a known date come first, and overdue ones are marked. Click the circle when it’s done.
• Open threads lists Kepler conversations with an unsent draft or a reply in progress. Click one to pick up where you left off.
• New lists other chats with unread messages, one line each.
• Search stays at the top. With Kepler available, ⌥Return or Ask Kepler turns what you typed into a new Kepler conversation for you to send.
• ↑/↓ move through every section. Return on a waiting chat prepares a reply with Kepler, and ⌘Return opens it. On other rows Return opens. ⌘↑ opens the full inbox in Orbit, and Esc goes back or closes.
• Hover or right-click a row for Prepare Reply, No Reply Needed, Mark as read, Pin, Mute, Archive and Open in Orbit. No Reply Needed takes the chat out of Waiting until they write again. It is remembered across launches.
• Open a chat to read its latest 60 messages and reply in place. The draft is shared with the main window.
• The header button opens a floating Today window that stays visible over other apps.
• Controls shows each account’s connection state, notification snooze, Hotspot Mode, Today, MCP and Kepler controls, Settings and Quit.

Sorting on this Mac

On Pro and Studio, on a Mac with Apple Intelligence (Apple silicon, macOS 26 or later, Apple Intelligence turned on), Apple’s on-device model sorts Today. It checks whether the people in Waiting actually expect an answer: a “thanks!” doesn’t. It also finds the promises in your sent messages. Messages and results never leave your Mac. Results are saved in the account’s folder on this Mac so they aren’t worked out again; turning sorting off deletes them. The model doesn’t read Lao or Thai, and Orbit doesn’t guess. Those chats keep the basic rule, and Ask Kepler can read them for you. Turn sorting off in Controls › Today › Sort on this Mac.

Notifications and unread counts

• macOS asks for notification permission after your first account connects. Message previews in notifications are off by default.
• Notifications show the contact or group photo, and in groups name both the group and the sender.
• Snooze notifications for 15 minutes or 1 hour from Controls; snooze survives restarts and expires on its own.
• The Dock badge counts unread messages; the menu bar counts unread chats that are waiting for your reply. Opening a conversation, in the main window or the menu bar, clears its local count and its delivered notification.
• Muted chats still count unread messages but do not alert.

Read receipts

Choose when contacts see blue ticks: after you reply (default), when you open the conversation, or never. Replies mark only incoming messages that arrived before you started sending.

Hotspot Mode

On a metered connection, Hotspot Mode pauses automatic image and avatar downloads, high-quality link thumbnails and optional history backfill. Text messaging, cached history and downloads you request explicitly keep working.

Keyboard shortcuts

Appearance

Settings offers System, Mocha, Graphite, Pearl and custom palettes, message fonts, text sizes, density, panel and detail visibility, transparency and background opacity. Message bubbles stay opaque for legibility. With Reduce Transparency or Increase Contrast enabled in macOS, surfaces stay opaque. Settings save immediately.

Kepler assistant

Kepler is Orbit’s assistant, available on Pro and Studio in the direct-download build, as a panel beside your conversation and as a tab in the menu bar. Ask it about your chats, have it translate a conversation or draft replies. It runs your own Claude Code on this Mac; your AI sign-in stays with Claude Code and Orbit never sees it.

Set up

1. Install Claude Code and sign in to it.
2. In Orbit, open Settings › Assistant and click Enable Assistant.
3. Choose which accounts the assistant can use. Orbit lists exactly what it will change (turning MCP on, adding those accounts) before applying it.

Agents and identities

Settings › Assistant has three tabs: Engine, Agents and Identities.

• An agent gives Kepler a purpose, instructions, a colour, an optional Claude Code model and a mode: Read only, Draft only or Approval required. Start from a template or a blank agent; duplicate, disable or delete it later.
• An identity sets how Kepler writes: tone, primary language, language rules and what to avoid. Any agent can use it, and Preview shows a sample reply. An identity never changes what Kepler may do.
• Choose a default agent, an agent per account, and assign one to a chat from Kepler’s agent menu. A new conversation picks its agent from the chat, then the account, then the default.
• Agents can only narrow what Settings › MCP allows, never widen it. Orbit enforces the mode itself, and agents can never delete, link accounts or quit Orbit.

Conversations

• Several Kepler conversations can be open. The list is grouped by agent, each with its colour; choose an agent to filter the list and see its stats.
• History (⌘Y in the menu bar) is searchable and grouped, with Open, Rename, Pin, Archive, Fork, Delete and Export Markdown….
• Each conversation keeps a log of the tools and actions it used, and the Activity view shows recent agent actions across conversations.
• A chat shows Kepler (N) when conversations are about it; click to open them. In Kepler, a removable chat chip filters the list to one chat.
• Orbit keeps the 20 most recent conversations, plus up to 50 archived ones.

Prepare replies and see what Kepler read

• Press Return on a chat in Today’s Waiting list, or choose Prepare Reply. Kepler gets a ready request to read that chat and put a reply in its Orbit draft. You send the request, review the draft on the approval card, and nothing goes out until you send it yourself.
• Under each answer, a line shows what Kepler used: the Orbit tools, accounts and chats, and which engine ran it.
• Kepler links the messages it relies on. Clicking one shows it with its neighbours, read from this Mac, without marking anything read. Citations only open accounts the conversation actually read.
• If a conversation read one account and Kepler asks to send or draft from another, the approval card warns you to check that nothing private crosses over.

How it stays safe

• Kepler is an ordinary MCP client named “Orbit Assistant”. It goes through the same grants, approvals and activity log as any external assistant, and starts from an ask-first preset.
• Enabling it never loosens a limit you set. If sending is turned off for all MCP clients, Kepler cannot send either.
• Text sends and reactions show an inline card in the panel with Send, Edit and Decline. Every other request is reviewed in Orbit’s approval window.
• Each turn runs Claude Code in a restricted mode: only Orbit’s tools are available, with no shell, file or web tools, and no session is persisted by Claude Code.
• Kepler conversations are saved encrypted on this Mac. Turn saving off or delete them all in Settings › Assistant.

Codex appears in Settings as “Not supported yet”. Kepler is not part of the Mac App Store build.

Local MCP

MCP (Model Context Protocol) is an open standard that lets AI assistants call tools. Orbit includes a local MCP server so an assistant you already use (for example Claude Desktop or Claude Code) can work with your WhatsApp accounts. Local MCP is included in Pro and Studio. For an overview, see WhatsApp MCP server for Mac.

How a request travels:

AI host → orbit-mcp adapter (stdio) → private Unix socket → Orbit app
        → permission check / your approval → account helper → WhatsApp

• Everything stays local: the adapter is bundled inside Orbit and talks to the running app over an owner-only socket. There is no public network listener.
• Orbit must be running with MCP enabled. The adapter never opens WhatsApp databases or launches Orbit by itself.
• Reads only use history already cached on the Mac. They never open chats, clear unread counts, download media or send read receipts.
• Voice messages and voice calls are excluded from MCP. They remain available in the native app.

Connect an assistant

Claude Desktop (one click)

1. Open Settings › MCP, choose the accounts Claude can use and a preset.
2. Click Connect Claude Desktop. Orbit adds an orbit entry to Claude Desktop’s configuration, keeps your other settings and saves one backup.
3. Quit and reopen Claude Desktop, then ask it to list your Orbit accounts.

Presets can raise a global limit from Deny to Ask so Claude can request an action, never straight to Allow.

Other MCP hosts

1. In Settings › MCP › Advanced, click Add Client… and name it after your host.
2. Set its accounts, read scopes, action permissions, folders and optional expiry. New clients start with no read or write permissions.
3. Copy the generated configuration into your host and restart its MCP connection. The token is shown only once; a lost token means creating a new client.

The generated configuration looks like this:

{
  "mcpServers": {
    "orbit": {
      "command": "/Applications/Orbit.app/Contents/Helpers/orbit-mcp",
      "env": { "ORBIT_MCP_TOKEN": "<shown once in Orbit>" }
    }
  }
}

Claude Code approval hook

Settings › MCP can add a hook to ~/.claude/settings.json so Claude Code shows the exact message (and its translation when provided) and asks you before an assistant sends, edits, forwards, deletes or schedules a message, or removes an account. Other settings are kept, with a backup next to the file. Restart Claude Code to apply it.

ChatGPT and other remote hosts may need a secure tunnel to reach a local MCP server. A ChatGPT session has not been verified.

Permissions

Permissions work at two layers. The owner limits in Settings › MCP apply to every client. Each named client then gets its own grant, which can never exceed those limits. Denial at either layer wins; Ask at either layer requires your approval.

Action policies

Seven independent policies, each set to Ask, Allow or Deny:

Privacy and notification-preview changes and group administration always require approval, even when the related policy is Allow.

Read scopes and grants

• Read scopes separately gate messages, contacts, drafts, files, activity, diagnostics and preferences.
• New accounts are never granted automatically. Removing an account or folder from the owner limits removes it from every client.
• Assistants cannot change their own grants, permissions, tokens or allowed folders.

Actions and approvals

Every write returns an action ID immediately. The assistant then polls orbit_get_action for its state:

• The approval sheet names the requesting client and shows the operation, account, conversation, participants, text, schedule time, file and destination in plain language. Technical details open automatically for destructive and sensitive requests.
• Each write carries an idempotency key, so a retry with the same key returns the original action instead of sending twice. Never retry an uncertain action with a new key.
• Each client can have at most 32 requests awaiting approval; further requests return a retryable BUSY.
• Settings › MCP shows recent activity. The log keeps metadata only: no message bodies, conversation targets, file paths or linking codes.

Tool reference

The current version of Orbit exposes twenty-three tools. Your host’s tools/list returns the exact JSON schemas; unknown fields are rejected.

Limits worth knowing

• Query pages hold at most 100 records. Cursors expire after ten minutes, on restart or when grants change.
• Outgoing text and captions are limited to 16,000 bytes; result envelopes to 250,000 bytes.
• Message content returned to the assistant is marked as untrusted external data: names and texts are data, never instructions.
• Results state that coverage comes from the Mac’s cache and is not complete history.
• Chat markRead and markUnread change WhatsApp chat state without sending read receipts.
• Deleting a conversation and pinning synchronize through WhatsApp to your other linked devices.

Files and exports

• Choose the folders an assistant may use in Settings › MCP. Uploads and exports stay inside them.
• Files are copied into an immutable snapshot (1 byte to 25 MiB) before sending, then referenced by a handle that expires after ten minutes. Audio files are rejected.
• Image previews are downscaled to at most 512 pixels.
• Exports create new files and never overwrite existing ones. An export covers one cached page of a conversation; it is not a backup.

Scheduled messages

• Text only, up to 366 days ahead, with a time zone. Up to 200 per account.
• Stored encrypted with the account’s Keychain key.
• Orbit must be running and the account connected at the due time. Due messages wait up to five minutes for availability; otherwise they are marked missed and not sent later.
• Under Ask, each scheduled message asks again for approval when it is due.
• Review, reschedule or cancel them in Orbit’s Scheduled Messages view.

Other languages

On Pro and Studio, a connected assistant (or Kepler) can translate permitted conversations and draft replies in your contact’s language, in native script or romanized. Quality depends on the assistant. For English, French and Thai, Orbit can also translate on your Mac: see On this Mac. Keep sending on Ask every time to approve each message before it leaves.

Plans and billing

Plans are for one operator; there is no shared team access. Account allowances are commercial tiers.

Buy and activate

1. Choose a plan on the pricing section (or from Orbit’s Settings › Plan). Checkout is hosted by Whop.
2. In Orbit, open Settings › Plan › Sign In with Browser and sign in with the same Whop account you paid with.
3. The plan activates. A purchase does not link a WhatsApp account; link accounts as usual.

If your plan lapses, existing MCP client settings and scheduled messages are kept until you reactivate. Cancellation and the 14-day first-payment refund are described in the terms.

The Mac App Store is a separate channel that uses Apple purchases, Restore Purchases and Manage Subscriptions. Whop and App Store subscriptions do not transfer between channels.

Data and privacy

• Sessions, history and media are stored on your Mac under ~/Library/Application Support/WhatApps/Accounts/, one folder per account, with owner-only file permissions.
• Text drafts, quoted replies, scheduled messages and Kepler conversations are encrypted with keys in your Keychain. The main session, history and media stores have no additional application-level encryption, so turn on FileVault.
• Orbit has no server in the message path. The update check sends no account data; billing talks to Whop.
• Assistants only receive what you grant. Their provider’s handling of that content is governed by the provider.

Keep a chat out of AI

Choose Keep Out of AI in a chat’s menu. From then on:

• Kepler, the Assistant panel and any connected MCP assistant can’t see that chat: it doesn’t appear in lists or search results, and reading, exporting or sending to it fails as if it didn’t exist.
• Today’s on-device sorting skips it, Catch me up refuses it, and Prepare Reply opens the chat instead of asking Kepler. Its earlier results are no longer shown.
• Kepler refuses requests focused on that chat, so its name isn’t sent either.

Settings › Privacy › Kept out of AI lists these chats; Allow AI restores one. The list stays on this Mac and isn’t synced to WhatsApp. Translation, transcription and reading text in images still work, because they run on your Mac only when you ask. Requests waiting for your approval in that chat are closed straight away, and scheduled sends to it are cancelled when due. What an assistant already received, files it staged earlier and earlier Kepler conversations about the chat aren’t withdrawn.

Never share a QR linking code, session database, MCP token, Whop token, Keychain item or encryption key. Full details are in the privacy notice.

Known limitations

• Unofficial integration. Orbit connects through an unofficial WhatsApp multi-device library. Protocol changes can interrupt connectivity, and unofficial clients carry a risk of account restriction.
• Cached history. Search, MCP reads and exports cover history stored on this Mac. Asking the phone for older history does not guarantee recovery, and old messages may lack sender or media details.
• Not implemented: group and video calls, communities and channels, status publishing, online and last-seen status, GIF search. View-once photos and videos appear only as a notice.
• Disappearing messages are removed from this Mac within about a minute of expiring.
• Voice over MCP: voice messages and calls are never exposed to assistants.
• Scheduling requires Orbit to stay running. A completed send means WhatsApp acknowledged it, not that it was delivered or read.
• Capacity. High numbers of simultaneously connected accounts have not been validated.
• Preview build. Not yet notarized by Apple; Apple Silicon only.

Troubleshooting

macOS says Orbit can’t be opened

Open System Settings › Privacy & Security and click Open Anyway next to Orbit.

An account is orange or logged out

Check the phone has internet and WhatsApp still lists the link under Linked Devices. If the link was removed, use Remove and Link Again.

No notifications

Orbit must be running (it stays in the menu bar when the window closes). Check macOS notification permission for Orbit, that snooze is off, and that the chat is not muted.

A conversation is missing older messages

Orbit shows what is cached on this Mac. Scroll up to load more, or request history from the phone; WhatsApp may not return everything.

My assistant doesn’t see Orbit

1. Keep Orbit running and confirm MCP is enabled in Settings › MCP.
2. Confirm your plan is Pro or Studio.
3. Restart the host (quit and reopen Claude Desktop) and ask it to list Orbit accounts.
4. If it still fails, check that the host uses this client’s current token and that the client has accounts and read scopes.

My assistant’s request is stuck

Look for Orbit’s approval sheet or the pending-request button in the menu bar. Pending requests expire after five minutes. If the result is unconfirmed, check the conversation yourself before trying again.

Kepler says it isn’t signed in

Sign in to Claude Code from Settings › Assistant (Sign in opens Terminal), then try again.

My plan didn’t activate

Sign in from Settings › Plan with the same Whop account used at checkout. If it still shows Free, contact support with your Whop email (not your token).

Support

Email [email protected] with the Orbit version, macOS version, the area (linking, history, MCP, Kepler or billing) and steps to reproduce. Leave out private conversation content and redact identifiers from screenshots. See also the support page, privacy notice and terms.