Plugins¶

RelayFabric never speaks a native protocol itself. Each bridged network is owned by a plugin — a separate process the switchyardd daemon spawns, supervises, and talks to over a small IPC. This page covers the plugin model shared by every bridge, then one section per shipped plugin: what network it bridges, its config keys, its licensing posture, and (where the plugin's own README documents them) known field-test risks. For the full config schema see Configuration; to write a new plugin, see Plugin Authoring; for how these plugins were exercised against real infrastructure, see Live & Field Testing.

The plugin model¶

Separate, supervised processes. A plugin is whatever the daemon's command: spawns — a Rust binary, a Python script, anything that speaks the wire protocol. The daemon restarts a plugin that dies unexpectedly with bounded backoff (1s, 5s, 30s, 2m, ...); a plugin that keeps crashing is marked unhealthy rather than restarted forever.

CBOR-over-Unix-socket IPC. The daemon spawns each plugin with RELAYFABRIC_SOCKET (the Unix domain socket path), RELAYFABRIC_PLUGIN_NAME, and RELAYFABRIC_PLUGIN_CONFIG (the plugin's config: block as JSON) in its environment. Every frame on the socket is a 4-byte big-endian length prefix followed by a CBOR body, with a t tag identifying the frame (hello, hello_ack, inbound, send, send_direct, delivery_result, shutdown). Wire bytes are golden-locked across implementations, so a Rust plugin (relay-core + relay-ipc) and a Python plugin (relayfabric_sdk) interoperate exactly.

Capability advertisement (Hello). Before anything else, a plugin sends one Hello { plugin, version, protocol_version, capabilities } frame and waits for HelloAck; a non-null error means the daemon rejected it and it must exit rather than proceed. Capabilities (text, direct_messages, groups, attachments, location, reactions, receipts, presence, max_payload) aren't cosmetic — the daemon uses them to route and to gate features. direct_messages in particular gates whether a plugin ever receives a send_direct frame (used today for identity-link challenge delivery).

Deny-by-default. A plugin only subscribes to, and only accepts sends for, the channels/topics/filters explicitly present in its config — unconfigured native traffic is never bridged. Several plugins add a second, protocol-specific layer of this: Nostr and Bitchat recompute and verify every inbound event's signature before bridging it, since a relay is untrusted infrastructure.

Content never logged. Default daemon logs carry operational metadata (message id, route, source protocol) and never message bodies — privacy tests assert this holds even with linked identities and location data in play.

MQTT¶

The in-tree Rust reference plugin (relayfabric-mqtt), and also a useful integration/testing transport in its own right (spec §8). Bridges arbitrary MQTT topics over MQTT v5: each subscribed topic doubles as the fabric endpoint name, and there is no separate channel-mapping layer — topics is the config. Delivery results are reported only once the broker's QoS 1 PUBACK arrives, not merely on local enqueue. Loop prevention here is transport-level: subscriptions set MQTT v5's No Local flag so the broker never echoes the plugin's own publishes back to it.

plugins:
  mqtt:
    enabled: true
    command: relayfabric-mqtt
    config:
      broker: mqtt://127.0.0.1:1883
      topics: [chat/a, chat/b]

LXMF¶

Bridges LXMF over Reticulum (RNS). Each configured channel maps to a set of LXMF destination hashes ("members"): inbound messages from a member land on the channel, and messages sent to the channel fan out as direct LXMF messages to every member, falling back to a propagation node (store-and-forward) if direct delivery fails.

plugins:
  lxmf:
    enabled: true
    command: /path/to/.venv/bin/python /path/to/plugins/lxmf/relayfabric-lxmf
    config:
      storage: /var/lib/relayfabric/lxmf
      channels:
        - name: pasadena
          members: ["a91d00aa..."]
          open: false

Optional extras (Pillow for image downscaling; ffmpeg + pycodec2 for voice-to-codec2 transcoding) degrade gracefully when absent — oversize images or untranscoded voice fall back to plain file attachments rather than failing the send.

Signal¶

Bridges Signal groups: each configured group maps to a channel, one endpoint per group (fan-out across groups is the daemon's routing concern, not this plugin's). Talks to a locally-run signal-cli daemon over JSON-RPC/SSE rather than embedding Signal's protocol directly.

plugins:
  signal:
    enabled: true
    command: /path/to/.venv/bin/python /path/to/plugins/signal/relayfabric-signal
    config:
      account: "+1234567890"
      rpc_url: http://127.0.0.1:7583
      groups:
        pasadena: "GRP=="

If the account is a linked device, sync-message echoes of the gateway's own posts are filtered and bare DMs (no group) are dropped; if allowed_users is set, the account's own UUID must be included or its posts are dropped by the ACL. Attachments cross as opaque bytes — no downscaling or transcoding happens here (that lives in the LXMF plugin, for messages routed onward there).

Meshtastic¶

Bridges Meshtastic device channels. Each configured channel maps to a RelayFabric channel: text uplinks arrive over the node's MQTT JSON stream, and messages sent to the channel are delivered back over MQTT (one topic per Meshtastic channel).

plugins:
  meshtastic:
    enabled: true
    config:
      broker: mqtt://127.0.0.1:1883
      topic_root: msh/US
      channels:
        zone1: {index: 0, topic_channel: "general"}

A consume-on-match cache keyed on (channel, text) breaks the MQTT→Meshtastic→MQTT loop: a successful downlink is remembered for 1 hour and the next matching uplink is dropped instead of re-bridged.

MeshCore¶

Bridges MeshCore (Companion Radio Protocol) devices directly — no intermediary broker. Each configured channel maps to a RelayFabric channel; text uplinks land on the channel, sent messages go back over the radio. Requires companion-mode firmware.

plugins:
  meshcore:
    enabled: true
    config:
      connection: serial:///dev/ttyUSB0
      channels:
        primary: {index: 0}

Sender identity is channel-scoped, not per-node: MeshCore PSK channels carry no per-node identity, so the plugin keys sender on (channel index) — every message on a channel maps to the same sender. Rate limits, aliases, and moderation therefore all operate at channel granularity, not per-user.

Nostr¶

Bridges Nostr relays natively over NIP-01 WebSockets — no intermediary broker. Each channel is a (relay-set, filter) pair for inbound plus a publish target. Scope: kind-1 public text notes only — encrypted DMs, attachments, and profile/contact-list management are out of scope this cycle.

plugins:
  nostr:
    enabled: true
    config:
      identity_file: /var/lib/relayfabric/nostr.nsec
      relays: ["wss://relay.example.com"]
      channels:
        regional:
          filter: {kinds: [1], "#t": ["pasadena"]}
          publish_tags: [["t", "pasadena"]]

Every inbound event's id is recomputed and its schnorr signature verified against the claimed pubkey before bridging — a relay is untrusted; bad id/sig events are dropped, never bridged.

Bitchat¶

Bridges Bitchat's public geohash channels over the Internet/Nostr transport only — ephemeral kind-20000 events, channel = ["g", <geohash>] tag. Reuses the shipped Nostr NIP-01 crypto and relay machinery. BLE mesh is out of scope, deferred — Bitchat's direct Bluetooth-LE mesh is a separate mechanism not built here. DMs and attachments are out of scope too.

plugins:
  bitchat:
    enabled: true
    config:
      identity_file: /var/lib/relayfabric/bitchat.nsec
      relays: ["wss://relay.example.com"]
      channels:
        pasadena:
          geohash: "9q5c"
          nickname: "relayfabric"

Same sig-verify-before-bridge and deny-by-default rules as Nostr apply (bad id/sig, wrong-kind, or wrong-geohash events are dropped; only configured geohashes are subscribed).