Skip to content

Configuration file ​

The relay reads its settings from a YAML file given with --config. Without one it runs on the defaults below.

Rules ​

  • Every key is optional. A key left out takes its default.
  • An unknown key stops the relay at startup.
  • Durations need a unit: 500ms, 10s, 30m, 1h.
  • Relative paths resolve against the directory the relay starts in, not the directory of the file.
  • The flags --bind, --cert-file and --key-file override the file.

The relay also refuses to start when:

SettingRefused when
dedup_retained_groupsabove 1000
ssts_algorithmsit lists an id the relay does not implement
peersit is not empty and hop_id is not set
apisee startup refusals

io_sockets is not refused: values outside 1 to 256 are clamped.

Keys ​

This is the file apps/relay/relay.example.yaml from the repository. It lists every key with its default and a short description. Commented-out keys have no default; uncomment one to set it.

yaml
# MOQtail relay configuration. Every key is optional and shown here with its
# default; full descriptions are on `AppConfig` in apps/relay/src/server/config.rs.
# Pass with `relay --config <file>`; --bind, --cert-file and --key-file override it.
# Durations take units: 500ms, 10s, 30m, 1h. Relative paths resolve against the
# directory the relay is started from, not this file's.

# Address to bind. [::] takes IPv4 and IPv6 alike; 0.0.0.0 is IPv4 only.
bind: '[::]:4433'
cert_file: apps/relay/cert/cert.pem
key_file: apps/relay/cert/key.pem
# Folder for the object logs (enable_object_logging) and cache_eviction.log, which is always written.
log_folder: /tmp

# QUIC
# A connection silent for max_idle_timeout is closed; keep-alives keep it open.
max_idle_timeout: 7s
keep_alive_interval: 3s
# UDP sockets sharing the port via SO_REUSEPORT (Linux only).
io_sockets: 1
# UDP send/receive buffer per socket in KiB; 0 = kernel default.
socket_buffer_kib: 8192
# QUIC max_concurrent_bidi_streams a peer may open.
max_request_streams: 10000

# Cache
# Groups cached per track.
cache_size: 1000
# ttl drops an entry cache_expiration after it was cached; tti after it was last used.
cache_expiration_type: ttl
cache_expiration: 30m

# Logging
# Object logs in log_folder: track_<alias>.log, sub_<alias>_<connection>.log and one per FETCH.
enable_object_logging: false
# AUTHORIZATION_TOKEN registrations from SETUP, appended to token_log_path as CSV.
enable_token_logging: false
token_log_path: /tmp/tokens.csv
# qlog traces of control messages, one .sqlog file per connection (unset = off)
# A long-lived publisher's file grows with every stream it opens; a file stops
# at about qlog_max_file_bytes, with a last event saying so (0 = no limit).
# qlog_folder: /tmp/qlog
qlog_max_file_bytes: 0

# Load and subscriber limits (0 = off / unlimited)
# Request streams served relay-wide before new ones get EXCESSIVE_LOAD.
max_active_requests: 0
# Objects queued for a subscriber before TOO_FAR_BEHIND.
max_subscriber_lag: 0
# How long an Object may wait in a subscriber's queue before its group is skipped.
delivery_timeout: 0s
# Payload bytes queued for one subscriber before its group is skipped.
max_subscriber_queue_bytes: 16777216
# PUBLISH streams per SUBSCRIBE_TRACKS before PUBLISH_SKIPPED.
max_publish_streams: 0
# Simulated per-connection bandwidth cap in kbps.
write_kbps_limit: 0

# Track Alias given to subscribers: per-subscription or per-track.
track_alias_mode: per-subscription
# URI advertised in GOAWAY; unset reuses the current URI.
# redirect_uri: moqt://other-relay.example:4433

# Upstream and timing
# Cache gaps one FETCH may fill from upstream; later gaps are sent as missing.
max_upstream_fetch_gaps: 10
upstream_fetch_timeout: 10s
# How long a publisher has to answer the relay's SUBSCRIBE before it counts as declined.
upstream_subscribe_timeout: 10s
# How long a data stream waits for the message that sets its track alias.
track_alias_resolution_timeout: 2s
# How long objects queue for a subscriber whose track alias is not sent yet.
downstream_alias_timeout: 3s
# How long PUBLISH_DONE waits for the data streams still in flight.
publish_done_stream_timeout: 2s
# PUBLISH_DONE on a datagram track waits until no datagram arrived for this long.
publish_done_datagram_quiet: 100ms
# Longest a SUBSCRIBE waits for a publisher; 0s never waits.
max_rendezvous_timeout: 10s

