ovos-busmon

A DevTools-style live log for the OpenVoiceOS messagebus. Every message streams into a dense, one-row-per-message log. Filter it with chips and click-to-filter, inspect a row, group the stream by session, inject messages, and export a capture.

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.

The bus is noisy. Sensor polling, sync heartbeats, enclosure animation, and IPC traffic can drown the messages you care about, so the log mutes that noise by default. Click Show noise to bring it back.

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 Save offline copy in the UI and open the saved file locally. It has the same functions and no restrictions. For this and other connection problems, see docs/troubleshooting.md.

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

• Stream & filter: a live "now" line, a dense DevTools-style log with coalesced bursts and a mutable noise firehose, category chips and click-to-filter, and a bounded, configurable buffer with a dropped-count
• Trace a session: group the flat stream into expandable per-interaction traces, from utterance to skill to speech
• Debug tools: inject a message onto the bus with presets, resend or edit a captured row, build a Session (including pipeline) to attach to injects and chat, and chat with the assistant over a stable session id
• Export: JSONL, JSON, or a full offline copy of the monitor with its captured messages
• GitHub Pages deployable (Mode 1, no server needed)

For the full detail on each control, see the docs.

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.

A token in the URL can end up in the browser's history, in server access logs, and in any proxy log between the browser and the service. Use a trusted network, and prefer a short-lived token when you must expose the service beyond loopback.

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.