Skip to content

OVOS Skills Server

This is the setup that turns your hive into a real voice assistant — weather, timers, music, home control, hundreds of skills. Behind hivemind-core sits a full OpenVoiceOS install, and every satellite that connects gets the whole thing: ask any of them a question and an OVOS skill answers. It's the default flavour, and the one most people want when they picture "a private smart speaker I actually own." hivemind-core is the gateway; OVOS is the brain behind it.

In a nutshell

  • A hivemind-core server whose agent talks to a local ovos-core / ovos-messagebus on 127.0.0.1:8181.
  • Every setting lives in ~/.config/hivemind-core/server.json — hivemind-core listen takes no flags.
  • Manage satellites with the hivemind-core CLI (node IDs are positional).

Prerequisites

ovos-core and ovos-messagebus must be running on the same machine before you start hivemind-core. For a minimal OVOS install:

pip install ovos-core ovos-messagebus

See the OVOS documentation for a complete OVOS setup guide.

Install

pip install hivemind-core

Configuration

All server configuration lives at ~/.config/hivemind-core/server.json. hivemind-core listen takes no command-line flags — edit the file to change any setting. Run hivemind-core print-config to dump the effective configuration.

Don't be daunted by the block below — for a standard OVOS server you barely touch it. It shows the keys relevant to a standard setup (hivemind-core print-config shows the rest — protocol-version floor, password policy, presence, rendezvous, upstream, transformers, timing — all at their own defaults). The one line that matters for this setup is the agent_protocol block pointing at your OVOS messagebus. Everything else already does the right thing:

{
  "binarize": false,
  "allowed_encodings": [
    "JSON-B64", "JSON-URLSAFE-B64", "JSON-B91",
    "JSON-Z85B", "JSON-Z85P", "JSON-B32", "JSON-HEX"
  ],
  "allowed_ciphers": ["CHACHA20-POLY1305", "AES-GCM"],
  "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,
      "ssl": false,
      "cert_dir": "~/.local/share/hivemind",
      "cert_name": "hivemind"
    },
    "hivemind-http-plugin": {
      "host": "0.0.0.0",
      "port": 5679,
      "ssl": false,
      "cert_dir": "~/.local/share/hivemind",
      "cert_name": "hivemind"
    }
  },
  "policy": {
    "chain": [
      {"module": "hivemind-ovos-agent-policy"}
    ]
  },
  "database": {
    "module": "hivemind-sqlite-db-plugin",
    "hivemind-sqlite-db-plugin": {
      "name": "clients",
      "subfolder": "hivemind-core"
    }
  }
}

The WebSocket plugin defaults to port 5678 and the HTTP plugin defaults to 5679 — the port keys above are the defaults spelled out explicitly, not an override.

The agent_protocol block points at the OVOS agent plugin. Its keys are host (127.0.0.1, the OVOS messagebus host) and port (8181, the messagebus port). connection_timeout (default 10 seconds, how long to wait for the messagebus before giving up) is an optional override the plugin falls back to internally — it isn't part of hivemind-core's own shipped defaults, so add it explicitly if you need a different value. The entry-point names above — hivemind-ovos-agent-plugin, hivemind-ovos-agent-policy, hivemind-websocket-plugin, hivemind-http-plugin, and hivemind-sqlite-db-plugin — are the strings hivemind-core resolves at startup.

TLS is enabled per network protocol by setting ssl to true and pointing cert_dir/cert_name at the certificate to serve.

More transports than WebSocket + HTTP

The two network_protocol entries above are the defaults, but the carrier is pluggable — MQTT and an experimental Usenet transport also exist. See Transports for the full status table.

Starting the server

hivemind-core listen

All behaviour comes from server.json; there are no flags to pass here.

Managing clients

Client commands take the node ID as a positional argument (omit it and the CLI prompts you to pick one from a table):

# Add a new satellite
hivemind-core add-client --name "living-room"

# List all registered satellites
hivemind-core list-clients

# Remove a satellite (node ID 2)
hivemind-core delete-client 2

# Rename a client (new name via --name, node ID positional)
hivemind-core rename-client --name "new-name" 2

See CLI Reference for all commands and Security for permission management.

Adding server-side audio processing

To support mic-satellite and voice-relay, install the audio binary protocol plugin:

pip install hivemind-audio-binary-protocol

Then configure server.json to enable it. See Audio Binary Protocol.

Systemd service

Once it works from the terminal, you'll want it to come back on its own after a reboot. The unit below does that — the one detail worth copying carefully is the ordering: OVOS's messagebus has to be up before hivemind-core tries to reach it, which the After= / Requires= lines guarantee.

# /etc/systemd/system/hivemind-core.service
[Unit]
Description=HiveMind Core
After=network.target ovos-messagebus.service
Requires=ovos-messagebus.service

[Service]
Type=simple
User=ovos
ExecStart=/home/ovos/.venvs/ovos/bin/hivemind-core listen
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable hivemind-core
sudo systemctl start hivemind-core

Other agent flavors

Beyond the OVOS, persona, and A2A agent plugins, two more agent-plugin flavors exist for advanced or experimental setups. Both are alpha / unpublished, and both repos are private, collaborator access only — the links below resolve only for collaborators.

Advanced: other agent flavors

localhive (hivemind-localhive-agent-plugin, private repo, collaborator access only) — an "isolated-skills" agent. It runs OVOS skills in-process (no separate ovos-core / ovos-messagebus), but each skill only ever sees its own messages. Here skill_id is purely a routing label, not a credential — one skill cannot eavesdrop on another's traffic. Useful when you want OVOS skills without a full messagebus and with strict per-skill isolation.

multimind (hivemind-multimind-agent-plugin, private repo, collaborator access only) — a per-access-key agent multiplexer. Every access key gets its own isolated agent instance (by default a bundled MiniCroft brain), and each key's {module, config} is stored in that client's DB metadata. This is the multi-tenant story: one server, many independent assistants, one per satellite key.

Source

Validated against the HiveMind source: