HiveMind Matrix Bridge

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:

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.

Related projects

• HiveMind-core: the HiveMind hub this bridge connects to.
• hivemind-bus-client: the client library that provides set-identity and the HiveMind connection.

License

See LICENSE.