HiveMind is a flexible protocol that facilitates communication and collaboration among devices and AI agents within a unified network. It enables lightweight devices, called satellites, to connect to a central hub, with customizable permissions and centralized control.
HiveMind also supports hierarchical hub-to-hub connections, creating powerful, scalable smart environments.
Initially developed as part of the OpenVoiceOS (OVOS) ecosystem, HiveMind is adaptable to various AI backend systems.
For more details and demonstrations, check our YouTube channel.
- Modular Design: Easily extend functionality with plugins for different protocols and behaviors.
- Protocol Flexibility: Use HiveMind with different network, agent, and binary protocols.
- Customizable Database Options: Support for JSON, SQLite, and Redis.
- Centralized Control: Manage and monitor devices from a single hub.
- Fine-Grained Permissions: Control access to skills, intents, and message types for each satellite.
- Multi-Agent Support: Integrate various AI assistants, such as OpenVoiceOS or LLMs.
HiveMind is designed to be modular, allowing you to customize its behavior through plugins managed by the HiveMind Plugin Manager.
- Transport Mechanism 🚚: The protocol does not specify how messages are transported; this is implemented via network protocol plugins (e.g., Websockets, HTTP).
- Payload Handling 🤖 : The protocol does not dictate who handles the messages; this is implemebted via agent protocol plugins (e.g., OVOS, Persona).
- Message Format 📦: The protocol supports JSON data modeled after the
Messagestructure from OVOS and binary data; what happens to the received binary data is implemented via binary data protocol plugins (e.g., process incoming audio). - Database: 🗃️ how client credentials are stored is implemented via database plugins (e.g., JSON, SQLite, Redis).
HiveMind Core now supports a configuration file, making it easier for users to define server settings and reduce the need for complex command-line arguments.
💡 The configuration file is stored at
~/.config/hivemind-core/server.json
The default configuration
{
"agent_protocol": {
"module": "hivemind-ovos-agent-plugin",
"hivemind-ovos-agent-plugin": {
"host": "127.0.0.1",
"port": 8181
}
},
"binary_protocol": {
"module": null
},
"network_protocol": {
"module": "hivemind-websocket-plugin",
"hivemind-websocket-plugin": {
"host": "0.0.0.0",
"port": 5678,
"ssl": false,
"cert_dir": "/path/to/xdg/data/hivemind",
"cert_name": "hivemind"
}
},
"database": {
"module": "hivemind-json-db-plugin",
"hivemind-json-db-plugin": {
"name": "clients",
"subfolder": "hivemind-core"
}
}
}To get started, HiveMind Core provides a command-line interface (CLI) for managing clients, permissions, and connections.
pip install hivemind-coreAdd credentials for each satellite device:
$ hivemind-core add-client --db-backend sqlite
Database backend: SQLiteDB
Credentials added to database!
Node ID: 3
Friendly Name: HiveMind-Node-2
Access Key: 42caf3d2405075fb9e7a4e1ff44e4c4f
Password: 5ae486f7f1c26bd4645bd052e4af3ea3
Encryption Key: f46351c54f61a715
WARNING: Encryption Key is deprecated, only use if your client does not support passwordNOTE: You will need to provide this information on the client devices to connect.
Start the HiveMind Core server to accept connections:
$ hivemind-core listenHiveMind Core CLI supports the following commands:
$ hivemind-core --help
Usage: hivemind-core [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
Commands:
add-client add credentials for a client
allow-intent remove intents from a client blacklist
allow-msg allow message types to be sent from a client
allow-skill remove skills from a client blacklist
blacklist-intent blacklist intents from being triggered by a client
blacklist-msg blacklist message types from being sent from a client
blacklist-skill blacklist skills from being triggered by a client
delete-client remove credentials for a client
list-clients list clients and credentials
listen start listening for HiveMind connections
rename-client Rename a client in the databaseFor detailed help on each command, use --help (e.g., hivemind-core add-client --help).
💡 Tip: if you don't specify the numeric client_id in your commands you will be prompted for it interactively
Click for more details
Add credentials for a new client that will connect to the HiveMind instance.
$ hivemind-core add-client --name "satellite_1" --access-key "mykey123" --password "mypass"- When to use:
Use this command when setting up a new HiveMind client (e.g., Raspberry Pi, IoT device). Provide credentials for secure communication with the server.
List all registered clients and their credentials.
$ hivemind-core list-clients- When to use:
Use this command to view or inspect all registered clients, helpful for debugging or managing devices connected to HiveMind.
Rename a registered client.
$ hivemind-core rename-client "new name" 1- When to use:
Use this command when you need to change the name of an existing client in the database.
Remove a registered client from the HiveMind instance.
$ hivemind-core delete-client 1- When to use:
Use this command to revoke a client’s access, for example, when a device is lost, no longer in use, or compromised.
By default only some messages are allowed, extra messages can be allowed per client
Allow specific message types to be sent by a client.
$ hivemind-core allow-msg "speak"- When to use:
Use this command to enable certain message types, particularly when extending a client’s communication capabilities ( e.g., allowing TTS commands).
Revoke specific message types from being allowed to be sent by a client.
$ hivemind-core blacklist-msg "speak"- When to use:
Use this command to prevent specific message types from being sent by a client, adding a layer of control over communication.
Prevent a specific skill from being triggered by a client.
$ hivemind-core blacklist-skill "skill-weather" 1- When to use:
Use this command to restrict a client’s access to particular skills, such as preventing a device from accessing certain skills for safety or appropriateness.
Remove a skill from a client’s blacklist, allowing it to be triggered.
$ hivemind-core allow-skill "skill-weather" 1- When to use:
If restrictions on a skill are no longer needed, use this command to reinstate access to the skill.
Block a specific intent from being triggered by a client.
$ hivemind-core blacklist-intent "intent.check_weather" 1- When to use:
Use this command to block a specific intent from being triggered by a client. This is useful for managing permissions in environments with shared skills.
Remove a specific intent from a client’s blacklist.
$ hivemind-core allow-intent "intent.check_weather" 1- When to use:
Use this command to re-enable access to previously blocked intents, restoring functionality for the client.
Start the HiveMind instance to listen for client connections.
$ hivemind-core listen- When to use:
Use this command to start the HiveMind instance, enabling it to accept connections from clients (e.g., satellite devices). Configure the host, port, and security options as needed.
| Category | Plugin | Description |
|---|---|---|
| Network Protocol | hivemind-websocket-protocol | Provides WebSocket-based communication for Hivemind, enabling real-time data exchange. |
| Binary Protocol | hivemind-listener | Listens for incoming audio and processes it using the ovos-plugin-manager, enabling seamless interaction between Hivemind and audio input systems. |
| Agent Protocol | OpenVoiceOS | Integration with OpenVoiceOS, facilitated by ovos-bus-client, enabling seamless communication with OVOS systems. |
| Persona | LLM (Large Language Model) integration powered by ovos-persona, works with all OpenAI server compatible projects. | |
| Database | hivemind-sqlite-database | SQLite-based database solution for managing local data within Hivemind applications. |
| hivemind-redis-database | Redis integration for scalable, in-memory database solutions with fast data access. | |
| hivemind-json-database | A JSON-based database plugin provided by json-database, offering lightweight storage and retrieval using JSON format. |
| Category | Client | Description |
|---|---|---|
| Satellites | Voice Satellite | Standalone OVOS local audio stack for Hivemind. |
| Voice Relay | Lightweight audio satellite, STT/TTS processed server side, requires hivemind-listener. |
|
| Mic Satellite | Only VAD runs on device, audio streamed and fully processed server side, requires hivemind-listener. |
|
| Web Chat | Client-side browser Hivemind connection for web-based communication. | |
| Bridges | Mattermost Bridge | Bridge for talking to Hivemind via Mattermost |
| Matrix Bridge | Bridge for talking to Hivemind via Matrix | |
| DeltaChat Bridge | Bridge for talking to Hivemind via DeltaChat |
- Visit the documentation for detailed guides.
- Join the HiveMind Matrix Chat for support and updates.
- Explore additional plugins and expand your HiveMind ecosystem.
HiveMind Core is open source and welcomes contributions from the community. If you’d like to contribute, here’s how you can get started:
-
Fork the Repository:
Fork the HiveMind Core GitHub repository. -
Open an Issue:
Report bugs or suggest features by creating an issue. -
Submit Pull Requests:
Develop your features or bug fixes in a feature branch and submit a pull request to the main repository. -
Join the Discussion:
Participate in the Matrix chat to share ideas and collaborate with the community.
As HiveMind continues to grow, there are several exciting projects on the horizon that could benefit from community involvement.
🚧 Here are some beginner-friendly projects where you can contribute: 🚧
- Wyoming Binary Protocol 🏡: Translate binary payloads to the Wyoming protocol, using Wyoming servers instead of OVOS plugins.
- Assist Protocol Agent 🏡: Develop an agent that communicates with Home Assistant, enabling seamless integration of HiveMind satellites with Home Assistant.
- HTTP / MQTT Network Protocols 🌐: Implement network protocols specifically designed for IoT devices, enhancing connectivity and communication within smart environments.
- GGWave Network Protocol 🎶: Create a solution for HiveMind communication via sound, allowing for networkless systems to interact using audio signals.
HiveMind is open-source software, licensed under the Apache 2.0 License.
