Mediastarr runs a search cycle on a configurable schedule. Each cycle it fetches missing and cut-off content from all enabled Sonarr and Radarr instances, applies filters, selects items randomly for even coverage, and sends the search command to the arr API.

Cycle flow

• Ping all instances — offline instances are marked and skipped
• Purge expired cooldown — items older than cooldown_days become searchable again
• Hunt each instance — missing first, then upgrades, up to max_searches_per_run per instance
• Wait — configured interval ± jitter before the next cycle
• Maintenance windows — search pauses silently during configured windows (re-checks every 60s)

Filters (applied per item)

• Upcoming — unaired episodes and unreleased movies are always skipped automatically
• IMDb rating — global threshold or per-service override (0 = off)
• Target resolution — upgrades skipped if current quality already meets the target
• Cooldown — items searched within cooldown_days are skipped
• Daily limit — global and per-instance; search stops when either is reached

Completed milestones

• ✅ v1.0 — First working Sonarr search automation
• ✅ v2.0 — Radarr support, multi-instance, cooldown system
• ✅ v3.0 — Discord notifications with rich embeds
• ✅ v4.0 — SQLite history, daily limits, random selection
• ✅ v5.0 — First-run wizard, IMDb filter, quality target, jitter
• ✅ v6.0 — Full UI redesign, 4 themes, German/English, CSRF protection
• ✅ v6.4.0 — Statistics page, Charts (instance, year, donut, timeline)
• ✅ v6.4.1 — Per-instance daily limits, config export/import, public API mode
• ✅ v6.4.2 — Sonarr/Radarr stats filter tabs, live console page
• ✅ v6.4.3 — Skip upcoming/unreleased content, configurable log rotation
• ✅ v6.4.4 — Maintenance windows, rich series embeds, Discord embed fixes
• ✅ v6.4.5 — Central VERSION file, Huntarr comparison text, homepage badge
• ✅ v6.4.6 — Console dual-output fix, startup version fix, per-instance upgrade toggle, improved logging, mobile language selector, help page redesign, stats layout fix
• ✅ v7.1.12 — Subpfad-Routing-Fix: PrefixMiddleware ersetzt ProxyFix, API-Fehler auf Englisch (#54 Nachfolge)
• ✅ v7.1.11 — Subpfad/Base-URL-Support (MEDIASTARR_BASE_URL, schließt #54)
• ✅ v7.1.10 — History: expandable rows, Deep-link Sonarr/Radarr, search duration, status icons; Jitter up to 24h
• ✅ v7.1.7 — Kubernetes deployment manifests (Deployment, Service, PVC, Ingress, kustomize)
• ✅ v7.1.6 — Bug #52 (dashboard mixed language: Tageslimit/Verlauf), font readability (Inter), Codex handover
• ✅ v7.1.5 — FAQ page (DE+EN, accordion, 11 Q&As, language-aware)
• ✅ v7.1.4 — Bug #51 (EN translation), dashboard stats freeze, CodeQL #12+#13, tooltips
• ✅ v7.1.3 — Bug #50 (webhook URL vanishes), Bug #49 (Discord update card button misplaced)
• ✅ v7.1.2 — UI redesign (settings sections, light theme), export/import fix, dashboard update badge, Discord update toggle, sidebar update indicator
• ✅ v7.1.1 — Bug #47 Discord v6 fix, AES-256 encryption, tooltips (#48), Docker-update-safe migration
• ✅ v7.1.0 — Stalled download monitor (#46), API key censoring (#41), CodeQL security fixes #7/#8/#9
• ✅ v7.0.5 — Tag chips persist (no re-render on poll), tag filter per instance (#37), separate Discord webhooks (#38), webhook trigger endpoint, log spam fix, Chrome flag emoji fix
• ✅ v7.0.4 — Feature #36: tagging (global + per-instance), page size 500→2000
• ✅ v7.0.3 — Bug #33/#34/#35 upgrades/toggles/Discord, settings revert fix, season dedup, 10-field sync
• ✅ v7.0.2 — Skip items no longer consume slots; should_search() key fix
• ✅ v7.0.1 — EN translations, jitter in minutes, per-type global daily limits
• ✅ v7.0.0 — Structured logging system: ms_log() / MSLog v2 with configurable DEBUG/INFO/WARN/ERROR, Docker format [DATE TIME] [LEVEL] msg, Settings UI

Planned

• ⬜ Webhook endpoint to trigger a cycle from external automation
• ⬜ Push via Gotify / Apprise (alternative to Discord)

• Password — set MEDIASTARR_PASSWORD env var to require login on all routes
• CSRF tokens — every POST/PATCH/DELETE requires a valid token issued at login
• Brute-force lockout — 10 failed logins → 5-minute IP block
• API keys never exposed — /api/state always strips all api_key fields
• Config permissions — config.json is chmod 0600 on every save
• SSRF protection — instance URLs are validated against private IP ranges before any request
• Security headers — X-Frame-Options, X-Content-Type-Options, Referrer-Policy, CSP on all responses
• Public API mode — /api/state can optionally be read-only public for external tools; API keys still never included

v7.1.12 — 2026-04-05

• Changed — Settings redesign: tabs now use named sections with icon badges; form labels readable (no all-caps); inputs taller with focus ring; light theme sidebar/topbar white background fixed
• Add — Dashboard update badge; sidebar version indicator; Discord "Update available" card with notify_update toggle; /api/state now includes version field
• Fix — exportConfig() missing; importConfig() missing async + CSRF header; cards blank due to _CURRENT_VERSION JS reference; Discord update toggle not persisting; update preview dummy versions; demo link removed from sidebar

v7.1.1 — 2026-04-01

• Fix — Bug #47: Discord test showed "v6"; AES-256 encryption for API keys/webhooks (#41); tooltips for all settings fields (#48); SECURITY.md updated

v7.1.0 — 2026-04-01

• Add — Feature #46: Stalled Download Monitor — detects stuck downloads via Sonarr/Radarr queue API; configurable threshold (minutes) and action (new search / Discord warning only); global toggle + per-instance override
• Add — Feature #41: API key censoring — all 32–128 char strings masked in activity log; API keys and webhooks never returned in /api/state
• Fix — CodeQL #8/#9: _safe_ping_msg() allowlist ensures only known-safe strings are returned from ping endpoints (no exception taint)
• Fix — CodeQL #7: URL redirect validation hardened with urlparse to fully block open redirect attacks

v7.0.5 — 2026-03-30

• Fix — Tag toggle and tag chips no longer reset every 4 seconds; instance cards are no longer re-rendered on each poll cycle — only on tab open or after save/add/delete
• Fix — Tag global toggle now correctly persists via _tagGlobalEnabled variable (was reading stale DOM class)
• Add — Feature #37: per-instance tag filter — load tags from Sonarr/Radarr, select one or more, only matching items are searched
• Add — Feature #38: separate Discord webhooks for Sonarr and Radarr (optional, falls back to main webhook)
• Add — Webhook trigger endpoint POST /api/webhook/trigger for external automation
• Fix — Log rotation spam (#39): only reconfigures when values actually change
• Fix — Radarr/Sonarr add form pre-filled with default name (#40)
• Fix — Flag emojis replaced with CSS badges for Chrome on Windows
• Fix — Discord tab now shows 💬 emoji
• Add — README: full API reference table (EN + DE)

v7.0.4 — 2026-03-27

• Add — Feature #36: tagging — after each search, Mediastarr adds a configurable tag to the series/movie in Sonarr/Radarr; global toggle + per-instance 3-state override (Global/On/Off)
• Fix — Page size increased 500 → 2000 for wanted/missing and wanted/cutoff

v7.0.3 — 2026-03-26

• Fix — Bug #33: upgrade search never ran (global + per-instance toggle logic fixed)
• Fix — Bug #34: per-instance upgrade toggle not saved to config
• Fix — Bug #35: Discord toggles reverted on general settings save
• Fix — Settings reverted every 4 seconds (_configDirty guard added)
• Fix — 10 settings fields not synced back to DOM after poll
• Fix — Season/Series mode: eliminated duplicate SeasonSearch/SeriesSearch per cycle
• Fix — Upgrades now respect the configured search mode

v7.0.2 — 2026-03-26

• Fix — Skip items no longer counted against search slots; should_search() reason key mismatch fixed ("daily_limit" → "daily")

v7.0.1 — 2026-03-26

• Fix — Missing EN translations in Sonarr/Radarr tabs; log level dropdown; jitter changed to minutes
• Add — Per-type global daily limit (Sonarr + Radarr separately)

v7.0.0 — 2026-03-26

• Logging-System — ms_log(level, service, action, item): schreibt in Docker-Console, Logdatei und UI-Aktivitätslog
• 4 Level — DEBUG | INFO | WARN | ERROR · konfigurierbar in Einstellungen → Allgemein
• Docker-Format — [2026-03-26 14:32:10] [INFO] [Sonarr] Missing searched: Breaking Bad S01E03
• Helfer — ms_debug(), ms_info(), ms_warn(), ms_error()
• MSLog v2 — Timestamp-Format, MSLog.log(), Level in sessionStorage gespeichert

v6.4.6 — 2026-03-26

• Fix — Startup log showed v6.3.8; now uses current version dynamically
• Fix — Console empty in both Settings tab and standalone page; refactored to write to both outputs simultaneously
• Fix — Help page German translation broken; CSS class-based language switching
• Fix — Mobile language selector invisible; persistent fixed toggle added
• Add — Per-instance upgrade toggle (search_upgrades, default off)
• Add — Improved logging: run_now trigger, config save events
• Add — Help page redesigned as single scrollable page (no tabs)
• Add — Stats charts all full-width; All/Sonarr/Radarr filter preserved

v6.4.5 — 2026-03-26

• Add — Central VERSION file — single source of truth for all components
• Add — Huntarr comparison text restored in README and Help page (DE + EN)
• Fix — Homepage badge version

v6.4.4 — 2026-03-25

• Add — Scheduled maintenance windows (up to 10, overnight support, yellow banner)
• Fix — Series Discord embeds: poster, fanart, multi-source ratings

v6.4.3 — 2026-03-25

• Add — Skip upcoming / unreleased content automatically
• Add — Configurable log rotation (size + backups) in General settings
• Fix — Console feed field mapping, stats tab theme, settings full-width

v6.4.2 — 2026-03-25

• Add — Sonarr / Radarr filter tabs on Statistics page
• Add — Live Log Console page with level filter, search, auto-scroll
• Fix — History titles truncated; Discord embed missing series title

v6.4.1 — 2026-03-24

• Add — Per-instance daily limits
• Add — Config export / import as JSON
• Add — Public API mode (/api/state without auth)

Earlier versions

v6.4.0 — Statistics page · v6.0 — Full UI redesign, themes, i18n, CSRF · v5.0 — Setup wizard, IMDb filter, jitter · v4.0 — SQLite history, daily limits · v3.0 — Discord embeds · v2.0 — Radarr, multi-instance · v1.0 — First release

Independent project, built from scratch. Not affiliated with Huntarr.

# Anyone on your network could run this against a stock Huntarr install:
curl -X POST http://huntarr:9705/api/settings/general   -H "Content-Type: application/json"   -d '{"proxy_enabled": true}'
# → Full config dump: Sonarr API key, Radarr API key, Prowlarr API key — all in cleartext

What about the forks?

Community forks have appeared, but they inherit the same codebase. As the security researcher noted: "Fixing 21 specific findings doesn't fix the process that created them."

How Mediastarr is different

Mediastarr was built independently from scratch — with security as a foundation, not an afterthought:

• No unauthenticated write access — every state-changing route is protected by session auth and CSRF tokens
• API keys never in responses — stripped at the serialisation layer in /api/state; cannot be leaked even if session auth is bypassed
• Input validation everywhere — safe_str(), validate_url(), SSRF protection on all URL inputs
• Config permissions — config.json chmod 0600 on every write
• CSRF tokens — every POST/PATCH/DELETE requires a valid token
• Brute-force lockout — 10 failed logins → 5-minute IP block
• Security headers — X-Frame-Options, X-Content-Type-Options, Referrer-Policy, CSP on all responses
• Actively maintained — report issues via Discord or GitHub private advisory

The full audit findings: github.com/rfsbraz/huntarr-security-review (Feb 2026).