From 316fa13d8986202f01ca746db9130bc1c7b92999 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 6 Jun 2026 17:24:26 +0000 Subject: [PATCH 1/7] Initial plan From c793a3264913aa990533244a713cd8cf977aeae7 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 6 Jun 2026 17:29:50 +0000 Subject: [PATCH 2/7] docs: add download client configuration section --- docs/Configuration.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/Configuration.md b/docs/Configuration.md index 5fb37d0a..cb12f6c3 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -136,6 +136,30 @@ Sonarr's configuration is required to use its parameters in rules and to remove | Base URL | The URL base configured in Sonarr, if one is set | | API key | The API key from Sonarr settings | +## Download Client + +:::note +The separate `Settings -> Download Client` page only appears once Radarr or Sonarr is configured. +::: + +When media is removed through Radarr or Sonarr, Maintainerr can remove the matching completed download (and optionally its data) from your download client. The download is matched using the Radarr/Sonarr download history, so media removed without Radarr/Sonarr is left untouched. qBittorrent is currently the only supported client. + +| Setting | Description | +| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| URL | The base URL of your qBittorrent WebUI, such as `http://localhost:8080` or `https://qbittorrent.example.com` | +| Username | The qBittorrent WebUI username. Leave blank if the WebUI bypasses authentication (e.g. _Bypass authentication for clients on localhost_). | +| Password | The qBittorrent WebUI password. Leave blank if authentication is bypassed. | +| Delete downloaded data | When enabled, removing a download also deletes its files from disk. Turn this off if you cross-seed, so other torrents that share the data keep working. | +| Only delete after a seeding ratio | When enabled, a download is only removed once it reaches the configured ratio; otherwise it keeps seeding. Leave disabled to remove regardless of ratio. | +| Minimum ratio | The share ratio a download must reach before Maintainerr removes it. Only shown when _Only delete after a seeding ratio_ is enabled. | + +How it works: + +- Cleanup runs only for media that Radarr or Sonarr deletes. Maintainerr looks up the download that produced the files in the Radarr/Sonarr download history and removes that download from qBittorrent. Media removed directly from the media server (without Radarr/Sonarr), manually imported items, or items whose download history has been cleared are left untouched. +- For **Sonarr**, cleanup runs only on whole-show deletions. Season- and episode-level deletions are skipped on purpose, because a season-pack download can contain episodes you still want. +- Removal is best-effort: a failure to reach the download client never blocks the Radarr/Sonarr deletion itself. +- `Test Connection` verifies the URL and credentials against the qBittorrent WebUI. + ## Metadata Maintainerr has a separate `Settings -> Metadata` page for poster, backdrop, and metadata-provider settings used across the UI. From 6eafc78987f70ec400fd29ce5c3b06320da96e48 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 6 Jun 2026 17:58:07 +0000 Subject: [PATCH 3/7] docs: expand download client troubleshooting --- docs/Configuration.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/Configuration.md b/docs/Configuration.md index cb12f6c3..1bf24a0a 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -157,9 +157,14 @@ How it works: - Cleanup runs only for media that Radarr or Sonarr deletes. Maintainerr looks up the download that produced the files in the Radarr/Sonarr download history and removes that download from qBittorrent. Media removed directly from the media server (without Radarr/Sonarr), manually imported items, or items whose download history has been cleared are left untouched. - For **Sonarr**, cleanup runs only on whole-show deletions. Season- and episode-level deletions are skipped on purpose, because a season-pack download can contain episodes you still want. +- If a download is cross-seeded (another torrent shares the same files), Maintainerr removes only the torrent entry and keeps the data, so the other torrent keeps working. - Removal is best-effort: a failure to reach the download client never blocks the Radarr/Sonarr deletion itself. - `Test Connection` verifies the URL and credentials against the qBittorrent WebUI. +:::tip Troubleshooting: "403 Forbidden" after a successful login +A `403 Forbidden` on the connection test (or in the logs) means qBittorrent authenticated Maintainerr but its Web UI security then rejected the request — it is **not** a wrong username/password. In qBittorrent go to **Options → Web UI → Security** and either add Maintainerr's IP/subnet to **"Bypass authentication for clients in whitelisted IP subnets"**, or review **"Enable Host header validation"** and CSRF protection (commonly triggered when qBittorrent is behind a reverse proxy). This is the most common setup issue. +::: + ## Metadata Maintainerr has a separate `Settings -> Metadata` page for poster, backdrop, and metadata-provider settings used across the UI. From 192a5b61a4b201d687f0a69f3d20bf3a31992968 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 6 Jun 2026 18:37:03 +0000 Subject: [PATCH 4/7] docs: correct download client configuration details --- docs/Configuration.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/Configuration.md b/docs/Configuration.md index 1bf24a0a..dbd9d065 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -144,25 +144,25 @@ The separate `Settings -> Download Client` page only appears once Radarr or Sona When media is removed through Radarr or Sonarr, Maintainerr can remove the matching completed download (and optionally its data) from your download client. The download is matched using the Radarr/Sonarr download history, so media removed without Radarr/Sonarr is left untouched. qBittorrent is currently the only supported client. -| Setting | Description | -| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -| URL | The base URL of your qBittorrent WebUI, such as `http://localhost:8080` or `https://qbittorrent.example.com` | -| Username | The qBittorrent WebUI username. Leave blank if the WebUI bypasses authentication (e.g. _Bypass authentication for clients on localhost_). | -| Password | The qBittorrent WebUI password. Leave blank if authentication is bypassed. | -| Delete downloaded data | When enabled, removing a download also deletes its files from disk. Turn this off if you cross-seed, so other torrents that share the data keep working. | -| Only delete after a seeding ratio | When enabled, a download is only removed once it reaches the configured ratio; otherwise it keeps seeding. Leave disabled to remove regardless of ratio. | -| Minimum ratio | The share ratio a download must reach before Maintainerr removes it. Only shown when _Only delete after a seeding ratio_ is enabled. | +| Setting | Description | +| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| URL | The base URL of your qBittorrent WebUI, such as `http://localhost:8080` or `https://qbittorrent.example.com` | +| Username | The qBittorrent WebUI username. Leave blank if the WebUI bypasses authentication (e.g. _Bypass authentication for clients on localhost_). | +| Password | The qBittorrent WebUI password. Leave blank if authentication is bypassed. | +| Delete downloaded data | When enabled, removing a download also deletes its files from disk. Turn this off if you cross-seed, so other torrents that share the data keep working. | +| Fallback seeding ratio | Whether a download has finished seeding is decided by qBittorrent's own ratio / seed-time limits. This fallback ratio only applies to downloads qBittorrent isn't limiting, and can't be below 0.5 (default 0.5). | How it works: - Cleanup runs only for media that Radarr or Sonarr deletes. Maintainerr looks up the download that produced the files in the Radarr/Sonarr download history and removes that download from qBittorrent. Media removed directly from the media server (without Radarr/Sonarr), manually imported items, or items whose download history has been cleared are left untouched. +- **Seeding is decided by qBittorrent.** A download is only removed once it has met qBittorrent's own ratio or seed-time limit; one still below its limit keeps seeding. The **Fallback seeding ratio** applies only to downloads qBittorrent enforces no limit on. +- **Separate download and library folders are handled automatically.** qBittorrent deletes its own downloaded files (in its download directory) while Radarr/Sonarr delete the imported library copy, so the common "downloads separate from the library" (hardlink/copy) setup is fully cleaned without Maintainerr needing to know any paths. - For **Sonarr**, cleanup runs only on whole-show deletions. Season- and episode-level deletions are skipped on purpose, because a season-pack download can contain episodes you still want. -- If a download is cross-seeded (another torrent shares the same files), Maintainerr removes only the torrent entry and keeps the data, so the other torrent keeps working. +- If a download is cross-seeded (another torrent shares the same files), Maintainerr removes only the torrent entry and keeps the data so the other torrent keeps working. - Removal is best-effort: a failure to reach the download client never blocks the Radarr/Sonarr deletion itself. -- `Test Connection` verifies the URL and credentials against the qBittorrent WebUI. :::tip Troubleshooting: "403 Forbidden" after a successful login -A `403 Forbidden` on the connection test (or in the logs) means qBittorrent authenticated Maintainerr but its Web UI security then rejected the request — it is **not** a wrong username/password. In qBittorrent go to **Options → Web UI → Security** and either add Maintainerr's IP/subnet to **"Bypass authentication for clients in whitelisted IP subnets"**, or review **"Enable Host header validation"** and CSRF protection (commonly triggered when qBittorrent is behind a reverse proxy). This is the most common setup issue. +A `403 Forbidden` on the connection test (or in the logs) means qBittorrent accepted the credentials but its Web UI security then blocked the request — it is **not** a wrong username/password. The usual cause is that Maintainerr and qBittorrent run on different IPs (e.g. separate Docker containers). In qBittorrent go to **Options → Web UI → Security** and add Maintainerr's IP or subnet to **"Bypass authentication for clients in whitelisted IP subnets"**. A reverse proxy or host-header validation can also cause it. ::: ## Metadata From 0acb44d1b8fcaeab6ade36d704a86dc9d7b4095e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 6 Jun 2026 18:48:52 +0000 Subject: [PATCH 5/7] docs: clarify download client prerequisites --- docs/Configuration.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/Configuration.md b/docs/Configuration.md index dbd9d065..6c606c3a 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -144,22 +144,28 @@ The separate `Settings -> Download Client` page only appears once Radarr or Sona When media is removed through Radarr or Sonarr, Maintainerr can remove the matching completed download (and optionally its data) from your download client. The download is matched using the Radarr/Sonarr download history, so media removed without Radarr/Sonarr is left untouched. qBittorrent is currently the only supported client. -| Setting | Description | -| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| URL | The base URL of your qBittorrent WebUI, such as `http://localhost:8080` or `https://qbittorrent.example.com` | -| Username | The qBittorrent WebUI username. Leave blank if the WebUI bypasses authentication (e.g. _Bypass authentication for clients on localhost_). | -| Password | The qBittorrent WebUI password. Leave blank if authentication is bypassed. | -| Delete downloaded data | When enabled, removing a download also deletes its files from disk. Turn this off if you cross-seed, so other torrents that share the data keep working. | +:::note +Maintainerr matches downloads by the hash recorded in the Radarr/Sonarr download history, so point it at the **same qBittorrent instance Radarr/Sonarr use as their download client**, with the Web UI enabled (qBittorrent 4.1 or newer). Media grabbed through a different qBittorrent — or through a Usenet/other download client — won't be found and is left untouched. +::: + +| Setting | Description | +| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| URL | The base URL of your qBittorrent WebUI, such as `http://localhost:8080` or `https://qbittorrent.example.com` | +| Username | The qBittorrent WebUI username. Leave blank if the WebUI bypasses authentication (e.g. _Bypass authentication for clients on localhost_). | +| Password | The qBittorrent WebUI password. Leave blank if authentication is bypassed. | +| Delete downloaded data | When enabled, removing a download also deletes its files from disk. Turn this off if you cross-seed, so other torrents that share the data keep working. | | Fallback seeding ratio | Whether a download has finished seeding is decided by qBittorrent's own ratio / seed-time limits. This fallback ratio only applies to downloads qBittorrent isn't limiting, and can't be below 0.5 (default 0.5). | How it works: - Cleanup runs only for media that Radarr or Sonarr deletes. Maintainerr looks up the download that produced the files in the Radarr/Sonarr download history and removes that download from qBittorrent. Media removed directly from the media server (without Radarr/Sonarr), manually imported items, or items whose download history has been cleared are left untouched. +- Only collection actions that delete files trigger cleanup (**Delete**, **Unmonitor and delete files**). **Unmonitor and keep files** and **Change quality profile** never remove a download. - **Seeding is decided by qBittorrent.** A download is only removed once it has met qBittorrent's own ratio or seed-time limit; one still below its limit keeps seeding. The **Fallback seeding ratio** applies only to downloads qBittorrent enforces no limit on. - **Separate download and library folders are handled automatically.** qBittorrent deletes its own downloaded files (in its download directory) while Radarr/Sonarr delete the imported library copy, so the common "downloads separate from the library" (hardlink/copy) setup is fully cleaned without Maintainerr needing to know any paths. - For **Sonarr**, cleanup runs only on whole-show deletions. Season- and episode-level deletions are skipped on purpose, because a season-pack download can contain episodes you still want. - If a download is cross-seeded (another torrent shares the same files), Maintainerr removes only the torrent entry and keeps the data so the other torrent keeps working. - Removal is best-effort: a failure to reach the download client never blocks the Radarr/Sonarr deletion itself. +- `Test Connection` verifies the URL and credentials against the qBittorrent Web UI before saving. :::tip Troubleshooting: "403 Forbidden" after a successful login A `403 Forbidden` on the connection test (or in the logs) means qBittorrent accepted the credentials but its Web UI security then blocked the request — it is **not** a wrong username/password. The usual cause is that Maintainerr and qBittorrent run on different IPs (e.g. separate Docker containers). In qBittorrent go to **Options → Web UI → Security** and add Maintainerr's IP or subnet to **"Bypass authentication for clients in whitelisted IP subnets"**. A reverse proxy or host-header validation can also cause it. From 512e4cda8f3874f3dbd827cdc43f33b0be12ef1a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 6 Jun 2026 19:01:18 +0000 Subject: [PATCH 6/7] docs: generalize download client docs --- docs/Configuration.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/Configuration.md b/docs/Configuration.md index 6c606c3a..ce41f0c8 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -142,7 +142,11 @@ Sonarr's configuration is required to use its parameters in rules and to remove The separate `Settings -> Download Client` page only appears once Radarr or Sonarr is configured. ::: -When media is removed through Radarr or Sonarr, Maintainerr can remove the matching completed download (and optionally its data) from your download client. The download is matched using the Radarr/Sonarr download history, so media removed without Radarr/Sonarr is left untouched. qBittorrent is currently the only supported client. +When media is removed through Radarr or Sonarr, Maintainerr can remove the matching completed download (and optionally its data) from your download client. Downloads are matched using the Radarr/Sonarr download history, so media removed without Radarr/Sonarr is left untouched. + +qBittorrent is currently the only supported client. + +### qBittorrent :::note Maintainerr matches downloads by the hash recorded in the Radarr/Sonarr download history, so point it at the **same qBittorrent instance Radarr/Sonarr use as their download client**, with the Web UI enabled (qBittorrent 4.1 or newer). Media grabbed through a different qBittorrent — or through a Usenet/other download client — won't be found and is left untouched. @@ -163,8 +167,8 @@ How it works: - **Seeding is decided by qBittorrent.** A download is only removed once it has met qBittorrent's own ratio or seed-time limit; one still below its limit keeps seeding. The **Fallback seeding ratio** applies only to downloads qBittorrent enforces no limit on. - **Separate download and library folders are handled automatically.** qBittorrent deletes its own downloaded files (in its download directory) while Radarr/Sonarr delete the imported library copy, so the common "downloads separate from the library" (hardlink/copy) setup is fully cleaned without Maintainerr needing to know any paths. - For **Sonarr**, cleanup runs only on whole-show deletions. Season- and episode-level deletions are skipped on purpose, because a season-pack download can contain episodes you still want. -- If a download is cross-seeded (another torrent shares the same files), Maintainerr removes only the torrent entry and keeps the data so the other torrent keeps working. -- Removal is best-effort: a failure to reach the download client never blocks the Radarr/Sonarr deletion itself. +- If a download is cross-seeded (another torrent shares the same files), Maintainerr removes only the torrent entry and keeps the data so the other torrent keeps working. This follows the same general approach as [qbit_manage](https://github.com/StuffAnThings/qbit_manage), rather than trying to replace a dedicated torrent-management workflow. +- Removal is best-effort: a failure to reach the download client never blocks the Radarr/Sonarr deletion itself, so treat it as cleanup assistance rather than guaranteed download-client reconciliation. - `Test Connection` verifies the URL and credentials against the qBittorrent Web UI before saving. :::tip Troubleshooting: "403 Forbidden" after a successful login From 5216b850247c81434d69526e664ed73970d3d933 Mon Sep 17 00:00:00 2001 From: enoch85 Date: Sat, 6 Jun 2026 21:05:03 +0200 Subject: [PATCH 7/7] Update removal process details in Configuration.md Clarified the removal process and added a note about advanced usage. --- docs/Configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Configuration.md b/docs/Configuration.md index ce41f0c8..b98e1308 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -168,7 +168,7 @@ How it works: - **Separate download and library folders are handled automatically.** qBittorrent deletes its own downloaded files (in its download directory) while Radarr/Sonarr delete the imported library copy, so the common "downloads separate from the library" (hardlink/copy) setup is fully cleaned without Maintainerr needing to know any paths. - For **Sonarr**, cleanup runs only on whole-show deletions. Season- and episode-level deletions are skipped on purpose, because a season-pack download can contain episodes you still want. - If a download is cross-seeded (another torrent shares the same files), Maintainerr removes only the torrent entry and keeps the data so the other torrent keeps working. This follows the same general approach as [qbit_manage](https://github.com/StuffAnThings/qbit_manage), rather than trying to replace a dedicated torrent-management workflow. -- Removal is best-effort: a failure to reach the download client never blocks the Radarr/Sonarr deletion itself, so treat it as cleanup assistance rather than guaranteed download-client reconciliation. +- Removal is best-effort: a failure to reach the download client never blocks the Radarr/Sonarr deletion itself, so treat it as cleanup assistance rather than guaranteed download-client reconciliation. For more advanced usage; look elsewhere. - `Test Connection` verifies the URL and credentials against the qBittorrent Web UI before saving. :::tip Troubleshooting: "403 Forbidden" after a successful login