HiveMind - Quickstart and updated docs

Community Projects OpenVoiceOS's Voice AI Platform
, ,
1

HiveMind is an extension of the OpenVoiceOS (OVOS) voice assistant platform that allows you to connect multiple devices into a shared ecosystem, even those with limited hardware. By acting as a central hub, HiveMind enables seamless collaboration between devices across your network.

:books: New HiveMind Documentation

The docs recently got a huge update! They’re packed with everything you need to start building with HiveMind, including step-by-step guides, command overviews, and advanced use cases.

:link: Check out the docs here: HiveMind Documentation

Quick Start Guide

New to HiveMind? Here is the quick start guide taken directly from the updated documentation.

This guide will help you get started quickly with the HiveMind platform, allowing you to extend your OpenVoiceOS (OVOS) ecosystem across multiple devices, even with low-resource hardware. HiveMind lets you connect lightweight devices as satellites to a central OVOS hub, offering centralized control and fine-grained permissions.

imagem

:rocket: Installation

To begin using HiveMind Core, you need to install the hivemind-core package in your OVOS device. This can be done via pip:

pip install hivemind-core

:artificial_satellite: Adding a Satellite Device

Once the server is running, you’ll need to add client credentials for each satellite device you want to connect.

Run the following command to add a satellite device:

hivemind-core add-client

The output wi*ll show you important details like:

  • Node ID
  • Friendly Name
  • Access Key
  • Password
  • Encryption Key (deprecated, only used for legacy clients)

Provide these credentials on the client devices to enable the connection.

:desktop_computer: Running the HiveMind Server

Start the HiveMind server to accept client connections on a specified port:

hivemind-core listen --port 5678

The server will now listen for incoming satellite connections.

:bulb: hivemind-core needs to be running in the same device as OVOS

:key: Permissions

HiveMind Core uses a flexible permissions system, where each client’s permissions are customizable. By default:

  • Only essential bus messages are allowed.

  • Skills and intents are accessible but can be blacklisted or restricted.

You can manage permissions for clients by using commands like allow-msg, blacklist-msg, allow-skill, and blacklist-skill.

:keyboard: HiveMind Core Commands Overview

Here are the basic commands for managing clients and their permissions:

  • Add a new client:
hivemind-core add-client --name "satellite_1" --access-key "mykey123" --password "mypass"
  • List all registered clients:
hivemind-core list-clients
  • Start listening for client connections:
hivemind-core listen --port 5678

For detailed help on each command, use --help (e.g., hivemind-core add-client --help).

đź–§ Hivemind Server Comparison

When building your HiveMind servers there are many ways to go about it, with many optional components

Common setups:

  • OVOS Device, a full OVOS install without hivemind (for reference only)
  • Hivemind Device, a OVOS device also running hivemind, eg. a Mark2 with it’s own satellites.
  • Hivemind Skills Server, a minimal HiveMind server that satellites can connect to, supports text utterances
    only
  • Hivemind Sound Server, a HiveMind server that supports text utterances and streaming audio
  • Hivemind Persona Server, exposes a ovos-persona (eg. an LLM) that satellites can connect to, without
    running ovos-core.

The table below illustrates the most common setups for a OVOS based Mind, each column represents a running OVOS/HiveMind
service on your server

hivemind-core hivemind-listener ovos-core ovos-audio ovos-listener hivemind-persona
OVOS Device :x: :x: :heavy_check_mark: :heavy_check_mark: :heavy_check_mark: :x:
Hivemind Device :heavy_check_mark: :x: :heavy_check_mark: :heavy_check_mark: :heavy_check_mark: :x:
Hivemind Skills Server :heavy_check_mark: :x: :heavy_check_mark: :x: :x: :x:
Hivemind Sound Server :x: :heavy_check_mark: :heavy_check_mark: :x: :x: :x:
Hivemind Persona Server :x: :x: :x: :x: :x: :heavy_check_mark:

The table below indicates compatibility for each of the setups described above with the most common voice satellites,
each column corresponds to a different satellite

