config.yaml

This page lists every key the go-ricochet 1.1.0 config file accepts, from yamlFileConfig in internal/core/config.go. The annotated sample is config.example.yaml.

Loading rules

Rule	Behaviour
File location	--config <path>; without it, /etc/ricochet/config.yaml when that file exists
Precedence	Preset (--development, --production, --high-capacity, or the defaults) → config file → RICOCHET_PG_PASSWORD → CLI flags
Omitted key	Keeps the preset’s value
Zero or empty value	Treated as omitted, except for the keys marked “explicit zero applies”
Unknown key	Startup error (parse config file: ... field <name> not found)
Unreadable or unparsable file	Startup error, exit code 2
Durations	Keys ending _sec, _min or _days take integers in that unit; keys without a unit suffix (acquire_timeout, window, readiness_timeout, …) take Go duration strings such as 5s or 1m

Defaults below are the built-in values (core.DefaultConfig). Presets change some of them.

server

Key	Type	Default	Meaning
server.port	int	55223	UDP port; also rewrites the port in every listen_addresses entry
server.region	string	default	Region label advertised in service announcements
server.identity_file	string	none	Ed25519 identity key file; without it, RICOCHET_SEED_HEX or <data_directory>/peer_identity.key
server.listen_addresses	list of multiaddr	[/ip4/0.0.0.0/udp/55223/udx]	Addresses to listen on; only /udx addresses have a transport
server.external_addresses	list of multiaddr	none	Extra addresses advertised through Identify, such as the public IP
server.bootstrap_peers	list of multiaddr	none	DHT bootstrap peers, dialled at start; also the static relays for enable_auto_relay

See Transport, DHT & bootstrap peers and Identity keys.

storage

Key	Type	Default	Meaning
storage.data_directory	string	./sf_storage	Data directory; holds the generated identity key
storage.max_storage_gb	int	10	Storage budget in GiB; writes are refused with 507 once the database reaches it
storage.retention_days	int	30	Default retention for new mailboxes
storage.max_messages_per_mailbox	int	1000	Default message cap for new mailboxes; a full mailbox refuses with 507
storage.max_mailboxes	int	100000	Mailboxes across the server
storage.max_mailboxes_per_owner	int	100	Mailboxes one peer may own
storage.mailbox_cache_size	int	10000	Loaded mailboxes kept in memory by the delivery path
storage.max_entries_per_feed	int	10000	Ceiling on entries in one feed
storage.near_capacity_ratio	float	0.9	Fill fraction at which a mailbox counts as near capacity; 0 to 1

See Storage, quotas & retention.

database

Key	Type	Default	Meaning
database.host	string	localhost	PostgreSQL host
database.port	int	5432	PostgreSQL port
database.name	string	ricochet	Database name
database.username	string	ricochet	Role name
database.password	string	none	Password; prefer RICOCHET_PG_PASSWORD
database.sslmode	string	require	require or disable; the development preset sets disable
database.pool_size	int	25	Connection pool size; the production preset sets 50

See Database setup.

performance

Key	Type	Default	Meaning
performance.max_concurrent_connections	int	10000	Hard cap on peer connections; idle peers are trimmed past 90% of it
performance.max_connections_per_ip	int	0	Connections per source address (IPv4 address or IPv6 /56); 0 is no cap
performance.connection_timeout_sec	int	30	Seconds a stream may stall with no bytes moving before it is dropped
performance.message_timeout_sec	int	10	Seconds a request may spend after it is read
performance.worker_threads	int	4	Push notifications in flight; surplus notifications are dropped

intervals

Key	Type	Default	Meaning
intervals.service_announcement_min	int	60	Minutes between announcements on /sf-network/services/announce
intervals.health_check_min	int	5	Minutes between self-checks and heartbeats on /sf-network/services/heartbeat
intervals.cleanup_min	int	5	Minutes between cleanup sweeps; also paces the capacity sample
intervals.presence_check_sec	int	30	Seconds between presence reconciliations
intervals.presence_heartbeat_sec	int	60	Seconds between online-set heartbeats on the presence topic
intervals.presence_timeout_sec	int	120	TTL in seconds advertised on an online event

features

Each flag applies whenever the file sets it, false included.

Key	Type	Default	Meaning
features.enable_forwarding	bool	false	Accept messages submitted for another sender by a peer in security.trusted_peers; the high-capacity preset sets true
features.enable_push_delivery	bool	true	Send notifications on new messages
features.enable_presence_monitoring	bool	true	Check a peer is reachable before a direct notification
features.enable_presence_broadcast	bool	true	Publish presence on /sf-network/presence/<serverPeerID>
features.enable_metrics	bool	true	Mount /metrics on the ops listener
features.enable_authentication	bool	false	Accept connections only from security.trusted_peers; on with an empty list is a startup error
features.enable_relay	bool	true	Circuit Relay v2 transport; required by the three relay keys below
features.enable_relay_service	bool	true	Relay for other peers. Forces the host to report itself as publicly reachable, so turn it off when using enable_auto_relay (NAT traversal)
features.enable_auto_relay	bool	false	Reserve relay slots on the static relays in server.bootstrap_peers; has no effect while enable_relay_service is on
features.enable_hole_punching	bool	false	DCUtR hole punching
features.enable_autonat	bool	true	AutoNAT v2

