Warp/docs/configuration.md

Configuration

Warp reads one YAML file. Every setting can also come from the environment, and the environment wins. With no file at all the defaults plus WARP_* variables are used, which is how the container image runs.

Where the file comes from, in order:

1. --config <path>
2. $WARP_CONFIG
3. ./warp.yaml, if it exists
4. nothing — defaults and environment only

An unknown field is a fatal error. A typo in a security-relevant setting must not be ignored.

List-valued variables are comma-separated. A single - clears a list: WARP_CORS_ALLOWED_ORIGINS=-.

Settings

YAML	Environment	Default	Notes
global.server_name	WARP_SERVER_NAME	—	Required. Part of every ID; cannot be changed later.
global.private_key	WARP_PRIVATE_KEY	./keys/signing.key	Written by warp generate-keys.
global.well_known.client_base_url	WARP_WELL_KNOWN_CLIENT_BASE_URL	https://<server_name>	Advertised to clients.
global.well_known.identity_server_base_url	WARP_WELL_KNOWN_IDENTITY_SERVER_BASE_URL	empty	Omitted from the document when empty.
global.well_known.server_address	WARP_WELL_KNOWN_SERVER_ADDRESS	empty	host:port for other homeservers. Empty = no delegation, other servers fall back to SRV/A.
listen.address	WARP_LISTEN_ADDRESS	:8008
listen.read_header_timeout	WARP_READ_HEADER_TIMEOUT	10s
listen.read_timeout	WARP_READ_TIMEOUT	60s
listen.write_timeout	WARP_WRITE_TIMEOUT	120s	Must stay above sync.long_poll_timeout, or a blocked /sync is cut off before it can answer.
listen.idle_timeout	WARP_IDLE_TIMEOUT	120s
listen.max_header_bytes	WARP_MAX_HEADER_BYTES	1048576
listen.shutdown_timeout	WARP_SHUTDOWN_TIMEOUT	30s	Grace period for in-flight requests.
database.driver	WARP_DB_DRIVER	sqlite	sqlite, postgres, pocketbase (not implemented).
database.connection_string	WARP_DB_CONNECTION_STRING	SQLite file in the working directory
database.max_open_conns	WARP_DB_MAX_OPEN_CONNS	10	Ignored by SQLite: writes are serialised onto one connection.
database.max_idle_conns	WARP_DB_MAX_IDLE_CONNS	5
database.conn_max_lifetime	WARP_DB_CONN_MAX_LIFETIME	1h
database.auto_migrate	WARP_DB_AUTO_MIGRATE	true	false makes startup fail while migrations are pending.
client_api.cors_allowed_origins	WARP_CORS_ALLOWED_ORIGINS	["*"]	The spec expects any origin.
client_api.trust_x_forwarded_for	WARP_TRUST_X_FORWARDED_FOR	false	Only behind a proxy that overwrites the header; the rate limiter keys on the result.
client_api.access_token_lifetime	WARP_ACCESS_TOKEN_LIFETIME	0s	0 = never expire. With a lifetime, clients may ask for a refresh token at login.
client_api.refresh_token_lifetime	WARP_REFRESH_TOKEN_LIFETIME	0s	0 = never expire.
client_api.rate_limit.enabled	WARP_RATE_LIMIT_ENABLED	true
client_api.rate_limit.default.burst / .interval	—	30 / 100ms	Every rate-limited endpoint without its own bucket.
client_api.rate_limit.login.burst / .interval	—	10 / 1s	/login and /refresh.
client_api.rate_limit.register.burst / .interval	—	5 / 2s	/register and /register/available.
client_api.rate_limit.room_create.burst / .interval	—	10 / 1s	/createRoom, which writes a dozen events per call.
client_api.rate_limit.join.burst / .interval	—	10 / 1s	The two join endpoints.
client_api.rate_limit.sync.burst / .interval	—	100 / 20ms	/sync and the writes behind it: typing, receipts, to-device, presence.
sync.presence	WARP_SYNC_PRESENCE	false	Off by default; see below.
sync.typing_timeout	WARP_SYNC_TYPING_TIMEOUT	30s	How long a typing notification lasts, and the cap on what a client may ask for.
sync.long_poll_timeout	WARP_SYNC_LONG_POLL_TIMEOUT	30s	The cap on a /sync ?timeout=.
federation.enabled	WARP_FEDERATION_ENABLED	false
federation.allowlist	WARP_FEDERATION_ALLOWLIST	[]	Non-empty = federate only with these.
federation.denylist	WARP_FEDERATION_DENYLIST	[]	Always wins over the allowlist.
federation.allow_runtime_toggle	WARP_FEDERATION_ALLOW_RUNTIME_TOGGLE	true	See below.
registration.enabled	WARP_REGISTRATION_ENABLED	false
registration.allow_runtime_toggle	WARP_REGISTRATION_ALLOW_RUNTIME_TOGGLE	true
registration.tokens	WARP_REGISTRATION_TOKENS	[]	Non-empty = sign-up also needs one of these, as the m.login.registration_token stage.
logging.level	WARP_LOG_LEVEL	info	debug, info, warn, error.
logging.format	WARP_LOG_FORMAT	text	text or json.
logging.add_source	WARP_LOG_ADD_SOURCE	false	File and line in every record.
metrics.enabled	WARP_METRICS_ENABLED	true
metrics.path	WARP_METRICS_PATH	/metrics	Served on the same listener.

