Configuration

Configuration

Ferrum is configured two ways, deliberately split:

• config.yaml / FERRUM_* environment variables — infrastructure-level settings needed to start the process at all (listen address, database, TLS, the encryption secret, an optional first-boot OIDC seed). Environment variables take precedence over the file.
• The admin Settings UI — everything else (notifications, SSO details after first boot, security policy, system settings, AI providers, API/MCP toggles). These live in the database, not in a file, so they survive redeploys and are the same across every instance sharing that database.

Copy config.example.yaml to config.yaml and adjust as needed — every field there is commented with its purpose and FERRUM_* equivalent. The sections below summarize it.

Server

Key	Env var	Default	Purpose
server.addr	FERRUM_ADDR	:8080	Listen address.
server.secureCookies	FERRUM_SECURE_COOKIES	false	Mark the session cookie Secure. Enable whenever Ferrum is served over TLS (directly or behind a reverse proxy).
server.behindProxy	FERRUM_BEHIND_PROXY	false	Read client IPs from X-Forwarded-For; also marks the session cookie Secure for requests the proxy reports as https.
server.tlsCertFile / server.tlsKeyFile	FERRUM_TLS_CERT_FILE / FERRUM_TLS_KEY_FILE	""	Set both to have Ferrum terminate TLS itself. Leave blank (the common case) when a reverse proxy terminates TLS in front of it.

Database

Key	Env var	Default	Purpose
db.driver	FERRUM_DB_DRIVER	sqlite	sqlite or postgres.
db.path	FERRUM_DB_PATH	./data/ferrum.db	SQLite file path (driver sqlite).
db.dsn	FERRUM_DB_DSN	—	postgres://user:pass@host:5432/ferrum?sslmode=disable (driver postgres).

PostgreSQL is the right choice once more than one Ferrum instance needs to share the same data (HA/multi-instance deployments); SQLite is fine for a single instance.

Secret

FERRUM_SECRET (no config.yaml key — env only) pins the encryption key used for stored connection credentials (API tokens/passwords) at rest. Set it explicitly (16+ characters) for Postgres/shared-database deployments so every instance shares one key. Left unset, a random secret is generated and persisted next to the SQLite file on first run — fine for a single-node SQLite install, but it means the database isn't portable to another host without that secret file.

Needle 2 (local LLM binary path)

needleBinPath / FERRUM_NEEDLE_BIN points at a Needle 2 CLI binary you've downloaded separately, to back the built-in local AI provider. On Windows/Linux/macOS (amd64/arm64) Ferrum already bundles this binary and this setting isn't needed — see AI Assistant and MCP.

OIDC (first-boot seed only)

The oidc: block (and its FERRUM_OIDC_* equivalents) is copied into the database once, the first time Ferrum ever starts against a fresh database — useful for scripted/automated first-time deployment. After that first boot, editing this file has no effect; manage SSO from Settings > SSO instead. The first SSO login for a provider-verified email that already has a local account links the two; otherwise a new (non-admin) account is created automatically, and needs promoting to admin from Users.

Everything else: the Settings UI

Once Ferrum is running, configure from Settings (admin only):

• Appearance — theme, look preset, accent color, density (per-user, follows the account across devices).
• Notifications — SMTP, alert email recipients, scheduled fleet health digests.
• Security — session policy, password requirements.
• AI Providers — OpenAI-compatible endpoints (OpenAI, Ollama, LM Studio, LocalAI, OpenRouter, the built-in Needle 2, ...) backing the AI Assistant.
• API & MCP — turns on the REST API and/or MCP endpoint (both off by default) and caps AI-assistant tool calls per message.
• Webhooks — outbound event delivery for real-time integrations.

See Features for what each of these areas actually does.