Configuration

Lific reads its settings from one TOML file, lific.toml. lific init writes one for you. Every section and key is optional, and anything you leave out takes the default shown on this page.

Some settings live in the database instead, because administrators change them while the server runs: the instance name, signup, session length, the login message, browser auto-login and membership enforcement. Change those in the web UI's instance settings or with lific instance set.

File discovery

Lific uses the first of these files that exists:

1. The path given with --config <PATH>. When you pass it, Lific looks nowhere else, and a path that does not exist is an error.
2. ./lific.toml in the current directory.
3. The user configuration directory.
4. The system configuration directory.

A file that exists but cannot be read or parsed stops Lific with an error naming the file. It does not fall through to the next location, because silently using another file, or the defaults, would quietly undo settings such as a loopback bind or closed signup. Unknown keys are errors too, so a typo like allow_signupp fails instead of being ignored.

On Linux and macOS, Lific refuses a configuration file that is a symbolic link or not a regular file, and when the file can be read by other users it changes the permissions to owner-only. The file can hold secrets such as mcp_path_token.

If no file exists anywhere, Lific uses the built-in defaults. Defaults never create a database: ordinary commands refuse a missing database and name the path they expected. Run lific init, restore a backup, or use the container bootstrap. lific doctor reports a missing or unreadable configuration and skips the checks that depend on it.

A relative database.path resolves against the directory holding the configuration file. A relative backup directory then resolves against the database's directory.

Command-line overrides

No environment variable overrides a lific.toml key. The variables Lific does read are listed under Environment variables.

Default configuration

This is the built-in configuration. The optional [server] and [backup] keys that default to unset are left out.

[server]
host = "0.0.0.0"
port = 3456
cors_origins = []
trusted_proxies = []

[database]
path = "lific.db"

[backup]
enabled = true
dir = "backups"
interval_minutes = 60
retain = 24

[log]
level = "info"

[auth]
allow_signup = true
required = true

[retention]
trash_days = 30

[server]

public_url is the OAuth issuer that MCP clients discover, the base of the links in CLI and MCP output, and the address lific connect writes into remote tool configurations. Its host name is added to the hosts the MCP endpoint accepts, which a reverse proxy needs. Its scheme also decides the session cookie: an https:// URL, or no URL at all, gives a cookie marked Secure, and only an explicit http:// URL turns that off, because browsers discard Secure cookies over plain HTTP.

trusted_proxies names proxy hops, not trusted clients. Lific ignores forwarding headers unless the connection itself comes from an address on this list. From a trusted proxy, Lific reads X-Forwarded-For from right to left, skips addresses on the list, and takes the first one that is not as the client. It uses X-Real-IP only when X-Forwarded-For is absent. A malformed chain, or one made entirely of trusted addresses, falls back to the proxy's own address, and IPv4-mapped IPv6 addresses count as IPv4. List every proxy layer you run, and do not add client networks just because they appear in a header. The client address matters because rate limits and the audit log are keyed on it.

A trusted proxy can instead send the client address in X-Lific-Client-IP, together with X-Lific-Proxy-Secret. Lific accepts that pair only from an address in trusted_proxies, and only when the secret equals the LIFIC_TRUSTED_PROXY_SECRET environment variable of the server process. If a trusted proxy sends either header without a valid pair, including when the variable is unset, requests to rate-limited routes are answered with 503 rather than counted against a bucket every visitor shares. Set the variable before the proxy starts sending the headers, use a long random value, and have the proxy strip any copies of both headers that arrive from clients. Self-hosting shows complete proxy setups.

mcp_path_token bypasses API keys and OAuth: anyone who knows the URL can use every MCP tool as mcp_path_user. It exists for MCP clients whose OAuth support is broken. Use a long random token and serve it only over HTTPS.

[database]

Attachments are stored in a directory named attachments next to the database file.

--db on the command line resolves a relative path against the current directory instead. lific init --db <PATH> writes the absolute path into a new configuration file, so later commands find the same database from anywhere.

[backup]

Automatic backups run from any process that opens the database directly: lific start, the stdio MCP server lific mcp, and local data commands such as lific issue list. A backup is due when the newest archive in dir is at least interval_minutes old. The server and stdio sessions check five seconds after startup and then on schedule; a data command checks after it finishes. When several processes share a database, only one of them writes each archive. Each one has the same format as lific dump.

interval_minutes = 0 and retain = 0 are not honored. A zero interval is not a schedule, and keeping zero archives would delete every backup seconds after writing it. Either value falls back to its default, and the server logs a warning saying so. To stop taking backups, set enabled = false.

[log]

The level applies to lific start and lific mcp. Setting the RUST_LOG environment variable replaces it entirely, using the tracing filter syntax. lific mcp always logs to standard error so the stdio session stays clean.

[retention]

The server empties the trash 30 seconds after it starts and then every six hours, so an item can outlive its window by up to six hours. The sweep runs only while lific start is serving, and a changed value takes effect at the next restart.

[auth]

With required = false, a request that carries no credential is treated as the operator, and the browser signs in as the first administrator automatically. An instance with no accounts shows signup instead, so there is an account to attribute changes to. A request with an invalid credential is still rejected.

Lific refuses to start with required = false, or with browser auto-login turned on, when server.host is not a loopback address, or when server.public_url is set and does not point at a loopback or private-network address. Public DNS names and URLs that cannot be parsed fail this check. Binding to loopback does not exempt a public URL.

secure_cookies is not a setting. Older configuration files may carry it under [auth]; remove it, because it is now an unknown key. Lific derives the value from public_url, as described under [server].

What lific init writes

On a fresh install, lific init asks how people should sign in and edits the configuration file in place, leaving every other setting alone.

Browser auto-login is stored in the database, not in lific.toml. Change it later with lific instance set --auto-login <BOOLEAN>. Turning it on checks the configuration by the same rule as startup; turning it off always works, so you can recover. Because login-free mode depends on the loopback bind, changing host or adding a public public_url makes such an instance refuse to start.

Environment variables

Lific reads no environment variable in place of a lific.toml key. These are the variables it does read.

Example public configuration

This configuration serves Lific behind a reverse proxy on the same machine, at a public HTTPS address, and allows browser API calls only from that address. Replace the example values with your own.

[server]
host = "127.0.0.1"
port = 3456
public_url = "https://lific.example.com"
cors_origins = ["https://lific.example.com"]
trusted_proxies = ["127.0.0.1"]

[database]
path = "/var/lib/lific/lific.db"

[backup]
enabled = true
dir = "/var/backups/lific"
interval_minutes = 60
retain = 24

[log]
level = "info"

[auth]
allow_signup = false
required = true