voice satellite voice relay mic satellite
OVOS Device :x: :x: :x:
Hivemind Device :heavy_check_mark: :heavy_check_mark: :x:
Hivemind Skills Server :heavy_check_mark: :x: :x:
Hivemind Sound Server :heavy_check_mark: :heavy_check_mark: :heavy_check_mark:
Hivemind Persona Server :heavy_check_mark: :x: :x:
2 Likes
2

:rocket: Big News for HiveMind Fans! :rocket:

Another milestone for HiveMind—introducing a shiny new Plugin Manager and Config File Support! :hammer_and_wrench::tada: This update brings unparalleled modularity, making it easier than ever to customize HiveMind Core for your needs.

:point_right: What’s New?

  • HiveMind Plugin Manager (HPM): Inspired by OVOS, HPM simplifies plugin management. Swap out or add functionality with just a few lines of code.
  • Config File: No need to juggle command-line options—everything is managed via the server.json file for clean, centralized configuration.

:jigsaw: Plugin Types

Here’s what HPM supports today—and the exciting possibilities it unlocks:

:one: Database Plugins :card_file_box:

  • Current: JSON, SQLite, Redis

:two: Agent Protocol Plugins :robot:

  • Current: OVOS, Persona

:three: Network Protocol Plugins :globe_with_meridians:

  • Current: WebSockets

:four: Binary Data Handler Plugins :package:

  • Current: Audio and other binary streams for TTS/STT.

:star2: Possible New Projects :construction:

Interested in getting started with HiveMind development? Here are some beginner-friendly plugin ideas made possible via HPM:

  • Wyoming Binary Protocol :house_with_garden:: Translate binary payloads to the Wyoming protocol, using Wyoming servers instead of OVOS plugins.
  • Assist Protocol Agent :house_with_garden:: Build an agent that bridges HiveMind satellites with Home Assistant, creating seamless smart home integrations.
  • HTTP / MQTT Network Protocols :globe_with_meridians:: Design IoT-friendly network protocols for enhanced connectivity and automation.
  • GGWave Network Protocol :notes:: Enable HiveMind communication using sound! Perfect for networkless setups where devices communicate through audio signals.

:fire: Featured Plugin: HiveMind Audio Binary Protocol

This plugin extends hivemind-core by integrating with ovos-simple-listener, enabling secure, distributed voice assistant functionality with advanced audio-handling features.

:star2: Key Features

  • Audio Stream Handling:

    • Handles encrypted binary audio streams for WakeWord detection, Voice Activity Detection (VAD), Speech-to-Text (STT), and Text-to-Speech (TTS).
    • Works seamlessly with lightweight clients like hivemind-mic-satellite.

  • STT & TTS Services:

    • Provides authenticated STT/TTS over HiveMind, accepting and returning Binary or Base64-encoded audio streams.

:globe_with_meridians: Example Use Cases

  1. Satellite Devices: Deploy microphones with VAD that stream raw audio to a centralized listener for further processing.
  2. Secure Audio Services: Enable authenticated clients to transcribe or synthesize audio with fine-grained access control in comparison to directly using ovos plugin servers.

:open_book: Learn more: HiveMind Audio Binary Protocol.

Why This Matters :dart:

With HPM and plugin flexibility, HiveMind Core becomes a fully customizable platform for endless use cases:

  • Integrate new database backends, network protocols, or AI agents with ease.
  • Extend functionality for IoT, smart homes, or distributed systems without overhauling the core.

:star2: What’s Next?

This is just the beginning. Got an idea? Share it or build a plugin! Whether it’s a new protocol, agent, or database integration, HiveMind is ready for your creativity.

:open_book: Explore the docs and examples:
:arrow_right: HiveMind Core GitHub
:arrow_right: HiveMind Plugin Manager GitHub
:arrow_right: HiveMind Docs

:hammer_and_wrench: Install now:

pip install hivemind-core
1 Like
3

here is a recent demo from @goldyfruit

2 Likes