Configuration

After installation, configure Librariarr through the Settings page. Settings are organized into tabs.

Authentication

Librariarr supports three independent authentication methods. Configure each in Settings → Authentication. The login page only shows the methods that are actually usable (linked + toggle on); methods you haven’t set up stay hidden until you do.

Method	When the login page shows it
Plex OAuth	Plex account linked AND the Allow Plex Login toggle is on
Local username/password	Local credentials set AND the Enable Local Login toggle is on AND SSO is not active (SSO replaces local)
Single Sign-On (SSO)	OIDC / forward-auth configured, an identity is linked, and the Enable SSO Login toggle is on

Sessions are encrypted via iron-session and expire after 30 days. Every request — pages and API calls alike — checks the session against the admin record, so a cookie stops working the moment you change credentials, link/unlink SSO, log out (which revokes every session on every device, not just the one you pressed the button in), or rotate your SESSION_SECRET.

The cookie’s Secure attribute follows the request: it is set whenever the request arrived over HTTPS (directly, or through a proxy that sends X-Forwarded-Proto: https) and omitted on plain HTTP, so LAN installs keep working. Set COOKIE_SECURE explicitly to override in either direction.

Initial setup

The first user is created by whatever method you choose on the login screen:

Local-first: click Create Local Account on the login page. You’ll set a username (≥3 chars) and password (≥8 chars). The Allow Plex Login toggle starts off — Plex stays hidden until you link a Plex account.
Plex-first: click Sign in with Plex and complete the OAuth flow. The first Plex login becomes the admin. Enable Local Login starts off since no password is set yet.

Only one initial setup is allowed — once the first admin exists, the login page locks to the configured methods.

Plex OAuth

Click Sign in with Plex on the login page or Connect Plex Account in Settings → Authentication to link a Plex account.

Automatically discovers your Plex servers
The Plex token is stored in the database only — never in the session cookie
The display name + email sync from Plex on every Plex login
Linking from Settings needs a sign-in from the last 15 minutes; if it has been longer, Librariarr asks you to confirm it’s you (your password, or signing in again with Plex or SSO in a pop-up) and then links the account — no need to sign out

The Allow Plex Login toggle (visible once a Plex account is linked) controls whether the Sign in with Plex button appears on the login page. Turning it off keeps your Plex token attached for server discovery and library sync — it just won’t appear as a login option. Useful if you prefer SSO or local auth for sign-in but still need Plex linked for media-server features. Turning it back on needs a sign-in from the last 15 minutes, by another method: with it off, whoever holds the Plex account (say, a household that shares it) cannot sign in, and a stolen browser session must not be able to change that.

Linking Plex never turns the toggle on. If it is off when you link an account, Librariarr asks Allow signing in with Plex? right away; choose Enable Plex login or Keep it off.

Local Authentication

Username/password authentication. Configured in Settings → Authentication → Local Authentication.

Username: minimum 3 characters
Password: 8 characters to 72 bytes (bcrypt reads only the first 72 bytes, so a longer password is refused rather than silently shortened; accented letters and emoji count as more than one byte)
Stored as a bcrypt-cost-12 hash
Toggling Enable Local Login on without an existing password opens a credential prompt to create one
Changing an existing password needs the current one. Setting the first password on a Plex- or SSO-only account needs a sign-in from the last 15 minutes instead; if it has been longer, Librariarr asks you to confirm it’s you (signing in again with Plex or SSO in a pop-up) and then sets it
Hidden on the login page when SSO is active (SSO is intended to replace local credentials)
While local login is off, or SSO is active, the password is accepted for nothing — not to sign in, not to confirm it’s you, not to create an API key, not to change your credentials. Those ask for a sign-in from the last 15 minutes with Plex or SSO instead. Turning password sign-in back on (this toggle, or turning SSO off while local login is on) needs the same recent sign-in, so a stolen browser session cannot switch it on and then use an old password. SSO_DISABLE_OVERRIDE turns password sign-in on regardless, as the recovery path when SSO is down

The toggle is disabled and shows a warning when disabling local auth would leave you with no working sign-in method.

Single Sign-On (SSO)

OpenID Connect (OIDC) and forward-auth modes for integrating with self-hosted identity providers (Authentik, Authelia, Keycloak, Pocket ID, Zitadel, etc.) or upstream auth-proxies (Authelia, Authentik outpost, oauth2-proxy, etc.).

