Unbridled

Send and read messages on Facebook Messenger, WhatsApp, Instagram, LinkedIn, Twitter/X, Signal, Telegram, Discord and other networks through a Beeper account...

Security Scan

The skill is internally coherent for turning a personal Beeper account into a programmable messaging client, but it requires very sensitive secrets (Beeper recovery key and bbctl access token) and installs a long-running sync daemon — proceed only if you trust the host and understand the risks.

Purpose & Capability

Name/description match what the code and SKILL.md do: they use a Beeper per-user Matrix homeserver to send/read bridged networks and to bootstrap cross-signing and import the Megolm key backup. One inconsistency: the registry metadata lists no required env vars or config paths, but the runtime instructions and code rely on user files (~/.config/bbctl/config.json, ~/.secrets/beeper-recovery-key.txt, ~/.local/share/clawd-matrix/). This is explainable (instruction-only skill) but worth noting.

Instruction Scope

SKILL.md and scripts explicitly instruct the agent/installer to (a) store the Beeper recovery key in ~/.secrets, (b) run bbctl login (which populates ~/.config/bbctl/config.json), (c) run bootstrapping/import scripts, and (d) optionally install a systemd user daemon for continuous sync. All of these actions are within the stated purpose (establish trust, decrypt history, and maintain Megolm sessions). The instructions do require writing and reading highly sensitive files (the recovery key and bbctl token) — this is necessary for full functionality but is a sensitive operation the user must accept explicitly.

Install Mechanism

Install steps are conventional: download the official bbctl binary from the project's GitHub releases, apt/brew for libolm and ffmpeg, and create a Python venv to pip-install matrix-nio[e2e] and crypto deps. No obfuscated or unusual remote hosts are used; archives are not pulled from arbitrary personal servers. The skill is instruction-only in the registry (no automatic installer), but an included install.sh automates the same steps.

Credentials

The skill requires access to two very powerful secrets: the bbctl access token (stored in ~/.config/bbctl/config.json) and the Beeper Recovery Key (explicitly stored in ~/.secrets/beeper-recovery-key.txt). Those are exactly the credentials needed to read and send messages and to import full Megolm backups — which is coherent with the purpose, but the sensitivity is high. The registry did not declare these config paths/credentials as required, so the user may not expect the level of secret access requested. The scripts also create persistent local key stores (~/.local/share/clawd-matrix).

Persistence & Privilege

The package installs (via provided scripts) a user-level systemd service (clawd-beeper-sync) to run a long‑running sync daemon that consumes to_device events and maintains Megolm sessions. The skill is not marked always:true; it does not request platform-global privileges, but the daemon combined with stored secrets gives ongoing access to inbound keys and the ability to decrypt future messages. This persistence increases blast radius and should be judged deliberately.

Assessment

This skill appears to do what it says (use your Beeper account as a unified API) but it requires highly sensitive secrets: the Beeper Recovery Key (full account recovery and decryption of message history) and the bbctl access token (API access). If you install it, you will be asked to store those secrets on the agent host (plaintext file and bbctl config) and to run an optional systemd user daemon that continuously syncs keys and messages. Before installing, consider: - Only install on a host you fully control and trust (use an isolated VM/container or a dedicated agent user). - Understand that the recovery key + bbctl token = read+write access to all bridged networks (inbox history + sending). Treat them like root passwords. If leaked, rotate/regenerate the recovery key from Beeper Desktop and revoke the device. - If you only need to send messages and can accept not reading history, skip importing the recovery key and decline installing the sync daemon — functionality will be reduced but risk is lower. - Verify the scripts yourself (they are provided) and inspect any changes before running. The install steps download bbctl from the project's GitHub releases and pip packages from PyPI — standard but run them in a controlled environment if you're cautious. - Audit and cleanup steps are provided in the README; after testing you can remove ~/.local/share/clawd-matrix, ~/.config/bbctl, and the recovery key file to revoke local access. Keep an eye on the user systemd unit and logs (journalctl --user -u clawd-beeper-sync). The skill is coherent with its purpose, but because it requires full decryption keys, treat it as high-trust and follow the precautions above.

Unified messaging for agents via a personal Beeper account.

What it does

• Connects to the user's Beeper Cloud account (https://matrix.beeper.com/_hungryserv/<user>).
• Uses the hungryserv Matrix homeserver that Beeper exposes per-user.
• Reads / sends messages across all networks bridged inside Beeper (Messenger, WhatsApp, Instagram, LinkedIn, Twitter/X, Signal, Telegram, Discord, Google Messages, …).
• Handles Olm/Megolm E2EE via matrix-nio[e2e].
• Bootstraps cross-signing from the user's Beeper Recovery Key, so Beeper's bridges trust the agent's device and actually relay messages to the external networks.

