Environment Variables

CONFIG_DIR

Directory for storing configuration files and plugin settings.

• Type: string (path)
• Default: /config

LOG_ROOT

Root directory for log files.

• Type: string (path)
• Default: /var/log/

TMP_DIR

Staging directory for downloads before moving to destination.

• Type: string (path)
• Default: /tmp/shelfmark

ENABLE_LOGGING

Enable file logging under LOG_ROOT/shelfmark/ (including shelfmark.log and startup logs).

• Type: boolean
• Default: true

FLASK_HOST

Host address for the Flask web server.

• Type: string
• Default: 0.0.0.0

FLASK_PORT

Port number for the Flask web server.

• Type: number
• Default: 8084

SESSION_COOKIE_SECURE

Enable secure cookies (requires HTTPS).

• Type: boolean
• Default: false

CWA_DB_PATH

Path to the Calibre-Web database for authentication integration.

• Type: string (path)
• Default: /auth/app.db

HIDE_LOCAL_AUTH

Hide the username/password login form when OIDC is active.

• Type: boolean
• Default: false

DISABLE_LOCAL_AUTH

Disable username/password login and remove the local-admin prerequisite for OIDC. Implies HIDE_LOCAL_AUTH; with AUTH_METHOD=builtin, everyone is locked out until auth env vars are changed.

• Type: boolean
• Default: false

OIDC_AUTO_REDIRECT

Automatically redirect to the OIDC provider instead of showing the login page.

• Type: boolean
• Default: false

DOCKERMODE

Indicates the application is running inside a Docker container.

• Type: boolean
• Default: false

ONBOARDING

Show the onboarding wizard on first run. Set to false to skip (useful for ephemeral storage).

• Type: boolean
• Default: true

USING_WIREGUARD

Route all traffic through a WireGuard VPN tunnel with a fail-closed iptables kill-switch (non-tunnel egress is dropped). Requires root startup and NET_ADMIN (plus NET_RAW). Mutually exclusive with USING_TOR.

• Type: boolean
• Default: false

WIREGUARD_CONFIG

Path to the mounted wg-quick configuration file.

• Type: string (path)
• Default: /config/wg0.conf

WIREGUARD_INTERFACE

WireGuard interface name brought up by wg-quick.

• Type: string
• Default: wg0

LAN_NETWORK

Comma-separated CIDRs kept off the tunnel so the WebUI and internal download clients (Prowlarr, qBittorrent) stay reachable.

• Type: string (comma-separated)
• Default: 127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16

WIREGUARD_ENFORCE_DNS

Pin the container's resolver so DNS cannot silently fall back to an off-tunnel path. The resolver used is WIREGUARD_DNS if set, else the tunnel config's DNS = line. This does NOT force queries through the tunnel: it is designed for a trusted LAN resolver kept reachable off-tunnel via LAN_NETWORK (the query leaves over the LAN; the resolver encrypts upstream while the download still egresses via the tunnel). Special case: when Docker's embedded resolver (nameserver 127.0.0.11) is present, it is PRESERVED so container-name resolution (e.g. prowlarr, qbittorrent) keeps working, and the embedded resolver's upstream must be pinned via the container's compose dns: list. Fails closed (refuses to start) only when no embedded resolver is present AND no resolver is defined, or /etc/resolv.conf is not writable.

• Type: boolean
• Default: true

WIREGUARD_DNS

Explicit resolver(s) (comma/space separated) to pin when WIREGUARD_ENFORCE_DNS is true and Docker's embedded resolver is NOT in use. Use when the VPN's pushed DNS filters domains you need; point it at a resolver reachable via the tunnel or an allowed LAN resolver. NOTE: when the embedded resolver (127.0.0.11) is present it is preserved and this value cannot repoint its upstream from inside the container — set the container's compose dns: list to the trusted resolver instead.

• Type: string (comma-separated)
• Default: unset (uses config DNS = line)

WIREGUARD_DISABLE_IPV6

Strip IPv6 Address/AllowedIPs/DNS from the tunnel config before wg-quick (many container kernels lack the ip6tables raw table wg-quick needs) and remove IPv6 as a leak surface.

• Type: boolean
• Default: true

WIREGUARD_ALLOW_IPV6_LEAK

Escape hatch: continue startup even when an IPv6 kill-switch cannot be installed AND IPv6 cannot be disabled. Only set when the container has no IPv6 connectivity, as IPv6 egress may otherwise bypass the tunnel.

• Type: boolean
• Default: false

WIREGUARD_ALLOW_WEBUI_OFFTUNNEL

When false (default) the kill-switch is strictly fail-closed: the only off-tunnel egress permitted is loopback, the tunnel device and the LAN allowlist. Set true only if a NON-LAN client (e.g. a public reverse proxy on a different segment) must reach the WebUI; it permits app-server REPLY packets (--sport FLASK_PORT, conntrack REPLY) to leave off-tunnel. Server replies only, never client-initiated egress, so it cannot leak outbound browsing/downloads or the real IP for outbound requests, but it is still an off-tunnel path while the tunnel is down, hence opt-in. LAN WebUI clients never need it (covered by LAN_NETWORK).