# Groups of Object ids remembered per track for duplicate detection (max 1000).
dedup_retained_groups: 30
# Range Filter ranges a subscriber may ask for (MAX_FILTER_RANGES).
max_filter_ranges: 32

# Sender-side track switching (provisional draft; off by default)
ssts_enable: false
# Algorithm ids to run and advertise; decimal or 0x hex.
ssts_algorithms: [0]
# How long an SSTS subscriber's subgroup stream may take to finish before it is reset; 0s never resets.
ssts_discard_timeout: 1600ms

# Relay mesh; off unless hop_id is set. peers needs hop_id.
# hop_id: 1
# Egress cost declared to peers as RELAY_COST; unset means peers assume 1.
# relay_cost: 1
# Relays to dial over raw QUIC; announcements flow both ways over each link.
peers: []
# Skip certificate checks when dialing peers (self-signed development certificates).
peer_no_cert_validation: false

# HTTP API under /api/v1 for observing and operating the relay, and the
# measurements behind it. Off unless api.enable is true.
api:
  enable: false
  # Address of the API; unset means 127.0.0.1:4480.
  # bind: 127.0.0.1:4480
  # Parts that run; unset means [health, state, metrics, latency, qlog].
  # Also available: events, actions (needs write_token), mcp (needs mcp_token_hash).
  # features: [health, state, metrics, latency, qlog]
  # Client ranges allowed when bind is a network address; unset means loopback
  # only. Ignored on a loopback bind, where only local programs can connect.
  # allow: [127.0.0.1/32, '::1/128', 10.0.0.0/8]
  # Bearer token for reads (health, ready and meta never need it), and for writes.
  # read_token: ""
  # write_token: ""
  # Browser origins allowed to call the API, such as the dashboard's.
  cors_origins: []
  # A second listener serving only /api/v1/metrics, and a token that reads the
  # metrics and nothing else (for Prometheus).
  # metrics_bind: 0.0.0.0:4481
  # metrics_token: ""
  # MCP server for AI agents at /api/v1/mcp (add mcp to features). It accepts only
  # this token, stored as a salted hash: run `relay api-token` and paste the line
  # it prints. Agents see namespaces, track names and whatever peers send in
  # control messages, which goes to the agent's model provider.
  # mcp_token_hash: ""
  # Lets MCP clients use the write tools; needs the actions feature too.
  mcp_write: false
  # How the relay introduces itself to MCP clients, so an agent connected to
  # several relays can tell them apart (unset = the host name).
  # mcp_name: interop-paris
  # Anything apps should read from GET /api/v1/meta, served as written and
  # without a token, so put nothing secret here. For example:
  # meta:
  #   fqdn: relay.example.com
  #   region: eu-west
  # Closed connections kept in a summary (a few hundred bytes each).
  closed_connection_history: 10000
  # How finely object processing time is kept: relay, track or subscription.
  latency_detail: subscription
  # Measure every Nth object only (by object id); 1 measures every object.
  latency_sample: 1
  # Deliveries slower than this go to /api/v1/latency/slow, and subscriptions that
  # wait longer than the second for their first object; the last slowlog_size kept.
  slowlog_threshold: 20ms
  slowlog_first_object_threshold: 1s
  slowlog_size: 1000
  # Namespace prefixes counted separately in /api/v1/zones and the metrics, such as
  # one per tenant; a namespace belongs to the longest prefix it falls under.
  # Fields are joined by "-", as the dashboard shows namespaces: tenant1-live.
  accounting_zones: []
  # Publish the relay's own metrics as MoQ tracks (catalog, "4" every second, "6"
  # every ten seconds) under metrics.moq.arpa/v1/<metrics_resource_id>. The
  # publisher connects to this relay over loopback. Needs enable.
  metrics_track_enable: false
  # metrics_resource_id: 0123456789abcdef

The field documentation on AppConfig in apps/relay/src/server/config.rs has the longer descriptions.