cplieger/seadex-scout repository overview

⁠seadex-scout

A report-only watcher that compares your Sonarr/Radarr anime library against SeaDex⁠ (the community-curated index of the best anime releases) and tells you, per title, when SeaDex recommends a better release than the one on disk. It never downloads, grabs, or touches a torrent client: it tells you what to go get, and you decide.

One image and one config file give you three things:

1. Findings on the log (always on): the daemon compares your library to SeaDex and logs a warn line when a better release exists than the one on disk. You turn those lines into Loki/Grafana alerts (see Alerting⁠); the app ships no notifier of its own.
2. An on-demand report: a season-by-season audit of how your whole library lines up with SeaDex, written as Markdown and JSON. See The report⁠.
3. An optional Torznab feed⁠: publishes SeaDex's picks for Sonarr/Radarr to grab through their own engine. It stays off until you configure it, and it is the only automation path: seadex-scout itself still never grabs, the arrs do.

⁠The problem

To keep an anime library aligned with SeaDex by hand, you open releases.moe, look up each show, and compare your files against the recommendation. seadexarr⁠ automates the lookup, but two gaps matter for a storage- and bandwidth-conscious library:

• Its only notifier is Discord, so it cannot alert through Loki and Grafana.
• Its filters cannot keep encodes and drop remuxes. For a library that prefers a good x265 encode over a 40 GB remux, that distinction is the whole point.

seadex-scout closes both gaps and nothing more.

⁠What it does

On start, and every 24 hours after that, seadex-scout runs one full pass:

1. It walks the Sonarr/Radarr anime library (with arr-side tag include/exclude) and fingerprints each item's current release: group, resolution, codec, remux-vs-encode, and dual-audio.
2. It matches each SeaDex entry to a library item by AniList ID through the Fribb anime-lists⁠ ID bridge, with an AniList title fallback for the entries that do not map.
3. It filters SeaDex's recommended releases by your preferences (remux policy, AnimeBytes on or off, dual-audio).
4. It compares the surviving recommendation against what you have and emits a warn log line when SeaDex has something better.

Between two full passes, a cheap tick runs every poll_interval. It asks SeaDex what changed in the last 48 hours and compares only those entries against the cached library. Upstream load then tracks how often SeaDex changes, not how often you poll. See Scheduling⁠.

When the Torznab feed⁠ is configured, the same pass rebuilds it from that one SeaDex fetch, so a finding and what the arrs can grab from the feed always reflect the same refresh.

⁠Pull

docker pull cplieger/seadex-scout:latest

Also published to ghcr.io/cplieger/seadex-scout with identical images and tags. Release versions are tagged vX.Y.Z alongside latest.

⁠Quick start

# Example compose for seadex-scout. See the README for all configuration options and hardening.
services:
  seadex-scout:
    image: ghcr.io/cplieger/seadex-scout:latest
    container_name: seadex-scout
    restart: unless-stopped
    # PUID/PGID come from .env; ./config must ALREADY be owned by this uid, or the
    # first-boot starter write fails and unless-stopped retries the failure forever.
    user: "${PUID:-1000}:${PGID:-1000}"

    # The first boot writes /config/config.yaml reading these. A key-only entry passes
    # the .env value through and leaves an unset variable unset, so Radarr stays off
    # until RADARR_URL is set. See README "Configuration reference".
    environment:
      - "SONARR_URL=http://sonarr:8989"  # where seadex-scout reaches Sonarr
      - SONARR_API_KEY  # Sonarr's Settings -> General -> API Key, from .env
      - RADARR_URL  # set both RADARR_* to add Radarr
      - RADARR_API_KEY
      - SEADEX_SCOUT_FEED_KEY  # the SEADEX_SCOUT_* keys serve the Torznab feed once config.yaml references them; see README "Security"
      - SEADEX_SCOUT_PROWLARR_KEY
      - SEADEX_SCOUT_AB_PASSKEY
    volumes:
      - "./config:/config"  # config.yaml, state, and the reports dir

⁠Documentation

• Full documentation⁠ — configuration, behavior, security
• Torznab feed setup⁠
• Contributing⁠
• Releases and changelog⁠

⁠License

GPL-3.0-or-later. Linking arrapi⁠ (GPL-3.0-or-later) makes seadex-scout GPL-3.0-or-later. See LICENSE⁠. The image carries the license text of every bundled component under /usr/share/licenses/.

Third-party attributions are in THIRD_PARTY_NOTICES.md⁠.