A client-server automation engine for qBittorrent with an HTTP API, a persistent job queue, and Docker-first deployment.
📖 Full documentation lives on the wiki — this README covers the pitch and getting started; everything else links out from here.
Left unattended, a qBittorrent instance turns into digital clutter: uncategorized downloads, dead torrents nobody's seeding anymore, ratio requirements quietly going unmet, the occasional file you really didn't want finishing before you noticed. qbt-rules automates all of that away — you write what you want to happen as declarative YAML, and it keeps enforcing it, whether that's the moment a torrent lands, on a schedule, or whenever you trigger it by hand.
Key Features:
- Declarative YAML rules — no coding required
- Reusable references — define a variable, condition, or action sequence once under
refs:, reuse it everywhere (docs) - Free-form execution contexts — webhooks, cron sweeps, manual runs; no fixed trigger list (docs)
- Rich conditions — AND/OR/NOT groups, 17+ operators, dot-notation access to 8 qBittorrent API categories
- Idempotent actions — safe to run repeatedly
- Multi-version qBittorrent support — v4.1 through v5.1+ via
qbittorrent-api's auto-detection
How it works: a small HTTP server, backed by a persistent SQLite or Redis job queue and a background worker, evaluates your rules and executes actions — categorize, tag, pause, resume, delete, throttle — against qBittorrent. Jobs survive server restarts, and the whole thing ships as a single Docker image (amd64/arm64, GHCR) with no PyPI package or manual install for end users.
- Docker and Docker Compose
- qBittorrent with Web UI enabled
version: '3.8'
services:
qbt-rules:
image: ghcr.io/andronics/qbt-rules:latest
container_name: qbt-rules
restart: unless-stopped
ports:
- "5000:5000"
volumes:
- ./config:/config
environment:
QBT_RULES_SERVER_API_KEY: "your-secure-api-key-here" # Change this!
QBT_RULES_QBITTORRENT_HOST: "http://qbittorrent:8080"
QBT_RULES_QBITTORRENT_USERNAME: "admin"
QBT_RULES_QBITTORRENT_PASSWORD: "adminpass"Default config.yml/rules.yml are created automatically in /config on first run if they don't already exist.
docker-compose up -d
curl http://localhost:5000/api/healthEdit config/rules.yml:
rules:
- id: auto-categorize-hd-movies
meta:
description: "Auto-categorize HD movies"
enabled: true
stop_on_match: true
context: torrent-imported
conditions:
all:
- field: info.name
operator: matches
value: '(?i).*(1080p|2160p|4k).*'
actions:
- type: set_category
params:
category: "Movies-HD"
- type: add_tag
params:
tags: [hd, auto-categorized]# Dry-run first
docker exec qbt-rules qbt-rules --dry-run --context torrent-imported --wait
# For real
docker exec qbt-rules qbt-rules --context torrent-imported --wait
# Or via the HTTP API directly
curl -X POST "http://localhost:5000/api/execute?context=torrent-imported&key=your-api-key"Continue with the Quick Start guide for the full walkthrough, or jump straight to Contexts to understand how jobs get triggered.
Everything beyond getting started lives on the wiki:
Core Concepts Rules Architecture · Contexts · Conditions · Actions · Available Fields · Reusable References · HTTP API Reference
Security Threat model, API auth, network exposure, credential management, content-safety rules
Configuration & Examples In-Depth Configuration · Examples · Advanced Topics
Help FAQ · Troubleshooting
For Developers Contributing · Architecture Internals · Extending the Engine · Testing Guide · Release Process
- Docker and Docker Compose (the only supported distribution method)
- qBittorrent with Web UI enabled
- Optional: a Redis server, if you choose
queue.backend: redisover the SQLite default
See CHANGELOG.md for version history and release notes.
Contributions are welcome — see the wiki's Contributing guide for the full workflow (dev setup, code style, testing, and how to report issues or security vulnerabilities).
This project is released into the public domain under the Unlicense. You are free to use, modify, and distribute this software for any purpose without attribution.