Unbridled

unbridled

Unified messaging for agents via a personal Beeper account.

What it does

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/   (Matrix CS API)
    ▼
Beeper bridges (cloud) → Messenger / WhatsApp / IG / LinkedIn / Twitter / …

When to use this skill

Use beeper-matrix when the user asks to:

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)

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: @:beeper.com, all bridges RUNNING

3. Save the Beeper Recovery Key

mkdir -p ~/.secrets && chmod 700 ~/.secrets
cat > ~/.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

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

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