Skip to content
Carabase Host

Beeper

Beeper Desktop is a unified messaging client that bridges iMessage, WhatsApp, Signal, SMS, Telegram, Discord, Slack, Matrix, and others behind a single local REST surface. Carabase’s Beeper connector talks to Beeper Desktop on your own machine — the host never connects to upstream chat networks directly.

The connector is single-account today (multiAccount: false); one OAuth grant per workspace covers every network Beeper Desktop bridges.

Highlights

Section titled “Highlights”
  • Local-only OAuth, nothing to paste. Carabase performs OAuth 2.0 with PKCE and dynamic client registration (RFC 7591) against Beeper Desktop’s local authorization server. There are no client_id / client_secret to copy from a developer console — every host discovers Beeper’s endpoints at flow-start, registers itself as a public client, and stores the resulting tokens encrypted.
  • SSRF guard. The Beeper base URL must point at loopback (127.0.0.1, ::1, localhost) or a Tailnet hostname (*.ts.net, *.tailscale.io); anything else is refused. The guard re-validates the discovered authorization, registration, and token endpoints, and refuses to follow redirects, so a misconfigured discovery document can never send the flow to an arbitrary host.
  • Privacy-first materialization. By default messages are stored metadata-only (no body indexed). You promote a room to full ingest per-room, with an optional auto-promote for direct messages whose partner you’ve marked as a trusted contact.
  • Per-room policy. Per-room materialization decisions live in beeper_room_policies; the messages themselves flow through the same shared routing pipeline every other connector uses.
  • Optional MCP-client integration. Set workspace_settings.beeper_mcp_enabled = true to register Beeper Desktop’s local MCP endpoint into the workspace’s external-MCP registry — the agent runtime then discovers Beeper-supplied tools (such as message-send and chat-search) automatically.

Setup

Section titled “Setup”

Pair Beeper from the Connections page in the Admin SPA: start the Beeper connector’s connect flow and Carabase handles the local OAuth pairing for you. Because pairing runs entirely against Beeper Desktop on your own machine, there is nothing to copy from a developer console. From the connector’s detail page you can set per-room policy overrides, flip the MCP-client toggle, and disconnect the account.

Sync cadence

Section titled “Sync cadence”

The beeper-sync cron runs hourly (0 * * * *) as a REST sweep against the local Beeper Desktop API — REST is always the source of truth. An optional WebSocket accelerator (gated behind the default-off workspace_settings.beeper_ws_accelerator_enabled) sits on top: when enabled and a Beeper account is connected, it watches for live message events and triggers an immediate chat-scoped sync instead of waiting for the next hourly tick. A dead socket never breaks REST sync.

To pull in older history, run a backfill: POST /api/v1/backfill/start with { connector: "beeper", range } pages each chat’s history from newest to oldest through Beeper Desktop’s pagination contract.

Privacy controls

Section titled “Privacy controls”

Two workspace-level booleans gate hydration; both default to false:

  • beeper_concept_role_auto_promote — when true, direct messages whose partner is a trusted contact (marked via that entity’s concept role, against the list configured on the matched room rule) materialize at full ingest instead of metadata-only.
  • beeper_agent_can_hydrate — gates whether the agent runtime is allowed to re-fetch Beeper message bodies via the mesh resolver. Off by default.

Tables

Section titled “Tables”
  • beeper_room_policies — per-room materialization override.
  • policy_tombstones — soft-deleted room policies, kept for audit so a re-imported chat doesn’t silently inherit a stale tier.
  • external_mcp_servers — when MCP-client integration is on, holds the registered Beeper MCP endpoint and bearer.