Configured in Settings → Authentication → Single Sign-On as a three-step wizard:

Configure your identity provider. Pick OIDC or Forward Auth, fill in the connection settings (issuer URL, client ID/secret, etc.), save.
Link your SSO identity. For OIDC, click Verify & Link via OIDC — this runs a real OAuth round-trip that validates the client ID + client secret + redirect URI end-to-end and auto-captures your sub claim. Bad credentials fail here, before SSO is activated. For forward-auth, paste the username your proxy injects.
Enable SSO login. Toggle the switch. The Sign in with SSO button appears on the login page; the local username/password form is hidden while SSO is active.

When SSO is enabled and your identity is linked, the Verify & Link via OIDC flow is the recommended way to validate any credential changes — it gives you confirmation the IdP still talks to Librariarr before you sign out.

See the SSO Authentication guide for provider-specific setup, reverse-proxy snippets, and recovery procedures.

Recovery from lockout

The Authentication settings have lockout guards that prevent you from disabling the only working method via the UI. If you still manage to get locked out (broken IdP, lost credentials, etc.):

What you’ve still got	Recovery path
A working method on the login page	Sign in with it
Plex linked but button hidden	Set `SSO_DISABLE_OVERRIDE=true` — the override re-surfaces the Plex button
Local credentials but local-auth disabled	Set `SSO_DISABLE_OVERRIDE=true` — the override re-surfaces the local form when a passwordHash is set
SSO only, IdP unreachable, with Plex or local fallback	Set `SSO_DISABLE_OVERRIDE=true`, sign in via Plex or local, then Revert to Previous to roll back the most recent SSO config change
SSO on but not offered after an upgrade — the login page says “SSO login is turned on but cannot be offered”	Do what the message says: set `FORWARD_AUTH_SECRET` and have the proxy send it, or move the OIDC issuer to `https://` (or set `OIDC_ALLOW_INSECURE_HTTP=true` for a lab), then restart. No other change is needed; the stored SSO configuration is untouched
No fallback credentials at all, just shell access	Copy `scripts/reset-auth.js` into the container with `docker cp` and run `node /tmp/reset-auth.js wipe-sso` (the script isn’t bundled into the image, by design)
No fallback, no shell, just DB access	Run the SQL recovery commands against PostgreSQL
None of the above	Restore from a backup file with a working state via the Restore from Backup button on the login page (shown when no users exist — wipe the DB to surface it)

Scheduling

Three independent schedules control automated tasks. Configure in Settings → Scheduling.

Timezone

Scheduled jobs run according to the server’s local time. In Docker, set the TZ environment variable to your timezone:

environment:
  - TZ=America/New_York

If TZ is not set, the container defaults to UTC. The current server timezone is displayed in the scheduling settings. On a daylight saving change, a schedule at a fixed time runs once: a time that happens twice runs at its first occurrence, and a time that is skipped runs as the clock jumps past it. Schedules that run every hour (an hour field of *, */1 or 0-23) run every real hour.

Daily Run Time

The Time of day for scheduled jobs setting (default 00:00) controls when preset schedules fire. All preset frequencies (Daily, Every 6h, Every 12h, Weekly) use this time as their anchor. For example, setting it to 02:00 with “Every 6 hours” runs at 2:00 AM, 8:00 AM, 2:00 PM, and 8:00 PM in the server’s timezone. Custom schedule expressions are not affected by this setting.

Sync Schedule

Controls how often Librariarr fetches metadata from your connected media servers.

Preset	Description
Every 6 hours	4 times daily, anchored to Daily Run Time
Every 12 hours	Twice daily, anchored to Daily Run Time
Daily (default)	Once daily at the Daily Run Time
Weekly	Weekly on Monday at the Daily Run Time
Manual only	Never runs on a schedule; sync from Settings → Servers instead
Custom (cron)	A custom schedule expression

A custom schedule is standard cron: five fields, or six with seconds. Wrap-around ranges such as 22-2 or FRI-MON are refused — list the values instead (22,23,0,1,2). The same rule applies to the lifecycle schedules.

When Real-Time Sync is enabled, library and watch-state changes on a server also trigger an incremental sync between scheduled runs, so this schedule mainly acts as a full reconciliation pass.

Lifecycle Detection Schedule

