HiveMind Matrix Bridge

July 31, 2026 · View on GitHub

Relay a Matrix chatroom to a HiveMind hub.

The bridge is a HiveMind satellite. Its input and output are a Matrix room instead of a microphone. Messages that mention the bot go to the hub as utterances. The hub's spoken reply posts back into the room. This turns any HiveMind hub, and the OVOS skills behind it, into a Matrix chatbot.

Matrix room  ⇄  HiveMind-matrix-bridge  ⇄  HiveMind hub (hivemind-core)  ⇄  OVOS skills

Prerequisites

  • A running HiveMind hub (hivemind-core) you can reach over the network.
  • A HiveMind access key and password for this bridge, issued by the hub with hivemind-core add-client (see Quickstart).
  • A Matrix account for the bot and an access token for it. Any homeserver works (matrix.org or self-hosted). Create the account, log in once, and copy its access token (in Element: Settings → Help & About → Access Token).
  • The room alias the bot should join, for example #hivemind-bots:matrix.org. Invite the bot account to that room.

Install

pip install git+https://github.com/JarbasHiveMind/HiveMind-matrix-bridge

Or from a checkout:

git clone https://github.com/JarbasHiveMind/HiveMind-matrix-bridge
cd HiveMind-matrix-bridge
pip install .

This installs the HiveMind-matrix console command.

Quickstart

1. Register the bridge on the hub (run where hivemind-core is installed):

hivemind-core add-client --name matrix-bridge \
  --access-key "your-access-key" --password "your-password"

Note the access key and password. The bridge needs them to authenticate.

2. Store the HiveMind credentials so they are read automatically:

hivemind-client set-identity \
  --key "your-access-key" \
  --password "your-password" \
  --host "ws://192.168.1.100"

set-identity ships with hivemind-bus-client, a dependency of this bridge. You can instead pass --key/--password/--host on every run, without storing an identity.

3. Run the bridge:

HiveMind-matrix run \
  --botname thehivebot \
  --matrixtoken "syt_your_access_token" \
  --matrixhost "https://matrix.org" \
  --room "#hivemind-bots:matrix.org"

4. Send a message. In the joined room, mention the bot:

thehivebot what time is it?

The bridge strips the mention, forwards what time is it? to the hub, waits for the hub's speak reply, and posts it back to the room.

Configuration

HiveMind-matrix run options:

OptionDescriptionDefault
--botnameMention prefix that triggers the botnone
--matrixtokenMatrix access token for the bot accountnone
--matrixhostMatrix homeserver URLhttps://matrix.org
--roomRoom alias to join#hivemind-bots:matrix.org
--keyHiveMind access keyread from identity file
--passwordHiveMind passwordread from identity file
--hostHiveMind host (a ws:// prefix is added if no scheme)read from identity file
--portHiveMind port5678

When --key/--password/--host are omitted, the bridge reads them from the stored NodeIdentity. If none of the three are available, the bridge exits with an error that points you at hivemind-client set-identity.

Troubleshooting

  • NodeIdentity not set: run hivemind-client set-identity, or pass --key/--password/--host explicitly.
  • Bot ignores messages: the message must contain --botname exactly. Messages without the mention are dropped by design.
  • Reply is the literal text Error: the hub did not return a speak within the response timeout (30s). Confirm the hub is reachable, the access key is authorized, and an OVOS pipeline produces spoken answers.
  • Connection refused or no reply: verify --host and --port point at the running hub, and that the bridge's access key is registered (hivemind-core list-clients).

Documentation

  • Setup walkthrough: a full path from an empty machine to a running bridge.
  • Operator setup: get the bot's Matrix account and access token (or self-host a homeserver), register the bridge on a HiveMind hub, run it, and check the live end-to-end test.
  • Configuration reference: every option, credential, and default.
  • Examples: sample runs and embedding the bridge in your own program.

License

See LICENSE.