Rangarr

Rangarr is a lightweight orchestration service that automates and staggers media searches across multiple *arr instances (Radarr, Sonarr, Lidarr, Readarr, Whisparr). It helps keep your library complete without overwhelming your indexers or API limits.

Key Features

• Multi-Instance Support: Manage Radarr, Sonarr, Lidarr, Readarr, Whisparr v2, and Whisparr v3 from a single service.
• Global Slot Allocation: Efficiently distributes search slots across all instances, ensuring no search capacity is wasted.
• Instance Interleaving: Spreads search pressure evenly across multiple *arr instances and shared indexers throughout the cycle.
• Smart Staggering: Prevents "thundering herd" issues by spacing out search requests.
• Proportional Interleaving: Balanced searching between missing items and upgrades within each instance.
• Weighted Distribution: Prioritize specific instances (e.g., prioritize Movies over Music).
• Season Pack Support: Group Sonarr and Whisparr v2 searches by season, with configurable count or ratio thresholds and automatic fallback to individual episode searches for seasons that are still airing.
• Independent Scheduling: Run missing item searches and upgrade searches on separate, configurable intervals — poll for missing content aggressively while checking for upgrades less frequently, or any combination that fits your indexer usage.
• Retry Logic: Configurable skip windows for recently searched items, with independent retry intervals for missing and upgrade searches, plus automatic startup connection retries (3 attempts, 10-second delay) to handle Docker Compose race conditions.
• Custom Format Score Awareness: Finds Radarr, Sonarr, Whisparr v2, and Whisparr v3 items below their custom format score target — candidates *arr's Cutoff Unmet endpoint silently omits.
• Tag Filtering: Restrict searches to items with specific *arr tags, or exclude tagged items entirely.
• Active Hours: Restrict searches to a configured time window (e.g., overnight only) to avoid peak indexer load.
• Flexible Configuration: Configure via config.yaml with ${ENV_VAR} expansion for secrets, or skip the file entirely and use environment variables only.
• No External Connections: Only communicates with the *arr instances you configure. No telemetry, no phone-home, no external services.

Why Rangarr?

Some tools in this space have done things their users didn't know about — phoning home, collecting data, making connections that were never disclosed. Rangarr exists as a direct response to that. It talks to the *arr instances you configure. It talks to nothing else.

The codebase is intentionally small. There is no database, no persistence layer. If you want to verify what it does, SECURITY.md documents the exact threat model, and the source itself is four files you can read in an afternoon.

Quick Start

The fastest way to get started is with Docker Compose.

# 1. Get the configuration
curl -O https://raw.githubusercontent.com/JudoChinX/rangarr/main/config.example.yaml
curl -O https://raw.githubusercontent.com/JudoChinX/rangarr/main/compose.example.yaml
mv config.example.yaml config.yaml
mv compose.example.yaml compose.yaml
chmod 644 config.yaml  # Required: container runs as UID 65532 (nonroot), not your user
2. Edit config.yaml with your *arr API keys and hostnames
nano config.yaml
3. Start with dry_run: true to verify config before triggering real searches
   Set dry_run: false in config.yaml once logs look correct, then restart
docker compose up -d

Without Compose, use docker run directly:

docker run -d \
  --name rangarr \
  --restart unless-stopped \
  -v ./config.yaml:/app/config/config.yaml:ro \
  judochinx/rangarr:latest

See the User Guide for full details including Docker networking.

A minimal config.yaml to get you running:

global:
  interval: 3600             # Run every hour
  stagger_interval_seconds: 30 # Wait 30s between searches
  missing_batch_size: 20      # Search 20 missing items per cycle (0=disabled, -1=unlimited)
  upgrade_batch_size: 10      # Search 10 upgrade-eligible items per cycle (0=disabled, -1=unlimited)
  max_queue_size: 0           # Skip/limit searches when the download queue is busy (0=disabled)
  interleave_instances: true  # Alternate between instances during search
  search_order: last_searched_ascending  # Prioritize items not searched recently
instances:
  Radarr:
    type: radarr
    host: "http://radarr:7878"
    api_key: "YOUR_API_KEY"
    enabled: true

Quick Start (Environment Variables Only)

If you prefer not to use a config.yaml file, you can configure Rangarr entirely through environment variables.

docker run -d \
  --name rangarr \
  --restart unless-stopped \
  -e RANGARR_CONFIG_SOURCE=env \
  -e RANGARR_GLOBAL_INTERVAL=3600 \
  -e RANGARR_INSTANCE_0_NAME=MyRadarr \
  -e RANGARR_INSTANCE_0_TYPE=radarr \
  -e RANGARR_INSTANCE_0_URL=http://radarr:7878 \
  -e RANGARR_INSTANCE_0_API_KEY=YOUR_API_KEY \
  judochinx/rangarr:latest

Documentation

• User Guide — Setup, configuration, Docker networking, and troubleshooting.
• Technical Audit — Architecture, security model, and design philosophy.
• Security & Trust — What Rangarr does and doesn't do, how to verify it, and how to report vulnerabilities.
• Contributing — How to help improve Rangarr.
• Roadmap — Planned and in-progress features.

Related Projects

• Killarr — Detects and removes stalled downloads from Radarr, Sonarr, and Lidarr queues. Shares the same config.yaml format as Rangarr — both tools can run side-by-side from a single config file.

Development Transparency

AI tooling was used to assist with development tasks in this project. The architecture — no database, no persistence layer, four files, two dependencies — was designed by the author. All code is human-reviewed before inclusion.

License

MIT License — see LICENSE for details.