Getting Started

July 31, 2026 · View on GitHub

Prerequisites

Hardware

  • A microphone accessible to the OS (USB, 3.5 mm, or built-in).
  • A speaker or headphone output for TTS playback.
  • Enough compute to run STT and TTS models locally. A Raspberry Pi 4 (4 GB) is the practical minimum; Pi 5 or any x86 machine is comfortable.

Software

  • Python 3.10 or later.
  • A running HiveMind-core instance (the "hive") reachable from this device.

Install

pip install HiveMind-voice-sat

Linux — adds ALSA and SoundDevice microphone backends:

pip install "HiveMind-voice-sat[linux]"

macOS:

pip install "HiveMind-voice-sat[mac]"

Default plugins installed alongside the core package:

RoleDefault plugin
VADovos-vad-plugin-silero
Wakewordovos-ww-plugin-vosk
STTovos-stt-plugin-server
TTSovos-tts-plugin-server

You can swap any of these — see Configuration.

Pairing: get an access key from the hive

On the machine running HiveMind-core, add a client entry and note the credentials it prints:

hivemind-core add-client --name my-voice-sat

Example output:

Access Key : abc123...
Password   : def456...

These two values identify this satellite to the hive. Keep them. The server does not store them after display, but you can re-list them with hivemind-core list-clients.

First run

Pass the credentials and host directly on the command line:

hivemind-voice-sat \
  --host <hive-host-or-ip> \
  --key abc123... \
  --password def456... \
  --port 5678

Or store the identity once so you do not repeat the flags:

hivemind-client set-identity \
  --host <hive-host-or-ip> \
  --key abc123... \
  --password def456...

hivemind-voice-sat   # reads ~/.config/mycroft/identity2.json

If neither credentials nor an identity file are present, the satellite falls back to GGWave. It listens for an audio-encoded identity broadcast from the hive (see hivemind-ggwave).

Verify it works

  1. Watch the log output. A successful connection prints:

    HiveMind Voice Satellite alive.
HiveMind Voice Satellite is ready.

  2. Say your wakeword (default: Hey Mycroft). You should hear a chime.

  3. Ask a question: "What time is it?" The hive processes the utterance and the satellite speaks the response.

If you see connection errors, consult Troubleshooting.

Next steps

Home · Configuration →