hivemind-core 4.2.0a3

Mesh Networking utilities for OpenVoiceOS

HiveMind Core

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.

---

• HiveMind Core
  • Key Features
  • Modular Design with Plugins
  • Protocol Configuration
  • Quick Start
    • Installation
    • Adding a Satellite
    • Running the Server
  • Commands Overview
  • Plugins Overview
  • Clients Overview
  • Next Steps
  • License
  • Trademark
  • Contributing

---

🌟 Key Features

• 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.

---

🔌 Modular Design with Plugins

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 Message structure 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).

---

📖 Protocol Configuration

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"
    }
  }
}

---

🛰️ Quick Start

To get started, HiveMind Core provides a command-line interface (CLI) for managing clients, permissions, and connections.

Installation

pip install hivemind-core

Adding a Satellite

Add 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 password

NOTE: You will need to provide this information on the client devices to connect.

Running the Server

Start the HiveMind Core server to accept connections:

$ hivemind-core listen

---

🛠️ Commands Overview

HiveMind 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 database

For 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-client

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-clients

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-client

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.

---

delete-client

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.

---

allow-msg

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).

---

blacklist-msg

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.

---

blacklist-skill

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.

---

allow-skill

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.

---

blacklist-intent

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.

---

allow-intent

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.

---

listen

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.

---

---

🧩 Plugins Overview

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.

---

💬 Clients Overview

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

---

🚀 Next Steps

• Visit the documentation for detailed guides.
• Join the HiveMind Matrix Chat for support and updates.
• Explore additional plugins and expand your HiveMind ecosystem.

---

⚖️ License

HiveMind-core is licensed under the Apache License 2.0, matching the rest of the HiveMind ecosystem.

💡 Releases ≤ hivemind-core 3.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.

Trademark

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.

Supporting the project

If your organisation depends on HiveMind-core in production, consider sponsoring the project, contracting paid support / custom integrations, or commissioning proprietary skills. Contact: [e-mail].

---

🤝 Contributing

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 dev branch. Keep changes focused; follow existing code style.
• Discussion — Matrix chat.