Setup

Configuration

Copy config.example.yaml to config.yaml next to the binary (or at /etc/ferrum/config.yaml on a systemd install) and adjust what you need, or skip the file entirely and set the equivalent FERRUM_* environment variables, which always take precedence over the file.

This file only covers what has to exist before Ferrum can start. Notifications, SSO details beyond the first-boot seed, security policy, system settings, AI providers, and the REST API/MCP switches are all configured from the admin Settings UI once Ferrum is running.

Server

Key	Env var	Default	What it does
`server.addr`	`FERRUM_ADDR`	`:8080`	Listen address and port.
`server.secureCookies`	`FERRUM_SECURE_COOKIES`	`false`	Mark the session cookie `Secure`. Turn on whenever Ferrum is served over TLS, directly or behind a proxy.
`server.behindProxy`	`FERRUM_BEHIND_PROXY`	`false`	Read client IPs from `X-Forwarded-For` and mark the session cookie `Secure` for requests the proxy reports as HTTPS.
`server.tlsCertFile` / `tlsKeyFile`	`FERRUM_TLS_CERT_FILE` / `FERRUM_TLS_KEY_FILE`	`""`	Set both to have Ferrum terminate TLS itself. Leave blank for plain HTTP behind a reverse proxy, which is the common case.

Database

Key	Env var	Default	What it does
`db.driver`	`FERRUM_DB_DRIVER`	`sqlite`	`sqlite` or `postgres`.
`db.path`	`FERRUM_DB_PATH`	`./data/ferrum.db`	SQLite file path, used when the driver is `sqlite`.
`db.dsn`	`FERRUM_DB_DSN`	none	e.g. `postgres://user:pass@localhost:5432/ferrum?sslmode=disable`; required when the driver is `postgres`.

SQLite is the right default for a single-node install. Move to Postgres when you're running more than one Ferrum instance against the same database, or you already have Postgres in your stack and would rather manage backups there.

Encryption secret

secret (FERRUM_SECRET) pins the key used to encrypt stored connection credentials. Leave it blank and Ferrum generates a random one and persists it next to the SQLite file on first run, which is fine for a single-node SQLite install. Set it explicitly, at least 16 characters, whenever multiple instances share one database (Postgres deployments especially), so every instance can decrypt the same stored credentials.

Single sign-on (OIDC)

Optional SSO through any standard OpenID Connect provider (Keycloak, Authentik, Entra ID, Okta, and similar). Local username/password login keeps working regardless; this just adds a "Continue with…" button next to it.

oidc:
  enabled: false            # FERRUM_OIDC_ENABLED
  displayName: Keycloak     # FERRUM_OIDC_DISPLAY_NAME, shown on the login button
  issuerUrl: https://keycloak.example.com/realms/myrealm
  clientId: ferrum
  clientSecret: ""          # from a confidential client in your IdP
  redirectUrl: https://ferrum.example.com/api/v1/auth/oidc/callback

The first SSO login for a provider-verified email that already has a matching local account links the two automatically; otherwise a new, non-admin account is created. Unverified IdP emails never link into existing accounts, and that first SSO user still needs promoting to admin from the Users page.

This block (and its env equivalents) is a first-boot seed only: it's copied into the database once, the first time Ferrum starts against a fresh database. Every boot after that, and any save from Settings > SSO, reads and writes the database exclusively; editing the file later has no effect. It exists purely to pre-seed SSO for scripted, first-time deployments.

Built-in local AI provider (Needle 2)

The AI assistant and the MCP tool-calling loop work with any OpenAI-chat-completions-compatible provider (OpenAI, Ollama, LM Studio, LocalAI, OpenRouter) configured from Settings > AI Providers. There's also a zero-config option with no API key and no network access at inference time, backed by Needle 2, a 45M-parameter tool-calling model distributed as a self-contained CLI binary.

On Windows, Linux, and macOS (amd64 or arm64), Ferrum bundles Needle 2's binary directly into itself and registers it automatically as the default assistant the first time it starts with no provider configured: nothing to download, nothing to set. On any other platform there's no bundled binary, and Ferrum never fetches executable content on its own; to use Needle there:

Download the needle CLI binary for your platform from the Needle 2 files.
Point Ferrum at it with needleBinPath in config.yaml, or FERRUM_NEEDLE_BIN=/path/to/needle, which also overrides the bundled binary if you'd rather run a different build.

Ferrum starts it as a local, 127.0.0.1-only subprocess the first time it's used and stops it on shutdown. If nothing is bundled and FERRUM_NEEDLE_BIN isn't set, this provider is simply unavailable; every other provider is unaffected.

On small ARM boards (Raspberry Pi and similar): Needle's one-time tool-retrieval pass over Ferrum's ~60-tool catalog briefly spikes memory and CPU, and on very little RAM the kernel's OOM-killer can take the subprocess out (needle process exited: signal: killed). Set FERRUM_NEEDLE_MAX_TOOLS=<n> (e.g. 10) to trim the catalog and lighten that pass. If it still fails, the board likely can't run even this small a model reliably; point at a hosted or remote OpenAI-compatible provider instead.

Back← Installation NextFeatures & workflows →