Stewarrd

Stewarrd brings qBittorrent, RDT-Client, SABnzbd and RQBit together in one authenticated web interface and API, alongside the Sonarr and Radarr instances that use them. It shows what every download is doing, explains why one is stuck, and can repair common failures once you have reviewed what it would do.

Documentation · Automation guide · Contributing · Security · MIT license

What it does

• Manage downloads. Search, filter and sort downloads across any number of client instances, with each client's native status and, for RDT-Client, provider and local progress shown separately. Pause, resume, retry or recheck where the client supports it. Protect a download to keep automation away from it. Every action is recorded, and an action whose outcome is uncertain must be reviewed before another is sent.
• Monitor Sonarr and Radarr. Follow their queues and health checks, and notice failed downloads and blocked imports.
• Recover failures. Replace releases that RDT-Client reports as failed, and, if you opt in, downloads that have stalled. Recovery blocklists the release in Arr, removes it from the client while keeping its files, and searches for a replacement within daily limits.
• Repair stuck imports. Copy-import Sonarr and Radarr downloads that are blocked only because Arr could not match them to an ID.
• Clean up unsafe content. Remove downloads containing executables or other unsafe files, after ownership, sharing and protection checks.
• Notify. Send each problem, and its resolution, to a JSON webhook.

Every recovery, import and cleanup policy starts in preview: it records what it would do without doing it. Stewarrd does not choose media for Arr, transfer files itself, enforce seeding rules, clean up orphaned files, or manage hosts and containers. The automation guide describes each policy's requirements and limits.

Install with Docker Compose

You need Docker Engine with BuildKit, Docker Compose v2, an x86-64 Linux host, and network access from the container to your clients and Arr applications.

git clone https://github.com/jamtur01/stewarrd.git
cd stewarrd
cp .env.example .env    # add the credentials for the connections you will use
docker compose up -d --build
docker compose exec stewarrd cat /data/access-token

Open http://localhost:8787 and sign in with that token. Keep it private: it authorizes both the web interface and the API. The included Compose file builds the checked-out source, listens on loopback only, runs read-only as UID/GID 1000 with no added capabilities, and keeps the token and SQLite database in the stewarrd-data volume.

Prebuilt images are published to Docker Hub. To use one, replace build: . and image: stewarrd:local in compose.yaml with image: jamtur01/stewarrd:<version>, then run docker compose pull && docker compose up -d.

Connect clients and Arr applications

1. In Connections, add each client instance: its type, a unique instance ID, a display name, and a base URL the Stewarrd container can reach. Enter the username where needed and the name of the environment variable that holds its password or API key.
2. Use Test & refresh to confirm the connection.
3. In Media, add Sonarr and Radarr the same way, then map each download client to the exact name it has in that Arr.
4. Check that the queues look right before adding any Recovery, Imports or Cleanup policy.

Credentials

Credentials live in .env, never in the connection form. Each variable must start with STEWARRD_CLIENT_ and have a companion _URL variable that matches the connection's base URL exactly, including any reverse-proxy path. Stewarrd refuses to send a credential to any other address.

STEWARRD_CLIENT_SAB_API_KEY=replace-with-your-api-key
STEWARRD_CLIENT_SAB_API_KEY_URL=http://sabnzbd:8080

Here the form takes STEWARRD_CLIENT_SAB_API_KEY and http://sabnzbd:8080. After editing .env, run docker compose up -d --force-recreate; a plain restart does not reload it.

Networking

Container names resolve only on a shared Docker network. If your clients run in a separate Compose project, join Stewarrd to their network or use hostnames and published ports it can reach; localhost inside the container is Stewarrd itself. If a client's reverse proxy validates Host headers, configure its external host and port rather than turning the check off.

Client notes