Controls when Librariarr evaluates lifecycle rules to find matching media. Default: every 6 hours.

Lifecycle Execution Schedule

Controls when matched lifecycle actions are actually executed (delete, unmonitor, tag, etc.). Default: every 6 hours.

All schedules show their next run time and last run time in the Settings UI. If a scheduled task is overdue, it will be flagged.

General Settings

Appearance

Accent Color: Choose from preset color themes applied to buttons, active items, and links
Badge & Chart Colors: Customize colors for resolution, dynamic range, and audio profile badges displayed throughout the UI
Reset to Defaults: Restore original color scheme

Display

Deduplicate stats across servers: When enabled, media appearing on multiple servers is counted only once in dashboard statistics
Real-time server sync: When enabled (default), Librariarr keeps a live WebSocket to each server for instant active-session updates and stream enforcement, plus near-real-time library and watch-history sync between scheduled runs. Turn it off to rely on scheduled polling only (useful if a reverse proxy blocks WebSocket upgrades). See Real-Time Sync

Library Display (Multi-Server)

When the same media exists on multiple connected servers:

Preferred Title Source: Choose which server’s title to display
Preferred Artwork Source: Choose which server’s poster/artwork to display

These settings only appear when you have more than one server connected.

Data Retention

Keep logs for: 1 to 365 days (default: 7). Logs older than today are automatically archived to compressed files (in /config/logs) and removed from the database; archive files older than the retention period are automatically pruned
Keep action history for: 0 to 365 days (default: 30). Completed and failed lifecycle actions that ran longer ago than this are deleted; 0 keeps them forever
Delete without asking, up to: an optional per-run limit on lifecycle deletions (default: no limit). A run that would delete more is held — nothing is deleted and the actions stay on the Pending page for you to execute

Backup Settings

Configure in Settings → General under the Backup & Restore section. See the Backup & Restore guide for full details.

Schedule: Manual only, Every 6 hours, Every 12 hours, Daily (default), or Weekly
Keep backups: Number of backups to keep (1–100, default: 7)
Encryption Password: Optional password-based encryption for all backups (minimum 8 characters)

AI Analysis

Configure in Settings → AI. Connect a provider to ask questions about your library in plain language (read-only). See the AI Analysis guide for full details.

Enable AI assistant: Show the AI Analysis page and allow it to answer questions (default off)
Provider: OpenAI-compatible (OpenAI, Ollama, LM Studio, OpenRouter, Groq, vLLM, …) or Anthropic (Claude)
API base URL: Optional override; leave blank for the provider default, or point at a local model (e.g. http://localhost:11434/v1)
API key: Optional (local models often need none); stored on your server and masked in responses
Model: The model identifier your provider expects (must support tool / function calling)

System

The Settings → System tab displays system information and release notes.

System Information

Application Version: Current version with update indicator when a newer release is available on GitHub
Database Migration: Latest applied Prisma migration
Database Size: Current PostgreSQL database size
Media Items / Libraries / Servers: Counts of synced content

Release Notes

Displays changelog entries fetched from GitHub Releases, including:

The current version’s release notes
Release notes for any newer versions, if an update is available (auto-expanded)
Each release can be expanded/collapsed to view its full changelog

What’s New

After an upgrade, Librariarr opens a What’s new dialog the first time you load any page, listing the features and fixes of every release since the version you last saw (fetched from GitHub Releases). Closing it records the running version, so it stays closed until the next upgrade. Breaking changes are listed first in each release, and a release with any opens expanded. A fresh install does not show it, restoring a backup does not reopen it for releases already seen, and if GitHub cannot be reached — or has not yet published the running version’s release — it waits for a later page load rather than opening without that version’s notes.

Image Cache

Shows the number of cached images and total size
Clear Image Cache button to reclaim disk space
Artwork is resized by your media server before it is sent (Plex’s photo transcoder, Jellyfin/Emby’s maxWidth), so a poster transfers tens of kilobytes rather than the full-resolution original, and it is cached on first view. If your server’s transcoder is unavailable, Librariarr falls back to fetching the original and resizing it locally.

Environment Variables

Container-level settings (database URL, session secret, timezone, file ownership, directories, proxy and SSO options) are set as environment variables rather than in the UI. See the full list in Installation → Environment Variables.

Next Steps

Connect a server to start syncing your media library