OmaqBT

A themed Omarchy Quattro bar widget for qBittorrent. The mark shows live ↓/↑ speeds while anything is transferring, and a desktop notification fires when a download finishes. Left-click the mark to watch live transfers, add a magnet or a .torrent file, start or stop, remove a torrent, and set file priorities. Right-click starts or stops everything. The official Qt window stays as an escape hatch.

OmaqBT talks to qbittorrent-nox on your existing ~/.config/qBittorrent library through the local Web API. It does not talk to any host other than 127.0.0.1.

License: MIT.

Install

omarchy plugin add https://github.com/Aweiward/omaqbt.git --enable

If qbittorrent-nox is missing, open the widget and click Install qBittorrent-nox. That runs pkexec omarchy pkg add qbittorrent-nox (Arch extra, polkit password prompt) and then starts the user service omaqbt-nox.service. It will not remove desktop qbittorrent if you already have it.

Close the Qt qBittorrent window before starting the daemon. Stop the daemon before opening the Qt app. They share one profile and must not run at the same time.

Connect Mullvad before you start the daemon if you want traffic bound to the VPN. The bind only happens when wg0-mullvad is already up. If nox starts with Mullvad down, it stays unbound until the next start.

omarchy bar move aweiward.omaqbt --section right

Usage

• Left click: open or close the panel
• Right click: start or stop all torrents
• Middle click: refresh
• Esc: close the panel

While a torrent is downloading or seeding, compact ↓/↑ speeds appear next to the bar mark (horizontal bars only; hover for exact rates). When a download reaches 100% between two polls, a desktop notification fires through notify-send. Already-finished torrents never re-notify, including on shell restart.

If Mullvad (or QBT_BIND_IFACE) is up but the running daemon is not bound to it, the mark shows the warning badge and the panel offers Restart daemon to bind. Restarting writes the bind keys and brings the daemon back on the tunnel.

Clicking a magnet: link in a browser opens this panel (after the browser’s own “open xdg-open?” prompt, if any). The torrent is added so metadata can load, then stopped. The confirm row shows the name (and size when known). Enter starts it. Esc cancels and deletes it. Paste, y, and drag-drop are unchanged.

List keys: j/k move, Enter opens files, Space start/stop, o open the save folder, x remove (keep files), X delete files, t start/stop all, s cycle sort (default → speed → eta → added), z turtle mode, a/p/c/* filter, / magnet field, y add clipboard magnet, r refresh. While a browser magnet is waiting, Enter starts it and Esc cancels it (unless the paste field is focused).

The field takes a magnet, a .torrent URL, or a local .torrent path (/…, ~/…, or file://…). Once it holds something addable, a Save to… field and an Add stopped row appear: Enter adds and starts, Add stopped adds without starting, and the save path overrides qBittorrent’s default when filled. Dropping a .torrent file or magnet link onto the open panel adds it too. From a terminal, qbt add also accepts --category <name>.

Typing anything that is not addable filters the list by name; Esc clears the filter first, then closes.

File view keys: j/k move, Enter cycle priority, x skip, Space start/stop, X delete files, Backspace or h back.

Turtle mode (z, or the row in the list) toggles qBittorrent’s alternative speed limits; the header shows “turtle” while it is on. Configure the alternative rates themselves in qBittorrent.

On a torrent’s detail view, size, ratio, seeds/peers, the added date, and the save path sit under the title, followed by Open folder, Remove, keep files and Delete files. Below the file list controls, clickable rows cycle the per-torrent download/upload limit (∞ → 8M → 4M → 1M → 256K), toggle sequential download, and cycle the seed ratio limit (global → 1.0 → 2.0 → none). Open folder (o) opens the save path in your file manager. Remove takes it out of the list and leaves the download on disk. Delete asks first, then removes the torrent and its files.

Configure

The only plugin setting is refreshIntervalSec (default 5) on the widget entry in ~/.config/omarchy/shell.json.

Starting the daemon writes these keys under [Preferences] in ~/.config/qBittorrent/qBittorrent.conf if you click Install or Start daemon:

WebUI\Enabled=true
WebUI\Address=127.0.0.1
WebUI\LocalHostAuth=false
WebUI\AuthSubnetWhitelistEnabled=true
WebUI\AuthSubnetWhitelist=127.0.0.1, ::1
WebUI\Port=<existing port, or 8080>

If wg0-mullvad is present (or QBT_BIND_IFACE is set), starting the daemon also writes under [BitTorrent]:

Session\Interface=<iface>
Session\InterfaceName=<iface>
Session\InterfaceAddress=

That binds the tunnel interface, not a single relay IP, so a Mullvad city change does not stall announces.

No other qBittorrent keys are rewritten. The plugin never stores a Web UI password.

Remove

omarchy plugin remove aweiward.omaqbt

Restore the Qt magnet handler before removing the plugin:

qbt magnet-uninstall-handler

qbt here is the helper in the plugin checkout. That points magnet: back at org.qbittorrent.qBittorrent.desktop when the Qt app is installed, and removes ~/.local/share/applications/omaqbt-magnet.desktop.

If the plugin is already gone:

xdg-mime default org.qbittorrent.qBittorrent.desktop x-scheme-handler/magnet

That disables the widget and deletes the plugin checkout. It does not uninstall qbittorrent-nox, stop omaqbt-nox.service, delete torrents, or revert the Web UI keys above. It also does not restore the magnet handler unless you ran uninstall first.

To stop the daemon yourself:

systemctl --user stop omaqbt-nox.service

Requirements

• Omarchy 4 (Quattro) / omarchy-shell
• qbittorrent-nox 5.2+ (installed from the panel if missing)
• On PATH for the helper: curl, jq, python3
• notify-send (libnotify) for completion notifications; without it they are skipped silently
• xdg-open (xdg-utils) for Open folder
• pkexec only when installing the package from the panel (no TTY for sudo)
• systemctl --user for omaqbt-nox.service

What this plugin does on your system

• Runs qbt from the plugin folder. That helper is the only process that talks HTTP, and only to 127.0.0.1.
• Installs the Arch extra package qbittorrent-nox through omarchy pkg add when you click Install. Privilege is pkexec, not a sudoers rule.
• Writes ~/.config/systemd/user/omaqbt-nox.service and enables it as your user.
• Writes the localhost Web UI keys listed under Configure. It stops the daemon first so qBittorrent does not overwrite those keys on exit.
• If wg0-mullvad is up, also writes the [BitTorrent] interface keys so qBittorrent binds the tunnel, not a single relay IP.
• Stores sync state in $XDG_RUNTIME_DIR/omaqbt/ (private, mode 700). If that variable is unset it falls back to a uid-scoped /tmp/omaqbt-<uid>, created with umask 077, and refuses to write through a symlink or a directory it does not own.
• Sends a desktop notification through notify-send when a download completes, and when a browser magnet arrives but the panel could not open.
• On widget load, writes ~/.local/share/applications/omaqbt-magnet.desktop and claims x-scheme-handler/magnet. Chromium may still ask to open xdg-open; that is a browser prompt, not a bug in this plugin.
• Stores pending browser magnets in ${XDG_STATE_HOME:-$HOME/.local/state}/omaqbt/ (not the runtime rid dir).
• Does not add torrents, delete files, or start the daemon unless you click or press the matching control, or click a magnet: link that this handler claimed.

Dev

node --test tests/*.test.js
tests/api-contract.sh
tests/magnet-handler.sh
omarchy plugin validate .

tests/api-contract.sh talks to a fixture HTTP server. It does not start qbittorrent-nox, add a real torrent, or delete files on disk.