david/homelab-dashboard
Watch
1
0
Fork
You've already forked homelab-dashboard
 0
Code Issues Pull requests Projects Releases 93 Packages 1 Wiki Activity Actions
Page: qBittorrent
Pages
Changelog Container Registry Dense View Design Language Documentation Screenshots Grimmory Home Kavita Lab View Module Setup Navidrome Notifications Plex Proxmox Roadmap SABnzbd Security Hardening Seerr Requests Storage Health UniFi Network Uptime Kuma Wallboard White Labeling qBittorrent
1 qBittorrent
David Spitzer edited this page 2026-10-14 15:04:05 -07:00
Table of contents

qBittorrent

Dashboard Status

This module is live. The dashboard logs in to the qBittorrent WebUI API, keeps the session between polls, and reads one sync snapshot per poll.

Primary API surfaces:

/api/v2/auth/login
/api/v2/sync/maindata
/api/v2/app/version

Dashboard Admin Form

qBittorrent settings in the dashboard admin console

The qBittorrent page in /admin, filled with fictional example values from the built-in demo data. Secret fields show as dots while typing and as Saved secret once stored. Use Test saved connection after saving.

Admin Fields

  • qBittorrent WebUI URL
  • WebUI Username
  • WebUI Password
  • Low disk warning (GB free) (optional, default 20)

Recommended Values

qBittorrent WebUI URL: http://downloads.example.lan:8080
WebUI Username: dashboard
WebUI Password: the-webui-password
Low disk warning (GB free): 20

Use the address and port the dashboard container can reach. This is the WebUI port, not the torrent listening port.

Enable The WebUI

  1. Open qBittorrent.
  2. Open Tools > Options > Web UI.
  3. Tick the Web User Interface (remote control) option and note the port.
  4. Set a username and password for the dashboard to use.

What The Card Shows

  • Download and upload speed and the downloading, stalled and seeding counts.
  • Torrents in an error state, named in the detail.
  • Connection state. A firewalled connection is shown as a warning because incoming connections are blocked.
  • Free disk space as reported by qBittorrent, with a warning below the configured threshold.

On the wallboard, the Downloads panel shows the live rate with a one-minute graph, and a torrent error or low disk space turns the panel red.

Test From The Docker Host

curl -i -c /tmp/qb.cookies \
  -H 'Referer: http://downloads.example.lan:8080' \
  --data 'username=dashboard&password=YOUR_PASSWORD' \
  http://downloads.example.lan:8080/api/v2/auth/login

A working login answers Ok. and sets a cookie. Then:

curl -b /tmp/qb.cookies http://downloads.example.lan:8080/api/v2/app/version

Do not repeat a failing login in a loop: qBittorrent bans the IP after several failures.

Common Problems

  • IP ban. After repeated failed logins qBittorrent blocks the address. The dashboard protects you from causing this: after a rejected login it stops trying for 5 minutes (15 minutes after a 403), then retries once. Fix the credentials, or wait out the ban, before testing again.
  • 403 with correct credentials. Check Enable Host header validation and the CSRF protection options in the WebUI settings. The dashboard sends matching Referer and Origin headers for the URL you saved, so use the same hostname there that you use in a browser.
  • Wrong URL. Use the WebUI URL, not an API path. If qBittorrent is behind a reverse proxy at a sub-path, include the sub-path.
  • HTTPS with a self-signed certificate. Put the WebUI behind a trusted internal proxy, or use plain HTTP on a trusted network.