See NAT traversal & relay and Trusted peers.

ops

Key	Type	Default	Meaning
ops.enabled	bool	true	Run the operator HTTP listener (explicit false applies)
ops.bind	string	127.0.0.1	Listen interface
ops.port	int	9090	TCP port; 0 picks an ephemeral port (explicit zero applies)
ops.enable_pprof	bool	false	Mount /debug/pprof/
ops.readiness_timeout	duration	2s	Limit on /readyz checks
ops.query_timeout	duration	10s	Limit on each /ops/* query
ops.shutdown_timeout	duration	5s	Wait for in-flight requests at shutdown
ops.drain_delay	duration	0s	Time shutdown keeps serving after /readyz turns unready

See Ops HTTP endpoints and Upgrades & draining.

relay_limits

Consulted only with features.enable_relay_service on. Zero or omitted keeps the go-libp2p default.

Key	Type	Default	Meaning
relay_limits.max_reservations	int	go-libp2p	Concurrent reservations, server-wide
relay_limits.max_circuits	int	go-libp2p	Concurrent circuits per reservation
relay_limits.buffer_size	int	go-libp2p	Relay copy buffer, bytes
relay_limits.max_reservations_per_peer	int	go-libp2p	Reservations per peer
relay_limits.max_reservations_per_ip	int	go-libp2p	Reservations per IP
relay_limits.max_reservations_per_asn	int	go-libp2p	Reservations per ASN
relay_limits.reservation_ttl_min	int	go-libp2p	Reservation lifetime, minutes
relay_limits.connection_duration_sec	int	go-libp2p	Circuit lifetime, seconds
relay_limits.connection_data	int	go-libp2p	Bytes relayed per circuit before it is cut

admission_control

Key	Type	Default	Meaning
admission_control.enabled	bool	true	Bound work in flight (explicit false applies)
admission_control.max_in_flight	int	0	Concurrent requests server-wide; 0 derives 4 × database.pool_size
admission_control.max_in_flight_per_peer	int	64	Concurrent requests per peer; 0 removes the bound (explicit zero applies)
admission_control.acquire_timeout	duration	5s	Wait for a slot before the request is shed with 503

See Admission & rate limits.

rate_limiting

Off by default: every bucket’s rate is -1. Limits are per peer and per request.

Key	Type	Default	Meaning
rate_limiting.window	duration	1m	Period over which rate replenishes
rate_limiting.protocols.<name>.requests.rate	int	-1	Sustained requests per window for msa, msa_batch, maa, mma, mta; -1 disables
rate_limiting.protocols.<name>.requests.burst	int	0	Requests a peer may save up and spend at once; 0 means equal to rate
rate_limiting.protocols.<name>.read.rate / .burst	int	-1 / 0	Read bucket for sda, sfa, sca
rate_limiting.protocols.<name>.write.rate / .burst	int	-1 / 0	Write bucket for sda, sfa, sca
rate_limiting.window_minutes	int	none	Legacy alias for window, in minutes
rate_limiting.max_requests_per_window	int	none	Legacy: sets the mta rate to this and its burst to twice this

A <name> outside msa, msa_batch, maa, mma, sda, sfa, sca, mta is a startup error.

security

Key	Type	Default	Meaning
security.trusted_peers	list of peer ID	none	Peers allowed to connect under enable_authentication and to forward under enable_forwarding; each entry must parse as a peer ID

pubsub

Key	Type	Default	Meaning
pubsub.relay_topics	list of string	none	GossipSub topics the server joins and relays without subscribing; no empty or duplicate entries

See Relayed GossipSub topics.

No logging section

There is no logging: key; a config file that has one fails to load. The server logs at INFO, or DEBUG with --development. Library logging follows --debug-dht and GOLOG_LOG_LEVEL.

Environment variables

Variable	Read by	Meaning
RICOCHET_PG_PASSWORD	ricochet	PostgreSQL password; overrides database.password, overridden by --pg-password
RICOCHET_SEED_HEX	ricochet	Hex-encoded Ed25519 seed for the server identity; takes priority over server.identity_file and the generated key file
GOLOG_LOG_LEVEL	go-log (libp2p)	Log level of the libp2p subsystems
DB_PASSWORD	deploy/run.sh	Exported by the package’s start script as RICOCHET_PG_PASSWORD; required
EXTERNAL_IP	deploy/run.sh	Passed as --external-addrs /ip4/<EXTERNAL_IP>/udp/<port>/udx
LISTEN_PORT	deploy/run.sh	Passed as --port
DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_SSLMODE	deploy/run.sh	Passed as --pg-host, --pg-port, --pg-database, --pg-username, --pg-sslmode

The .deb package installs /etc/ricochet/env.example and, on first install, copies it to /etc/ricochet/env (owner root:ricochet, mode 640), which run.sh sources. See Install.