Configuration

CLI flags

All flags are optional. Missing values fall back to the stored identity (see below).

Usage: hivemind-voice-sat [OPTIONS]

  connect to HiveMind

Options:
  --host TEXT       HiveMind host. Include protocol: ws://host or wss://host.
                    If bare hostname is given, ws:// is assumed.
  --key TEXT        Access Key issued by hivemind-core add-client.
  --password TEXT   Password for key derivation.
  --port INTEGER    HiveMind WebSocket port. Default: 5678.
  --selfsigned      Accept self-signed TLS certificates (wss:// targets).
  --siteid TEXT     Location tag written into message.context. Useful when
                    multiple satellites share one hive.
  --help            Show this message and exit.

---

Identity file

When --host, --key, and --password are all omitted, the satellite reads ~/.config/hivemind/_identity.json (the HiveMind NodeIdentity file). Populate it with:

hivemind-client set-identity \
  --host ws://192.168.1.10:5678 \
  --key  abc123... \
  --password def456...

Fields resolved from the identity file (CLI flags override):

CLI flag	Identity field
--host	default_master
--key	access_key
--password	password
--port	default_port
--siteid	site_id

---

OVOS configuration file

The satellite is built on top of ovos-dinkum-listener and ovos-audio. All plugin selection and tuning happens in the standard OVOS config:

~/.config/mycroft/mycroft.conf

Minimal example

{
  "listener": {
    "VAD": {
      "module": "ovos-vad-plugin-silero"
    },
    "wake_word": "hey_mycroft",
    "hey_mycroft": {
      "module": "ovos-ww-plugin-vosk"
    }
  },
  "stt": {
    "module": "ovos-stt-plugin-server",
    "ovos-stt-plugin-server": {
      "url": "https://stt.openvoiceos.org/stt"
    }
  },
  "tts": {
    "module": "ovos-tts-plugin-server",
    "ovos-tts-plugin-server": {
      "host": "https://tts.openvoiceos.org"
    }
  }
}

---

Plugin slots

All plugin types are managed by ovos-plugin-manager. Install the plugin with pip, then set module in the config.

Plugin type	Config key	Required	Default installed	Documentation
Microphone	microphone.module	Yes	ovos-microphone-plugin-alsa (Linux)	Mic plugins
VAD	listener.VAD.module	Yes	ovos-vad-plugin-silero	VAD plugins
Wakeword	listener.hey_mycroft.module	Yes*	ovos-ww-plugin-vosk	WW plugins
STT	stt.module	Yes	ovos-stt-plugin-server	STT plugins
TTS	tts.module	Yes	ovos-tts-plugin-server	TTS plugins
G2P	tts.g2p_module	No	n/a	G2P plugins
Audio transformers	audio_transformers (legacy: listener.audio_transformers)	No	n/a	Transformer plugins
Dialog transformers	dialog_transformers	No	n/a	Transformer plugins
TTS transformers	tts_transformers	No	n/a	Transformer plugins
Media playback	Audio.backends	No	n/a	Media playback plugins
OCP	ocp	No	n/a	OCP plugins
PHAL	n/a	No	n/a	PHAL

* Wakeword can be skipped by enabling continuous listening mode.

Transformer pipelines in a split deployment

The satellite runs the full on-device pipeline stack: audio transformers (listener, pre-STT), dialog transformers, and TTS transformers (playback). Utterance, metadata, and intent transformers do not run here. They run server-side, in ovos-core behind the HiveMind server. hivemind-core can also run its own utterance, metadata, and dialog chains for the mesh.

Enable each plugin in exactly one place. Put per-device effects (denoise, speaker-specific audio tweaks) on the satellite. Put fleet-wide effects (persona or tone rewrites, shared corrections, policy stop-words) on the server. If TTS audio says different text than the skill produced, a server-side dialog transformer is rewriting it. This is deliberate when centralizing a persona, but check it if it is unexpected. See the ovos-plugin-manager transformer docs for the full contract.

Fully local example (no cloud calls)

{
  "microphone": {
    "module": "ovos-microphone-plugin-alsa",
    "ovos-microphone-plugin-alsa": {
      "device_name": "hw:1,0"
    }
  },
  "listener": {
    "VAD": { "module": "ovos-vad-plugin-silero" },
    "wake_word": "hey_mycroft",
    "hey_mycroft": { "module": "ovos-ww-plugin-vosk" }
  },
  "stt": {
    "module": "ovos-stt-plugin-faster-whisper",
    "ovos-stt-plugin-faster-whisper": { "model": "small" }
  },
  "tts": {
    "module": "ovos-tts-plugin-piper",
    "ovos-tts-plugin-piper": { "voice": "en_US-lessac-medium" }
  }
}

Continuous listening (no wakeword)

{
  "listener": {
    "continuous_listen": true
  }
}

---

PHAL

If ovos-PHAL is installed, the satellite starts it automatically alongside the voice loop. PHAL plugins add platform-specific integrations (hardware buttons, LEDs, Mark 1 faceplate, and similar). Configure them under PHAL in mycroft.conf.

---

← Getting started · Home · Architecture →