Configuration¶

Reclaimerr is configured through General Settings, service settings, and a small set of environment variables for the runtime container or desktop process.

Core Settings Areas¶

• Media servers - connect Plex, Jellyfin, Emby, Radarr, and Sonarr
• Authentication - choose allowed Local, Media, and SSO login methods, configure OpenID Connect, and customize SSO labels
• General Settings - path mappings, move destinations, public application URL, fallback deletion, Leaving Soon, and default auto-delete review periods
• Tasks - schedule scans, tagging, syncs, and optional auto-deletion
• Notifications - configure Apprise destinations, and an instance-wide SMTP server so users can be notified at their account email address

Sonarr versions and episode ordering¶

Reclaimerr uses Sonarr's /api/v3 API for Sonarr v3, v4, and the v5 beta. Sonarr v5 retains this API but marks it deprecated. Read-only checks against v5.0.0.2569 verified series, episode inventory, files, and import dates; mutation contracts are covered by offline tests rather than live deletion tests.

Set Sonarr and your media servers to the same episode order. Reclaimerr recognizes aired/official, DVD, and absolute ordering. Plex show overrides take precedence over library defaults; Jellyfin and Emby use the series display order. Matching supported orders are allowed, including DVD. Other streaming or alternate order identifiers are treated as unknown until their numbering equivalence is supported.

Number-based cleanup is blocked when orders differ or cannot be verified. This includes season and episode actions, plus whole-show actions whose rules depend on watch data, episode inventory, or Sonarr import dates. The candidate's error identifies the affected instance. Correct the ordering, run Sync Media, and retry. Reclaimerr does not change server settings or translate historical episode numbers. Independent whole-series rules, such as title or year conditions, remain available.

Important Environment Variables¶

LOG_LEVEL is read once at startup and there is no in-app switch for it, so raising it means setting the variable and restarting the container. Confirm it took effect by looking for the Log level: LogLevel.DEBUG line the API logs on boot - if that line says LogLevel.INFO, the variable did not reach the container and debug lines will be missing no matter what else is configured.

Email notifications are configured under Settings - Notifications, in the Email server (SMTP) panel, which only administrators see. Enter the host, port, encryption mode (STARTTLS, SSL/TLS or none), optional credentials and a from address, then use Send Test Email to confirm it works. The password is encrypted at rest with ENCRYPTION_KEY and is never returned to the browser; leaving the field blank on a later save keeps the stored one. Once it is enabled, each user can add an Email destination from the same page, and it is delivered to the address on their account unless they enter a different one.

Application URL is configured in General Settings. It is used for Plex and OIDC callback generation behind a reverse proxy, and it is what lets notifications link back into Reclaimerr. When it is unset, notifications are still delivered but contain no links.

Login Background¶

Administrators can customize the instance-wide sign-in screen under Settings → General → Login background:

• Default rotating backgrounds keeps the existing media backdrops.
• Uploaded image uses one static JPEG, PNG, or WebP. Uploads can be up to 10 MB and 25 million pixels; they are resized to fit within 3840 × 2160 and stored under the configured static directory in login-backgrounds/.
• Custom image URLs replaces the default rotation with up to 50 direct HTTP or HTTPS image URLs, one per line. A single URL stays static; multiple URLs rotate in the listed order.

The rotation interval can be set from 5 to 300 seconds. Click Save login background to apply the selected source, URLs, and interval. Uploading or replacing a file stores it immediately; removing an active uploaded image restores the default backgrounds.

The dark overlay remains in place. Images that fail to load are skipped, and the default backgrounds are used if no custom image loads. URL images load directly in visitors' browsers, so their hosts must allow image embedding. Use HTTPS image URLs when Reclaimerr is served over HTTPS. Login artwork and configured URLs are available before sign-in.

Login Methods and Recovery¶

Administrators can choose Local, Media, and SSO under Settings → Authentication → Login Methods. All are allowed by default; Media and SSO only appear on the login page when their providers are configured. Disabled methods reject new sign-ins through the API as well as disappearing from the page. Existing sessions stay signed in. These controls do not change API-token access or trusted proxy authentication.

At least one configured method must remain allowed. Reclaimerr rejects settings that would remove every usable method, including disabling the last SSO provider or disabling/deleting the last media server when it is the only allowed method. Restore defaults selects all three methods; click Save to apply. Before disabling Local, test that your administrator account can sign in through an allowed provider.

If an external provider fails or your admin identity cannot sign in:

