Configuration & env vars
The environment variables and runtime settings that configure Fosnie.
Fosnie reads boot settings from the environment (the .env for Docker, or the config file on
bare-metal) and keeps operational settings in the database, editable in the admin UI. See
Configuration for the split.
Deployment environment (.env)
The variables in the Docker .env. Secrets are regenerated by the installer – never reuse placeholders.
| Variable | Purpose | Default |
|---|---|---|
APP_VERSION | Released version to run; pin for reproducible upgrades | latest |
HOST_PORT | Host port the browser reaches Fosnie on | 8080 |
POSTGRES_PASSWORD | Database password | – (required) |
MESSAGE_ENCRYPTION_KEY | At-rest encryption key, base64 of 32 bytes; a set-but-invalid value fails boot | – (required) |
ML_SHARED_SECRET | Backend ↔ ML service shared secret | – (required) |
AUDIT_SIGNING_KEY | Ed25519 audit-signing seed (32-byte hex). Empty = hash-chain only (tamper-detection) | empty |
AUTH_MODE | local (built-in email/password) or keycloak (OIDC) | local |
PUBLIC_URL | External base URL; must be https for a non-loopback host | localhost |
LOCAL_STACK | Set by --local; seeds local model providers on boot | empty |
PAI__DATABASE_URL | DSN for a managed Postgres (drop the bundled postgres service). Session/direct pooler only | – |
Generate secrets with openssl rand -base64 32 (encryption key) or openssl rand -hex 32.
Key custody (BYOK)
The at-rest encryption key (DEK, AES-256-GCM) is protected according to PAI__BYOK__MODE:
| Mode | Edition | Meaning |
|---|---|---|
env-file | Core (default) | DEK is the configured MESSAGE_ENCRYPTION_KEY |
software-file | Enterprise | DEK wrapped under a key file you hold (PAI__BYOK__KEK_FILE) |
pkcs11 | Enterprise | DEK wrapped by a key in your HSM (PAI__BYOK__PKCS11_*) |
Under the Enterprise modes, destroying your key makes all ciphertext permanently unreadable (a
kill-switch), and the key CLI (init, rotate-kek, rotate-dek, status) manages custody. Back up
your key independently – losing it is unrecoverable.
Runtime settings (admin UI)
These live in the database and change with no restart, under Admin → Config (or Settings):
auth.require_mfa– force two-step verification org-wide.features.voice,features.voice_live,features.groundedness,features.workflows– enable capabilities (all off by default).integration.web_search.enabled,integration.mcp.enabled– enable outbound connectors and the MCP host (off by default).- Retrieval defaults (chunk size, overlap, Top-K), branding, retention, tool timeouts, and the login welcome message.
Every configuration change is written to the audit log, and there is no bulk "import config" – each setting is edited explicitly.