ClairePlatform mode
Production configuration for direct and Matrix-backed platform adapters.
PLATFORM_MODE selects how Claire reaches messaging networks. Getting it wrong is quiet rather than loud, which is why the server now refuses to guess in production.
| Mode | What it does | Intended for |
|---|---|---|
matrix | Synapse plus mautrix bridges. All networks flow through Matrix rooms. | Production |
direct | Native per-platform adapters (whatsapp-web.js and friends). | Local development |
MOCK_BRIDGE=true | Scripted fixtures; no infrastructure at all. | Tests and demos |
The bug this guards against#
PLATFORM_MODE defaults to direct. A production deploy that forgets to set it boots in direct mode and silently diverges from the documented architecture — everything looks healthy while the system is not the system you designed. Config validation now fails fast in production when the variable is unset:
PLATFORM_MODE must be set explicitly in production (matrix|direct).
Refusing to default to direct mode.Required configuration#
| Mode | Required environment |
|---|---|
matrix | MATRIX_HOMESERVER_URL, MATRIX_SERVER_NAME, and in production MATRIX_ADMIN_TOKEN. MATRIX_BOT_USER_ID is recommended. |
direct | Per-platform credentials, as applicable. |
mock | MOCK_BRIDGE=true, which overrides the above. |
PLATFORM_MODE=matrix with missing bridge configuration fails at startup and names the missing variables.
Observability#
GET /health reports the effective mode, and in Matrix mode also checks that Synapse is reachable.
{ "status": "ok", "platformMode": "matrix", "checks": { "matrix": { "status": "ok" } } }Direct mode in production additionally logs a prominent startup warning.
Recovery#
Set the mode and its Matrix variables on the deployment
Redeploy and confirm
The startup log should read
Initializing platform adapters in matrix mode, and/healthshould show"platformMode": "matrix"withmatrix: ok.If startup fails with a platform-mode error, set the variable it names