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 REST surface. Carabase’s Beeper connector talks to Beeper Desktop locally — the host never sees 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. Carabase performs OAuth 2.0 dynamic client registration (RFC 7591) against Beeper Desktop’s local OAuth server. There are no client_id / client_secret to paste anywhere.
  • SSRF guard. The base URL must point at loopback (127.0.0.1, ::1, localhost) or a Tailnet hostname (*.ts.net, *.tailscale.io). The guard re-validates the discovered authorization_endpoint before redirecting.
  • Materialization defaults to Tier 2 (metadata-only) per privacy-first sprint decision D1. Promotion to Tier 0 is per-room via beeper_room_policies, with optional concept-role auto-promote when the workspace toggle is on AND the DM partner has a privileged concept_role (e.g. close_friend, family, partner).
  • Substrate vs routing split. Per-room policy lands in beeper_room_policies; messages themselves are processed through the standard applySyncRouting pipeline at sync time.
  • Optional MCP-client integration (Lane C). Flip workspace_settings.beeper_mcp_enabled = true to register Beeper Desktop’s /v0/mcp endpoint into the workspace’s external-MCP registry — the agent runtime then discovers Beeper-supplied tools (message-send, chat-search) automatically.

Setup

Section titled “Setup”

See the Beeper OAuth setup guide in the repo for the full pairing flow, including the manual SQL pattern for per-room policy overrides (no public CRUD endpoint ships in v0.1), MCP-client toggle behaviour, and disconnect ordering.

Sync cadence

Section titled “Sync cadence”

beeper-sync cron at 0 * * * * (hourly REST sweep). Per sprint decision D11, REST is primary — the WebSocket opportunistic accelerator (Beeper PR-A part 3, deferred) merely triggers a chat-scoped sync immediately when a new message arrives.

Privacy controls

Section titled “Privacy controls”

Two workspace-level booleans gate hydration:

  • beeper_concept_role_auto_promote — default false. When true, DMs whose partner has a privileged concept_role materialize at Tier 0 instead of Tier 2.
  • beeper_agent_can_hydrate — default false. Gates whether the agent runtime is allowed to re-fetch Beeper message bodies via the mesh resolver. Privacy-first off by default.

Tables

Section titled “Tables”
  • beeper_room_policies — per-room materialization tier 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 /v0/mcp URL + bearer.

See the database schema reference for column-level detail.