Prerequisites

What you need before installing Diskovarr.

Required

Network Access

Diskovarr must be able to reach your Plex server and Tautulli over HTTP/HTTPS. If they run on the same machine, http://localhost:PORT works. If they're on separate machines, use local IPs or hostnames.

Optionally, expose Diskovarr externally (via Nginx Proxy Manager or similar) so users can access it from outside your home network. An external URL is also required if you want Discord bot avatar upload to work.

Optional Services

Installation

Docker is the recommended installation method — it handles all dependencies, isolates Diskovarr from your host, and makes updates a one-liner. Native installation is also supported if you prefer to run directly on the host.

docker run -d \
  --name diskovarr \
  --restart unless-stopped \
  -p 3232:3232 \
  -v ./data:/app/data \
  -e ADMIN_PASSWORD=your_admin_password \
  -e SESSION_SECRET=$(openssl rand -hex 32) \
  -e PLEX_URL=http://192.168.1.x:32400 \
  -e PLEX_TOKEN=your_plex_admin_token \
  -e PLEX_SERVER_ID=your_plex_machine_identifier \
  -e PLEX_SERVER_NAME=Your\ Server\ Name \
  lebbi/diskovarr:latest

mkdir -p /opt/diskovarr && cd /opt/diskovarr

services:
  diskovarr:
    image: lebbi/diskovarr:latest
    container_name: diskovarr
    restart: unless-stopped
    ports:
      - "3232:3232"
    volumes:
      - ./data:/app/data
    environment:
      # ── Required ────────────────────────────────────────────────
      - ADMIN_PASSWORD=change_this_to_a_secure_password
      - SESSION_SECRET=change_this_to_a_long_random_string
      - PLEX_URL=http://192.168.1.x:32400
      - PLEX_TOKEN=your_plex_admin_token
      - PLEX_SERVER_ID=your_plex_machine_identifier
      - PLEX_SERVER_NAME=Your Server Name
      # ── Optional (can be configured in admin panel instead) ─────
      - TAUTULLI_URL=http://192.168.1.x:8181
      - TAUTULLI_API_KEY=your_tautulli_api_key
      - TMDB_API_KEY=your_tmdb_api_key
      - PLEX_MOVIES_SECTION_ID=1
      - PLEX_TV_SECTION_ID=2
      - APP_URL=http://localhost:3232
      - PORT=3232

openssl rand -hex 32

docker compose up -d

docker compose logs -f diskovarr

docker compose pull && docker compose up -d

services:
  diskovarr:
    image: lebbi/diskovarr:latest
    container_name: diskovarr
    restart: unless-stopped
    ports:
      - "3232:3232"
    volumes:
      - ./data:/app/data
    environment:
      - ADMIN_PASSWORD=your_password
      - SESSION_SECRET=your_secret
    networks:
      - media

networks:
  media:
    external: true    # name of your existing Docker network

node -v

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc

# Install and use Node.js 23
nvm install 23
nvm use 23

git clone https://github.com/Lebbitheplow/diskovarr.git
cd diskovarr

npm install
cd server && npm install

cp server/.env.example server/.env
nano server/.env

npm run build

cd server && npm start

cd server && npm run dev

npm run dev

sudo nano /etc/systemd/system/diskovarr.service

[Unit]
Description=Diskovarr
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/home/your-user/diskovarr/server
ExecStart=/usr/bin/node server.js
Restart=on-failure
RestartSec=5
EnvironmentFile=/home/your-user/diskovarr/server/.env

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now diskovarr
sudo systemctl status diskovarr

cd /home/your-user/diskovarr
git pull
npm install
cd server && npm install
cd .. && npm run build
sudo systemctl restart diskovarr

First-Time Setup

After starting Diskovarr for the first time, follow these steps to get the core services connected. Once done, Diskovarr will be fully functional — optional integrations (Overseerr, Radarr, Sonarr, Riven, Agregarr) can be added any time from the Connections tab.

Admin Panel — General

The General tab contains app-wide settings: public URL, theme, library sync, logging, and the API key.

App Public URL

