Configuration

Simmetric Chat has two configuration levels: environment variables validated with Zod at process startup, and a runtime config layer stored in the database that admins can edit from the UI without restarting any service.

1. Environment variables (process startup) - validated with Zod in packages/<pkg>/src/config/env.ts; process.exit(1) when invalid.
2. Runtime config (DB `SystemConfig`) - editable from the admin UI without a restart.

Resolution:

• ALWAYS_READONLY keys (JWT_SECRET, DATABASE_URL, SERVER_PORT, COLLECTOR_PORT, SERVER_URL, COLLECTOR_URL): ENV > Default, not editable from the UI.
• All the others: DB > ENV > Default, editable via PUT /api/system/settings.

The three packages read .env via path.resolve(__dirname, "../../.env") (independent of the cwd). The reference document is .env.example at the repo root.

Environment variables - server

Schema: packages/server/src/config/env.ts. Defaults shown; REQ = required.

Core / infra

Bootstrap admin (seed)

LLM

Agent watchdog (loop/stall prevention)

Embedding / Vector DB / OCR / Synthesis

License, push, email, collector

Variables in .env.example but managed as DB settings (not in envSchema): OCR_ENABLED, OCR_PRECHECK_CHARS, STORAGE_PATH (collector), RESET_PASSWORD_STRATEGY.

Environment variables - collector

Schema: packages/collector/src/config/env.ts.

Environment variables - widget

Schema: packages/widget/src/config/env.ts.

Frontend: no VITE_* variables and no .env file. The frontend reads branding/config

from the server (GET /api/system/settings, GET /api/license/info).

Feature flags & license

Defined in packages/shared/src/constants/license.ts (FEATURE_FLAGS + defaults). Verified in packages/server/src/services/licenseService.ts.

How to move from Community to Enterprise

1. Set LICENSE_KEY (a vendor-issued RS256 JWT; the public key is embedded in the server source - packages/server/src/services/license-public-key.ts) - or, without touching .env and without a restart, paste it in Settings → Security → License or PUT /api/license/instance (F-LIC-1).
2. The payload is validated against licensePayloadSchema (tier, iss, sub, iat, exp, features); probe-first verification: a rejected key is never stored.
3. tier=enterprise → starts from ENTERPRISE_FEATURE_DEFAULTS + the JWT features overrides.
4. Source precedence (identical at boot and runtime): the INSTANCE_LICENSE slot (AES-256-GCM ciphertext) → verified plugin row → ENV LICENSE_KEY → Community.
5. Expired/invalid → Community fallback with a warning.

Graceful degradation: getLicenseInfo() checks expiry at runtime; if Enterprise expires while in use, it degrades to Community without a restart. requireFeature(flag) → HTTP 402 when disabled; requireFeatureLimit(flag, model) → 402 when count >= limit (Enterprise = Infinity).

Always-on commodity flags: since the EPA-02 removal the 8 commodity flags no longer exist in FEATURE_FLAGS - webhooks, push_notifications, web search, memory, lead_export, widget_analytics, auto_title, synthesis_rate_limit are always on in Community (commodity routes run without gating). priority_support is not a flag: it is a commercial/SLA contract (EPA-08). 14 flags remain, including widget_credits_editing (widget credits editing, Community false / Enterprise true), custom_agents as a numeric limit (Community 3, Enterprise Infinity), max_skills (Community 3, Enterprise Infinity, F-SKILL-1), max_users (Community 5, Enterprise Infinity - enforced at user creation) and connectors_enabled (Community false, F-CONN-1).

Flag table (14)

Runtime config (DB SystemConfig)

Editable via GET/PUT /api/system/settings (bulk) and PUT /api/system/chat-retention (specific, audited). Defaults live in CONFIG_DEFAULTS (packages/shared/src/constants/permissions.ts).

Key groups: LLM (LLM_PROVIDER, LLM_MODEL, LLM_TEMPERATURE, ...), Embedding/Vector, Server ports/URLs, Auth (SESSION_EXPIRY), Branding (BRANDING_APP_NAME, BRANDING_PRIMARY_COLOR, BRANDING_APP_SUBTITLE, BRANDING_APP_ICON_URL - gated by white_label), Feature (DISABLE_TELEMETRY, ALLOW_REGISTRATION, DLP_ENABLED), OCR (OCR_DEFAULT_MODEL, OCR_DEFAULT_MODE, OCR_DEFAULT_CUSTOM_INSTRUCTIONS, OCR_ENABLED, OCR_PRECHECK_CHARS), Synthesis (SYNTHESIS_LLM_PROVIDER_ID, SYNTHESIS_LLM_MODEL), Retention (upload_draft_retention_days, ALLOW_NON_ADMIN_UPLOAD, chat_message_retention_days).

PUT /api/system/settings always returns 200 with { updated: [...], rejected: [...] } (readonly keys are rejected while the others are applied).

Chat message retention (reaper)

Service: packages/server/src/services/chatMessageReaperJob.ts. DB knob: chat_message_retention_days.

• Pass 1 (soft-delete): tombstones messages of ACTIVE chats beyond retentionDays. No-op when the value is null/""/<=0.
• Pass 2 (hard-purge): deletes tombstoned rows beyond a 7-day grace period (hardcoded). Always runs, regardless of the retention config (anti-PII leak).
• Cadence: 24h setInterval, first run at 03:00 local time. isRunning mutex.
• Only PUT /api/system/chat-retention (audited, confirmDataLoss: true, retentionDays: integer|null, min 1); the bulk settings endpoint rejects this key.

Backup retention

Per-job (the retentionDays field on BackupJob, default 30). backupRetentionService.ts cleans logs/files beyond cutoffDate. It is not global.

Encryption key rotation

packages/server/src/services/encryptionService.ts (AES-256-GCM, 32-byte key, 16-byte IV, salt simmetric-chat-encryption-salt).

• Current key: ENCRYPTION_KEY (base64 32 bytes) when set; else scryptSync(JWT_SECRET, salt, 32).
• LEGACY_PREVIOUS_ENCRYPTION_KEYS (CSV base64 32-byte) → decrypt key chain [current, ...previous, scryptLegacy?].
• encrypt() uses chain[0]. There is no automatic re-encryption job: the procedure is a manual decrypt-with-old → re-encrypt-with-new.

v0.28.1 Provenance

Operational reference - Simmetric Chat v0.28.1 (docs updated 2026-10-02, census SHA `aca5b8ff`).

Cross-link

• Settings endpoints: 04 - API Reference
• Internal features: 05 - Feature Guide
• Deploy env vars: 09 - Deployment