Configuration¶

switchyardd reads a single YAML file at startup (--config <path>, default /etc/relayfabric/relayfabric.yaml). The file is deny-by-default: nothing is bridged between plugins unless a routes entry says so. This page documents every top-level block, exactly as switchyardd/src/config.rs parses and validates it, and which parts of a running daemon pick up an edited file live versus need a restart.

The canonical, fully annotated reference is docs/relayfabric.example.yaml — every field on this page appears there with the same defaults and commentary. Copy it as a starting point rather than writing a config from scratch.

node¶

plugins¶

A map of plugin name → configuration. The name is also the protocol prefix used in route endpoints (mqtt:chat/a, lxmf:pasadena, ...).

Python plugins run under a venv and need an absolute interpreter path (command: /path/to/.venv/bin/python /path/to/relayfabric-lxmf) — a bare relayfabric-lxmf isn't on PATH under sh -c, and the script's shebang won't see the venv's dependencies.

routes¶

Render knobs¶

render tunes the transform pipeline that already runs on every send:

routes:
  - name: demo
    sources: ["mqtt:chat/a", "mqtt:chat/b"]
    destinations: ["mqtt:chat/a", "mqtt:chat/b"]
    render:
      tag: alias
      max_chars: 900

See Routing & Policy for how routes interact with policies and public_services.

transports¶

A map of plugin name → transport class and optional policy overrides, distinct from the plugin's wire protocol. This drives egress payload caps and image/video allow/disallow — see Transport Classes for the full class list and built-in policy defaults.

A plugin with no transports entry gets a default class by protocol name: mqtt/signal/nostr/bitchat → terrestrial_internet, meshtastic → meshtastic, meshcore → mesh_core, lxmf → reticulum; anything else also falls back to terrestrial_internet. That default reproduces pre-transport-class behavior exactly (no cap beyond the daemon's 16 MiB frame limit, images and video allowed).

At egress, the composed policy caps payload to min(plugin cap, transport cap); an attachment the class forbids is dropped and replaced with a body note (e.g. [image 'photo.jpg' omitted — constrained transport]) rather than sent. Sealed routes are exempt — no transform ever touches a sealed payload.

transports:
  meshtastic: { class: meshtastic }
  mqtt:       { class: satellite_internet, max_payload_bytes: 32768, allow_images: false }

Takes effect live — no restart needed.

transport_budgets¶

Rate limits per egress protocol.

transport_budgets:
  mqtt:
    messages_per_minute: 500
  lxmf:
    messages_per_minute: 200

Takes effect live: reload resets the budget window for every configured protocol (and every fed/<peer_name> window).

privacy¶

Node-level sealed-routing privacy floor.

privacy:
  minimum_security: sealed
  allow_gateway_decryption: false

Deliberately kept a top-level block (not nested under node) so it applies live rather than forcing a restart. See Security & Sealed Routing.

federation¶

Absent entirely — as in every pre-federation config — means the feature is off: no Noise listener, no fed egress/ingress, no trust seeding.

Each peers[] entry:

federation:
  listen: "127.0.0.1:47000"
  accept_from: verified
  peers:
    - name: phoenix
      node_id: "rf:<64hex>"
      addr: "10.0.0.2:47000"

RFDP discovery (node adverts describing public_services) is a related, separately-versioned discovery: block that requires federation to be set — see Federation & Discovery.

Top-level TTLs and limits¶

dedup_ttl_secs applies live (pushed into the dedup store's TTL on reload; entries already recorded keep aging out under whatever TTL was in effect when they were recorded). The other three are read fresh on every use, so they also take effect on the next config apply with no restart.

Secret references¶

Any string value inside a plugin's config: block may be, in its entirety, one of two forms:

• ${env:NAME} — the named environment variable, resolved once at config load. Errors at load if unset or empty.
• ${file:/abs/path} — a file's trimmed contents, resolved once at config load. The path must be absolute; a relative ${file:...} is rejected. Errors at load if unreadable or empty after trimming. A group/world-readable secret file triggers a warning (still resolves — not a hard error).

config:
  broker_token: ${env:RELAYFABRIC_MQTT_TOKEN}
  api_key: ${file:/etc/relayfabric/secrets/api-key}

Resolved values are passed to the plugin process via the RELAYFABRIC_PLUGIN_CONFIG env var at spawn (the plugin scrubs it from its own environment immediately after parsing, so children it spawns don't inherit it). Resolved secret values never appear in admin API responses, logs, or --check-config output — those always show the unresolved ${...} form.

Other top-level blocks¶

A few blocks round out the example config but are documented in depth elsewhere:

Validating configuration¶

switchyardd --config /path/to/relayfabric.yaml --check-config

Parses, validates, and resolves secrets using the exact same pipeline the daemon uses at startup, then exits without binding any sockets or spawning any plugins:

• Valid: prints configuration valid: N route(s), M plugin(s) and exits 0.
• Invalid: prints config error: <message> to stderr and exits 1.

The admin API exposes the same pipeline for a running daemon: POST /v1/config/validate checks a candidate YAML body without applying it, PUT /v1/config validates and applies it (returning which parts need a restart), and GET /v1/config serves the currently loaded config back byte-for-byte, secrets still in ${...} form. See Operations.

Hot reload summary¶

PUT /v1/config (or restarting against an edited file) swaps in the new config. Most blocks apply live; a few require a restart:

Minimal working example¶

node:
  name: example-gateway
  data_dir: /var/lib/relayfabric

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

routes:
  - name: demo
    sources: ["mqtt:chat/a", "mqtt:chat/b"]
    destinations: ["mqtt:chat/a", "mqtt:chat/b"]

ttl_default_secs: 86400
dedup_ttl_secs: 86400
hop_limit: 8
max_attachment_bytes: 8000000

Validate it, then run the daemon against it:

switchyardd --config docs/relayfabric.example.yaml --check-config
switchyardd --config docs/relayfabric.example.yaml

For the complete, heavily annotated reference — every plugin's config shape, policies, public_services, limits, federation, discovery, and privacy all shown together — see docs/relayfabric.example.yaml.

See also¶

• Routing & Policy — how routes, policies, and public_services combine to decide what's allowed to cross.
• Security & Sealed Routing — security_mode, the privacy floor, and sealed federation routing in depth.
• Transport Classes — the full class list and built-in TransportPolicy defaults behind transports.
• Operations — the admin API, limits, and running a daemon in production.