Download Clients and the Torrent Engine

This file covers Settings -> Download Clients (add, test, edit, delete, test all, categories, priority, tags, remote path mappings, completed/failed handling), the queue behaviours that depend on a client, the Built-in torrent engine and Settings -> Torrent Engine. Supported client kinds in this build are exactly seven: qBittorrent, Transmission, Deluge, rTorrent (torrent), SABnzbd, NZBGet (usenet) and Built-in (torrent). There is no Blackhole client. Prerequisites: signed in as an admin. For the external client checks you need at least one real client reachable from Arclight (for example qBittorrent WebUI at http://localhost:8080, or the qBittorrent container started with docker compose --profile qbittorrent up -d). Checks that need a usenet client or a specific client are marked; skip them if you do not run that client. Test environment: Native (scripts\local-test.ps1, http://localhost:17878) covers the Built-in engine and any client you can reach from your PC. Docker and NAS runs are needed for remote path mapping and “Bind to VPN” checks (marked). For API-only checks, <key> is the API key shown at Settings -> Security and <host> is localhost:17878 (Native) or <host>:7878 (Docker/NAS).

Add a client: qBittorrent

ID	Step	Expected result	Pass/Fail
DLC-01	Open Settings -> Download Clients.	Page “Download Clients” with a “Test all” button (greyed out when there are no clients), a card grid with “+ Add download client”, and a card “Remote path mappings” below.
DLC-02	Click “+ Add download client”.	A dialog “Add download client” lists tiles with a protocol badge, torrent ones first: qBittorrent, Transmission, Deluge, rTorrent, Built-in, then usenet: SABnzbd, NZBGet. Each tile has a one-line description.
DLC-03	Click the qBittorrent tile.	Dialog “Add qBittorrent” opens with fields Name, Enable, Host (pre-filled “localhost”), Port (8080), Use SSL, Username, Password, Category (default “arclight”), plus advanced ones.
DLC-04	Tick “Show advanced”.	More fields appear with an “advanced” tag: Client Priority (default 1), Remove Completed, Remove Failed, Tags, URL Base, Post-Import Category, Recent Priority, Older Priority, Initial State, Sequential Order, First and Last First, Content Layout.
DLC-05	Enter Name “qBittorrent”, your Host/Port and the correct Username and Password, then click Test.	A green “Test passed” box shows “version 4.x.x (API 2.x)” (your real version numbers).
DLC-06	Change the password to a wrong value and click Test.	A red “Test failed” box shows an error message with a code in brackets. Nothing is saved.
DLC-07	Enter a Host that does not exist (for example nohost.invalid) and click Test.	“Test failed” with a connection error. The dialog stays open.
DLC-08	Fix the credentials and click Save.	The dialog closes. A card “qBittorrent” appears with a torrent badge, a green “enabled” badge, “qBittorrent - priority 1” and the address line http://localhost:8080.
DLC-09	In qBittorrent’s own WebUI, check Categories after the first grab or after saving.	Arclight uses the category you entered (“arclight”) for its downloads. Only torrents in this category are tracked in Arclight’s queue.

Other client kinds

ID	Step	Expected result	Pass/Fail
DLC-10	Open “+ Add download client” -> Transmission.	Dialog “Add Transmission” with Port 9091 and URL Base “/transmission/”. The category fields are named Label and Post-Import Label; advanced shows Directory and Add Paused. (Transmission only.)
DLC-11	Open “+ Add download client” -> Deluge.	Dialog “Add Deluge” with Port 8112, a Password field and NO Username field, and labels named Label and Post-Import Label. (Deluge only.)
DLC-12	Open “+ Add download client” -> rTorrent.	Dialog “Add rTorrent” with URL Path default “RPC2”. (rTorrent only.)
DLC-13	Open “+ Add download client” -> SABnzbd.	Dialog “Add SABnzbd” with an API Key field (preferred over Username and Password, which are advanced). The tile in the picker carries a usenet badge. (SABnzbd only.)
DLC-14	Open “+ Add download client” -> NZBGet.	Dialog “Add NZBGet” with Port 6789 and Username default “nzbget”. (NZBGet only.)
DLC-15	For each client kind you actually run, fill in the correct values, click Test and then Save.	Each shows “Test passed” with a version, and a card with the right protocol badge (torrent or usenet) appears.

Edit, disable, delete and test all

ID	Step	Expected result	Pass/Fail
DLC-16	Click the title of a client card.	The editor reopens titled “Edit ” with the stored values. The Password field does not show the real password (it is stored masked).
DLC-17	Untick “Enable” and Save.	The card is greyed out and its badge reads “disabled”. Re-enable it afterwards.
DLC-18	Set the Client Priority (advanced) to 50 and then 51, 0.	50 is accepted and the card reads “priority 50”. 0 and 51 are refused (valid range 1 to 50, 1 is highest). Set it back to 1.
DLC-19	Add a second client of the same protocol with a different priority, then grab something (Search page -> Grab).	With different priorities the lower number (higher priority) client receives the download. With equal priorities clients are used in rotation.
DLC-20	Click “Test all” with one working and one broken client.	Each card shows a line: green “Test passed - version …” or red “Test failed: ”.
DLC-21	Open the editor of the broken client, click Delete.	A confirmation “Delete ?” appears. Confirm: the card disappears. Cancel: it stays.
DLC-22	Set a Tags value (click a tag chip, advanced) on a client and Save.	The client is then used only for series/movies with a matching tag. With no tags selected it is used for everything.

Completed and failed download handling

ID	Step	Expected result	Pass/Fail
DLC-23	In a client editor with “Show advanced” on, read the “Remove Completed” and “Remove Failed” checkboxes.	Both are ticked by default. Help text: “Remove imported downloads from the client once they are allowed to be removed (seeding goals met).” and “Remove failed downloads from the client.”
DLC-24	Set “Post-Import Category” to “arclight-done” (qBittorrent), Save, then let a download finish and import.	After the import the torrent in qBittorrent moves to category “arclight-done” instead of being removed (Remove Completed off) or is removed once seeding goals are met (Remove Completed on).
DLC-25	Check the server-wide handling switches via the API (there is no screen for them): curl http://<host>/api/v1/settings/mediamanagement -H "X-Api-Key: <key>".	The reply contains enableCompletedDownloadHandling (default true) and autoRedownloadFailed (default true).
DLC-26	Cancel a download inside the external client (delete the torrent in qBittorrent) while it is still in Arclight’s queue.	Within a minute or two the queue row shows a warning or failed state; with autoRedownloadFailed true Arclight blocklists that release and searches for another. A matching row appears in Activity -> History as a failed download.

Remote path mappings

ID	Step	Expected result	Pass/Fail
DLC-27	On the Download Clients page scroll to “Remote path mappings” with no mappings defined.	The card shows “No mappings” and the text “Only needed when the download client sees paths differently from Arclight (e.g. Docker).”
DLC-28	Click “Add” in that card.	Dialog “Add remote path mapping” with Host (suggests your clients’ hosts), Remote path (“The path as the download client reports it.”) and Local path (“The same directory as Arclight sees it.”).
DLC-29	Click Save with all fields empty.	An error “Host, remote path and local path are all required” appears and nothing is saved.
DLC-30	Enter Host “qbittorrent”, Remote path “/downloads/”, Local path “D:\Downloads" (or the matching folder on your system) and Save.	A table row appears with Host, Remote path and Local path in code font and an “Edit” button.
DLC-31	(Docker/NAS) Put the qBittorrent container’s download folder under a different path than Arclight’s mount, add the matching mapping, then grab and complete a download.	The download imports into the library. Without the mapping the queue row shows a warning about a path that “may need a Remote Path Mapping” and the import does not happen.
DLC-32	Click “Edit” on a mapping, then “Delete” in the dialog.	The mapping row is removed.

Queue behaviours that depend on clients

ID	Step	Expected result	Pass/Fail
DLC-33	Open Activity -> Queue after a grab sent to your client.	A row appears with the release title, the Client column showing your client’s name, a progress bar and Time left.
DLC-34	Click “Remove” on the row and leave “Remove from download client” ticked, then confirm.	The row leaves the queue and the torrent also disappears from the external client. With the toggle off the torrent stays in the external client.
DLC-35	Stop the external client (close qBittorrent) and wait about a minute.	The queue row shows a warning or error state and System -> Health reports that the client is unavailable. Restart the client; the row recovers.

Built-in engine: client and auto-registration

ID	Step	Expected result	Pass/Fail
DLC-36	On a brand-new install (empty config folder) start Arclight and open Settings -> Download Clients.	A client named “Built-in” already exists with a torrent badge, “Built-in - priority 1” and the line “built-in engine”.
DLC-37	Delete the “Built-in” client and restart Arclight.	It is NOT re-created (auto-registration only runs once). It can be added again by hand from “+ Add download client” -> Built-in.
DLC-38	Click “+ Add download client” -> Built-in.	Dialog “Add Built-in” explains that engine-wide options are under Settings -> Torrent Engine. Fields: Name, Enable, Category (default “arclight”), Download Folder, Initial State, and advanced Post-Import Category, Category Folders, Seed Ratio Limit, Seed Time Limit (minutes). There is no Host or Port.
DLC-39	Under “Category Folders” click “Add category”, type name “tv” and save path D:\Media\Downloads\tv (or /downloads/tv), then Save.	The row is kept after saving. “Remove” deletes a row. Fully empty rows are dropped on save.
DLC-40	Start Arclight with the environment variable ARCLIGHT_TORRENT_ENGINE=0 (the older name MEDIATRON_TORRENT_ENGINE=0 is still accepted) on a fresh config folder.	The engine does not start, and no “Built-in” client is auto-registered. Settings -> Torrent Engine shows State “Disabled”.

Settings -> Torrent Engine

ID	Step	Expected result	Pass/Fail
DLC-41	Open Settings -> Torrent Engine.	Page “Torrent Engine” with a “Live status” card (State, Listen port, Bound address, VPN binding, DHT nodes, Peers, Download, Upload, Torrents) and an “Engine” card with the settings form. State shows a green “Running”.
DLC-42	Read the form fields.	Toggles: Enable engine, Auto-register client, DHT, Peer exchange, Bind to VPN. Numbers: Listen port (6881), Max connections (200), Max connections per torrent (50), Download limit (KiB/s) (0), Upload limit (KiB/s) (0), Max active downloads (3), Max active seeds (5), Default seed ratio, Default seed time (minutes), Max simultaneous checks (2), Magnet metadata timeout (60). Toggles also include Disk guard (on) and Tunnel guard. Text: Downloads folder, Resume data folder (read-only).
DLC-43	Set Listen port to 6999 and click Save.	A short confirmation appears, and after a few seconds “Listen port” in Live status shows 6999.
DLC-44	Enter 0 in Listen port or 70000 and Save.	The save is refused with a validation message (valid range 1 to 65535).
DLC-45	Set Download limit to 500 KiB/s, add a large torrent, and watch Download in Live status.	The download rate stays at or below roughly 500 KiB/s. Set it back to 0 (unlimited).
DLC-46	Set Max active downloads to 1 and add three torrents.	Only one downloads at a time; the others show as queued in the “Torrents” line (for example “1 downloading … 2 queued”). Set it back to 3.
DLC-47	Enter Default seed ratio 1.0, Save, and let a torrent finish and seed (with no per-client override).	The torrent stops seeding once it reaches ratio 1.0. Clearing the field shows the placeholder “unlimited”.
DLC-48	Set Default seed time to 1 (minute) and let a torrent seed.	Seeding stops after about a minute. Clear the field when done.
DLC-49	Untick DHT and PEX, Save, then watch “DHT nodes” in Live status.	DHT nodes drops to 0 after the engine restarts. Re-tick them afterwards.
DLC-50	Enter a Downloads folder (for example D:\Torrents) and Save. Add a torrent through the Built-in client.	Files are written under that folder (in a sub-folder named by category, for example D:\Torrents\arclight). The placeholder in the field normally shows the default folder in use.
DLC-51	Untick “Enable engine” and Save.	State changes to “Disabled” and torrents stop. Tick it again and Save: State returns to “Starting” then “Running”.
DLC-52	(Docker + VPN only) Tick “Bind to VPN” with VPN enabled and connected (see 11-vpn.md).	“VPN binding” in Live status reads “connected - tunnel ” and “Bound address” shows the tunnel address instead of “all interfaces”.
DLC-53	(Docker + VPN only) With Bind to VPN on, stop the tunnel.	State shows a red “Lockdown” and the line “VPN down - all torrents paused, sockets bound to 127.0.0.1”. When the tunnel returns the engine resumes.

Engine torrent actions

ID	Step	Expected result	Pass/Fail
DLC-54	Grab a torrent through the Built-in client, then open Activity -> Queue.	The row has a “Details” button (only rows downloaded by the Built-in engine have it).
DLC-55	Click “Details”.	A dialog opens titled with the torrent name and tabs “General”, “Peers (n)”, “Trackers (n)”, “Files (n)”. General shows State, Progress, Size, Transferred, Ratio, Rates, ETA, Peers, Pieces, Save path, Category, Added, Completed, Private. The footer has Pause (or Resume), Recheck and Close.
DLC-56	Click “Pause”.	The State changes to “paused” within a few seconds and the button becomes “Resume”. Click Resume: it returns to downloading.
DLC-57	Click “Recheck”.	State briefly shows “checking”, then returns to its previous state with the same progress.
DLC-58	Open the “Files” tab on a multi-file torrent and change one file’s priority to “Skip”.	Priority options are Skip, Normal, High, Max. The skipped file stops downloading and the wanted size on General shrinks.
DLC-59	Open the “Peers” and “Trackers” tabs.	Peers shows address, client, source, flags and rates (or “No peers connected”). Trackers shows URL, tier, state and seeds/leechers (or “No trackers” for magnet/DHT only).
DLC-60	Move a torrent’s data via API: curl -X POST http://<host>/api/v1/torrent/<id>/move -H "X-Api-Key: <key>" -H "Content-Type: application/json" -d "{\"savePath\":\"D:\\\\Torrents\\\\moved\"}" (the id is the queue row’s download id).	The reply is OK and the General tab’s Save path changes to the new folder.
DLC-61	Click “Remove” on the queue row with “Remove from download client” ticked.	The torrent disappears from the engine (GET /api/v1/torrent/torrents no longer lists it).

Engine: disk, checks, metadata and resume

ID	Step	Expected result	Pass/Fail
DLC-62	Open Settings -> Torrent Engine, section “Disk”.	A “Disk guard” toggle, on by default. In Live status a “Disk writes” line shows the write speed and the amount waiting.
DLC-63	(Needs a slow or busy disk.) Add several large torrents while copying a big file to the same disk.	While data piles up, a notice says downloads are held to a limit because the disk is falling behind. The limit is about 90% of the shown write speed and not below 1 MiB/s. Stop the copy: within a minute or so the limit rises step by step and the notice goes away.
DLC-64	Set a Download limit of 500 KiB/s while the disk guard limits at a higher value.	The lower limit wins: the rate stays at or below 500 KiB/s.
DLC-65	Untick Disk guard, Save. Copy a big file to the download disk during a download.	No disk notice appears and downloads are not held. Tick it again afterwards.
DLC-66	Copy the debug report (System -> Debugging) and find the engine command.	It lists “disk guard” (either “not limiting” or “limiting downloads to …”) and, while checks run, “data checks N running, M waiting”.
DLC-67	Set “Max simultaneous checks” to 1, put the files of three torrents on disk and add the three torrents.	Only one shows “checking” at a time. The Live status “Data checks” line reads “1 running · 2 waiting”. They finish in the order they were added. Set the field back to 2.
DLC-68	Set “Max simultaneous checks” to 0 or 17 and Save.	The save is refused (valid range 1 to 16).
DLC-69	Set “Magnet metadata timeout” to 1, add a magnet of a dead release (a made-up hash) and wait about 2 minutes.	The download fails with “no metadata after 1 minute: no peers had this magnet” and goes through the normal failed-download handling (removed, blocklisted, next release searched).
DLC-70	Set “Magnet metadata timeout” to 0 and repeat DLC-69 for 5 minutes.	The magnet keeps waiting on “Fetching metadata” and does not fail. Set the field back to 60.
DLC-71	Download a large torrent to about 50%, then kill the process hard (docker kill arclight, or end the process) and start it again.	The torrent comes back at about the same percentage without a full recheck. Only a short check of the pieces in flight runs.
DLC-72	With a compose file from this release, run docker compose stop during a download and time it. Then check the arclight service in the compose file.	The container stops cleanly, within about 6 seconds of engine shutdown. The service has stop_grace_period: 30s. After the next start the torrent resumes without a full recheck.
DLC-73	During a download, watch the torrent’s Progress.	Progress counts only verified pieces, so it never drops after a piece was shown as done.

Grabs, repeats and clean-up

ID	Step	Expected result	Pass/Fail
DLC-74	Add a torrent to qBittorrent by hand in Arclight’s category, then grab the same release in Arclight.	The grab counts as done, the queue tracks the existing torrent, and no second copy or “already exists” error appears. Repeat with the built-in engine.
DLC-75	Remove a download from the queue (Remove from download client ticked), then right away search and grab the same release.	The grab is skipped and the log says the same release was removed moments ago. After 30 minutes it can be grabbed again.
DLC-76	On a queue row use “Try another release” with the blocklist box unticked.	A different release is grabbed, not the one you just removed.
DLC-77	Make a client delete each torrent as soon as it is added, then grab one release repeatedly (for example four times within an hour).	After the third send, further grabs of that release to that client are held, and the log says so. The hold is 15 minutes, then doubles each time, up to 6 hours.
DLC-78	Make a client refuse a release (for example a broken .torrent) while another release for the same item exists.	The refused release fails and the next release is tried. The grab is not parked. Stop the client entirely: the grab is parked and retried a few minutes later.
DLC-79	With Remove Completed on, add a torrent by hand to Arclight’s category, let it finish, and let Arclight import it.	It is imported but stays in the client; the log says Arclight did not grab it. A torrent Arclight grabbed is removed with its files once its seeding goal is met, and the removal shows on the download’s timeline and in the log.
DLC-80	Start two downloads that write into the same source folder (for example two episodes of one season pack folder), let one import.	The shared source folder is not cleaned up while the other download is active.
DLC-81	Turn on “Mirror to qBittorrent”, switch alternative speed limits on in qBittorrent by hand, then use slow mode in Arclight and turn it off.	Arclight does not switch off the alternative limits that you switched on yourself. Limits Arclight switched on are switched off again.