Under the hood it is a thin, dependency-minimal layer:

agent / clawd
    │
    │ CLI / Python import
    ▼
scripts/
    ├── nio_client.py          ← async send / list / history (E2EE)
    ├── client.py              ← sync HTTP wrapper (no e2ee; list + bridge state)
    ├── bootstrap_crosssign.py ← one-shot: recovery key → cross-sign device
    ├── import_key_backup.py   ← one-shot: recovery key → import Megolm key backup
    ├── sync_daemon.py         ← long-running sync (systemd) → new Megolm sessions
    └── verify_interactive.py  ← fallback: SAS verification via Beeper Desktop
    ▼
bbctl + access token (~/.config/bbctl/config.json)
    ▼
https://matrix.beeper.com/_hungryserv/<user>   (Matrix CS API)
    ▼
Beeper bridges (cloud) → Messenger / WhatsApp / IG / LinkedIn / Twitter / …

When to use this skill

Use beeper-matrix when the user asks to:

• Send a Messenger / WhatsApp / IG / LinkedIn / Twitter DM from an agent context.
• Read or search their chats across networks.
• Build a recap, auto-reply, digest, or cron job that touches personal chats.

Do not use it to blast messages to many contacts or to automate replies without explicit consent per-thread.

Prerequisites (user-side)

The user must have:

1. A Beeper account (beeper.com) with the desired networks bridged (Facebook, WhatsApp, etc.).
2. Their Beeper Recovery Key — a phrase like EsUC HBcy scrf uiTy DTU2 rvEB Jmgj 9Cpa D6V2 z7Vk ZrU9 9RMh.

Where to find the Beeper Recovery Key

In Beeper Desktop:

1. Click Settings (gear icon)
2. Click on your name at the top
3. Click the arrow (⌄) next to your name to expand
4. Click "Show Recovery Code"

The code is shown as 12 groups of 4 base58 characters.

⚠️ It's a full account recovery secret — treat it like a password. If it's ever exposed, regenerate it from the same menu.

Prerequisites (host-side, agent)

• Linux (tested on Ubuntu 24.04). macOS should work too.
• python3 with venv
• uv (or plain pip) to create the venv
• libolm-dev (package for Olm/Megolm crypto)
• ffmpeg (optional, for media attachments later)

Setup (one-time, ~5 min)

Follow these steps once on the agent host.

1. Install bbctl and deps

# bbctl binary (Beeper Bridge Manager)
mkdir -p ~/bin
curl -sL -o ~/bin/bbctl https://github.com/beeper/bridge-manager/releases/latest/download/bbctl-linux-amd64
chmod +x ~/bin/bbctl

# System deps
sudo apt install -y libolm-dev ffmpeg python3-venv

# Agent Python venv (dedicated, not global)
uv venv ~/.venvs/beeper --python 3.12
VIRTUAL_ENV=~/.venvs/beeper uv pip install 'matrix-nio[e2e]' aiohttp pycryptodome cryptography pynacl unpaddedbase64 canonicaljson

2. Log into Beeper from bbctl

bbctl login

The user enters their Beeper credentials. This stores an access token at ~/.config/bbctl/config.json. That token is all the nio client needs.

Verify:

bbctl whoami
# Should show: User ID: @<user>:beeper.com, all bridges RUNNING

3. Save the Beeper Recovery Key

mkdir -p ~/.secrets && chmod 700 ~/.secrets
cat > ~/.secrets/beeper-recovery-key.txt <<EOF
EsUC HBcy scrf uiTy DTU2 rvEB Jmgj 9Cpa D6V2 z7Vk ZrU9 9RMh
EOF
chmod 600 ~/.secrets/beeper-recovery-key.txt

Replace the sample with the actual recovery key. Never commit to git.

4. Copy skill scripts into place

The 4 scripts live at scripts/beeper/ in the workspace (they come with the skill — see scripts/ subfolder). Ensure:

ls ~/.openclaw/workspace/scripts/beeper/
# client.py  nio_client.py  bootstrap_crosssign.py  verify_interactive.py

5. Bootstrap nio store + cross-sign the device

# First run initializes the Olm store (~/.local/share/clawd-matrix/)
~/.venvs/beeper/bin/python ~/.openclaw/workspace/scripts/beeper/nio_client.py whoami
# Should print: e2ee: enabled=True

