OpenVoiceOS Bus Client

A Python client for the OVOS messagebus. Connect to OVOS, emit messages, and react to system events.

The OVOS messagebus is the nervous system of an OVOS install. Every component — STT, intent parsing, skills, TTS, audio, GUI — talks over it. This package is the Python client.

⚠️ The bus is private. It has no authentication — every connected client can issue any natural-language command, speak through the speakers, take over any subsystem, and read every other client's traffic. Keep it bound to 127.0.0.1 (the default), never expose it on a network interface, and never put it behind a reverse proxy. For remote access, use HiveMind, which adds encryption, identity, and policy enforcement on top.

Install

pip install ovos-bus-client

Quick start

from ovos_bus_client import MessageBusClient, Message

client = MessageBusClient()
client.run_in_thread()
client.connected_event.wait()

client.emit(Message('speak', data={'utterance': 'Hello World'}))

Listening for messages:

from ovos_bus_client import MessageBusClient

client = MessageBusClient()

def on_speak(message):
    print('OVOS said:', message.data.get('utterance'))

client.on('speak', on_speak)
client.run_forever()

CLI tools

Command	Description
ovos-speak <text> [lang]	Ask OVOS to speak a phrase
ovos-say-to <text> [lang]	Inject an utterance into the intent pipeline
ovos-listen	Trigger the wake-word / listen cycle
ovos-simple-cli [lang]	Interactive text REPL for OVOS

Configuration

MessageBusClient reads the websocket block of your OVOS config (loaded by ovos-config) — defaults to ws://127.0.0.1:8181/core. Override at construction:

MessageBusClient(host='127.0.0.1', port=8181)

Do not change host to anything routable. See the security callout above.

Migrating from 1.x

Two modules were removed in 2.0.0. Install their replacement packages if you used them:

Removed	Replacement	Install
ovos_bus_client.hpm.OVOSProtocol	hivemind-ovos-agent-plugin	pip install hivemind-ovos-agent-plugin
ovos_bus_client.opm.OVOSMessagebusSolver	ovos-messagebus-chat-plugin	pip install ovos-messagebus-chat-plugin

The HiveMind agent entry point (hivemind.agent.protocol) and the solver entry point (neon.plugin.solver) are no longer registered by this package. See docs/migration.md for details.

Documentation

Full developer docs live in docs/:

• Getting started — install to first message
• Core concepts — bus model and the security boundary
• Messages — Message, GUIMessage, reply helpers
• The client — MessageBusClient API in depth
• Configuration — host, port, route, ssl
• Sessions — Session, SessionManager, IntentContextManager
• Waiters and collectors — request/response and multi-reply patterns
• High-level APIs — GUIInterface, OCPInterface, EnclosureAPI, scheduler
• CLI tools — ovos-speak, ovos-listen, ovos-say-to, ovos-simple-cli
• Common patterns — recipes for everyday use
• Testing — FakeBus, isolating tests
• Migration from 1.x — what moved out in 2.0
• Development — repo layout, releases
• Glossary — terms

Related

• ovos-pydantic-models — authoritative Pydantic v2 index of every OVOS bus message type. Opt-in validation layer for typing, docs generation, and integration tests. Browsable docs: https://openvoiceos.github.io/ovos-pydantic-models/.
• HiveMind — external-access layer in front of the bus; the right tool for remote clients.

License

Apache 2.0. See LICENSE.md.