1. Set AUTH_FORCE_LOCAL_LOGIN=true in the process environment or the .env file loaded by Reclaimerr. For Docker Compose, add it to the service's environment or env_file, then recreate the container with docker compose up -d --force-recreate reclaimerr.
2. Restart Reclaimerr if running outside Docker and sign in with an existing local admin username and password. The override enables Local without changing saved methods or resetting credentials. If the password is lost, use the existing ADMIN_PASSWORD startup reset.
3. Under Settings → Authentication, restore Local or fix another method and click Save.
4. Remove AUTH_FORCE_LOCAL_LOGIN and restart/recreate again. A recovery notice remains visible while the override is active.

A trusted proxy that rejects requests before they reach Reclaimerr still needs its own recovery path. For an unrecognized proxy username, see FORWARD_AUTH_ALLOW_LOCAL_FALLBACK below; AUTH_FORCE_LOCAL_LOGIN does not bypass proxy identity checks.

Import Users from CSV¶

Users with Manage users permission can bulk-create accounts under Settings → Users → Import CSV.

1. Choose Download CSV Template.
2. Add one user per row, keeping the four columns in this exact order.
3. Upload the file and choose Preview CSV.
4. Correct any errors, upload the corrected file, and preview again.
5. Choose Import Users to create the accounts marked ready.

username,email,display_name,password
jane_doe,jane@example.com,Jane Doe,
localuser,local@example.com,Local User,temporary-password

Use UTF-8, comma-separated CSV, up to 1 MB and 1,000 users. Blank rows are ignored. Surround values containing commas with double quotes. Leading and trailing whitespace in values is trimmed.

New accounts have the User role, Request permission, and configured default page access. Roles and permissions cannot be supplied in this CSV.

Matching uses email first, ignoring case, then username. Existing accounts are skipped without changing their password, profile, or access. Duplicate usernames or emails within the CSV, ambiguous existing matches, and usernames belonging to a different email are errors. Any error blocks the entire import. The server checks matches again when importing.

A blank password creates an account without local password sign-in. The user must sign in through an enabled external method that matches that account, or an administrator must set a local password later. Media sign-in retains its existing email/username matching and identity linking behavior; CSV import itself does not verify or link external identities.

Passwords are hashed on import and omitted from preview responses. If you supply temporary passwords, the CSV contains them in plain text; distribute them securely and remove the file when finished.

Trusted Proxy Authentication¶

Reclaimerr can trust a username asserted by Authelia or another forward-auth reverse proxy instead of requiring a local sign-in. This is disabled by default, and it never creates accounts or grants roles: it only maps an asserted username onto an existing, active Reclaimerr user. When Local login is allowed in Authentication settings (or AUTH_FORCE_LOCAL_LOGIN recovery is enabled), local sign-in works for requests where the trusted proxy does not assert an identity.

FORWARD_AUTH_ENABLED=true
FORWARD_AUTH_USER_HEADER=Remote-User
FORWARD_AUTH_TRUSTED_PROXIES=172.18.0.4
# Optional: identity provider sign-out endpoint
FORWARD_AUTH_LOGOUT_URL=https://auth.example.com/logout

reclaimerr.example.com {
    route {
        # Strip any client-supplied identity header before authentication runs,
        # so it can never survive into the upstream request.
        request_header -Remote-User

        forward_auth authelia:9091 {
            uri /api/authz/forward-auth
            copy_headers Remote-User
        }
    }

    reverse_proxy reclaimerr:8000
}

Create the Reclaimerr user first, then enable the feature. The asserted username must match an existing Reclaimerr username exactly, including case. A mismatch produces a 401 on every request, plus a log line naming the asserted username.

You do not need a second account to line the two names up. An administrator can rename any existing user, including the initial admin, from Settings -> Users by editing the user and changing the Username field. Renaming does not sign the user out and keeps their reclaim history, since accounts are tracked by ID internally. If the renamed user signs in through the proxy, update the proxy to assert the new username as well.

If you get locked out, for example the feature was enabled before the matching user existed, set FORWARD_AUTH_ALLOW_LOCAL_FALLBACK=true and restart. Sign in locally, create the matching user, then remove the variable and restart again. While the variable is set, an admin notice stays visible in the sidebar as a reminder to turn it back off.

FORWARD_AUTH_TRUSTED_PROXIES takes a comma-separated list of direct proxy IPs and CIDRs: the address of the reverse proxy container or host itself, not the client behind it. It rejects both * and all-address ranges such as 0.0.0.0/0 or ::/0.

For a trusted-proxy session, the sidebar logout control only appears when FORWARD_AUTH_LOGOUT_URL is set, since signing out of the identity provider is the proxy's job, not Reclaimerr's. When it is unset, the logout control is replaced by a "Managed by SSO" label. This does not apply to a local session started through FORWARD_AUTH_ALLOW_LOCAL_FALLBACK recovery mode: that session gets the normal logout button regardless of FORWARD_AUTH_LOGOUT_URL.

Multi-Server Setup¶

• Pick exactly one media server as the main server.
• Keep all connected servers pointed at the same physical media library.
• Use path mappings if the media server paths do not match local paths.

