JellyPassSettings reference
JellyPass reads its settings from environment variables when it starts; with Compose, put them in .env. An invalid value stops startup with a message naming the setting, except LOG_LEVEL: an unrecognised level logs a warning and JellyPass uses info. Booleans take true, false, 1 or 0.
Connections and basics
| Setting | Required | Default | What it does |
|---|---|---|---|
JELLYFIN_URL | Yes | — | Jellyfin's base URL as JellyPass reaches it, such as http://jellyfin:8096. |
JELLYFIN_API_KEY | Yes | — | A Jellyfin administrator API key. |
WEBHOOK_TOKEN | Yes | — | Secret Seerr's webhook must send. Use a long random value. |
ADMIN_TOKEN | Recommended | WEBHOOK_TOKEN | Bearer token for the admin API and /metrics. If unset, WEBHOOK_TOKEN is used (and a warning logged); use a different value. |
SEERR_URL | Set together | — | Seerr's base URL as JellyPass reaches it, such as http://seerr:5055. |
SEERR_API_KEY | Set together | — | Seerr API key. Startup stops if only one of the two is set. |
STATE_FILE | No | ./data/grants.json | The state file. The Compose file sets /app/data/grants.json. |
HOST | No | 0.0.0.0 | Listen address inside the container. |
PORT | No | 8787 | Listen port. |
RECONCILE_INTERVAL_SECONDS | No | 300 | How often tags and policies are re-applied and retried. 0 disables; at most 86400. |
CATALOG_SYNC_INTERVAL_SECONDS | No | 3600 | How often the Library catalogue is refreshed from Jellyfin. 0 disables; at most 604800. |
Household addresses and apps
| Setting | Required | Default | What it does |
|---|---|---|---|
HOUSEHOLD_DOMAIN | No | — | Turns on household addresses below this domain. |
HOUSEHOLD_HOST_PREFIX | No | jelly- | Put before each household ID: an address is <prefix><household>.<domain>. 1 to 32 lowercase letters, digits and hyphens. |
HOUSEHOLD_APP_ENABLED | No | false | Serves the household web app at /jellypass/app/ and its API, used by every JellyPass app. Needs HOUSEHOLD_DOMAIN, Seerr and TMDB_API_KEY. While on, at most 100 households. |
TMDB_API_KEY | With the app | — | TMDB v3 API key (32 hexadecimal characters) or v4 read access token. Checked at startup, never logged. Use a key for JellyPass alone. |
TV_ADDON_ENABLED | No | false | Adds the TV add-on to Jellyfin web on the households in TV_ADDON_HOUSEHOLDS. Needs HOUSEHOLD_APP_ENABLED. |
TV_ADDON_HOUSEHOLDS | With the add-on | — | Household IDs separated by commas, or * for all. |
WS_IDLE_TIMEOUT_MS | No | 300000 | Closes a household WebSocket after this long with no traffic either way. 0 disables. |
WS_UPSTREAM_IDLE_TIMEOUT_MS | No | 180000 | Closes a household WebSocket after this long with nothing from Jellyfin. 0 disables. |
Backfill, proxies and the rest
| Setting | Required | Default | What it does |
|---|---|---|---|
REQUEST_BACKFILL_SINCE | No | — | Turns on the request backfill for requests created on or after this date: YYYY-MM-DD (UTC midnight) or an ISO 8601 date-time with Z or an offset. |
REQUEST_BACKFILL_ENABLED | No | true when the date is set | Set false to pause the backfill. Needs Seerr and the date. |
TRUSTED_PROXIES | No | empty | Reverse proxies whose X-Forwarded-For is believed: IPv4/IPv6 addresses and CIDR ranges separated by commas, no ports. See Reverse proxy. |
JELLYFIN_UNTESTED_VERSION_OK | No | — | One exact Jellyfin version outside the supported releases, such as 13.0.0, that counts as confirmed, so JellyPass doesn't warn about it (and, from 4.0.0, household addresses serve on it). New in 3.10.0. |
LOG_LEVEL | No | info | debug, info, warn or error. Only debug changes output today (routine disconnects and skipped backfill items). |
JELLYPASS_IMAGE | Compose only | …/jellypass:latest | The image the Compose file runs. Pin a version. |
JELLYPASS_ENV_FILE | Compose only | .env | Another settings file for the Compose file. |
A minimal .env
JELLYPASS_IMAGE=ghcr.io/nicklongmore86/jellypass:X.Y.Z
JELLYFIN_URL=http://jellyfin:8096
JELLYFIN_API_KEY=jellyfin-admin-api-key
SEERR_URL=http://seerr:5055
SEERR_API_KEY=seerr-api-key
WEBHOOK_TOKEN=long-random-secret
ADMIN_TOKEN=different-long-random-secret
# Household addresses and the apps
HOUSEHOLD_DOMAIN=example.com
HOUSEHOLD_APP_ENABLED=true
TMDB_API_KEY=tmdb-key
TRUSTED_PROXIES=192.168.1.5The example settings file, .env.example, lists the same settings with comments. The server reference has every setting in full detail, with the administrator API and metrics.