Quick Navigation

Episeerr is an intelligent episode management system that automates content delivery and cleanup for Sonarr-managed TV shows.

Ways to Manage Episodes:

Accessing Setup Page

URL: http://your-server:5002/setup

Or click "Setup" in the sidebar

Required Services

Optional Services (For Automation)

Setup Page Features

• Test Connections: Verify URLs and API keys before saving
• Quick Links: Auto-populate sidebar links to configured services
• Database Storage: Configuration persists across container restarts
• No .env needed: Fresh installs can configure everything via GUI
• Migration Support: Existing .env values appear as defaults

After Setup

1. Configure your services on the Setup page
2. Test each connection (green checkmark = success)
3. Save configuration
4. Check Quick Links in sidebar - they should auto-populate
5. Set up webhooks (see Webhook Setup section below)
6. Create your first rule!

Before using Episeerr, you need to configure Sonarr and set up a default rule.

Step 1: Sonarr Delay Profile

How to Set Up Delay Profile in Sonarr:

1. Go to Sonarr → Settings → Profiles → Delay Profiles
2. Click Add New Delay Profile or edit existing
3. Set delays:
   • Usenet Delay: 999999 minutes (essentially infinite)
   • Torrent Delay: 999999 minutes (essentially infinite)
4. Set Tags: episeerr_[rule_name] and/or episeerr_select
5. Save

Step 2: Create Your First Rule

1. Go to Admin Panel
2. Scroll to Rule Management
3. Click Create New Rule
4. Configure:
   • Rule Name: e.g., "Default Weekly Shows"
   • Get: 1 episode
   • Keep: 0 or 1 episodes
   • Grace Unwatched: 7 days
   • Grace Watched: 3 days
   • Dormant Timer: 30 days
5. Save

Step 3: Add Shows to Episeerr

Three paths — pick what fits your workflow:

Step 4: Set Up Webhooks

Configure webhooks for automation (see Integration section below for details):

• Sonarr webhook: ✅ REQUIRED - http://your-server:5002/sonarr-webhook
• Jellyseerr/Overseerr: ✅ REQUIRED if using *seerr
• Tautulli/Jellyfin: ⚙️ OPTIONAL - For viewing-based automation

Rules define how episodes are managed for different shows. Each rule has four main settings:

Grace periods free up space from inactive shows while preserving your position so you can always resume where you left off.

All deletions go through an approval queue first - giving you full control before anything is removed.

How It Works

1. Cleanup Runs: Scheduled cleanup identifies episodes for deletion based on your rules
2. Queued for Review: Episodes are added to pending deletions (not deleted)
3. You Review: Visit the Pending page to see what would be deleted and why
4. You Decide: Approve (deletes immediately) or Reject (caches for 30 days)

Review Options

What You See

Each pending deletion shows:

Configuring Dry Run Mode

Dry run can be enabled at two levels:

Notifications

The navigation badge shows combined pending items:

• Pending Requests: Episode selection requests
• Pending Deletions: Episodes awaiting approval
• Badge: Shows total count of both

Best Practices

Three paths into Episeerr — choose based on where you're adding from:

External Tag-Based Workflows:

Auto-Assign (Separate Feature):

Jellyseerr/Overseerr Integration:

Tags are automatically created and managed by Episeerr. You don't need to manually create or maintain them.

How Tags Work:

1. When you create a rule called "binge_watcher":
   • Episeerr creates episeerr_binge_watcher tag in Sonarr automatically
   • Tag is added to Sonarr's delay profile (if configured)
2. When series is assigned to that rule:
   • Episeerr applies episeerr_binge_watcher tag to the series in Sonarr
   • Tag indicates which rule manages this series
3. If you manually change the tag in Sonarr:
   • Episeerr detects the drift (on next watch, cleanup, or startup)
   • Automatically moves the series to the correct rule in config
   • Your manual tag change becomes the new source of truth
4. When you delete a rule:
   • Tag removed from all series
   • Tag removed from Sonarr entirely
   • Tag removed from delay profile

Drift Detection:

Episeerr checks for tag mismatches in 4 places:

What Gets Detected:

Example Workflow:

Rule Descriptions:

Add optional descriptions to rules to document their purpose:

