Skip to content

Frequently Asked Questions

This page gives short answers with links to the full pages. New to the vocabulary? Keep the Glossary open in another tab.

In a nutshell

  • Quick answers grouped by topic: general concepts, setup, security, satellites, integration, and troubleshooting.
  • Each answer links to the page that covers it in depth.
  • Start with the Quick Start or Admin Panel to get hivemind-core running.

General

What is HiveMind?

HiveMind is an open-source protocol and platform that connects lightweight satellite devices (a microphone, a browser tab, a terminal) to a central AI server — hivemind-core — over an encrypted network. hivemind-core does the heavy lifting — skills, reasoning, speech-to-text — so the satellites can be cheap and simple. See About.

How is it different from a single-device voice assistant?

The work is distributed. One capable hivemind-core server serves many lightweight satellites, each with its own session and permissions. Speech processing can happen on the satellite or on the server, depending on which satellite you choose (comparison).

Which AI backend does it use?

HiveMind is backend-agnostic. By default hivemind-core runs OpenVoiceOS skills, but you can instead point it at an LLM/chatbot (Persona Server) or an external agent (A2A Server). The choice is just which agent plugin hivemind-core loads.

Do satellites talk directly to each other?

No. Satellites connect to hivemind-core, which routes everything. Two clients can exchange end-to-end-encrypted INTERCOM messages, but those are still relayed through hivemind-core — there is no satellite-to-satellite peer link. hivemind-core instances, on the other hand, can connect to other instances to form a mesh.

Setup

What's the easiest way to get started?

Two options:

  • Web UI: the Admin Panel starts hivemind-core and gives you a browser to manage it — one command.
  • Command line: the Quick Start takes you from zero to a working hivemind-core + voice satellite in about ten minutes.

No hardware? Try the WebSpeech browser satellite.

Do I need a dedicated machine for hivemind-core?

No. hivemind-core runs fine on a laptop/desktop (Linux, macOS, Windows via WSL), a Raspberry Pi 4+ (good for several satellites), a cloud VM, or a Docker container.

Can I run it over the internet?

Yes, but secure it properly. On a LAN, use a strong password (and optionally self-signed TLS). Internet-facing, put it behind a reverse proxy (Caddy, nginx, Traefik) that terminates real TLS, and keep a strong password + firewall. See Operations and Security.

Security

Is HiveMind secure?

Yes. Connections use authenticated encryption (AES-256-GCM or ChaCha20-Poly1305, negotiated), with a password-based handshake (PBKDF2-HMAC-SHA256, 100 000 iterations). The encryption key is never sent over the wire. Permissions are fail-closed: a new client may do nothing until you grant it specific message types. Full detail in Security & Permissions.

WebSocket vs HTTP — what's the difference?

WebSocket (default, port 5678) is a persistent, low-latency, bidirectional connection — ideal for real-time voice. HTTP is request/response, simpler for polling/REST-style clients. Both carry the exact same encrypted messages. See Transports.

Satellites & devices

Which satellite should I choose?

Quick guide (full table in Choosing a Satellite):

Can I have multiple satellites?

Yes. Each connects independently with its own access key and permissions. They can share an OVOS session for conversational continuity.

Integration & development

Can I run OVOS skills?

Yes — the OVOS skills backend runs the full skill stack; existing OVOS skills work as-is. See OVOS Skills Server.

How do I connect a chat platform or smart home?

Use a bridge: Home Assistant, Matrix, Twitch, Mattermost, DeltaChat, HackChat. Or write your own with the Client Library.

How do I write a custom satellite?

Use the Client Library (HiveMessageBusClient in Python) or HiveMind-js for the browser. To implement the protocol from scratch, follow the Protocol Specification.

Troubleshooting

A satellite can't connect to hivemind-core
  1. Confirm hivemind-core is running and reachable (ping <server-ip>).
  2. From the satellite, test the credentials: hivemind-client test-identity.
  3. Check the firewall allows port 5678 (WebSocket) or 5679 (HTTP).
  4. Make sure the client is allowed — a brand-new client is denied every message type until you run hivemind-core allow-msg ... (see Security).
INTERCOM messages stopped arriving after an upgrade

A node now drops an INTERCOM it cannot attribute to a sender. Check three things. First, the payload must be a signed, encrypted envelope. A stock server requires crypto and drops a plaintext INTERCOM. Second, the receiver must hold the sender's public key, either added out of band or pinned from the sender's first HELLO. Third, the signature must verify against that key. To keep sending plaintext INTERCOM, construct the listener protocol with require_crypto=False. See Bootstrapping satellite-to-satellite trust.

A satellite stopped seeing answers to other satellites' queries

That was never intended and a node no longer does it. When a node could not work out which downstream node a QUERY or CASCADE answer belonged to, it used to send that answer to every downstream node as a last resort. One satellite could therefore see another satellite's reply. A node now logs the unroutable answer and drops it.

Nothing legitimate is lost. A node still delivers to the originator when it is directly connected, and still walks the recorded route back when it is not, so an answer that has a return path still arrives. Only the fan-out is gone. If answers stop arriving after an upgrade, the return path is genuinely broken, and the node log names the query id and the originator it could not reach.

Cascade answers arrive split into several entries

Fixed. A gatherer used to append a fresh entry for every chunk that arrived, so one responder's answer became several unrelated entries and two responders answering at once interleaved. Chunks now accumulate into one entry per responder, and the entries stay in order of first arrival. Code that reads responses sees the same list, with one item per responder instead of one per chunk.

How do I find the server's address automatically?

Run hivemind-presence scan on the same network (hivemind-core announces itself when auto discovery is enabled). Most satellites also auto-scan when you start them without a --host. See Auto Discovery.

Audio is choppy or delayed

Prefer wired Ethernet or 5 GHz Wi-Fi; move wakeword/VAD onto the satellite (Voice Relay or Voice Satellite rather than Mic Satellite); and check hivemind-core isn't CPU-bound.

Documentation

How do I build these docs locally? 

pip install -r requirements.txt
mkdocs serve
Then open http://localhost:8000. Contributions welcome — everything is Markdown under docs/, published automatically to GitHub Pages.