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-fileand--key-fileoverride the file.
The relay also refuses to start when:
| Setting | Refused when |
|---|---|
dedup_retained_groups | above 1000 |
ssts_algorithms | it lists an id the relay does not implement |
peers | it is not empty and hop_id is not set |
api | see 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: 0123456789abcdefThe field documentation on AppConfig in apps/relay/src/server/config.rs has the longer descriptions.