ovos-busmon

Live monitor, capture, and injection tool for the OpenVoiceOS messagebus. Stream every bus message to a browser, filter by type (glob), inspect payloads, export captures as JSONL, and inject messages from the UI.

See the docs for a full walkthrough with screenshots. Start with the tutorials.

Debug your OVOS device from a URL

The monitor UI is a single static page. Host it on GitHub Pages, and anyone with a laptop that can reach an OVOS device connects to its messagebus at once. No install, no server: the page opens a WebSocket straight to ws://localhost:8181/core. Set the host and port in the connection panel or with the ?host=&port= query parameters.

Browser note: Chromium browsers allow a ws://localhost connection from an https:// page, because localhost is a trustworthy origin. Safari and some Firefox versions block it. If the connection is refused, click Download standalone HTML in the UI and open the saved file locally. It has the same functions and no restrictions.

Two transport modes, one UI

Mode 1: fully in-browser (zero server)

Open static/index.html directly, or deploy it to GitHub Pages. The page opens a WebSocket directly to the OVOS messagebus (ws://localhost:8181/core by default). Set the host, port, and path in the connection panel or with query parameters:

file:///path/to/static/index.html?host=192.168.1.10&port=8181&path=/core

This works whenever the browser can reach the bus, on the same machine as OVOS or on a LAN. No server is required.

Mode 2: service (ovos-busmon)

Install and run the FastAPI service. It connects server-side to the bus through ovos-bus-client and serves:

The UI auto-detects the transport:

• served from http:// or https://: SSE and REST (Mode 2)
• opened as file:// or from a static host: direct WebSocket (Mode 1)

Installation

pip install ovos-busmon

Or from source:

git clone https://github.com/OpenVoiceOS/ovos-busmon
cd ovos-busmon
pip install -e .[dev]

Running the service

ovos-busmon
# Listens on http://127.0.0.1:8005 by default

Configuration

Set every option through environment variables, or through a .env file:

Authentication is off until you set BUSMON_TOKEN, or BUSMON_USERNAME and BUSMON_PASSWORD. There are no default credentials.

Docker

docker compose up --build

The compose file binds the service to 127.0.0.1:8005 only (localhost). To reach an OVOS bus on the host machine, it sets OVOS_BUS_HOST=host.docker.internal automatically.

Message injection

The Inject panel is a power tool. It sends arbitrary messages onto the bus, which helps with development and testing. The service binds only to 127.0.0.1 by default. Do not expose it to untrusted networks.

Features

• Live message stream with expandable, highlighted JSON (vendored highlighter, fully offline, no CDN)
• Timeline view: group the stream by session into expandable per-interaction traces with category badges
• Chat panel: chat with the assistant in text over one stable session id (multi-turn and converse work) while you watch the bus handle each turn
• Filter by message type (glob patterns, for example ovos.* or recognizer_loop:*)
• Full-text search across type, data, context and session
• Filter by session id, source, and destination
• Sort newest-first or oldest-first
• Pause and resume capture, plus auto-pause on filter match
• Bounded client-side buffer (configurable, with a visible dropped-count)
• Export as JSONL or JSON (client-side or through /api/export)
• Message injection (type, JSON data, and optional JSON context)
• Ring buffer with configurable capacity and since_id pagination
• GitHub Pages deployable (Mode 1, no server needed)

Development

pip install -e .[dev]
pytest tests/ -v

Security

ovos-busmon is a local debugging tool. It can inject any message onto the bus, so an open bind beyond loopback is a remote-control hole.

Authentication is off by default and is meant for loopback use. There are no default credentials. To use the service beyond loopback, set BUSMON_TOKEN (recommended), or set BUSMON_USERNAME and BUSMON_PASSWORD. The service refuses to start on a non-loopback host when no authentication is set.

A token travels as ?token= on the URL or as an Authorization: Bearer header. The ?token= form lets the live UI carry the token on its SSE stream, which HTTP Basic cannot. HTTP Basic auth sends credentials in plaintext unless you add TLS. Keep the default 127.0.0.1 bind for local use, and do not expose the service to the public internet.

Related projects

• ovos-messagebus: the bus server this tool monitors
• ovos-bus-client: the client library used in service mode
• ovos-core: the intent pipeline whose traffic you trace
• hivemind-core: protected remote access to a bus, where busmon also works

License

MIT. See LICENSE.

Credits

Developed by TigreGotico for OpenVoiceOS.

Funded by NGI0 Commons Fund / NLnet under grant agreement No 101135429, through the European Commission's Next Generation Internet programme.