• Type: boolean
• Default: false

WIREGUARD_STALE_AFTER

Seconds since the last WireGuard handshake before the healthcheck bounces the tunnel.

• Type: number
• Default: 180

SEARCH_PAGE_TITLE

Search Page Title

Title shown above the main search box on the homepage.

• Type: string
• Default: Shelfmark

CALIBRE_WEB_URL

Library URL

Adds a navigation button to your book library (Calibre-Web Automated, Grimmory, etc).

• Type: string
• Default: none

AUDIOBOOK_LIBRARY_URL

Audiobook Library URL

Adds a separate navigation button for your audiobook library (Audiobookshelf, Plex, etc). When both URLs are set, icons are shown instead of text.

• Type: string
• Default: none

SUPPORTED_FORMATS

Supported Book Formats

Book formats to include in search results. ZIP/RAR archives are extracted automatically and book files are used if found.

• Type: string (comma-separated)
• Default: epub,mobi,azw3,fb2,djvu,cbz,cbr

SUPPORTED_AUDIOBOOK_FORMATS

Supported Audiobook Formats

Audiobook formats to include in search results. ZIP/RAR archives are extracted automatically and audiobook files are used if found.

• Type: string (comma-separated)
• Default: m4b,mp3

BOOK_LANGUAGE

Default Book Languages

Default language filter for searches.

• Type: string (comma-separated)
• Default: en

SEARCH_MODE

Search Mode

How you want to search for and download books.

• Type: string (choice)
• Default: universal
• Options: direct (Direct), universal (Universal)

AA_DEFAULT_SORT

Default Sort Order

Default sort order for search results.

• Type: string (choice)
• Default: relevance
• Options: relevance (Most relevant), newest (Newest (publication year)), oldest (Oldest (publication year)), largest (Largest (filesize)), smallest (Smallest (filesize)), newest_added (Newest (open sourced)), oldest_added (Oldest (open sourced))

SHOW_RELEASE_SOURCE_LINKS

Show Release Source Links

Show clickable release-source links in release and details modals. Metadata provider links stay enabled.

• Type: boolean
• Default: true

SHOW_COMBINED_SELECTOR

Show Combined Download Selector

Show the option to search for and download both a book and audiobook together.

• Type: boolean
• Default: true

FORCE_COMBINED_SEARCH

Always Use Combined Search

Force combined search whenever it's available. Locks the combined toggle on.

• Type: boolean
• Default: false

METADATA_PROVIDER

Book Metadata Provider

Choose which metadata provider to use for book searches.

• Type: string (choice)
• Default: openlibrary
• Options: "" (No providers enabled)

METADATA_PROVIDER_AUDIOBOOK

Audiobook Metadata Provider

Metadata provider for audiobook searches. Uses the book provider if not set.

• Type: string (choice)
• Default: empty string
• Options: "" (Use book provider), "" (No providers enabled)

METADATA_PROVIDER_COMBINED

Combined Mode Metadata Provider

Metadata provider for combined mode searches. Uses the book provider if not set.

• Type: string (choice)
• Default: empty string
• Options: "" (Use book provider), "" (No providers enabled)

DEFAULT_RELEASE_SOURCE

Default Book Release Source

The release source tab to open by default in the release modal for books. Leave unset to use the first available source.

• Type: string (choice)
• Default: empty string
• Options: "" (Use first available source)

DEFAULT_RELEASE_SOURCE_AUDIOBOOK

Default Audiobook Release Source

The release source tab to open by default in the release modal for audiobooks. Uses the book release source if not set.

• Type: string (choice)
• Default: empty string
• Options: "" (Use book release source)

BOOKS_OUTPUT_MODE

Output Mode

Choose where completed book files are sent.

• Type: string (choice)
• Default: folder
• Options: folder (Folder), email (Email (SMTP)), booklore (Grimmory (API))

INGEST_DIR

Destination

Directory where downloaded files are saved. Use {User} for per-user folders (e.g. /books/{User}).

• Type: string
• Default: /books
• Required: Yes

FILE_ORGANIZATION

File Organization

Choose how downloaded book files are named and organized.

• Type: string (choice)
• Default: rename
• Options: none (None), rename (Rename Only), organize (Rename and Organize)

TEMPLATE_RENAME

Naming Template

Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or ''); use Organize for folders. Applies to single-file downloads.

• Type: string
• Default: {Author} - {Title} ({Year})

TEMPLATE_ORGANIZE

Path Template

Use / to create folders. Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty.

• Type: string
• Default: {Author}/{Title} ({Year})

HARDLINK_TORRENTS

Hardlink Book Torrents

Create hardlinks instead of copying. Preserves seeding but archives won't be extracted. Don't use if destination is a library ingest folder.

