Environment variable reference

Every environment variable Loombre's settings registry recognizes, in two groups:

1. Bootstrap & lockout-boundary variables — no settings-screen equivalent at all. Some are needed before the database (and therefore any UI-stored setting) is even reachable; the rest are configuration an admin could otherwise lock themselves out with if it were editable at runtime.
2. Environment pins for admin-editable settings — these DO have a settings-screen equivalent (see the Admin Guide's settings reference); setting the variable overrides and locks whatever's in the database or the screen.

Assumption: variable names and defaults below are Loombre's own environment-variable convention as read by the server/worker processes directly — this is independent of how you set them (systemd Environment=, a Docker Compose env file, a shell export before running from source, etc.); see Install for the mechanism that applies to your install path.

Bootstrap & lockout-boundary variables

Database

DATABASE_URL

Database connection. PostgreSQL connection string. Read before any DB-backed configuration (including this registry's own DB half) can be resolved at all.

• Default when unset: postgres://loombre:loombre@localhost:5442/loombre

Network

PORT

HTTP port. TCP port the plain-HTTP listener binds. Ignored when tls.mode is not 'off' (TLS mode binds its own https port).

• Default when unset: 3001

LOOMBRE_TRUST_PROXY

Trust proxy. Express 'trust proxy' setting (boolean-like flag, hop count, or CIDR/preset list). Empty/unset means disabled — req.ip is the raw socket address and X-Forwarded-For is ignored.

• Default when unset: (empty — not set)
• Caution: Only enable behind a reverse proxy you control — enabling this trusts client-supplied X-Forwarded-For for rate-limit and anomaly-log keying.

LOOMBRE_CORS_ORIGINS

Allowed browser origins (CORS). Strict CORS origin allowlist for the browser web client. An explicitly empty list disables CORS entirely (same-origin deployments). Unset falls back to the local dev pairing.

• Default when unset: http://localhost:3000, http://127.0.0.1:3000

TLS

LOOMBRE_TLS_MODE

TLS mode. TLS termination mode: 'off' (plain HTTP, e.g. behind a reverse proxy), 'manual' (operator-supplied cert/key files), or 'acme' (built-in Let's Encrypt issuance).

• Default when unset: off

Paths

LOOMBRE_DATA_DIR

Data directory. App data directory (media cache, secrets, images, TLS state). Platform default when unset: XDG_DATA_HOME/loombre (Linux), ~/Library/Application Support/Loombre (macOS), %LOCALAPPDATA%/Loombre (Windows).

• Default when unset: ./data

LOOMBRE_CONFIG_DIR

Config directory. App config directory. Platform default when unset: XDG_CONFIG_HOME/loombre (Linux), Application Support/Loombre/config (macOS), %APPDATA%/Loombre (Windows).

• Default when unset: ./config

LOOMBRE_TRANSCODE_DIR

Conversion staging directory. Root directory transcode session staging directories are created under (docs/PLAYBACK.md §9 binding constraint 3). Default: <os.tmpdir()>/loombre-transcode.

• Default when unset: /tmp/loombre-transcode

ffmpeg / ffprobe

LOOMBRE_FFMPEG

ffmpeg binary path. Explicit ffmpeg binary path. Empty means resolve via PATH.

• Default when unset: (empty — not set)

LOOMBRE_FFPROBE

ffprobe binary path. Explicit ffprobe binary path. Empty means resolve via PATH.

• Default when unset: (empty — not set)

Environment pins for admin-editable settings

LOOMBRE_MAX_TRANSCODES

Pins Maximum simultaneous conversions (transcode.maxSimultaneousTranscodes) to a fixed value — set this and the admin settings screen shows the setting as controlled by the environment, read-only; any value stored from the settings screen is preserved but ignored until the variable is unset again.

How many videos this server will convert at the same time. Lowering it never interrupts anything already playing — it only makes the next person wait for a free slot.

• Default when unset: 1 (Tier 0) / 2 (Tier 1) / 4 (Tier 2) (or whatever was last saved from the settings screen)
• Caution: Setting this too high can overload the server if several videos convert at once — raise it gradually and keep an eye on how the machine handles it.

LOOMBRE_SCAN_CONCURRENCY

Pins Library scan speed (scanner.concurrency) to a fixed value — set this and the admin settings screen shows the setting as controlled by the environment, read-only; any value stored from the settings screen is preserved but ignored until the variable is unset again.

How many files Loombre examines at once while scanning. Higher is faster but works the machine harder; takes effect on the next scan. When you haven't changed it, Loombre uses half your processor cores (minimum 2).

• Default when unset: 2 (or whatever was last saved from the settings screen)

LOOMBRE_RESTRICTED_ENABLED

Pins Enable restricted content (restricted.enabled) to a fixed value — set this and the admin settings screen shows the setting as controlled by the environment, read-only; any value stored from the settings screen is preserved but ignored until the variable is unset again.

Turns the restricted-content feature on for this server. Off by default. While off, no restricted libraries or restricted content can be created.

• Default when unset: Off (or whatever was last saved from the settings screen)

LOOMBRE_UPDATE_CHECK

Pins Check for updates (updateCheck.mode) to a fixed value — set this and the admin settings screen shows the setting as controlled by the environment, read-only; any value stored from the settings screen is preserved but ignored until the variable is unset again.

Whether Loombre checks for a newer version. 'daily' checks at startup and once a day; 'manual' only when you ask; 'off' never. Nothing identifying is ever sent, in any mode. Loombre never installs an update by itself.

• Default when unset: daily (or whatever was last saved from the settings screen)

LOOMBRE_RATE_LOGIN

Pins Sign-in attempt limit (rateLimit.login) to a fixed value — set this and the admin settings screen shows the setting as controlled by the environment, read-only; any value stored from the settings screen is preserved but ignored until the variable is unset again.

How many sign-in attempts one device may make per minute before Loombre starts turning it away. Guards against password guessing.

• Default when unset: 10 (or whatever was last saved from the settings screen)

LOOMBRE_RATE_REFRESH

Pins Session refresh limit (rateLimit.refresh) to a fixed value — set this and the admin settings screen shows the setting as controlled by the environment, read-only; any value stored from the settings screen is preserved but ignored until the variable is unset again.

How many session-refresh requests one device may make per minute. Guards against a device flooding the server with requests for new sign-in tokens.

• Default when unset: 30 (or whatever was last saved from the settings screen)

LOOMBRE_RATE_UNLOCK

Pins Restricted-content PIN attempt limit (rateLimit.unlock) to a fixed value — set this and the admin settings screen shows the setting as controlled by the environment, read-only; any value stored from the settings screen is preserved but ignored until the variable is unset again.

How many PIN attempts one person may make per minute when unlocking restricted content. Guards against someone guessing the PIN.

• Default when unset: 5 (or whatever was last saved from the settings screen)

LOOMBRE_RATE_SETUP

Pins Setup wizard request limit (rateLimit.setup) to a fixed value — set this and the admin settings screen shows the setting as controlled by the environment, read-only; any value stored from the settings screen is preserved but ignored until the variable is unset again.

How many requests one device may make per minute to the first-time setup screen, before any account exists. Guards against abuse of that screen.

• Default when unset: 20 (or whatever was last saved from the settings screen)

LOOMBRE_RATE_CAPABILITIES

Pins Capability check request limit (rateLimit.capabilities) to a fixed value — set this and the admin settings screen shows the setting as controlled by the environment, read-only; any value stored from the settings screen is preserved but ignored until the variable is unset again.

How many times one device may ask the server what it supports, per minute. This is checked often during normal use, so the limit is set high.

• Default when unset: 120 (or whatever was last saved from the settings screen)

LOOMBRE_RATE_EXPORT

Pins Data export request limit (rateLimit.export) to a fixed value — set this and the admin settings screen shows the setting as controlled by the environment, read-only; any value stored from the settings screen is preserved but ignored until the variable is unset again.

How many full library exports one person may download per hour (not per minute — exports are heavy).

• Default when unset: 5 (or whatever was last saved from the settings screen)

LOOMBRE_RATE_MEDIA_TOKEN

Pins Media playback request limit (rateLimit.mediaToken) to a fixed value — set this and the admin settings screen shows the setting as controlled by the environment, read-only; any value stored from the settings screen is preserved but ignored until the variable is unset again.

How many media requests one person may make per minute — posters, video, and subtitles combined. Set this high: normal viewing makes many small requests.

• Default when unset: 600 (or whatever was last saved from the settings screen)

Secrets and other bootstrap variables not in this list

This page covers only registry-backed settings. A number of other operational variables live outside the registry and therefore aren't listed above: secrets (POSTGRES_PASSWORD, LOOMBRE_JWT_SECRET), performance-tier and transcode tuning (LOOMBRE_TIER, LOOMBRE_ALLOW_TRANSCODE, LOOMBRE_MAX_STREAM_BITRATE, LOOMBRE_TRANSCODE_WORKER_CONCURRENCY), metadata-provider keys (LOOMBRE_TMDB_API_KEY, LOOMBRE_TVDB_API_KEY), TLS/ACME companions to LOOMBRE_TLS_MODE (LOOMBRE_TLS_CERT_PATH/KEY_PATH, LOOMBRE_HTTPS_PORT, the LOOMBRE_ACME_* family — see docs/ops/acme.md), IPC and logging (LOOMBRE_IPC_*, LOOMBRE_LOG_FILE), and embedded-PG plumbing (LOOMBRE_EMBEDDED_PG_*). The full, accurate, hand-maintained list of every variable Loombre's Docker Compose distribution reads lives in installers/docker/loombre.env.example; docs/install/docker.md walks the two you cannot skip.