Throttlearr

Throttlearr

Docker app from allornothing's Repository

A gate that sits between Sonarr / Radarr / Lidarr / Readarr and SABnzbd.

Requirements

A running SABnzbd, and its API key (SABnzbd, Config, General). Point Sonarr/Radarr at Throttlearr instead of SABnzbd after you install it.
Overview
A gate that sits between Sonarr / Radarr / Lidarr / Readarr and SABnzbd. To your apps it looks like a normal SABnzbd, so the only change is the host, port and API key of the download client. Behind the scenes it keeps every grab in its own queue and hands them to the real SABnzbd only when your rules allow: at most N jobs in SABnzbd, a cap on gigabytes still to download, a limit on adds per hour, allowed hours, and a free-disk floor. Why: Sonarr and Radarr have no limit on how many jobs they push into a download client. One "search all missing" can put thousands of jobs in SABnzbd and bring it to a crawl. Held jobs show in your apps as queued, so the apps do not time out, re-grab or blocklist them. It also looks inside each NZB before it reaches SABnzbd and refuses releases that hold a program, only repair data and text, or only a sample clip. The app sees these as a failed download with the reason, so it blocklists the release and searches again. A small web page shows what is held and why, with Release now, Move up and Remove buttons, and a fail-open switch that sends everything straight through if you ever need it. /health and /metrics (Prometheus) are included. Held jobs are stored on disk and survive restarts. Version 0.1 supports SABnzbd as the download client (usenet). qBittorrent / rdt-client support is planned. Throttlearr does not download, search for or provide any content; it only controls the order and pace in which your existing apps hand work to your existing download client.

Throttlearr

A gate between your *arr apps and SABnzbd. Sonarr, Radarr, Lidarr and Readarr talk to Throttlearr as if it were SABnzbd. It holds the grabs in its own queue and hands them to the real SABnzbd only when your rules say there's room.

Why you'd want it:

  • No more queue floods. One "search all missing" can dump thousands of jobs into SABnzbd. Throttlearr releases them gradually, oldest first, so the apps don't time out or re-grab.
  • Bad releases get caught early. It looks inside the NZB first, and anything that's only a program, repair data or a sample clip is reported back as failed, so your app blocklists it and tries another.
  • Easy to step around. One switch (fail open) passes everything straight through.

It doesn't download, search for or provide any content. It only controls the pace of work between your apps and your download client.

Image: allornothing/throttlearr · Source: aon082910/throttlearr

Install

Unraid: search Throttlearr in Apps. Anywhere else: use docker-compose.example.yml.

Then:

  1. Set UPSTREAM_URL and UPSTREAM_API_KEY to your real SABnzbd.
  2. Open http://<server>:8085/ and copy the API key under Connect your apps.
  3. In Sonarr/Radarr, edit your SABnzbd download client to use Throttlearr's host, port and that key.

Tip: turn on Dry run first. Nothing is held, but the log shows what would have been.

Main settings

All settings are environment variables (template fields on Unraid). 0 means no limit.

Variable Default What it does
UPSTREAM_URL, UPSTREAM_API_KEY required Your real SABnzbd
MAX_ACTIVE 3 Most jobs SABnzbd may hold at once
MAX_ACTIVE_GB 0 Cap on total GB still to download
ADDS_PER_HOUR 0 Cap on jobs sent per hour
SCHEDULE any time Allowed hours, e.g. mon-fri 21:00-07:00
MIN_FREE_GB 0 Stop releasing when free space gets low
PORT 8085 Web page and API
PUID / PGID 99 / 100 File ownership

More options (NZB checks, UI login, held-job timeout) are in the template. Health and Prometheus metrics are at /health and /metrics.

Help

Open an issue. MIT licensed.

Categories

Download Statistics

65
Total Downloads

Related apps

Links

Details

Repository
allornothing/throttlearr:latest
Last Updated2026-11-16
First Seen2026-11-16

Runtime arguments

Web UI
http://[IP]:[PORT:8085]/
Network
bridge
Shell
sh
Privileged
false

Template configuration

WebUI / API PortPorttcp

Port for the web page and the SABnzbd-style API your apps connect to.

Target
8085
Default
8085
Value
8085
ConfigPathrw

Holds the database (held jobs, history, settings) and the held NZB files.

Target
/config
Default
/mnt/user/appdata/throttlearr
Value
/mnt/user/appdata/throttlearr
SABnzbd URLVariable

Address of your real SABnzbd, for example http://192.168.1.10:8080 (no trailing path).

Target
UPSTREAM_URL
Default
http://192.168.1.10:8080
Value
http://192.168.1.10:8080
SABnzbd API KeyVariable

SABnzbd's API key (SABnzbd, Config, General, API Key).

Target
UPSTREAM_API_KEY
Max jobs in SABnzbdVariable

Most jobs SABnzbd may hold at once, counting jobs Throttlearr did not add. 0 = no limit.

Target
MAX_ACTIVE
Default
3
Value
3
Max GB left to downloadVariable

Optional cap on the total gigabytes still to download in SABnzbd. An empty SABnzbd always accepts one job, whatever its size. 0 = no limit.

Target
MAX_ACTIVE_GB
Default
0
Value
0
Allowed hoursVariable

Optional. When jobs may be released, in the server's local time. Example: mon-fri 21:00-07:00; sat,sun 00:00-00:00 (an end before the start runs past midnight; 00:00-00:00 is the whole day). Empty = any time.

Target
SCHEDULE
API Key for your appsVariable

The key Sonarr/Radarr use to talk to Throttlearr. Leave blank to have one generated; it is shown on the web page.

Target
API_KEY
Adds per hourVariable

Optional cap on jobs sent to SABnzbd per hour (some providers limit adds). 0 = no limit.

Target
ADDS_PER_HOUR
Default
0
Value
0
Minimum free disk GBVariable

Optional. Stop releasing when free space would drop under this many GB. Needs the downloads folder mounted below. 0 = off.

Target
MIN_FREE_GB
Default
0
Value
0
Downloads folder (read only)Pathro

Optional: the folder SABnzbd downloads into, read only. Only used to measure free space for the setting above.

Target
/downloads
Max hours heldVariable

A job held longer than this is dropped and reported to the app as failed, so it searches again. 0 = never.

Target
MAX_HELD_HOURS
Default
72
Value
72
Force priority skips holdVariable

Jobs sent with SABnzbd's Force priority are never held (true or false).

Target
BYPASS_FORCE
Default
true
Value
true
Minimum NZB size MBVariable

Optional: refuse an NZB whose video and archives add up to less than this many MB. 0 = off.

Target
MIN_NZB_MB
Default
0
Value
0
Web page userVariable

Optional. Set both user and password to put the web page behind a login. The API for your apps is not affected.

Target
UI_USER
Web page passwordVariable

Optional password for the web page.

Target
UI_PASSWORD
Dry runVariable

true = never hold anything, only log what would have been held. Good for a first try.

Target
DRY_RUN
Default
false
Value
false
Time zoneVariable

Time zone for the allowed hours.

Target
TZ
Default
America/New_York
Value
America/New_York
PUIDVariable

User id the app runs as (Unraid: 99 = nobody).

Default
99
Value
99
PGIDVariable

Group id the app runs as (Unraid: 100 = users).

Default
100
Value
100