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	Raise before long-polling /sync lands in Phase 4.
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.
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 three 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.

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.