Settings — System

This page collects the settings that affect Sublarr’s runtime behaviour rather than its features: authentication, backups, log rotation, theme. Most users set these once during install and revisit only when the install moves to a new host or a new version ships breaking changes.

Authentication

Setting	Default	Values	Effect
Inbound API key	empty	string	Required X-Api-Key header on every API call. Empty = no auth. See API Keys for the dedicated page.
Session timeout (min)	60	5–1440	Inactive UI sessions log out after this.
Max login attempts	5	1–20	Failed attempts before lockout.
Lockout duration (min)	15	1–1440	Lockout window after threshold reached.
Allowed IP ranges	empty	CIDR list	When set, restricts UI access to these networks. Empty = any IP.

Danger

Disabling authentication removes the only barrier between your Sublarr instance and the network. Only do this on a fully trusted LAN, never with SUBLARR_CORS_ORIGINS=*, never exposed to the internet.

Backups

Setting	Default	Values	Effect
Auto-backup enabled	on	toggle	Run backup on the configured schedule.
Backup interval (h)	24	1–168	Hours between automatic backups.
Backup on startup	on	toggle	Run a backup once when the container starts.
Notify on failure	on	toggle	Fire backup_failed notification event.
Backup directory	/config/backups	absolute path	Where backup files land.
Retention (count)	7	0–100	Keep N most-recent; older backups deleted. 0 keeps all.

A backup includes:

Included	Notes
Database	SQLite or PostgreSQL dump.
Config entries	The DB rows that hold UI settings.
API keys (encrypted)	Wrapped with the install’s secret.
Glossary	Both global and per-series.
Translation memory	Optionally — toggle below.

Excluded
Subtitle files on disk (those live with your media library).
Whisper / metadata caches.
Plugin files (re-install after restore).

Setting	Default	Effect
Include translation memory	off	When on, TM rows are included in the backup (can grow the file by 100 MB+).

Encryption at rest

Every credential Sublarr stores — provider API keys, *arr keys, media-server tokens, LLM keys, and the multi-key provider pools — is encrypted before it reaches the database. Encryption is symmetric Fernet (AES-128-CBC with an HMAC-SHA256 authentication tag) and happens transparently: you save a key in the UI, Sublarr writes ciphertext to the database row, and reads decrypt it back on the way out. You never handle any of this yourself.

The master key is generated once, on first start, and lives in a single file outside the database — <config>/.encryption_key, mode 0600. Keeping it out of the database is the point: a stolen database dump on its own is useless, because the ciphertext can’t be decrypted without the key file. The config directory is the one Sublarr already uses (SUBLARR_CONFIG_DIR, default /config) — there is no separate key or passphrase to configure.

Ciphertext is tagged with an enc:v1: prefix, so encrypted and not-yet-encrypted values coexist safely and decryption is a no-op on plaintext. Which fields get encrypted is decided by name: keys ending in _api_key, _password, _token, or _secret (plus the inbound api_key) are treated as secrets. The bcrypt UI password hash and the session secret are deliberately left as-is — one is already a one-way hash, the other must stay readable to bootstrap the app.

Caution

Keep <config>/.encryption_key safe, and back it up together with your database. Without it, encrypted credentials cannot be recovered and you would have to re-enter every key. The full ZIP backup bundles the key file (the API keys (encrypted) row above) for exactly this reason.

Restore

The Restore button accepts a backup file produced by the same major version of Sublarr (or one minor version older — auto-migration runs on import). The restore happens in three stages:

1. Validate the file is a Sublarr backup with the expected schema.
2. Snapshot the current database to <config>/backups/.pre-restore.<timestamp> so the restore is reversible.
3. Replace the database; restart in-process.

Caution

Restore replaces every UI setting and credential with the backup’s values. The pre-restore snapshot is your safety net — verify the restore worked end-to-end before deleting it.

Logs

The on-disk log file is what gets shipped to log aggregators. The viewer in Logs is independent and shows the live tail.

Setting	Default	Values	Effect
Log level	INFO	DEBUG / INFO / WARNING / ERROR	Minimum severity written to the file. Tighter level = smaller log file.
Log file	/config/sublarr.log	path	File path. Match SUBLARR_LOG_FILE (env-loaded at startup, then UI takes over).
Log format	text	text / json	json for log aggregators (Loki, ELK); text for grep-by-eyeball.
Max size (MB)	50	1–1000	File rotates when this size is reached.
Retention (count)	10	1–100	Number of rotated archives kept.

Theme

Setting	Default	Values	Effect
Theme	dark	dark / light / system	UI theme. system follows OS preference.
Accent color	#1DB8D4 (Sublarr teal)	hex	Primary accent. Affects buttons, links, focus rings.

Version info

The footer shows runtime details that you’ll want when filing bugs:

Field	Reads
Version	The backend/VERSION shipped in the container.
Build SHA	Git commit the container was built from.
Build date	When the image was built.
Python	Interpreter version.
Database	sqlite:///<path> or postgresql://....
Redis	Connected URL or “not configured”.
Platform	linux/amd64, linux/arm64.

Subtitle repair

Restores subtitles damaged by the pre-1.6.6 HI-removal bug — scan is free, repairs are proven before anything is written, and multi-day runs resume themselves when the provider quota resets. See Subtitle Repair for the dedicated page.

Diagnostics jump-off

The Diagnostics page surfaces every health check Sublarr runs internally — see Diagnostics for the dedicated page. The button on this page jumps directly there.

Update checker

Setting	Default	Effect
Check for updates	on	Every 24h, check the GitHub releases for a newer tag. Surface in the dashboard banner if found.
Auto-update	off	(Reserved — currently a no-op; Sublarr doesn’t self-upgrade. The flag is plumbed for a future version.)