• Type: boolean
• Default: false

BOOKLORE_HOST

Grimmory URL

Base URL of your Grimmory instance

• Type: string
• Default: none
• Required: Yes

BOOKLORE_USERNAME

Username

Grimmory account username

• Type: string
• Default: none
• Required: Yes

BOOKLORE_PASSWORD

Password

Grimmory account password

• Type: string (secret)
• Default: none
• Required: Yes

BOOKLORE_DESTINATION

Upload Destination

Choose whether uploads go directly to a specific library path or to Bookdrop for review.

• Type: string (choice)
• Default: library
• Options: library (Specific Library), bookdrop (Bookdrop)

BOOKLORE_LIBRARY_ID

Library

Grimmory library to upload into.

• Type: string (choice)
• Default: none
• Required: Yes

BOOKLORE_PATH_ID

Path

Grimmory library path for uploads.

• Type: string (choice)
• Default: none
• Required: Yes

EMAIL_RECIPIENT

Default Email Recipient

Optional fallback email address when no per-user email recipient override is configured.

• Type: string
• Default: none

EMAIL_ATTACHMENT_SIZE_LIMIT_MB

Attachment Size Limit (MB)

Maximum total attachment size per email. Email encoding adds overhead; keep this below your provider's limit.

• Type: number
• Default: 25
• Constraints: min: 1, max: 600

EMAIL_SMTP_HOST

SMTP Host

SMTP server hostname or IP (e.g., smtp.gmail.com).

• Type: string
• Default: none
• Required: Yes

EMAIL_SMTP_PORT

SMTP Port

SMTP server port (587 is typical for STARTTLS, 465 for SSL).

• Type: number
• Default: 587
• Constraints: min: 1, max: 65535

EMAIL_SMTP_SECURITY

SMTP Security

Transport security mode for SMTP.

• Type: string (choice)
• Default: starttls
• Options: none (None), starttls (STARTTLS), ssl (SSL/TLS)

EMAIL_SMTP_USERNAME

Username

SMTP username (leave empty for no authentication).

• Type: string
• Default: none

EMAIL_SMTP_PASSWORD

Password

SMTP password (required if Username is set).

• Type: string (secret)
• Default: none

EMAIL_FROM

From Address

From address used for the email. You can include a display name (e.g., Shelfmark mail@example.com). Leave blank to default to the SMTP username (when it is an email address).

• Type: string
• Default: none

EMAIL_SUBJECT_TEMPLATE

Subject Template

Email subject. Variables: {Author}, {Title}, {PrimaryTitle}, {Year}, {Series}, {SeriesPosition}, {Subtitle}, {Format}.

• Type: string
• Default: {Title}

EMAIL_SMTP_TIMEOUT_SECONDS

SMTP Timeout (seconds)

How long to wait for SMTP operations before failing.

• Type: number
• Default: 60
• Constraints: min: 1, max: 600

EMAIL_ALLOW_UNVERIFIED_TLS

Allow Unverified TLS

Disable TLS certificate verification (not recommended).

• Type: boolean
• Default: false

DESTINATION_AUDIOBOOK

Destination

Directory where downloaded audiobook files are saved. Leave empty to use the Books destination.

• Type: string
• Default: none

FILE_ORGANIZATION_AUDIOBOOK

File Organization

Choose how downloaded audiobook files are named and organized.

• Type: string (choice)
• Default: rename
• Options: none (None), rename (Rename Only), organize (Rename and Organize)

TEMPLATE_AUDIOBOOK_RENAME

Naming Template

Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or ''); use Organize for folders. Applies to single-file downloads.

• Type: string
• Default: {Author} - {Title}

TEMPLATE_AUDIOBOOK_ORGANIZE

Path Template

Use / to create folders. Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty.

• Type: string
• Default: {Author}/{Title}/{Title}

HARDLINK_TORRENTS_AUDIOBOOK

Hardlink Audiobook Torrents

Create hardlinks instead of copying. Preserves seeding but archives won't be extracted. Don't use if destination is a library ingest folder.

• Type: boolean
• Default: true

AUTO_OPEN_DOWNLOADS_SIDEBAR

Auto-Open Downloads Sidebar

Automatically open the downloads sidebar when a new download is queued.

• Type: boolean
• Default: false

DOWNLOAD_TO_BROWSER_CONTENT_TYPES

Download to Browser

Automatically download completed files to your browser for the selected content types.

• Type: string (comma-separated)
• Default: empty list

MAX_CONCURRENT_DOWNLOADS

Max Concurrent Downloads

Maximum number of simultaneous downloads.

• Type: number
• Default: 3
• Requires restart: Yes
• Constraints: min: 1, max: 10

STATUS_TIMEOUT

Status Timeout (seconds)

How long to keep completed/failed downloads in the queue display.

• Type: number
• Default: 3600
• Constraints: min: 60, max: 86400

AUTH_METHOD

Authentication Method