# Sign the device using the recovery key
~/.venvs/beeper/bin/python ~/.openclaw/workspace/scripts/beeper/bootstrap_crosssign.py
# Expected output ends with:
#   🎉 SUCCESS — device is now cross-signed. Bridge should accept our messages.

After this step, Beeper's bridges trust the agent's device and will relay messages to the external networks.

6. Import the Matrix key backup (required for reading history)

Cross-signing only handles outgoing messages. To decrypt incoming history, import the server-side Megolm key backup into the local Olm store. Stop the sync daemon first to avoid a write conflict on the sqlite store.

systemctl --user stop clawd-beeper-sync 2>/dev/null || true
~/.venvs/beeper/bin/python ~/.openclaw/workspace/scripts/beeper/import_key_backup.py
systemctl --user start clawd-beeper-sync
# Expected: "✓ Imported N sessions into ~/.local/share/clawd-matrix/"

You only need to run this once per device (sessions accumulate in the store). Re-run it after any bbctl login that issued a new device id.

Daily usage

All commands run inside the venv. $SKILL_DIR is wherever this skill is installed (e.g. ~/.openclaw/workspace/skills/unbridled when installed via ClawHub, or the repo root if cloned from GitHub).

NIO=~/.venvs/beeper/bin/python
SCRIPT="$SKILL_DIR/scripts/nio_client.py"

# Identity check
$NIO $SCRIPT whoami

# List chats for a specific network (shows room name, which is often missing for DMs)
$NIO $SCRIPT list-chats --network messenger --limit 25
$NIO $SCRIPT list-chats --network whatsapp  --limit 50
$NIO $SCRIPT list-chats --network linkedin

# Aliases accepted: messenger/facebook/fb, whatsapp/wa, instagram/ig,
# linkedin, twitter/x, signal, telegram, discord

# ⚠️  IMPORTANT: DMs on Beeper usually have NO room name (listed as !xxx:beeper.local).
# The contact name lives in a member's display_name. To find a chat by contact, use:
$NIO $SCRIPT search-chats baptiste                     # scans all 344 rooms + members
$NIO $SCRIPT search-chats juliette --network messenger # restrict to one bridge
$NIO $SCRIPT search-chats "jean-baptiste" --json        # structured output

# Send a message (E2EE handled automatically)
$NIO $SCRIPT send --room '!xxx:beeper.local' --text "Hello from clawd"

# Read recent history in a room (requires megolm session in the store)
$NIO $SCRIPT history --room '!xxx:beeper.local' --limit 20

Python import usage (recommended for cron / scripts):

import os, sys, asyncio
sys.path.insert(0, os.path.expanduser(os.environ["SKILL_DIR"]) + "/scripts")
from nio_client import make_client

async def ping():
    c = await make_client()
    try:
        # ... use c.room_send / c.joined_rooms / etc.
        pass
    finally:
        await c.close()

asyncio.run(ping())

Quirks to know about

• Lazy sync: Beeper hungryserv doesn't ship all rooms on sync(full_state=True). nio's client.rooms will be mostly empty. The wrapper sidesteps this by calling joined_rooms() directly and manually injecting a minimal MatrixRoom before room_send. Don't rely on client.rooms being complete.
• Lots of decryption warnings: nio tries to decrypt every event across all 300+ rooms during sync and prints warnings for rooms where the group session is missing. The wrapper silences them via logging.getLogger("nio").setLevel(ERROR).
• Schema warning flood ('events' is a required property): hungryserv returns sync responses with fields nio doesn't fully recognize. Safe to ignore; already silenced.
• Bridge trust: without cross-signing, Beeper bridges reject outgoing messages with com.beeper.undecryptable_event / your device is not trusted (unverified). bootstrap_crosssign.py fixes this once and for all for this device.
• "Notes to self" chats don't relay: the Facebook Messenger (Jérémie Kalfon) auto-chat has no external recipient. Test sends on a chat with a real other user.
• First message to a new chat: may take 1-2 seconds extra as nio establishes the Megolm group session.
• Small recent-activity counts can be misleading: when a room has only 1 recent raw Matrix event, that event may be a reaction or bridge/meta event rather than the actual text message. Digest/collector code should over-fetch (history --limit >= 10) instead of mirroring the raw count, otherwise it can report a false decryption unavailable.
• Recovery key != SSH key: this is a secret that lets anyone with it impersonate the user on all Beeper-bridged networks. Handle accordingly.

Safety rules for the agent

