HiveMind WebSocket Client

August 10, 2026 ยท View on GitHub

hivemind-websocket-client (package: hivemind_bus_client) is the primary library for building and running HiveMind satellites. It provides a WebSocket client that extends the standard OpenVoiceOS (OVOS) bus client. The client encrypts and routes communication across the HiveMind network.

Key Features

  • Transparent Routing: Automatically handles message routing between satellites and hubs.
  • Per-link Encryption: AES-GCM or ChaCha20-Poly1305, negotiated at handshake.
  • Hybrid INTERCOM Encryption: AES-256-GCM payload + RSA-encrypted ephemeral key per message. hivemind-core decrypts the envelope with plain RSA, so a message sent to a hub must fit one RSA block (about 214 bytes with a 2048-bit key).
  • Trusted Peers: NodeIdentity.trusted_keys gates BUS injection for PROPAGATE and INTERCOM from untrusted sources.
  • CASCADE Aggregation: Collects responses from all nodes with timeout and early resolution via HiveMapper.
  • PING Discovery: Flood-based topology mapping with public key and locale announcement.
  • Binary Support: Optimized handling for binary payloads such as TTS audio and file transfers.
  • Drop-in Replacement: Designed to be mostly compatible with ovos-bus-client, allowing easy migration of existing OVOS skills or services to HiveMind.

Primary Components

  • HiveMessageBusClient: The main WebSocket client class (hivemind_bus_client/client.py).
  • HiveMessage: The fundamental message unit of the HiveMind protocol (hivemind_bus_client/message.py).
  • NodeIdentity: Manages device credentials, keys, and identity settings (hivemind_bus_client/identity.py).

Quick Start

from hivemind_bus_client import HiveMessageBusClient
from ovos_bus_client.message import Message

# Initialize the client
client = HiveMessageBusClient(key="my_access_key", password="my_password", host="ws://127.0.0.1")

# The hub must first grant this client the message types it sends:
#   hivemind-core allow-msg "recognizer_loop:utterance" <node_id>

# Connect and block until handshake is complete
client.connect()

# Listen for a 'speak' event from the hub
client.on_mycroft("speak", lambda msg: print(f"Hub says: {msg.data['utterance']}"))

# Send an utterance to the hub
client.emit(Message("recognizer_loop:utterance", {"utterances": ["hello world"]}))

Documentation Guides

  • Setup walkthrough - Pair a satellite with a hub step by step.
  • Installation - Getting started.
  • API Reference - HiveMessage, HiveMessageType, HiveMessageBusClient, BinaryDataCallbacks, NodeIdentity.
  • Client API - HiveMessageBusClient and HiveMindHTTPClient usage.
  • Async Client - AsyncHiveMessageBusClient for asyncio-native applications.
  • Fakes - AsyncFakeHiveMessageBus in-process stand-in for testing.
  • Message Types - HiveMessage, HiveMessageType enum, routing, serialization.
  • Binary Serialization - Bitstring wire format, get_bitstring, decode_bitstring (reference implementation).
  • Binary Handlers - BinaryDataCallbacks for TTS audio and file transfers.
  • Identity & Credentials - Managing node identity and settings.
  • CLI Reference - hivemind-client commands (terminal, ping, send-mycroft, etc.).
  • CLI Guide - Detailed CLI usage with HiveMapper network discovery.
  • Examples - Practical code snippets and walkthroughs.