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