The rate limit buckets share one Go type, so per-bucket environment variables would all collide on the same name; they are YAML only. WARP_RATE_LIMIT_ENABLED=false turns the whole limiter off, which is what a test harness wants.

Rate limiting

Each bucket allows burst requests back to back and returns one slot every interval, keyed per client address. Over the limit is 429 M_LIMIT_EXCEEDED with a retry_after_ms the client is expected to honour.

Buckets are per endpoint class, so a client hammering /login cannot spend the budget of /profile. The key is the client address and not the user, because the limiter runs before the access token is resolved — a limiter that had to query the database to find its own key would be a denial of service of its own. Behind a reverse proxy, set client_api.trust_x_forwarded_for: true, or every client shares one bucket.

The admin API under /_warp/admin/v1 is not rate limited: it needs an admin token, and bulk operations from the panel are exactly the traffic a limiter would get in the way of.

Presence

sync.presence is off by default. Presence — who is online, and the status message they set — is the noisiest thing in Matrix: every user's state change is published to everybody they share a room with, which over federation is quadratic in the worst case. Synapse deployments routinely turn it off for that reason, and a private homeserver with a dozen users gains little from it.

With it off:

• GET and PUT /presence/{userId}/status answer 403 M_FORBIDDEN. They are deliberately not unregistered: a client that gets a 404 from /presence concludes the server is too old to have it and stops asking, where a refusal says this one has it switched off.
• The presence section of a /sync response is empty.
• ?set_presence= on /sync is ignored rather than refused — it rides on every sync a client sends, and failing them all would make the server unusable.

It is a boot-time setting, not a runtime one: turning it on starts publishing a stream that nothing was tracking before, and a server that could do that mid-flight would owe every connected client a resync.

Long polling

/sync holds a request open until something happens or the timeout expires, so listen.write_timeout has to stay above sync.long_poll_timeout — otherwise the listener cuts off a blocked sync before it can answer, and the client sees a dropped connection instead of an empty response.

Raising sync.long_poll_timeout does not make a client hear about messages sooner: a blocked sync is woken the moment anything concerning it is written. All the timeout decides is how often an idle client re-establishes its request.

Settings that change at runtime

federation.enabled and registration.enabled are also stored in the server_settings database table, which is what the admin API writes to.

• With allow_runtime_toggle: true (the default) the stored value wins over the config file at boot, and the admin API may change it. The change takes effect on the next request; no restart.
• With allow_runtime_toggle: false the config file is authoritative and the admin API refuses to change the setting. Any previously stored value is kept but ignored, so re-enabling the toggle restores the administrator's last choice.

Everything else is read once at startup.

What federation off actually means

While federation.enabled is false:

• /.well-known/matrix/server answers 404 M_UNRECOGNIZED, and so will /_matrix/federation/* and /_matrix/key/* once they exist.
• Nothing outbound runs — in Phase 0 there is nothing outbound yet; from Phase 5 the transaction queue, key fetcher and remote media fetch stay stopped.
• Client-Server endpoints that would need a remote server answer M_FORBIDDEN with a message saying federation is disabled.
• Events are still signed with the server key, and room and event IDs are unchanged. A room created while federation is off federates normally once it is switched on.