Enter the full external URL where Diskovarr is accessible (e.g. https://diskovarr.example.com). This is used when uploading a Discord bot avatar — without it, the avatar upload will fail. It does not affect Plex authentication.

Theme Color

Pick an accent color for the entire app. Changes apply immediately — all users see the new color on their next page load without a restart.

• Preset swatches — click any swatch to apply instantly
• Custom color picker — enter any hex value or use the color wheel
• Apply button — confirms your selection

Library Sync

Diskovarr maintains an in-memory library cache synced from Plex every 2 hours. The General tab shows the current state and lets you trigger a manual sync.

Verbose Logging

When enabled, Diskovarr writes detailed HTTP request logs including headers, query params, and response times. Useful for debugging connection issues.

# View live logs (systemd)
journalctl -u diskovarr -f

# Or if running directly
npm start 2>&1 | tee diskovarr.log

API Key

Generate a token for external API access (scripts, automation tools, etc.). The key is shown once — copy it immediately. You can regenerate at any time, which invalidates the old key.

• Eye button — toggle visibility of the masked key field
• Copy button — copies key to clipboard
• Generate / Regenerate — creates a new key (old key is immediately invalid)

Pass the key in requests using the header: X-Api-Key: your-key-here

Overseerr Compat API

Diskovarr exposes an Overseerr-compatible API at /api/v1/ so external apps that speak the Overseerr API can connect to it directly. Supported apps include DUMB (Riven request polling), Agregarr (collection auto-requests), and Homarr (media stats and request list widgets).

API Endpoint Reference

A collapsible table of public API endpoints is shown below the API Key section. It documents every endpoint's method, path, parameters, and purpose. See the full API Reference section in this documentation.

Admin Panel — Users

Manage all users on your server: request limits, auto-approve, elevated privileges, bulk actions, and cache controls.

Server Owner

Select which Plex user is the designated server owner. The owner's elevated privileges toggle is permanently locked — they cannot have admin access removed. Choose yourself or a trusted admin account.

Watchlist Mode

Controls how the Watchlist feature works:

• Plex Watchlist — reads and writes to the user's actual Plex watchlist. Requires the user to be connected via Plex OAuth.
• Diskovarr Playlist — Diskovarr manages its own per-user playlist independent of Plex. Useful if users don't use Plex's native watchlist.

Individual Season Requests

When enabled, TV show request dialogs show a checkbox list of individual seasons so users can request only specific seasons rather than the whole show. When disabled, TV requests are submitted for the full series.

User Table

Lists all known Plex users who have signed in. Columns:

• Checkbox — select for bulk operations
• User — avatar, username, and Plex user ID
• Watched — number of items in their Tautulli watch history
• Requests — total number of requests submitted
• Last Visit — when they last accessed Diskovarr
• Settings ⚙ — opens the per-user settings page (when Diskovarr Requests is enabled)

The table paginates at 10 users per page. Use the per-page dropdown (10 / 25 / 50) to show more. Pagination controls are always visible.

Bulk Edit

Select one or more users via the row checkboxes, then click Bulk Edit Settings to apply settings to all selected users at once. Each field has a three-state selector — No change means that field is skipped for all selected users, so only fields you explicitly set will be updated.

Bulk editable fields: request limit overrides (movies and TV seasons), auto-approve (movies and TV), elevated privileges (grant or revoke).

Cache Management

These buttons affect all users at once. Use when troubleshooting stale data:

Global Request Limits

Set defaults applied to all users. Individual users can have overrides set on their per-user settings page.

• Movies — check Unlimited for no limit, or enter a count and window in days (e.g. "3 movies per 7 days")
• TV Seasons — same format, counted per season requested (not per show)

Auto-Approve

When enabled, requests skip the queue entirely and route directly to the configured service (Overseerr, Radarr, Sonarr, etc.) without waiting for admin approval.

• Auto-Approve Movies — toggle for all movie requests
• Auto-Approve TV Shows — toggle for all TV requests

Per-user overrides can enable or disable auto-approve independently of the global setting.

Auto-Request Watchlist

When enabled, adding an item to the Diskovarr watchlist automatically submits a request for it. Works per-media-type:

• Auto-Request Movies from Watchlist
• Auto-Request TV Shows from Watchlist

Disable All Requests

A global kill switch in the Request Limits section. When toggled on, the Request button is hidden site-wide and any attempt to submit a request is blocked. Individual users can be granted a bypass via their per-user settings page (Override Global → enable requests for that user).

Admin Panel — Connections

Configure all external services. Each service follows the same pattern: toggle to enable/disable, enter credentials, Test, then Save. Saved values are stored masked (shown as ••••••••).

Use the sidebar links to jump to a specific service:

Default Request Service

Visible when two or more request services are enabled. Sets which service handles new requests by default. Users with access to multiple services can switch via the Advanced button in the request dialog.

Alternate Request App Access

Controls who sees the Advanced service selector button in request dialogs:

• All Users — any user can choose which service to route their request to
• Admin Only — only admins and elevated users see the alternate service option

Connection — Plex

Plex is required. It provides the library, user authentication via Plex OAuth, and poster images. All other features depend on this connection being healthy.

What you need

• The IP address or hostname of your Plex server
• Your Plex server's port (default 32400)
• Your Plex admin token — retrieved automatically via the Sign in button, or manually if preferred

Entering the connection

In Admin → Connections → Plex:

Getting your token — Sign in to Plex (recommended)

Click the Sign in to Plex button on the Connections → Plex page. A Plex OAuth window opens — sign in with the account that owns the server. Diskovarr retrieves the token automatically and fills it in. No digging through URLs required.

Getting your token — manually

If you prefer to paste the token directly:

1. Open Plex Web (app.plex.tv) and sign in as the server owner.
2. Click any movie or show → ⋮ menu → Get Info → View XML.
3. In the new tab's address bar, copy the value after X-Plex-Token= — that's your 20-character token.

Enter the address, port, and token, then click Test. A green success message confirms Diskovarr can reach your Plex server. Click Save.

Connection — Tautulli

Tautulli is required for personalized recommendations. It tracks what every user has watched on your Plex server — Diskovarr uses that history to score and rank titles for each person.

What is Tautulli?

Tautulli is a free, open-source monitoring and tracking tool for Plex. If you don't have it installed yet, grab it from tautulli.com — it runs as a Docker container or native service and takes about 5 minutes to set up. It must be pointed at the same Plex server you connected in the previous step.

Finding your Tautulli API key

Entering the connection

In Admin → Connections → Tautulli:

Click Test then Save. Once saved, Diskovarr will start pulling watch history for recommendations.

Connection — TMDB

The Movie Database (TMDB) provides metadata, poster art, trailers, cast info, and discovery data. The API is completely free for personal use — no credit card required.

What TMDB enables

• Diskovarr Requests tab — genre/trending discovery, personalized TMDB picks, request actions
• Item detail modals — genres, ratings, cast, director credits, synopsis, trailer embeds
• Search autocomplete — title suggestions in the nav bar search
• Season data — TV season counts and episode info in request dialogs

Without a TMDB key the Requests tab is hidden for all users. The home recommendation page still works since it reads from your existing Plex library.

Getting a free TMDB API key

Entering the connection

In Admin → Connections → TMDB, paste your key into the API Key (v3) field and click Test then Save. The Diskovarr Requests tab appears immediately for all users.

Connection — Overseerr

Overseerr (or Jellyseerr) handles the actual download trigger when a user submits a request in Diskovarr. It connects to your Radarr and Sonarr instances and manages approvals, quality profiles, and notifications on its own side. Use this if you already have Overseerr running — or use Radarr/Sonarr directly instead.

Getting your Overseerr API key

Entering the connection

In Admin → Connections → Overseerr:

Click Test then Save. Users will now see a request button on all items not in the library.

Connection — Radarr

Direct movie request routing without needing Overseerr. When a user's movie request is approved in Diskovarr, it's sent straight to Radarr which handles searching, downloading, and adding it to your library.

Getting your Radarr API key

Entering the connection

In Admin → Connections → Radarr:

Click Test to load quality profiles, select one, then click Save. Movies requested through Diskovarr will now be added directly to Radarr.

Connection — Sonarr

Direct TV show request routing. Works the same as Radarr but for TV series — when a TV request is approved, Diskovarr sends it to Sonarr which handles downloading and library management.

Getting your Sonarr API key

In Sonarr, go to Settings → General → Security. Your API Key is shown there — copy it.

Entering the connection

In Admin → Connections → Sonarr:

Click Test to load profiles, select one, then click Save.

Connection — DUMB / Riven

DUMB (Debrid Unlimited Media Bridge) is an all-in-one Docker stack that bundles 25+ media automation services — including Riven, Zurg, rclone, Radarr, Sonarr, Tautulli, Plex, and more — into a single, modular deployment. Riven is one component within DUMB responsible for media automation: it finds debrid-cached torrents and symlinks them into your library without downloading anything locally. Diskovarr connects to the Riven component inside DUMB (or a standalone Riven install) to route requests and provides an Overseerr-compatible bridge for automatic request polling.

What this connection does

• Request routing — approved requests from Diskovarr are sent to Riven (inside DUMB) which finds a cached torrent on your debrid service and adds it to your library automatically
• Overseerr-compatible bridge — Diskovarr exposes an Overseerr-compatible API endpoint so Riven's poller can pull approved requests on its own schedule
• Overseerr-compatible bridge — Diskovarr exposes an Overseerr-compatible API endpoint so Riven's poller can pull approved requests on its own schedule

Prerequisites

• DUMB running with the Riven service enabled (recommended), or a standalone Riven instance
• An active Real-Debrid (or All-Debrid) subscription — Riven uses debrid for cached torrent access
• Riven already configured and connected to your Plex library within DUMB

Step 1 — Connect Diskovarr to Riven

In Admin → Connections → DUMB/Riven:

Click Test then Save. Once saved, request routing to Riven is active.

Step 2 — Set up the DUMB request bridge (recommended)

The DUMB integration lets Riven automatically pull and process approved requests from Diskovarr without any manual intervention. Diskovarr exposes an Overseerr-compatible endpoint — configure Riven to point at it using the Overseerr Compat Key from Admin → General.

How the bridge works

In Pull mode, Riven periodically calls Diskovarr's /api/v1/request endpoint (Overseerr-compatible format). Approved requests appear with media.status=3 (PROCESSING). Riven picks these up and triggers downloads via your debrid service. When content becomes available, Riven calls PUT /api/v1/media/:id/available which Diskovarr uses to mark the request as fulfilled and send a "Request Available" notification to the requester.

Using Riven without DUMB

If you're running Riven standalone (not inside DUMB), the connection works exactly the same way — enter your Riven URL and follow the same bridge steps above. Request routing and Overseerr-compatible polling both function identically. DUMB is recommended because it manages Riven alongside all the supporting services (rclone, Zurg, Tautulli, etc.) in one place, but it's not a hard requirement.

Connection — Agregarr

Agregarr is a Plex collection manager that can automatically request missing items from your collections. Diskovarr provides an Overseerr-compatible API shim so Agregarr can send those requests to Diskovarr as if it were Overseerr — they show up in your request queue with a bot badge and go through the same approval and routing as user requests.

How it works

When Agregarr finds a movie or show that belongs in one of your Plex collections but isn't in your library, it sends a request to Diskovarr's /api/v1/ shim endpoint. Diskovarr processes it as a regular request, auto-approves it if your settings allow, and routes it to whichever download service you have configured (Overseerr, Radarr, Sonarr, or Riven). Each collection type gets its own service user account in Diskovarr (e.g. "TmdbAgregarr", "ImdbAgregarr") that appears in the request queue.

Setting up the connection

Settings reference

For more details on the Agregarr integration workflow, see Integrations — Agregarr.

Admin Panel — Notifications

Diskovarr can notify users and admins through multiple channels: the in-app bell, Discord (shared channel webhook and/or personal bot DMs), Pushover push notifications, and eight additional agents — Webhook, Slack, Gotify, ntfy, Telegram, Pushbullet, Email, and WebPush. All can be active simultaneously with independent settings and per-type toggles. Notifications include clickable hyperlinks that open the relevant item in Diskovarr. This page walks through setting up each one from scratch.

Broadcast Message

Type a message in the textarea and click Notify All Users. The message is delivered simultaneously to the in-app bell for all users, plus Discord and Pushover if configured. Broadcast bell notifications open a full-text modal when clicked rather than navigating away.

Notification Types

All notification services share the same 10 event types. Each service has its own independent set of checkboxes — you can enable "Request approved" on Discord but not Pushover, for example. The recipient column shows who receives each type:

Discord — Webhook Setup

A webhook posts notification embeds to a single Discord channel. It's the simplest way to get shared visibility — everyone in that channel sees new requests, approvals, and alerts. No bot account needed.

Step 1 — Create the webhook in Discord

Step 2 — Enter the URL in Diskovarr

Paste the webhook URL into the Webhook URL field in Admin → Notifications → Discord Webhook. Toggle the enable switch on, choose your notification types, then click Save. Click Test to verify a test embed arrives in the channel.

Webhook Settings Reference

Discord — Bot Setup

A bot sends personal DMs to individual users. Each user receives only notifications relevant to them (their own requests, their own issues) rather than a shared channel flood. Both webhook and bot can be active at the same time with independent notification type selections.

Step 1 — Create a Discord application and bot

Step 2 — Enter the token in Diskovarr

Paste the bot token into Bot Token in Admin → Notifications → Discord Bot. Enable the toggle, configure your notification types, and click Save. Click Test — if your own Discord User ID is set in your My Settings, you should receive a test DM from the bot.

Step 3 — Create a non-expiring invite link (recommended)

Users need to be in your Discord server to receive DMs. Create a permanent invite: right-click your server → Invite People → click Edit invite link → set expiry to Never → copy the link. Paste it into the Discord Server Invite Link field in Diskovarr. This shows a "Join Server" button on each user's My Settings page.

Step 4 — Users configure their Discord User ID

Each user who wants bot DMs must enter their own Discord User ID in My Settings → Discord. To find a user ID:

1. In Discord, go to User Settings → Advanced → enable Developer Mode
2. Right-click any user's name → Copy User ID (a numeric string like 123456789012345678)
3. Paste that into the Discord User ID field in Diskovarr My Settings → Save

Bot Settings Reference

Pushover Setup

Pushover delivers push notifications to iOS and Android phones. The Pushover app costs a one-time $5 per platform (free 30-day trial). Once set up, it's highly reliable and works even when Discord DMs are blocked.

Step 1 — Create a Pushover account and install the app

Step 2 — Enter keys in Diskovarr (Admin)

In Admin → Notifications → Pushover:

• Application API Token — paste the token from the application you just created
• User or Group Key — paste your personal 30-character user key from the pushover.net dashboard. This is the admin's own key — it receives admin-type notifications (new request, new issue, etc.).

Choose a notification sound, configure your notification types, click Save, then click Test. Your phone should buzz within a few seconds.

Step 3 — Users add their own Pushover key

Each user who wants Pushover notifications must enter their own Pushover User Key in My Settings → Pushover. They follow the same signup process (pushover.net account + app install), then copy their user key and paste it in Diskovarr. They do not need to create a separate application — they all share the same application token you created as admin.

Pushover Settings Reference

Pushover Groups (for multi-admin setups)

If you have multiple admins who all need to receive admin-type notifications (new request, new issue), create a Pushover Group: on pushover.net → Your Groups → Create a Group. Add each admin's user key to the group. Paste the group key into Diskovarr's User or Group Key field. All group members receive the notification simultaneously.

Webhook

Send notifications to any HTTP endpoint as JSON. Supports customizable JSON templates, custom headers, and variable substitution. Works with tools like n8n, Make, Home Assistant, and custom scripts.

Configuration

Slack

Send notification messages to a Slack channel using an Incoming Webhook. Uses Slack's Block Kit for formatted messages with emoji icons, description text, and clickable links.

Step 1 — Create a Slack Incoming Webhook

Step 2 — Enter in Diskovarr

Paste the webhook URL into Admin → Notifications → Slack. Enable the toggle, select notification types, and click Save. Click Test to verify a message appears in your Slack channel.

Gotify

Send notifications to a self-hosted Gotify server. Gotify delivers push notifications to your phone and desktop with minimal setup.

Configuration

Messages are sent in Markdown format with a clickable link to the relevant Diskovarr page.

ntfy

Send notifications via ntfy — a simple pub-sub notification service. Use the free public server (ntfy.sh) or self-host your own instance.

Configuration

Messages include a clickable link that opens directly in Diskovarr.

Telegram

Send personal notifications through the Telegram Bot API. Each user can configure their own Telegram chat ID to receive DMs from the bot. Supports MarkdownV2 formatting, inline buttons, and poster images.

Step 1 — Create a Telegram Bot

Step 2 — Configure in Diskovarr

Each notification includes an inline View in Diskovarr button. Users can optionally configure their own Telegram chat ID in My Settings → Telegram to receive personal notifications (approved, denied, available).

Pushbullet

Send push notifications through Pushbullet. Messages are delivered to your linked devices (phone, desktop app, browser extension). Supports note-style messages and link-type messages with clickable URLs.

Configuration

Users can optionally set their own Pushbullet access token in My Settings → Pushbullet to receive personal notifications on their own devices.

Email

Send notification emails via SMTP. Supports custom sender name, HTML-formatted messages with poster images, and TLS/STARTTLS. Users with email addresses on file receive personal notifications.

Configuration

Emails are sent as formatted HTML with poster images. Each notification includes a clickable button to open the relevant page in Diskovarr.

WebPush

Send native browser push notifications using the Web Push API. Works even when the browser tab is closed. Users subscribe from their browser — no server-side email or phone setup required.

How It Works

WebPush uses VAPID keys (auto-generated on first use) to authenticate push messages. Users subscribe from My Settings → WebPush by clicking Subscribe and allowing browser notifications. Each subscription is stored and used to deliver push notifications to the user's browser.

Configuration

Admins receive WebPush notifications for admin-type events. Regular users receive personal notifications for events relevant to them (request approved, available, etc.). Users manage their subscription from My Settings → WebPush.

Page — Diskovarr Home

The home page shows personalized recommendations from your own Plex library for each user, based on their watch history.

Hero Controls

Recommendation Sections

Four carousels load in parallel after the page opens:

• Top Picks for You — highest-scored items across all types, labeled "Personalized"
• Movies — top-scored movies from your library's extended TMDB neighborhood
• TV Shows — top-scored TV series
• Anime — TV items tagged with the "Anime" genre

Sections show a shimmer skeleton while loading and are replaced with live cards on fetch.

Cards

Each card shows a poster with title, year, and rating below. On hover:

• + Watchlist — saves the item to the user's watchlist
• ✕ Dismiss — hides the item from all future recommendations for that user
• Clicking the poster opens the detail modal

Detail Modal

Shows full item information. Sections:

• Backdrop hero image, poster thumbnail
• Title, year, IMDB and audience ratings
• Recommendation reason tags (e.g. "Similar to Breaking Bad", "Director match")
• Genre chips, overview/synopsis
• Cast and director credits
• Embedded YouTube trailer (if available)
• Play on Plex — opens the item in Plex Web
• Cast to TV — sends playback to a Plex player (TV, streaming stick, etc.) registered to your account. See Cast to TV for requirements and troubleshooting.
• + Watchlist / ★ In Watchlist — toggle watchlist membership
• Report Issue — opens the issue reporting flow

Recommendation Engine

The engine builds a scored list of items from your library for each user by:

• Fetching TMDB recommendations and similar titles for everything the user has watched
• Scoring each candidate using: TMDB similarity (40pts), shared director (30pts), shared actor (35pts), keyword overlap (25pts), same collection (30pts), shared studio (10pts), genre match (8pts/genre), same decade (8pts), high rating bonus
• Subtracting points for previously dismissed items
• Filtering out items already in the user's library

Caches are pre-warmed every 25 minutes per user in the background so the page loads instantly.

Page — Diskovarr Requests

Shows personalized picks from TMDB that are not yet in your library. Users can request titles directly from this page. Requires TMDB API key to be configured in Admin → Connections → TMDB.

Hero Controls

Sections

• Top Picks for You — highest-scored non-library items, "Outside Your Library" badge
• Movies — top-scored movie candidates
• TV Shows — top-scored TV candidates
• Anime — anime candidates (sourced from Japanese-language TMDB discover)
• Trending Movies — TMDB weekly trending movies not in your library
• Trending TV Shows — TMDB weekly trending TV not in your library
• Browse by Genre — grid of 18 genre tiles with gradient backgrounds and emoji icons; clicking a genre navigates to Search filtered to that genre
• Upcoming Movies — movies releasing in the future, "Coming Soon" badge; shown when 8+ items are available
• Upcoming TV Shows — TV shows releasing in the future, "Coming Soon" badge; shown when 8+ items are available

Genre Browse

A genre browse section displays clickable genre cards (Action, Comedy, Drama, Horror, etc.) with gradient backgrounds and emoji icons. Clicking a genre card navigates to the Search page filtered to that genre, showing all TMDB results for that genre not in your library.

Coming Soon

Coming Soon sections show upcoming movies and TV shows with release dates in the future. Each card displays a "Coming Soon" badge (or "Requested" if already requested). These sections help users discover and request content before it's released.

Request Badges & Buttons

TMDB Pipeline

Candidate discovery is optimized to minimize API calls:

• A shared candidate pool is pre-fetched once per unique region+language+mature combination across all users (8-hour TTL)
• Full item details (genres, cast, keywords, ratings, trailers) are cached in the database permanently once fetched
• Per-user scoring runs every 28 minutes in the background against the shared candidates
• Region and language preferences (set in My Settings) are applied to TMDB discover queries at fetch time

Page — Filter

Browse your own Plex library with advanced filters. All items shown are already in your library.

Filter Controls

Results & Pagination

Results load in a card grid. A Load More button at the bottom fetches additional pages. Clicking a card opens the same detail modal as the home page — library items show Play on Plex and Cast to TV buttons.

Items you've already watched display a small green checkmark badge on the poster corner.

Page — Search

Search across both your Plex library and TMDB simultaneously. Supports text search, genre-based browsing, and advanced filtering.

Nav Bar Search

The search input is always visible in the navigation bar on desktop. On mobile it collapses to a magnifying glass icon — tapping it expands a full-width overlay input.

As you type, TMDB autocomplete suggestions appear in a dropdown showing title, year, and type (Movie/TV). Select a suggestion or press Enter to go to the full search results page.

Search Results Page (/search?q=…)

• Results from your Plex library appear first with an "In Library" indicator
• Library items you've already watched show a small green checkmark badge on the poster
• TMDB results not in your library appear below with a Request or Coming Soon button
• Library items open the full detail modal including Cast to TV and Report Issue
• Non-library items open the request dialog
• Load More button fetches additional TMDB results
• Back button returns to the previous page or falls back to the configured landing page

Filter Section

When viewing search results or genre-browse results, a collapsible filter section lets you narrow down what's shown:

More Like This

When viewing search results or item details, a More Like This section shows similar titles based on TMDB recommendations and local metadata overlap. It scores candidates by shared directors, cast, genres, keywords, collections, and language — then re-ranks them so the most relevant results appear first. The Hide in Library toggle also applies to this section, so you can see only items you don't already have.

Page — Queue

The request queue shows all submitted requests. Regular users see their own requests ("My Requests"). Admins and elevated users see all requests ("Request Queue") with full approval controls.

Filter Tabs

All · Pending (with count) · Requested · Approved · Available · Denied — click any tab to filter the table. The Available tab shows approved requests whose title has already arrived in the Plex library.

Sortable Columns

Click any column header to sort the queue by that column. Click again to reverse direction. An arrow indicator (↑ or ↓) shows the active sort. Sortable columns: Title, User, Type, Age, Status. Sort state is server-side — applies across all pages of results.

Table Columns

• Title — poster thumbnail (52 × 78 px), title, year, rating. If a request was denied, the denial note appears below in red.
• User — requester's avatar and name (admin view only)
• Type — Movie (gold) or TV (blue) badge
• Age — relative time since request was submitted (e.g. "3 hours ago")
• Status — Pending / Requested / Available / Denied badge
• Actions — varies by status and role (see below)

For TV requests, season chips appear below the title: S1 S2 S3… For shows with more than 9 seasons selected, the list truncates to an ellipsis followed by the last 8.

Request Actions (Admin / Elevated)

All actions update the row in place — no page scroll or reload.

Pagination

25 / 50 / 100 items per page. The per-page preference is saved to localStorage and restored on next visit. Previous/Next buttons plus page indicator.

Page — Issues

Users report playback problems with library content. Admins manage and resolve them.

Reporting an Issue

Any library item's detail modal has a Report Issue button. Clicking it opens the issue form:

• Description — text area for the problem details
• Scope (TV only) — Entire Series / Specific Season / Specific Episode
• Season number (if Specific Season selected)
• Season + Episode number (if Specific Episode selected)

User View ("My Issues")

Shows the user's own reports with scope label, status badge, and a Details button. Filter by All / Open / Resolved / Closed.

Admin View ("Issue Reports")

Shows all reports from all users. Additional columns: poster, reporter name. Additional actions: Resolve, Close, Delete.

Status Badges

• Open (orange) — awaiting admin action
• Resolved (green) — admin has addressed the issue
• Closed (gray) — issue closed without resolution (e.g. user error, duplicate)

Details Modal

Shows full description, scope breakdown, reporter (admin view), status, and admin note. Contains a threaded comment section:

• Both user and admin can leave comments
• Admin comments send a notification to the reporter
• User comments send a notification to all admins
• Admin can delete any comment

Admin Actions

All actions update the row in place.

Page — Watchlist

A personal save list. Add items from any card or detail modal; remove them from the watchlist page.

Adding Items

The + Watchlist button appears on card hover overlays and in detail modals across all pages (home, explore, filter, search). Once added, the button changes to ★ In Watchlist.

Watchlist Page

Shows a grid of saved items with poster, title, year, and rating. Clicking a poster opens the same detail modal. The ✕ Remove button on each card removes it with a fade animation.

Auto-Request from Watchlist

If enabled in Admin → Users → Auto-Request Watchlist, adding an item to the watchlist automatically submits a request for it. This works per-media-type (movies and TV can be configured separately). Per-user overrides are available in the per-user settings page.

Cast to TV

Cast to TV lets you send playback of any library item to a Plex player (smart TV, streaming stick, Roku, Apple TV, etc.) directly from a detail modal. It works entirely through the Plex cloud relay — no local network access to the TV is required.

How It Works

When you click Cast to TV, Diskovarr performs three steps server-side:

1. Create a PlayQueue — Diskovarr calls your Plex server to create a PlayQueue for the chosen title. This tells Plex what content is about to play and where it lives.
2. Look up your player — Diskovarr calls plex.tv/api/v2/resources using your own Plex account token. This returns the list of Plex player clients registered to your account, along with their connection URIs. Relay connections (routed through plex.tv) are preferred over direct LAN connections so casting works regardless of network location.
3. Send playMedia — Diskovarr calls the player's relay URI with a playMedia command, again using your own token. Your Plex app on the TV receives the command and begins playback.

Requirements

Using the Cast Picker

1. Open any library item's detail modal (click a poster on the home page or filter page)
2. Click the Cast to TV button in the action row
3. A dropdown expands showing all Plex player devices registered to your account. If the list is empty, see Troubleshooting below.
4. Click the device you want to cast to. The button shows "Casting…" while the command is sent.
5. Playback starts on your TV. A confirmation toast appears in the corner.

Troubleshooting

Cast picker is empty — no devices listed

Devices appear but cast fails or nothing happens on the TV

Cast works for the server admin but not for friends

My Settings

Each user's personal preferences: region and language for TMDB discovery, landing page, and notification preferences. Accessible from the user menu (avatar button).

Content Preferences

Notification Preferences

Checkboxes for each notification type. Standard users see: Request Approved, Declined, Available, Issue Resolved, Issue Comment, Auto-Requested from Watchlist. Elevated users also see: New Request Pending, Auto-Approved, Processing Failed, New Issue Reported.

Discord

Pushover

Telegram

Pushbullet

Email

WebPush

Integration — Plex Real-Time Sync

Diskovarr maintains a persistent WebSocket connection to your Plex server — the same method Tautulli uses — to detect new library content in real time. No Plex Pass required. No setup needed.

How It Works

On startup, Diskovarr opens a WebSocket to /:/websockets/notifications on your Plex server. Plex pushes timeline events over this connection whenever items are added or updated. When Diskovarr sees a new library item, it:

• Invalidates the library cache
• Checks all pending requests against the new content
• Sends "Request Available" notifications to requesters whose titles just arrived

This happens within seconds of Plex finishing the scan — no polling interval, no Plex Pass subscription needed.

Verifying It's Connected

Check your Diskovarr service logs for:

Plex WebSocket connected

If it disconnects (e.g. Plex restarts), Diskovarr automatically reconnects with exponential backoff.

Integration — Agregarr Setup

Connect Agregarr to Diskovarr so collection-based auto-requests route through Diskovarr's queue instead of directly to Overseerr.

Step 1 — Get the Overseerr Compat Key

In Admin → General → Overseerr Compat API, enable the toggle and copy the Compat Key using the copy icon.

Step 2 — Configure Agregarr

In the Agregarr web UI, add an Overseerr source:

• Overseerr URL — your Diskovarr URL (e.g. https://diskovarr.example.com)
• API Key — the Compat Key from Step 1

What Happens

When Agregarr syncs a collection:

• Agregarr sends requests to Diskovarr's /api/v1/ shim (Overseerr-compatible)
• Diskovarr creates service user accounts per collection type (e.g. "TmdbAgregarr")
• Requests appear in the Diskovarr queue with a bot badge
• If auto-approve is enabled, they route to your configured service immediately
• If rate limits are hit, Diskovarr returns a silent 201 so Agregarr's sync continues uninterrupted

After Updating the Key

If you regenerate the Overseerr Compat Key (Admin → General), update it in Agregarr's source configuration and restart the Agregarr container. Note this also invalidates the key for any other connected apps (DUMB, Homarr) — update those too.

API Reference

All public API endpoints. Authenticate with a session cookie (browser) or the X-Api-Key: your-key header (external tools). Generate your API key in Admin → General.

Authentication

Recommendations & Discovery

Library & Search

Watchlist

Requests

Issues

Notifications & Settings

Plex Integration

Overseerr Compatibility Shim

The /api/v1/ endpoint exposes an Overseerr-compatible API for external tools (Agregarr, DUMB/Riven, Homarr). Authenticate with the Overseerr Compat Key from Admin → General using the header: X-Api-Key: your-compat-key. The shim maps Diskovarr's data model to Overseerr API format automatically.