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": {
"hivemind-websocket-plugin": {
"host": "0.0.0.0",
"port": 5678
},
"hivemind-http-plugin": {
"host": "0.0.0.0",
"port": 5679
}
},
"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. - Optional metadata:
Admins can attach plugin-specific client context with
--metadata:
hivemind-core add-client --name "satellite_1" --metadata '{"account_id":"acct_123","device_type":"satellite"}'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. |
| hivemind-http-protocol | Provides HTTP-based communication for Hivemind, ideal for when a persistent connected is undesirable/not-possible | |
| Binary Protocol | hivemind-audio-binary-protocol | 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 provided 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-audio-binary-protocol. |
|
| Mic Satellite | Only VAD runs on device, audio streamed and fully processed server side, requires hivemind-audio-binary-protocol. |
|
| 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 licensed under the Apache License 2.0, matching the rest of the HiveMind ecosystem.
💡 Releases ≤
hivemind-core3.4.0 were Apache-2.0. The 4.x series shipped under AGPL-3.0 as a short-lived experiment; from this release forward HiveMind-core returns to Apache-2.0. Previously published 3.x and 4.x releases on PyPI remain under the licence they were published with.
The names HiveMind, HiveMind-core, HiveMind Protocol, the HiveMind logos, and any "HiveMind Compatible / Powered by HiveMind" marks are protected trademarks and are not licensed under Apache-2.0 (see Apache-2.0 §6). See TRADEMARK-USAGE.md for the brand-use policy. A no-cost trademark grant is available for nonprofits, academic projects, and OSI-licensed downstreams.
If your organisation depends on HiveMind-core in production, consider sponsoring the project, contracting paid support / custom integrations, or commissioning proprietary skills. Contact: jarbasai@mailfence.com.
HiveMind-core welcomes external contributions. Inbound code is licensed under Apache-2.0 by default (per Apache-2.0 §5 — no separate CLA needed).
- Bugs & features — open an issue on GitHub.
- Pull requests — target the
devbranch. Keep changes focused; follow existing code style. - Discussion — Matrix chat.
