Runtime System Settings

Starting from v1.8.0, several operational settings that were previously only configurable via environment variables can now be tuned at runtime through the admin API — without restarting any services.

---

How It Works

On first boot, environment variables are read and written to the system_settings Postgres table as seed values. After that:

• The database is authoritative — env-var changes after first boot have no effect.
• Settings changes made via the API take effect immediately across all running instances.
• A full reset to env-var defaults is available via a single API call (audited).

Token lifetime settings (access_token_seconds, refresh_token_seconds, and Enterprise per-role overrides) are managed through the related auth_settings table via PATCH /api/admin/auth/settings.

---

Viewing Current Settings

curl -s http://localhost:8000/api/admin/system/settings \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>"

Returns all current effective settings as a JSON object.

---

Updating Settings

Send a PATCH with only the fields you want to change — all other settings remain unchanged.

curl -s -X PATCH http://localhost:8000/api/admin/system/settings \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "log_level": "DEBUG",
    "conversation_max_turns": 50,
    "rag_query_rewrite_enabled": true
  }'

---

Resetting to Environment Defaults

Re-seeds all settings from the current environment variables (audited):

curl -s -X POST http://localhost:8000/api/admin/system/settings/reset \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>"

caution

This operation overwrites all current settings with the values from environment variables. Any changes made via the API since last reset will be lost.

---

Available Settings

Logging

Setting	Env var seed	Default	Description
log_level	LOG_LEVEL	INFO	Logging verbosity: DEBUG, INFO, WARNING, ERROR
log_anonymise	RAG_LOG_ANONYMISE	true	Anonymise user identifiers in log output
log_redact_queries	RAG_LOG_REDACT_QUERIES	true	Redact query text from log output
log_token_usage	RAG_LOG_TOKEN_USAGE	false	Log per-request token budget usage
api_log_enabled	(new in v1.8.0)	true	Enable/disable API request logging globally

Conversations

Setting	Env var seed	Default	Description
conversation_max_age_days	RAG_CONVERSATION_MAX_AGE_DAYS	90	Automatically purge conversations older than this many days
conversation_max_turns	RAG_CONVERSATION_MAX_TURNS	100	Maximum turns retained per conversation

Audit

Setting	Env var seed	Default	Description
audit_retention_days	RAG_AUDIT_RETENTION_DAYS	365	Audit log retention period in days (Enterprise only)

Query Pipeline

Setting	Env var seed	Default	Description
rag_query_rewrite_enabled	RAG_QUERY_REWRITE_ENABLED	false	Enable multi-turn query rewriting
rag_query_rewrite_max_turns	RAG_QUERY_REWRITE_MAX_TURNS	3	Number of prior turns used for query rewriting context
rag_min_chunk_length	RAG_MIN_CHUNK_LENGTH	50	Minimum character length for indexed chunks

Inference

Setting	Env var seed	Default	Description
inference_timeout_seconds	INFERENCE_TIMEOUT_SECONDS	120	Timeout for inference requests in seconds

---

Auth Settings

JWT token lifetimes are managed via a separate endpoint:

# View auth settings
curl -s http://localhost:8000/api/admin/auth/settings \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>"

# Update token lifetimes
curl -s -X PATCH http://localhost:8000/api/admin/auth/settings \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "access_token_seconds": 1800,
    "refresh_token_seconds": 86400
  }'

Enterprise plans also support per-role overrides: access_token_seconds_admin and refresh_token_seconds_admin.

---

Migration Note (Upgrading from v1.7.x)

When upgrading to v1.8.0, your existing env-var values are automatically seeded into the system_settings table on the first migration run. No manual action is required. After the upgrade, changes to the relevant env vars will no longer take effect at runtime — use the API instead.

See Environment Variables for the full list of first-boot seed variables.