The main server is the only source of library and file-version rows. Every other configured server is linked: it contributes watch state and same-media matches, but never library contents.

In Settings -> Media Servers, pick a type from the Server type list and choose Add server. Each server is configured in its own dialog -- name, base URL, API key or token -- and joins the list below once it saves, so a server is either fully configured or not there at all. The first server added becomes the main server automatically. Every server of the same type needs its own name, since a name identifies that server's libraries everywhere they are shown.

Changing which server is main is the Set as main action on any linked server's card, confirmed first because it starts a full resync. Edit reopens the same dialog for an existing server, and a linked server can be deleted from its card; the main server cannot be deleted or disabled while it holds that role.

Every library records the server it came from, and with more than one media server configured that server's name is shown beside it -- in a rule's Library picker, on candidate and media views, and in the reason a rule gives for matching. Two servers can each hold a library called Movies, and the provider logo alone does not say whose. With a single media server the name is left off, since there is nothing to tell apart.

Changing which server is main replaces the library list with the new server's. Rules scoped to a library the new server does not have are reported as stale in the sidebar rather than silently retargeted -- which matters most for Jellyfin and Emby, where a library's id is derived from its path and two servers holding a library at the same path report the same id.

Each media server card in Settings -> Media Servers has its own Sync button and reports when that server was last synced. Syncing the main server runs the full media sync (libraries, movies, series, then every linked server). Syncing a linked server refreshes only that server's watch data and supplemental matches, so it neither waits on nor blocks the others. The dashboard shows each server's own last-sync time, labelled main or linked.

Multiple Seerr Instances¶

Radarr, Sonarr and Seerr each support several named instances, added from the Instance selector at the top of their settings tab. A request frontend usually sits beside each media server, so an Overseerr and a Jellyseerr can be configured side by side.

Every Seerr instance is queried for the same question and the answers are combined: a title counts as requested if any instance holds a request for it, and its request age is that of the newest live request on any instance. Deleting media clears the request and media entry on every configured instance.

Requesters are identified per instance, because a Seerr user ID only names a person within the Seerr that issued it. Rules and requester watch mappings therefore record instanceId:userId rather than a bare number, and the same person with an account on two Seerrs counts as two requesters. See Rules.

Disabling Or Deleting Offline Services¶

Service configuration changes do not require the external service to be online. An existing Radarr, Sonarr, Seerr, Tautulli, Tracearr, Jellyfin, Emby, or Plex configuration can be disabled or deleted while that service is unreachable.

Tracearr Playback History¶

Tracearr requires its stable public API v2, available in Tracearr 2.0.0 and newer. Add the Tracearr base URL and a public API key, choose Discover servers, then confirm the Tracearr server that belongs to each configured Plex, Jellyfin, or Emby server. One Tracearr instance can cover multiple media servers.

A binding selects the single durable history provider for that media server: Tracearr replaces Tautulli for a bound Plex server and Playback Reporting for a bound Jellyfin or Emby server. Reclaimerr never combines those durable event streams or silently falls back when the selected Tracearr source is offline. Jellyfin and Emby native current-watch snapshots remain complementary and are still used where applicable. Remove a binding to return to the prior durable provider; retained events are remapped without double-counting.

• Disable keeps the saved URL, credentials, and related configuration for later use.
• Delete permanently removes the service configuration without contacting the external service.
• Enabling a service or saving a new enabled configuration still requires a successful connection test.
• The active main media server cannot be disabled or deleted. Assign another configured media server as main first.

Deleting a Radarr or Sonarr instance also performs local dependency cleanup:

• stored media references for that instance are removed;
• the instance is removed from explicitly assigned rules; a rule is disabled only when that removal leaves it with no selected ARR instances;
• path mappings scoped only to that instance are removed.

The Settings page reports when dependent rules or path mappings were changed. Review any disabled rules before enabling them again and select the intended ARR instances.

Safety Settings Worth Reviewing¶

• Allow Media Server Fallback Deletion - controls whether Reclaimerr may delete through the media server. It does not stop Reclaimerr keeping the library in step: after Radarr, Sonarr, or Reclaimerr itself removes files, the media server is always told to re-check the affected path, which is a read-only scan and deletes nothing. See Deletion Flow.
• Default ARR Delete Behavior
• Add Arr Import List Exclusions on Delete
• Default Auto-Delete Review Periods
• Warn requesters before deletion
• Move Destination Folders

Resetting The Admin Password¶

Set ADMIN_PASSWORD in the environment, start Reclaimerr, sign in with the new password, then remove ADMIN_PASSWORD again.

If an admin account already exists, Reclaimerr resets that account's password on startup. If no admin account exists yet, Reclaimerr creates the initial admin account with that password.