This skill gives the agent direct write access to the user's personal chats on every bridged network. The agent MUST treat every send as a privileged operation:

• Never send a DM on a new thread without explicit user confirmation. One-line acks like "go ahead" count; inferred intent does not.
• Never mass-send or loop over contacts. Even mundane messages become spam at N≥3 recipients; users get banned from WhatsApp / Messenger for this.
• In group chats, the agent is not the user's voice. Stay silent unless directly addressed by name. If unsure, don't post.
• Never paraphrase emotional/sensitive messages on the user's behalf — show the draft to the user first and let them approve or rewrite.
• Never forward messages from one private thread into another without explicit permission.
• Log every outgoing send in the workspace journal (e.g. memory/YYYY-MM-DD.md) so the user can audit after the fact.
• Respect quiet hours. Midnight sends look like the user is chaotic, not like an assistant is helpful.
• Never share or paste the recovery key, access token, or Olm store path in any external output (message bodies, issues, logs the user didn't ask for). These are the keys to the whole kingdom.
• If the user revokes the Beeper session (logout device), the Olm store becomes stale — re-run bootstrap_crosssign.py and import_key_backup.py after the next bbctl login.

Files in this skill

unbridled/
├── SKILL.md                              (this file)
├── README.md                             GitHub-facing doc
├── LICENSE                               MIT
├── install.sh                            prerequisites installer
├── scripts/
│   ├── client.py                         sync HTTP wrapper (list + bridge state)
│   ├── nio_client.py                     async E2EE client (send/list/history)
│   ├── bootstrap_crosssign.py            one-shot: recovery key → cross-sign
│   ├── import_key_backup.py              one-shot: recovery key → import Megolm backup
│   ├── verify_interactive.py             fallback: SAS via Beeper Desktop
│   ├── sync_daemon.py                    long-running sync (Megolm accumulation)
│   └── collect_beeper_daily.py           daily digest generator
├── systemd/
│   ├── clawd-beeper-sync.service         user-level systemd unit for the daemon
│   └── install.sh                        installs the unit into ~/.config/systemd/user/
└── references/
    ├── setup-checklist.md                step-by-step for humans
    └── architecture.md                   diagrams and crypto flow

Status

• v0.2.2 — 2026-04-21 — Fix packaged-skill path resolution in collect_beeper_daily.py (scripts/client.py and scripts/nio_client.py live next to the collector, not under scripts/beeper/). Validated by running the collector directly from the published skill layout.
• v0.2.1 — 2026-04-21 — Fix false decryption unavailable in collect_beeper_daily.py by over-fetching a small history window instead of using the raw recent-event count as the decrypt limit. Validated on Messenger + WhatsApp groups where the latest raw event was reaction/meta noise.
• v0.2.0 — 2026-04-18 — Full send + read across Messenger / WhatsApp / IG / LinkedIn / Twitter after import_key_backup.py was added. Confirmed decrypting >95% of joined rooms on an active Beeper account (357/357 backup sessions imported, 0 errors).
• v0.1.0 — 2026-04-18 — Works for send on cross-signed device. History (megolm decrypt) partial.

Inbound decryption — key backup + sync daemon

Two complementary mechanisms feed Megolm group sessions into the local Olm store so inbound history can be decrypted:

1. Matrix key backup (m.megolm_backup.v1.curve25519-aes-sha2): Beeper keeps a server-side, encrypted-at-rest backup of every Megolm session the user has ever held. import_key_backup.py downloads those, decrypts them with the recovery key (same key used for cross-signing), and injects each one into the nio sqlite store. One-shot, imports the entire history.
2. Live sync daemon (sync_daemon.py, systemd-supervised): runs sync_forever against hungryserv. Beeper's bridges push new sessions via to_device events as they're created, which the daemon stores. Keeps everything up-to-date for future messages.

After the one-shot backup import and a minute or two of the daemon running, history and collect_beeper_daily.py decrypt nearly all traffic. Coverage is typically ≥ 95% of joined rooms (the rest being inactive rooms that had no session in the backup).

Install:

bash systemd/install.sh
systemctl --user enable --now clawd-beeper-sync.service
systemctl --user status clawd-beeper-sync
journalctl --user -u clawd-beeper-sync -f

Resource footprint: ~35 MB RAM idle, negligible CPU.

Roadmap

• unread --network X helper (summarize unread chats)
• reply --to <event_id> with proper Matrix reply threading
• mark-read on inbound messages
• Media / attachments (image send)
• Publish v1.0 on ClawHub