Select the authentication method for accessing Shelfmark. Restart container after changing Calibre-Web passwords.

• Type: string (choice)
• Default: none
• Options: none (No Authentication), builtin (Local), proxy (Proxy Authentication), oidc (OIDC (OpenID Connect)), cwa (Calibre-Web Database)

PROXY_AUTH_USER_HEADER

Proxy Auth User Header

The HTTP header your proxy uses to pass the authenticated username.

• Type: string
• Default: X-Auth-User

PROXY_AUTH_LOGOUT_URL

Proxy Auth Logout URL

The URL to redirect users to for logging out. Leave empty to disable logout functionality.

• Type: string
• Default: empty string

PROXY_AUTH_ADMIN_GROUP_HEADER

Proxy Auth Admin Group Header

Optional: header your proxy uses to pass user groups/roles.

• Type: string
• Default: X-Auth-Groups

PROXY_AUTH_ADMIN_GROUP_NAME

Proxy Auth Admin Group

Optional: users in this group are treated as admins. Leave blank to skip group-based admin detection.

• Type: string
• Default: empty string

OIDC_DISCOVERY_URL

Discovery URL

OpenID Connect discovery endpoint URL. Usually ends with /.well-known/openid-configuration.

• Type: string
• Default: none
• Required: Yes

OIDC_CLIENT_ID

Client ID

OAuth2 client ID from your identity provider.

• Type: string
• Default: none
• Required: Yes

OIDC_CLIENT_SECRET

Client Secret

OAuth2 client secret from your identity provider.

• Type: string (secret)
• Default: none
• Required: Yes

OIDC_SCOPES

Scopes

OAuth2 scopes to request from the identity provider. Managed automatically: includes essential scopes and the group claim when using admin group authorization.

• Type: string (comma-separated)
• Default: openid,email,profile

OIDC_GROUP_CLAIM

Group Claim Name

The name of the claim in the ID token that contains user groups.

• Type: string
• Default: groups

OIDC_ADMIN_GROUP

Admin Group Name

Users in this group will be given admin access (if enabled below). Leave empty to use database roles only.

• Type: string
• Default: empty string

OIDC_USE_ADMIN_GROUP

Use Admin Group for Authorization

When enabled, users in the Admin Group are granted admin access. When disabled, admin access is determined solely by database roles.

• Type: boolean
• Default: true

OIDC_AUTO_PROVISION

Auto-Provision Users

Automatically create a user account on first OIDC login. When disabled, users must be pre-created by an admin.

• Type: boolean
• Default: true

OIDC_BUTTON_LABEL

Login Button Label

Custom label for the OIDC sign-in button on the login page.

• Type: string
• Default: empty string

CERTIFICATE_VALIDATION

Certificate Validation

Controls SSL/TLS certificate verification for outbound connections. Disable for self-signed certificates on internal services (e.g. OIDC providers, Prowlarr).

• Type: string (choice)
• Default: enabled
• Options: enabled (Enabled (Recommended)), disabled_local (Disabled for Local Addresses), disabled (Disabled)

CUSTOM_DNS

DNS Provider

DNS provider for domain resolution. 'Auto' rotates through providers on failure.

• Type: string (choice)
• Default: auto
• Options: auto (Auto (Recommended)), system (System), google (Google), cloudflare (Cloudflare), quad9 (Quad9), opendns (OpenDNS), manual (Manual)

CUSTOM_DNS_MANUAL

Manual DNS Servers

Comma-separated list of DNS server IP addresses (e.g., 8.8.8.8, 1.1.1.1).

• Type: string
• Default: none

USE_DOH

Use DNS over HTTPS

Use encrypted DNS queries for improved reliability and privacy.

• Type: boolean
• Default: true

USING_TOR

Tor Routing

Route all traffic through Tor for enhanced privacy. Requires root startup.

• Type: boolean
• Default: false

PROXY_MODE

Proxy Mode

Choose proxy type. SOCKS5 handles all traffic through a single proxy.

• Type: string (choice)
• Default: none
• Options: none (None (Direct Connection)), http (HTTP/HTTPS Proxy), socks5 (SOCKS5 Proxy)

HTTP_PROXY

HTTP Proxy

