hivemind-websocket-protocol

July 30, 2026 · View on GitHub

WebSocket transport plugin for hivemind-core.

This is the reference network protocol for HiveMind. Clients connect to hivemind-core over a persistent WebSocket connection (ws:// or wss://). All HiveMessage frames pass over this connection after an initial authentication handshake.

Where it fits

hivemind-core
  └── hivemind-plugin-manager  (NetworkProtocolFactory loads plugins by entry-point)
        └── hivemind-websocket-protocol  ← this repo
              └── Tornado WebSocket server

The plugin registers under the hivemind.network.protocol entry-point group as hivemind-websocket-plugin. hivemind-core loads it automatically when server.json sets network_protocol.module to this name. It is the default transport and is loaded without any explicit config when none is provided.

Install

pip install hivemind-websocket-protocol

Quickstart

The default transport requires no explicit configuration. To confirm it is active or to customize it, add the following to ~/.config/hivemind-core/server.json:

{
  "network_protocol": {
    "module": "hivemind-websocket-plugin",
    "hivemind-websocket-plugin": {
      "host": "0.0.0.0",
      "port": 5678
    }
  }
}

Start hivemind-core:

hivemind-core listen

Clients connect to ws://<host>:5678/?authorization=<base64(name:key)>.

Enable TLS (wss://)

{
  "network_protocol": {
    "module": "hivemind-websocket-plugin",
    "hivemind-websocket-plugin": {
      "host": "0.0.0.0",
      "port": 5678,
      "ssl": true,
      "cert_dir": "/etc/hivemind/ssl",
      "cert_name": "hivemind"
    }
  }
}

If the key file does not exist at <cert_dir>/<cert_name>.key, a self-signed 2048-bit RSA certificate valid for 10 years is generated automatically. For production, replace the auto-generated cert with a properly signed one.

Behind a reverse proxy

When hivemind-core runs behind nginx or another reverse proxy, configure trusted CIDRs so the plugin reads the real client IP from the forwarded header:

{
  "network_protocol": {
    "module": "hivemind-websocket-plugin",
    "hivemind-websocket-plugin": {
      "trusted_proxy_cidrs": ["127.0.0.1/32"],
      "trusted_client_ip_headers": ["x-forwarded-for"]
    }
  }
}

Or via environment variables:

export HIVEMIND_TRUSTED_PROXY_CIDRS="127.0.0.1/32"
export HIVEMIND_TRUSTED_CLIENT_IP_HEADERS="x-forwarded-for"

Configuration reference

Key	Env var	Default	Description
`host`	n/a	`0.0.0.0`	Bind address. Falls back to `identity.default_master`.
`port`	n/a	`5678`	Listen port. Falls back to `identity.default_port`.
`ssl`	n/a	`false`	Enable TLS.
`cert_dir`	n/a	`$XDG_DATA_HOME/hivemind`	Directory for TLS cert and key files.
`cert_name`	n/a	`hivemind`	Base filename. It produces `<name>.crt` and `<name>.key`.
`trusted_proxy_cidrs`	`HIVEMIND_TRUSTED_PROXY_CIDRS`	(none)	Comma-separated CIDRs of trusted proxy addresses.
`trusted_client_ip_headers`	`HIVEMIND_TRUSTED_CLIENT_IP_HEADERS`	`x-forwarded-for,x-real-ip`	Ordered list of headers to inspect for real client IP.

Both trusted_proxy_cidrs and trusted_client_ip_headers accept a string, list, or tuple. The feature is disabled unless at least one CIDR is configured.

Docs

docs/architecture.md: handler lifecycle, authorization flow, IP resolution
docs/configuration.md: full configuration reference
docs/operations.md: TLS, reverse proxy, authoring a transport plugin

hivemind-core: the server that loads this plugin
hivemind-plugin-manager: plugin manager and abstract interfaces that define the NetworkProtocol base class
hivemind-http-protocol: REST/HTTP alternative transport
hivemind-mqtt-protocol: MQTT broker-mediated alternative transport
hivemind-audio-binary-protocol: binary audio streaming plugin, layered on top of a network protocol like this one

License

Apache-2.0. See LICENSE.md.