• RDT-Client: connect to its native API, not its qBittorrent-compatible endpoint. Its Retry action deletes the local files and the provider's copy before re-adding the torrent, so it asks for confirmation and requires cleanup storage mappings, the original torrent or magnet, and provider auto-import turned off. See native controls.
• RQBit: connect to its native HTTP API, normally on port 3030. Leave the credentials blank if the API has no authentication, or use the username and password fields for HTTP Basic authentication. It supports pause, resume, retry of failed jobs, stalled recovery, cleanup and copy-import recovery, but has no recheck. Map its storage before enabling cleanup on any client that shares that storage.

Automation

Recovery, Imports and Cleanup each have per-client or per-Arr policies. A new policy is in preview: it reads client and Arr state and records what it would do, but sends nothing. Enabling a policy authorizes only that policy's documented writes. Manual controls in the interface always act immediately; there is no global dry-run switch.

Add the mounts to the Compose service, keeping them read-only, for example:

volumes:
  - stewarrd-data:/data
  - /srv/downloads/complete:/downloads/complete:ro
  - /srv/rdt-client/db:/evidence/rdt:ro
  - /srv/sonarr/config:/evidence/sonarr:ro

Follow the automation guide for mappings, prerequisites and exactly what each policy does. Run only one automation tool against the same downloads at a time.

Notifications

Set STEWARRD_NOTIFICATION_URL to deliver these as JSON webhook events (see the automation guide for the payload). Each title names what happened and to which download; the detail names the client and Arr and gives the reason. Most conditions notify only after they persist for the delay shown, and send one event when they start. When a condition ends, a second event prefixes the title with Cleared: (the problem resolved) or Monitoring stopped: (Stewarrd stopped watching it: a recovery plan was discarded or took over, a policy was turned off, or a client or Arr was removed).

Configuration

Running in production

• Remote access: put Stewarrd behind an HTTPS reverse proxy and set STEWARRD_SECURE_COOKIE=true. Never expose the unencrypted login to the internet.
• One instance per data volume. With a bind mount instead of the named volume, make the directory writable by UID/GID 1000. Keep download and evidence mounts read-only: clients make their own changes through their APIs, and Stewarrd needs no Docker socket or elevated privileges.
• Health: GET /healthz needs no login. It returns 503 when no polling cycle has completed in 10 minutes, so the container health check and an uptime monitor catch a hung polling loop or failing notification delivery. A worker that fails within a cycle is logged and reported through its own notifications instead.

Upgrades, backups and rollback

Stop Stewarrd before backing up its data volume, and keep the whole volume, including access-token, together with your Compose and .env files. Keep backups private, and never run docker compose down --volumes unless you mean to discard everything.

Read the release notes before upgrading. Older credential names must be renamed to STEWARRD_CLIENT_*, given _URL bindings, and updated in saved connections. Build or pull the chosen version, recreate the container, and check the connections with policies in preview.

To roll back, stop the service and restore both the previous version and the data backup taken with it; an older version may not read newer state. Changing the access token and recreating the service rotates access, and any restart signs out existing browser sessions.

Troubleshooting

• Connection unavailable: test the URL from inside the Docker network, then check the credential variable names, their _URL bindings and the client's authentication log.
• "Set …_URL": add the matching _URL variable and recreate the container.
• Unknown action outcome: check the client itself, then acknowledge the action in Activity. An accepted API call does not prove the requested result.
• Cleanup held: check the journal and storage mappings. Every connected client must be mapped before Stewarrd can prove a payload is not shared.
• Import still blocked: only specific ID-match failures qualify for copy import; permission, quality and ambiguous matches need your review.
• Logs: docker compose logs --since 30m stewarrd. Remove credentials, signed URLs and personal paths before sharing them.

API and development

API clients send Authorization: Bearer <access-token>. The authenticated GET /api/openapi.json documents the same operations the interface uses.

Stewarrd is built with Node 24, TypeScript, React, Fastify and SQLite. See CONTRIBUTING.md for local development and checks, and SECURITY.md to report a vulnerability privately. The project is MIT licensed; dependencies keep their own licenses.