• Hover over rule names to see descriptions as tooltips
• Helps organize and understand multiple rules
• Examples: "Weekly shows I'm actively watching", "Binge-watching mode - get full seasons"

Supported Services:

Webhook URL:
            http://your-server:5002/webhook

            Trigger: Watched
            (set % threshold in Tautulli
            Settings → General)

Configure in:
            Integrations → Plex
            → Watch Detection

            Modes: Scrobble |
            Stop+Threshold |
            Polling

Webhook URL:
            http://your-server:5002/api/integration/jellyfin/webhook

            Trigger: (depends on mode)
            See full guide below

Webhook URL:
            http://your-server:5002/sonarr-webhook

            Trigger:
            On Series Add

Delay profiles tell Sonarr to wait before downloading. For episeerr_select tagged shows, this holds all downloads until you confirm your selection in Episeerr.

Setup:

1. Sonarr → Settings → Profiles → Release Profiles → Add New
2. Name: Episeerr Episode Selection Delay
3. Delay: 10519200 (20 years)
4. Tags: episeerr_select
5. Save

Name: Episeerr Managed
Usenet/Torrent Delay: 999999 minutes
Tags: episeerr_[each_rule_name]

Auto-assign is a separate feature from tags - it automatically adds new shows to your default rule when they're added to Sonarr WITHOUT any tags.

How It Works:

Tags and Auto-Assign Work Together:

When to Enable Auto-Assign:

How to Enable/Disable:

1. Go to Settings (in sidebar)
2. Find Global Storage Gate card at top
3. Check/Uncheck "Auto-assign new series"
4. Click Save Global Settings

Workflow Comparison:

Common Issues:

Q: Which webhooks do I need?

A: It depends on your setup:

• Sonarr webhook: ✅ REQUIRED - Detects new series and processes tags (episeerr_[rule_name]/episeerr_select)
• Jellyseerr/Overseerr webhook: ✅ REQUIRED if you use *seerr - Captures requested seasons for proper automation
• Tautulli or Plex native webhook: ⚙️ OPTIONAL - For viewing-based automation (TV: auto-get next episode; Movies: update watchlist status). Choose one, not both.
• Jellyfin webhook: ⚙️ OPTIONAL - Same as above for Jellyfin users

Without viewing webhooks, you can still use manual selection and time-based cleanup rules.

Q: Can I use multiple rules?

A: Yes! Create different rules for different types of shows (weekly vs binge, kids vs adults, etc.)

Q: What happens if I don't set grace periods?

A: Without grace periods, episodes are deleted immediately based on Keep settings only.

Q: Can I test rules without actually deleting?

A: Yes! Enable Dry Run Mode in Admin → Global Settings, or set it per-rule.

Q: How do I know what's being deleted?

A: Check Admin → View Logs → cleanup.log for detailed deletion logs.

Q: What is "Pending Deletions"?

A: A safety system that queues all deletions for your review before executing them. When dry run mode is enabled (default), cleanup operations add episodes to a pending queue instead of deleting immediately. You review the queue and approve or reject each deletion.

Q: Why aren't episodes being deleted?

A: Check if dry run mode is enabled (Admin → Scheduler → Global Dry Run Mode). When enabled, all deletions go to the Pending page for review. This is the default behavior for safety. Review and approve deletions from the Pending page, or disable dry run if you want automatic deletion.

Q: What happens if I reject an episode deletion?

A: The episode is removed from the pending queue and cached for 30 days. It won't appear in pending deletions again during that time. After 30 days, if cleanup rules still target it, it will reappear. For permanent protection, create a rule with no cleanup parameters.

Q: Can I approve/reject multiple episodes at once?

A: Yes! You can approve or reject at multiple levels:

• Individual episodes (one at a time)
• Entire seasons (all episodes in that season)
• Entire series (all pending episodes for that show)
• Selected episodes (check boxes and bulk approve/reject)

Q: What's the difference between global and per-rule dry run?

A:

• Global dry run: Affects ALL rules - all deletions are queued
• Per-rule dry run: Affects only that specific rule - lets you test individual rules
• Either one enabled: Deletions are queued for approval

Use global dry run when learning Episeerr, per-rule dry run when testing changes to specific rules.

Q: Can different family members watch different seasons?

A: Yes! Use "Grace Scope: Per Season" in your rule settings.