HTTP proxy URL (e.g., http://proxy:8080)

• Type: string
• Default: none

HTTPS_PROXY

HTTPS Proxy

HTTPS proxy URL (leave empty to use HTTP proxy for HTTPS)

• Type: string
• Default: none

SOCKS5_PROXY

SOCKS5 Proxy

SOCKS5 proxy URL. Supports auth: socks5://user:pass@host:port

• Type: string
• Default: none

NO_PROXY

No Proxy

Comma-separated hosts to bypass proxy (e.g., localhost,127.0.0.1,10.,.local)

• Type: string
• Default: none

URL_BASE

Base Path

Optional URL path prefix. Use a path like /shelfmark (no hostname). Leave blank for root.

• Type: string
• Default: none
• Requires restart: Yes

DEBUG

Debug Mode

Enable verbose logging to console and file. Not recommended for normal use.

• Type: boolean
• Default: false
• Requires restart: Yes

MAIN_LOOP_SLEEP_TIME

Queue Check Interval (seconds)

How often the download queue is checked for new items.

• Type: number
• Default: 5
• Requires restart: Yes
• Constraints: min: 1, max: 60

DOWNLOAD_PROGRESS_UPDATE_INTERVAL

Progress Update Interval (seconds)

How often download progress is broadcast to the UI.

• Type: number
• Default: 1
• Requires restart: Yes
• Constraints: min: 1, max: 10

CUSTOM_SCRIPT

Custom Script Path

Path to a script to run after each successful download. Must be executable.

• Type: string
• Default: none

CUSTOM_SCRIPT_PATH_MODE

Custom Script Path Mode

Pass the path to the custom script as an absolute path or relative to the destination folder.

• Type: string (choice)
• Default: absolute
• Options: absolute (Absolute), relative (Relative)

CUSTOM_SCRIPT_JSON_PAYLOAD

Custom Script JSON Payload

Send a JSON payload to the script via stdin. Useful for multi-file imports (audiobooks) or richer metadata without relying on path parsing.

• Type: boolean
• Default: false

DOWNLOAD_CLIENT_COMPLETED_PATH_TIMEOUT

Completed Path Wait (seconds)

How long to wait after a torrent or usenet client reports completion for the completed file path to become visible to Shelfmark. Increase this for seedbox or remote-sync workflows.

• Type: number
• Default: 60
• Constraints: min: 0, max: 3600

COVERS_CACHE_ENABLED

Enable Cover Cache

Cache book covers on the server for faster loading.

• Type: boolean
• Default: true

COVERS_CACHE_TTL

Cache TTL (days)

How long to keep cached covers. Set to 0 to keep forever (recommended for static artwork).

• Type: number
• Default: 0
• Constraints: min: 0, max: 365

COVERS_CACHE_MAX_SIZE_MB

Max Cache Size (MB)

Maximum disk space for cached covers. Oldest images are removed when limit is reached.

• Type: number
• Default: 500
• Constraints: min: 50, max: 5000

METADATA_CACHE_ENABLED

Enable Metadata Caching

When disabled, all metadata searches hit the provider API directly.

• Type: boolean
• Default: true

METADATA_CACHE_SEARCH_TTL

Search Results Cache (seconds)

How long to cache search results. Default: 300 (5 minutes). Max: 604800 (7 days).

• Type: number
• Default: 300
• Constraints: min: 60, max: 604800

METADATA_CACHE_BOOK_TTL

Book Details Cache (seconds)

How long to cache individual book details. Default: 600 (10 minutes). Max: 604800 (7 days).

• Type: number
• Default: 600
• Constraints: min: 60, max: 604800

PROWLARR_ENABLED

Enable Prowlarr source

Enable searching for books via Prowlarr indexers

• Type: boolean
• Default: false

PROWLARR_URL

Prowlarr URL

Base URL of your Prowlarr instance

• Type: string
• Default: none
• Required: Yes

PROWLARR_API_KEY

API Key

Found in Prowlarr: Settings > General > API Key

• Type: string (secret)
• Default: none
• Required: Yes

PROWLARR_INDEXERS

Indexers to Search

Select which indexers to search. 📚 = has book categories. Leave empty to search all.

• Type: string (comma-separated)
• Default: empty list

PROWLARR_AUTO_EXPAND

Auto-expand search on no results

Automatically retry search without category filtering if no results are found

• Type: boolean
• Default: false

PROWLARR_COLLAPSE_DUPLICATES

Show one row per release

Collapse a release that several indexer entries returned down to a single row, keeping the entry with the best Prowlarr priority. Turn this off to see every entry that carried it, which is what makes results from filter-specific entries (freeleech and the like) visible.

• Type: boolean
• Default: true

PROWLARR_USE_SEED_PREFERENCES

Use Prowlarr seed preferences

Apply per-indexer seed time and ratio preferences from Prowlarr when sending torrents to the download client

• Type: boolean
• Default: false

NEWZNAB_ENABLED

Enable Newznab source

Enable searching for books via a Newznab-compatible indexer

• Type: boolean
• Default: false

NEWZNAB_URL

Newznab URL

Base URL of your Newznab indexer or aggregator

• Type: string
• Default: none
• Required: Yes

NEWZNAB_API_KEY

API Key

Your Newznab API key (leave blank if not required)

• Type: string (secret)
• Default: none

NEWZNAB_AUTO_EXPAND

Auto-expand search on no results

Automatically retry search without category filtering if no results are found

• Type: boolean
• Default: false

ABB_ENABLED

Enable AudiobookBay

Enable AudiobookBay as a release source for audiobooks.

• Type: boolean
• Default: false

ABB_HOSTNAME

Hostname

AudiobookBay domain (e.g., audiobookbay.lu, audiobookbay.is). Required to enable searches.

• Type: string
• Default: empty string
• Required: Yes

ABB_PAGE_LIMIT

Max Pages to Search

Maximum number of search result pages to fetch (1-10).

• Type: number
• Default: 1
• Constraints: min: 1, max: 10

ABB_EXACT_PHRASE

Prefer Exact-Phrase Search

Wrap generated queries in quotes for stricter matching. If no results are found, Shelfmark retries without quotes.

• Type: boolean
• Default: false

ABB_RATE_LIMIT_DELAY

Rate Limit Delay (seconds)

Delay between requests in seconds to avoid rate limiting (0-10).

• Type: number
• Default: 1.0
• Constraints: min: 0.0, max: 10.0

IRC_SERVER

Server

IRC server hostname

• Type: string
• Default: none
• Required: Yes

IRC_PORT

Port

IRC server port (usually 6697 for TLS, 6667 for plain)

• Type: number
• Default: 6697

IRC_USE_TLS

Use TLS

Enable TLS/SSL encryption for the IRC connection. Disable for servers that don't support TLS.

• Type: boolean
• Default: true

IRC_CHANNEL

Channel

Channel name without the # prefix. Used for all searches unless a separate audiobook channel is configured below.

• Type: string
• Default: none
• Required: Yes

IRC_NICK

Nickname

Your IRC nickname (required). Must be unique on the IRC network.

• Type: string
• Default: none
• Required: Yes

IRC_SEARCH_BOT

Search bot

The search bot to address queries to (required). Searches are sent as "@ ".

• Type: string
• Default: none
• Required: Yes

IRC_AUDIOBOOK_CHANNEL

Audiobook channel

Optional. Channel name (without the # prefix) to use for audiobook searches. Leave blank to use the main channel above for audiobooks too.

• Type: string
• Default: none

IRC_AUDIOBOOK_SEARCH_BOT

Audiobook search bot

Optional. Search bot for the audiobook channel. Leave blank to reuse the main search bot above. Only used when an audiobook channel is set.

• Type: string
• Default: none

IRC_CACHE_TTL

Cache Duration

How long to keep cached search results before they expire.

• Type: string (choice)
• Default: 2592000
• Options: 2592000 (30 days), 0 (Forever (until manually cleared))

PROWLARR_TORRENT_CLIENT

Torrent Client

Choose which torrent client to use

• Type: string (choice)
• Default: empty string
• Options: "" (None), qbittorrent (qBittorrent), transmission (Transmission), deluge (Deluge), rtorrent (rTorrent)

QBITTORRENT_URL

qBittorrent URL

Web UI URL of your qBittorrent instance

• Type: string
• Default: none

QBITTORRENT_USERNAME

Username

qBittorrent Web UI username

• Type: string
• Default: none

QBITTORRENT_PASSWORD

Password

qBittorrent Web UI password

• Type: string (secret)
• Default: none

QBITTORRENT_API_KEY

API Key

Found in qBittorrent: Options > Web UI > API Key (qBittorrent 5.2.0+). Used instead of the username and password when set.

• Type: string (secret)
• Default: none

QBITTORRENT_CATEGORY

Book Category

Category to assign to book downloads in qBittorrent

• Type: string
• Default: books

QBITTORRENT_CATEGORY_AUDIOBOOK

Audiobook Category

Category for audiobook downloads. Leave empty to use the book category.

• Type: string
• Default: empty string

QBITTORRENT_DOWNLOAD_DIR

Download Directory

Server-side directory where torrents are downloaded (optional, uses qBittorrent default if not specified)

• Type: string
• Default: none

QBITTORRENT_TAG

Tags

Tag(s) to assign to qBittorrent downloads. Leave empty for no tags.

• Type: string (comma-separated)
• Default: empty list

TRANSMISSION_URL

Transmission URL

URL of your Transmission instance (use https:// for TLS)

• Type: string
• Default: none

TRANSMISSION_USERNAME

Username

Transmission RPC username (if authentication enabled)

• Type: string
• Default: none

TRANSMISSION_PASSWORD

Password

Transmission RPC password

• Type: string (secret)
• Default: none

TRANSMISSION_CATEGORY

Book Label

Label to assign to book downloads in Transmission

• Type: string
• Default: books

TRANSMISSION_CATEGORY_AUDIOBOOK

Audiobook Label

Label for audiobook downloads. Leave empty to use the book label.

• Type: string
• Default: empty string

TRANSMISSION_DOWNLOAD_DIR

Download Directory

Server-side directory where torrents are downloaded (optional, uses Transmission default if not specified)

• Type: string
• Default: none

DELUGE_HOST

Deluge Web UI Host/URL

Hostname/IP or full URL of your Deluge Web UI (deluge-web)

• Type: string
• Default: localhost

DELUGE_PORT

Deluge Web UI Port

Deluge Web UI port (default: 8112)

• Type: string
• Default: 8112

DELUGE_PASSWORD

Password

Deluge Web UI password (default: deluge)

• Type: string (secret)
• Default: none

DELUGE_CATEGORY

Book Label

Label to assign to book downloads in Deluge

• Type: string
• Default: books

DELUGE_CATEGORY_AUDIOBOOK

Audiobook Label

Label for audiobook downloads. Leave empty to use the book label.

• Type: string
• Default: empty string

DELUGE_DOWNLOAD_DIR

Download Directory

Server-side directory where torrents are downloaded (optional, uses Deluge default if not specified)

• Type: string
• Default: none

RTORRENT_URL

rTorrent URL

XML-RPC URL of your rTorrent instance

• Type: string
• Default: none

RTORRENT_USERNAME

Username

HTTP Basic auth username (if authentication enabled)

• Type: string
• Default: none

RTORRENT_PASSWORD

Password

HTTP Basic auth password

• Type: string (secret)
• Default: none

RTORRENT_LABEL

Book Label

Label to assign to ebook downloads in rTorrent

• Type: string
• Default: cwabd

RTORRENT_AUDIOBOOK_LABEL

Audiobook Label

Label to assign to audiobook downloads in rTorrent (falls back to Book Label if not set)

• Type: string
• Default: none

RTORRENT_DOWNLOAD_DIR

Download Directory

Server-side directory where torrents are downloaded (optional, uses rTorrent default if not specified)

• Type: string
• Default: none

PROWLARR_TORRENT_ACTION

Torrent Completion Action

Choose whether to keep, remove, or move the torrent to another category or label after import

• Type: string (choice)
• Default: keep
• Options: keep (Keep), remove (Remove), change_category (Change Category)

PROWLARR_TORRENT_POST_IMPORT_CATEGORY

Post-Import Category

Category or label to assign after a successful import

• Type: string
• Default: empty string

PROWLARR_USENET_CLIENT

Usenet Client

Choose which usenet client to use

• Type: string (choice)
• Default: empty string
• Options: "" (None), nzbget (NZBGet), sabnzbd (SABnzbd)

NZBGET_URL

NZBGet URL

URL of your NZBGet instance

• Type: string
• Default: none

NZBGET_USERNAME

Username

NZBGet control username

• Type: string
• Default: nzbget

NZBGET_PASSWORD

Password

NZBGet control password

• Type: string (secret)
• Default: none

NZBGET_CATEGORY

Book Category

Category to assign to book downloads in NZBGet

• Type: string
• Default: Books

NZBGET_CATEGORY_AUDIOBOOK

Audiobook Category

Category for audiobook downloads. Leave empty to use the book category.

• Type: string
• Default: empty string

SABNZBD_URL

SABnzbd URL

URL of your SABnzbd instance

• Type: string
• Default: none

SABNZBD_API_KEY

API Key

Found in SABnzbd: Config > General > API Key

• Type: string (secret)
• Default: none

SABNZBD_CATEGORY

Book Category

Category to assign to book downloads in SABnzbd

• Type: string
• Default: books

SABNZBD_CATEGORY_AUDIOBOOK

Audiobook Category

Category for audiobook downloads. Leave empty to use the book category.

• Type: string
• Default: empty string

PROWLARR_USENET_ACTION

NZB Completion Action

Move deletes the job from your usenet client after import; Copy keeps it in the client

• Type: string (choice)
• Default: move
• Options: move (Move), copy (Copy)

HARDCOVER_ENABLED

Enable Hardcover

Enable Hardcover as a metadata provider for book searches

• Type: boolean
• Default: false

HARDCOVER_API_KEY

API Key

Get your API key from hardcover.app/account/api

• Type: string (secret)
• Default: none
• Required: Yes

HARDCOVER_DEFAULT_SORT

Default Sort Order

Default sort order for Hardcover search results.

• Type: string (choice)
• Default: relevance
• Options: relevance (Most relevant), popularity (Most popular), rating (Highest rated), newest (Newest), oldest (Oldest)

HARDCOVER_EXCLUDE_COMPILATIONS

Exclude Compilations

Filter out compilations, anthologies, and omnibus editions from search results

• Type: boolean
• Default: false

HARDCOVER_EXCLUDE_UNRELEASED

Exclude Unreleased Books

Filter out books with a release year in the future

• Type: boolean
• Default: false

HARDCOVER_AUTO_REMOVE_ON_DOWNLOAD

Auto-Remove from List on Download

Automatically remove a book from the active Hardcover list when you download it

• Type: boolean
• Default: true

OPENLIBRARY_ENABLED

Enable Open Library

Enable Open Library as a metadata provider for book searches

• Type: boolean
• Default: false

OPENLIBRARY_DEFAULT_SORT

Default Sort Order

Default sort order for Open Library search results.

• Type: string (choice)
• Default: relevance
• Options: relevance (Most relevant), newest (Newest), oldest (Oldest)

GOOGLEBOOKS_ENABLED

Enable Google Books

Enable Google Books as a metadata provider for book searches

• Type: boolean
• Default: false

GOOGLEBOOKS_API_KEY

API Key

Get your API key from Google Cloud Console (APIs & Services > Credentials)

• Type: string (secret)
• Default: none
• Required: Yes

GOOGLEBOOKS_DEFAULT_SORT

Default Sort Order

Default sort order for Google Books search results.

• Type: string (choice)
• Default: relevance
• Options: relevance (Most relevant), newest (Newest)

DIRECT_DOWNLOAD_ENABLED

Enable Direct Download Source

Show Direct Download in release-source lists and allow Direct mode searches. Add your own mirror URLs in the Mirrors tab before using it.

• Type: boolean
• Default: false

DIRECT_DOWNLOAD_LANGUAGE_FROM_PATH

Detect Language From Distant Path

When language metadata is missing or unknown, parse the distant path (file path shown in search results) for language tags like [BD FR] or [En]. Also enables local language filtering so lgli files without AA language metadata are not excluded before the distant path can be checked.

• Type: boolean
• Default: false

AA_DONATOR_KEY

Account Donator Key

Enables fast download access on AA. Get this from your donator account page.

• Type: string (secret)
• Default: none

FAST_SOURCES_DISPLAY

Fast downloads

Always tried first, no waiting or bypass required.

• Type: JSON array
• Default: see UI for defaults

SOURCE_PRIORITY

Slow downloads

Fallback sources, may have waiting. Requires bypasser. Drag to reorder.

• Type: JSON array
• Default: see UI for defaults

MAX_RETRY

Max Retries

Maximum retry attempts for failed downloads.

• Type: number
• Default: 10
• Constraints: min: 1, max: 50

DEFAULT_SLEEP

Retry Delay (seconds)

Wait time between download retry attempts.

• Type: number
• Default: 5
• Constraints: min: 1, max: 60

AA_CONTENT_TYPE_ROUTING

Enable Content-Type Routing

Override destination based on content type metadata.

• Type: boolean
• Default: false

AA_CONTENT_TYPE_DIR_FICTION

Fiction Books

• Type: string
• Default: none

AA_CONTENT_TYPE_DIR_NON_FICTION

Non-Fiction Books

• Type: string
• Default: none

AA_CONTENT_TYPE_DIR_UNKNOWN

Unknown Books

• Type: string
• Default: none

AA_CONTENT_TYPE_DIR_MAGAZINE

Magazines

• Type: string
• Default: none

AA_CONTENT_TYPE_DIR_COMIC

Comic Books

• Type: string
• Default: none

AA_CONTENT_TYPE_DIR_STANDARDS

Standards Documents

• Type: string
• Default: none

AA_CONTENT_TYPE_DIR_MUSICAL_SCORE

Musical Scores

• Type: string
• Default: none

AA_CONTENT_TYPE_DIR_OTHER

Other

• Type: string
• Default: none

USE_CF_BYPASS

Enable Cloudflare Bypass

Attempt to bypass Cloudflare protection on download sites.

• Type: boolean
• Default: true
• Requires restart: Yes

USING_EXTERNAL_BYPASSER

Use External Bypasser

Use FlareSolverr or similar external service instead of built-in bypasser. Caution: May have limitations with custom DNS, Tor and proxies. You may experience slower downloads and and poorer reliability compared to the internal bypasser.

• Type: boolean
• Default: false
• Requires restart: Yes

EXT_BYPASSER_URL

External Bypasser URL

URL of the external bypasser service (e.g., FlareSolverr).

• Type: string
• Default: http://flaresolverr:8191
• Requires restart: Yes

EXT_BYPASSER_PATH

External Bypasser Path

API path for the external bypasser.

• Type: string
• Default: /v1
• Requires restart: Yes

EXT_BYPASSER_TIMEOUT

External Bypasser Timeout (ms)

Timeout for external bypasser requests in milliseconds.

• Type: number
• Default: 60000
• Requires restart: Yes
• Constraints: min: 10000, max: 300000

AA_BASE_URL

Primary Mirror

Select Auto to try mirrors from your list on startup and fail over on errors. Choosing a specific mirror pins Shelfmark to that URL.

• Type: string (choice)
• Default: auto
• Options: auto (Auto (Recommended))

AA_MIRROR_URLS

Mirrors

List the Anna's Archive mirror URLs you want Shelfmark to use. Type a URL and press Enter to add it. Order matters when Auto is selected.

• Type: string (comma-separated)
• Default: empty list

LIBGEN_MIRROR_URLS

LibGen

Mirrors are tried in the order you add them until one works.

• Type: string (comma-separated)
• Default: empty list

ZLIB_MIRROR_URLS

Z-Library

Only the first mirror in the list is used.

• Type: string (comma-separated)
• Default: empty list

WELIB_MIRROR_URLS

Welib

Only the first mirror in the list is used.

• Type: string (comma-separated)
• Default: empty list