Open-source torrent client and magnet downloader for Windows, macOS, Linux, Android (APK) and iOS (build from source): an ad-free alternative to uTorrent for magnet links and .torrent files, with IDM-style multi-connection downloads for direct links (up to 16 parallel connections, resumable), optional debrid support (TorBox; Real-Debrid, AllDebrid, Premiumize and Debrid-Link experimental), and an MCP server so AI agents can queue downloads. Not affiliated with uTorrent or Internet Download Manager.
| Platform / feature | How to get it | Type |
|---|---|---|
Release: torrenter-x86_64-pc-windows-msvc.exe (CLI), torrenter-gui-x86_64-pc-windows-msvc.exe (GUI) |
Platform support | |
Release: CLI and GUI for Apple Silicon (aarch64) and Intel (x86_64); the GUI also as torrenter.app (.app.zip) |
Platform support | |
Release: torrenter-x86_64-unknown-linux-gnu (CLI), torrenter-gui-x86_64-unknown-linux-gnu (GUI) |
Platform support | |
Release: torrenter-android.apk, sideload (Android 11+) |
Platform support | |
| Build on a Mac with Xcode and sideload (iOS 16+); no App Store or IPA | Platform support | |
torrenter mcp, part of the CLI binary |
Feature – AI assistants queue and manage downloads over stdio | |
| Add your own account's API key in the GUI, CLI or phone apps. TorBox (verified); Real-Debrid, AllDebrid, Premiumize, Debrid-Link (experimental) | Feature – magnets download through your debrid service instead of peers |
torrenter gui
| android apk | ios app | torrenter cli |
|---|---|---|
|
|
|
No arguments opens the interactive menu (magnet, HTTP, auto-update, seed, download folder, debrid route, debrid accounts, connections). Subcommands:
torrenter magnet "magnet:?xt=urn:btih:…"
torrenter http "https://example.com/large-file.iso"
torrenter magnet "magnet:?xt=urn:btih:…" --dir /tmp/out # one-shot, not saved
torrenter magnet ~/Downloads/linux.torrent # a .torrent file works the same way
torrenter magnet "magnet:?xt=urn:btih:…" --debrid work # through your debrid account "work"
torrenter debrid add torbox --name work # save a key as an account (typed hidden or piped); also test / remove / list
torrenter --auto-update # persist: check GitHub Releases on startup (TTY only)
torrenter --no-auto-update
torrenter update # install the latest matching CLI asset now
torrenter mcp # stdio MCP (any host that can spawn a command)While a download runs, type 1 then Enter to pause/resume, or 2 then Enter to stop.
Downloader with two engines, two desktop fronts, an Android sideload APK, an iOS sideload app you build on a Mac, and stdio MCP. Each GitHub Release ships a CLI binary, a native GUI binary (egui), and torrenter-android.apk. There is no iOS IPA on Releases, no App Store listing, and no in-app updater.
- Magnet / torrent — BitTorrent via librqbit, or optionally through your own debrid service (see Debrid)
- Direct HTTP(S) — multi-part parallel download (Auto = 4 connections) with byte-range resume
Output goes to <OS Downloads>/torrenter until you pick another folder. Both fronts show danted4/torrenter vX.Y.Z. Auto-update is off by default.
Pick your OS below. Magnet vs HTTP is in Two download modes.
-
Open the latest GitHub Release.
-
Download the CLI and/or GUI asset:
- CLI:
torrenter-x86_64-unknown-linux-gnu - GUI:
torrenter-gui-x86_64-unknown-linux-gnu
- CLI:
-
Make it executable and put it on your
PATHif you want:chmod +x torrenter-x86_64-unknown-linux-gnu torrenter-gui-x86_64-unknown-linux-gnu
-
GUI only: install GTK 3 and xcb at run time. On Debian/Ubuntu:
sudo apt install libgtk-3-0 libxkbcommon0 libxcb-render0 libxcb-shape0 libxcb-xfixes0
The CLI does not need these.
-
Run:
./torrenter-x86_64-unknown-linux-gnu ./torrenter-gui-x86_64-unknown-linux-gnu
Linux does not show SmartScreen or Gatekeeper. Outbound network is allowed by default on most desktops, so there is usually no popup. If a firewall GUI (ufw, firewalld, a VPN client) asks, click Allow. Share-mode magnets listen on a random high TCP port; a deny-incoming firewall can block seeding even when downloads still work.
No Rust/Cargo is needed at runtime. Building from source is in the Development section.
- Open the latest GitHub Release.
- Download the CLI and/or GUI asset:
- CLI:
torrenter-x86_64-pc-windows-msvc.exe - GUI:
torrenter-gui-x86_64-pc-windows-msvc.exe
- CLI:
- Double-click the
.exe(or run it from PowerShell / Command Prompt).
Important
🚨 Windows SmartScreen will often show Windows protected your PC because the binary is not a Microsoft-signed installer. If you skip the second click below, the app never starts. The .exe did not fail — SmartScreen blocked it.
| Do this or the app never starts | |
|---|---|
| 1️⃣ | Click More options |
| 2️⃣ | Click Run anyway |
Releases are unsigned. If Explorer still blocks the file, right-click it → Properties → check Unblock → OK, then run it again and use More options → Run anyway if SmartScreen appears. Microsoft Defender may scan the first run. Pin-to-taskbar uses the icon baked into the .exe (v3.2.1+).
Note
Windows Defender Firewall often asks for network access on first launch, the first share-mode magnet, and again after an update (the new .exe looks like a different app).
| Do this or peers / share mode stay blocked | |
|---|---|
| 1️⃣ | When Windows asks Allow torrenter to communicate on these networks? (or similar) |
| 2️⃣ | Click Allow (Private networks is enough for most home PCs) |
Do not click Cancel or Don’t allow if you want magnet share mode or incoming peers.
-
Open the latest GitHub Release.
-
Download the asset for your Mac (Apple Silicon
aarch64, Intelx86_64):- CLI:
torrenter-<arch>-apple-darwin - GUI for Launchpad:
torrenter-gui-<arch>-apple-darwin.app.zip - GUI as a naked Mach-O (optional):
torrenter-gui-<arch>-apple-darwin
Releases are unsigned. The GUI updater still downloads the naked
torrenter-gui-*Mach-O (CLI usestorrenter-*). The.app.zipis extra packaging for Launchpad; it is not the updater asset. - CLI:
-
GUI (Launchpad): download the
.app.zip, double-click to unziptorrenter.app, drag it to Applications. GitHub setscom.apple.quarantine:xattr -dr com.apple.quarantine /Applications/torrenter.app open /Applications/torrenter.app
If macOS still blocks it (“Apple cannot check it for malicious software”): right-click torrenter → Open → Open, or System Settings → Privacy & Security → Open Anyway. Spotlight and Launchpad list it after it sits in Applications.
-
CLI / naked GUI:
chmod +x torrenter-aarch64-apple-darwin torrenter-gui-aarch64-apple-darwin xattr -d com.apple.quarantine torrenter-aarch64-apple-darwin xattr -d com.apple.quarantine torrenter-gui-aarch64-apple-darwin ./torrenter-aarch64-apple-darwin ./torrenter-gui-aarch64-apple-darwin
Note
macOS often shows a network access popup on first open and again after an update (a replaced binary is a new app to the OS). Wording varies: would like to find and connect to devices on the local network, or accept incoming network connections.
| Do this or magnet / share traffic is blocked | |
|---|---|
| 1️⃣ | When the network popup appears |
| 2️⃣ | Click Allow |
If you clicked Don’t Allow, open System Settings → Network → Firewall (or Privacy & Security → Local Network) and enable torrenter, then relaunch. Gatekeeper can also return after an update — clear quarantine again if macOS refuses to open the new file.
No Rust/Cargo is needed at runtime. Building from source is in the Development section.
Sideload only — not on Google Play. minSdk 30, ABIs arm64-v8a + x86_64. Same engines and chrome as the desktop GUI: magnet launcher icon, phosphor / amber / ice / scarlet / violet, MAGNET ⇄ HTTP, share/leech (seed ON/OFF), fetching metadata, verifying, then downloading, queue of four. There is no in-app updater (the APK is not a desktop torrenter-* / torrenter-gui-* asset).
-
Open the latest GitHub Release and download
torrenter-android.apk(sideload, arm64 + x86_64; from 3.9.1 signed with the project's release key, so later versions install over it). Or build it from this tree (see Development):cargo run --features android-ndk --bin android-ndk cd android && gradle assembleDebug
A local build lands at
android/app/build/outputs/apk/debug/. Copy the APK to the phone (USB, Nearby Share, or a file you trust). -
On the phone: allow Install unknown apps for that source, then open the APK. Android always asks before installing an app from outside the Play Store. 3.9.0 and older were signed with a new throwaway debug key every release, so moving from one of those to 3.9.1 or later needs one uninstall first (which clears the job list and saved accounts); from 3.9.1 on, updates install in place.
Check the APK before you install it (on a computer):
- Signing certificate (the stronger check, since it does not depend on the release page):
apksigner verify --print-certs torrenter-android.apk(from the Android SDK build-tools) must list exactly one signer, withcertificate SHA-256 digest: 25b1f25dcf7e5f875246daf1389801017cef56b595d482e9a56e384f4fa31a70. Every release since 3.9.1 is signed with that project key, and Android refuses an update signed with any other key. - Checksum:
shasum -a 256 torrenter-android.apk(Windows:certutil -hashfile torrenter-android.apk SHA256) must match thetorrenter-android.apkline in that release'sSHA256SUMS. As with the desktop updater, this proves the file is the one the release lists (same publisher). It is not a signature.
Important
🚨 Google Play Protect may show Harmful app blocked (This app may be harmful). Tapping Got it installs nothing.
| Only for the checked APK from this repo's Releases | |
|---|---|
| 1️⃣ | Run the checks above |
| 2️⃣ | Tap Install anyway (a small link above Got it; on some Android versions it is under More details) |
| 3️⃣ | Confirm Install / Update |
- Grant All files access (required). Output is public
Download/torrenter, same layout as desktop (<name>/for magnets,.resume/for HTTP). - Allow notifications so the foreground service can keep jobs alive when you leave the app.
- If Android asks to ignore battery optimizations, allow it. Denying that does not block jobs; OEMs may still freeze seeding.
Leaving the app (Back) keeps live jobs in a foreground service until they finish or you Stop. Reopen the app to restore incomplete jobs (jobs.json in app private storage). A reboot or process kill does not autostart torrenter. Share mode asks the LAN gateway to forward the listen port (UPnP); phones behind CGNAT can still finish at U 0.00 with no inbound peers. The header cog opens settings in place of the main screen. The header never changes: settings and a job's files start with a ← name bar that goes back (so do tapping the title and system Back). Settings use category chips (appearance · downloads · debrid accounts) with one card per setting (theme, connections, remove after download) and one per debrid account (test / remove, + add account: provider, optional name, key). Next to START, a route dropdown picks default (none) (peers) or an account. Theme, seed and those settings live in app preferences, not desktop config.json. Each account's key is encrypted with an Android Keystore key and excluded from backups.
No Rust/Cargo is needed on the phone. Building the APK is in the Development section.
Sideload from this tree onto your iPhone — not the App Store, not a GitHub IPA. min iOS 16, arm64 device + simulator slice. Same engines and chrome as Android (magnet icon, phosphor / amber / ice / scarlet / violet, MAGNET ⇄ HTTP, fetching metadata, verifying, then downloading, queue of four) with three product cuts: leech only (no share toggle), no background service (Home keeps downloading for the ~20 s iOS grace window, then parks live jobs; reopening restarts them, unless keep alive is on), dest is On My iPhone → torrenter (Documents/torrenter). There is no in-app updater.
You need a Mac, full Xcode from the App Store (Command Line Tools are not enough), Rust 1.85+, and the iPhone on USB. A free Apple ID can sign to that device (the cert expires about every 7 days). Linux and Windows cannot produce an installable iOS app.
-
Install Xcode, open it once, accept the license. Then:
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer sudo xcodebuild -license accept sudo xcodebuild -runFirstLaunch cargo run --features ios-xcframework --bin ios-xcframework open ios/torrenter.xcodeproj
-
Unlock the iPhone, tap Trust This Computer if asked. In Xcode’s destination bar pick the real iPhone, not a Simulator.
-
If Xcode says iOS X.Y is not installed with a Get button: click Get and wait (this can be several GB). Play will not work until that finishes. Ignore a yellow Update to recommended settings warning.
-
Left sidebar: click the top blue torrenter project → TARGETS → torrenter → Signing & Capabilities. Check Automatically manage signing. Team: Add Account…, sign in with your Apple ID, then pick Personal Team. You do not need a paid developer program.
-
Click Play. The Keychain dialog wants the Mac login password (not Apple ID, not the iPhone passcode). Prefer Always Allow.
-
First Run often fails with Developer Mode disabled. On the phone: Settings → Privacy & Security, scroll to the bottom (under Security / Lockdown Mode), tap Developer Mode, turn it on, Restart. After unlock, tap Enable / Turn On and enter the phone passcode. iOS search for “Developer” often finds nothing — do not look under General. Then Play again.
-
If the icon is on the home screen but will not open (Untrusted Developer): Settings → General → VPN & Device Management (sometimes Device Management) → the Apple Development / your name entry → Trust. Then open torrenter.
Downloads: Files → Browse → On My iPhone → torrenter. If On My iPhone is missing, enable it under Browse locations. Idle job rows have share for Open In / VLC.
The header cog opens settings in place of the main screen. The header never changes: settings and a job's files start with a ← name bar that goes back (so does tapping the title). Settings use category chips (appearance · downloads · debrid accounts) with one card per setting (theme, connections, remove after download, keep alive) and one per debrid account (test / remove, + add account: provider, optional name, key). Next to START, a route dropdown (the native iOS menu) picks default (none) (peers) or an account. Each account's key lives in the iOS Keychain (this device only).
Leaving the app keeps live jobs running for up to ~20 s (the iOS background grace window), then parks them: they stop and the app remembers which ones were running. Reopening the app (even after iOS kills it) restarts parked jobs on its own; jobs you paused stay stopped. Turn on keep alive (switch under the URL field) to keep downloading in the background: a silent audio loop that mixes with other apps keeps iOS from suspending torrenter until every job is done, at a battery cost. It is a sideload-only trick (the app declares the audio background mode) and is off by default. A phone call or another app grabbing audio falls back to the grace window. jobs.json is in Application Support (not in Files). Theme is UserDefaults. Incomplete work resumes from dest / .resume/. Local network permission may appear for magnet/DHT.
torrenter mcp speaks stdio MCP (rmcp). Any host that can spawn a local command can use it (Cursor, Claude Desktop, Cline, Pi, and others). Not an HTTP /mcp URL. Leech-only; same jobs.json as the GUI — do not run both at once. Hydrate forces seed off so a GUI share-mode torrent does not start uploading.
Put torrenter on PATH, then:
{
"mcpServers": {
"torrenter": {
"command": "torrenter",
"args": ["mcp"]
}
}
}Stdout is the protocol; logs go to stderr. There is no install token and no extra binary.
.torrent files: queue_torrent_file takes a local path (and the same optional debrid). Files inside a torrent job: list_files gives them grouped by folder with ids, sizes, bytes on disk and whether each is selected; set_files takes the ids to download (see Choose files). Debrid: queue_magnet takes an optional debrid account name (or a provider id when that provider has one account), and debrid_services lists the providers this build offers with the names of the user's accounts and whether each is experimental. Keys are never shown and cannot be set over MCP; configure them with torrenter debrid add, the GUI settings, or TORRENTER_<SERVICE>_KEY in the host's env block. Without debrid, a magnet downloads from peers.
| Magnet / torrent | Direct HTTP(S) | |
|---|---|---|
| Use when | magnet P2P | CDN, mirror, or any direct file URL |
| Input | magnet:?xt=urn:btih:…, or a .torrent file (file icon inside the box, MAGNET only; drop it on the desktop window; "Open with torrenter" on iOS; torrenter magnet file.torrent) |
https://example.com/file.iso |
| Engine | librqbit | reqwest + Range: bytes= |
| Parallelism | piece picker | byte-range parts: connections setting, Auto = 4 (1–16) |
| Resume | librqbit on disk under <dest>/<torrent-name>/ |
<dest>/.resume/ part files |
| Phases | fetching metadata (the swarm sends the file list; skipped for a .torrent file, which already has it) → verifying (data already on disk, e.g. after a resume) → connecting to peers (until the first bytes) → downloading → seeding or done; the bar is indeterminate until data flows |
downloading → done |
| Peers | live count in the bar | Peers: 0 |
| Upload | Share (default): upload while downloading and keep seeding until Stop. Leech: never upload; stop at 100% | — |
| Fallback | — | single stream if the server ignores ranges |
A magnet can instead go via debrid: your debrid service fetches it and torrenter downloads the files over HTTP (see Debrid). It is still a magnet job, not a third mode.
Magnet links need a 32-character base32 or 40-character hex info hash. A .torrent file (up to 32 MB) is checked by librqbit and becomes the magnet built from it (info hash, name, trackers): the job is a normal magnet job (its copy-link button gives that magnet, and debrid accounts receive it), and a copy of the file is kept as torrents/<info-hash>.torrent beside jobs.json so restarts start from it with no metadata wait. A magnet keeps the same kind of copy once its metadata arrives, so its file list survives a relaunch and a restart skips the metadata wait. The copy is deleted when the job is cleared. Picking or dropping a file starts it at once with the current route and share/leech; a file handed over by "Open with" on iOS (which another app can do) first asks Start this torrent? with its name and route. A private torrent (from a private tracker) is handled as its tracker requires: its tracker URLs, which carry your passkey, stay out of the magnet; it runs only from the kept copy, never through the DHT (if the copy is gone, the job fails and asks for the file again); and it cannot go through a debrid service. Picking or dropping one while a debrid account is the route asks first: download it from its tracker's peers? (or cancel). It is protected while it runs as the job created from its file: its copy-link button still gives a magnet (hash and name only), and pasting that back in makes an ordinary magnet job that uses the DHT. Older versions treat a private-torrent job as a plain magnet, so do not downgrade with one in the list. HTTP names come from Content-Disposition or the URL path (one path component only; . / .. become download.bin).
Single-stream HTTP does not resume. It truncates the destination and starts over.
HTTP pause aborts the live Range body and continues from <dest>/.resume/ on resume. Pause on a single-stream (no Range) download starts that GET over. Stop is honored during HEAD, range probe, part copy, and merge. Redirects are followed (up to 10), but never from HTTPS down to plain HTTP: an https:// link that redirects to http:// fails with a note saying so (paste the http:// link yourself if you trust it). The same rule covers debrid links and the updater.
Torrent mode uses DHT in memory only. Share (default, seed: on) uploads while downloading, opens an incoming TCP listen on a random high port, and stays connected after 100% until you press 2 or quit — torrenter magnet will not return when the file is complete. Leech (seed: off) never uploads and calls session.stop() at 100%. Each magnet writes into <dest>/<torrent-name>/ (whitespace becomes _). If the magnet has no name, or that folder belongs to a different info-hash, the folder is the hash (or name_hash). Overwrite is allowed only inside that folder so a retry can resume. Closing the CLI drops every seed. Closing the GUI drops live sessions too, then restores the job list on the next launch (share rows that were seeding start seeding again if their files are still in that row’s dest).
The GUI uses the same engines: phosphor / amber / ice / scarlet / violet (last pick saved), magnet/HTTP swap on the URL row, a fixed-width route dropdown (MAGNET only: default (none) = peers, or one of your debrid accounts by name, long names shortened with "…"; fades share/leech while on), share/leech glyphs, dest path, pause / stop / clear per row (plus files on a torrent with two or more files, see Choose files). The header cog swaps the URL row and job list for a settings page (the header itself never changes; every inner page starts with a ← name bar that goes back): a sidebar of categories (appearance, downloads, debrid accounts, updates) and the chosen category's settings as full-width tiles (theme, tint on macOS, connections, remove after download, auto-update, and one card per debrid account with test / remove plus + add account). Auto-update also stays on the header. Stop immediately shows clear (and restart). Click a job title to open that row’s folder (the dest saved on the job, not the folder used for new START jobs). The copy icon after the title puts that job’s magnet or HTTP URL on the clipboard. Idle rows use restart (confirm popup with route — peers or a debrid account — dest, and share/leech). Search filters jobs (Esc clears). At most four downloads run at once; the same magnet or HTTP URL cannot start twice while it is already active. The job list is saved across launches (jobs.json). Live rows continue after a dest check (paused rows start paused and still count toward the 4-run cap). A >0% magnet whose files were moved/deleted, or a live HTTP job without .resume parts, comes back stopped. Seeding still needs the window open; it resumes on the next launch if that row was left seeding.
A torrent job starts with every file selected. Its row gets a files button once the file list is known (a .torrent has it at once; a magnet after its metadata arrives) and the torrent has two or more files. The files screen takes the place of the job list, like settings, and its ← files bar goes back:
- files grouped by folder (one level; the header shows the folder's path), each with a checkbox, its size and its own progress bar;
- a folder's checkbox ticks or unticks the whole group (a bar in the box means some are ticked), and all does the same for every file shown;
- a search box filters the list by file or folder name.
A tick or untick takes effect at once. On a running job an unticked file stops downloading and a ticked one starts. Ticking a file on a done job starts it again in the same row. A stopped or failed job keeps the new choice for its restart (restart always keeps it). Unticking every file finishes the job ("no files selected"); a share job keeps seeding what it has. While some files are unticked, the row says how many download (4 of 20 files) and its bar and sizes count only those files.
Files on disk are never deleted or renamed. The torrent engine creates every file of the torrent when the job starts, so unticked files still appear in the folder: empty, or partial if they were unticked part-way (such a file may show its full size; its bar on the files screen shows how far it got). Bytes of pieces shared with a neighbouring file can also land in an unticked file. Ticking a file again continues from what is on disk. The choice is saved with the job (onlyFiles in jobs.json; older versions ignore it and download everything). Debrid jobs and the CLI always download the whole torrent. Over MCP, list_files and set_files do the same as the files screen.
A debrid service downloads a torrent on its own servers and hands back HTTPS links. With a key configured, a magnet job can go via debrid: torrenter adds the magnet to your account, waits while the service fetches it, then downloads every file over HTTP into the same <dest>/<torrent-name>/ folder a plain magnet would use. Your IP never joins the swarm; the service itself sees the torrent and may log it.
- Services: TorBox is confirmed with a real account. Real-Debrid, AllDebrid, Premiumize and Debrid-Link are experimental: they are built from each provider's API docs and tested against fakes of those APIs, but nobody has run them with a real account yet. They are shown as "Real-Debrid (experimental)" and so on in every provider picker,
torrenter debrid listand MCPdebrid_services(experimental: true). A failed job on one ends with a request to report it at github.com/danted4/torrenter/issues; a report that one works is welcome too, so it can drop the label. Premiumize keeps each torrent in atorrenter-…folder on your account: if a transfer vanishes and is added again, the old empty folder stays behind, and a single-file torrent the service files outside that folder stays on the account after removal (the transfer itself goes). - Accounts: each key is a named account for one provider, so a provider can have several (e.g. "home" and "work" on TorBox). The name defaults to the provider's ("TorBox", then "TorBox 2"); names are unique. Add one in settings (+ add account: provider, optional name, key; saving checks it and shows "premium until …" or the error) or with
torrenter debrid add torbox [--name work]. Jobs remember their account by an internal id, so they resume through the same account (the torrent lives there), and renaming never breaks them. - Keys: desktop
credentials.jsonnext toconfig.json(owner-only, never injobs.jsonor logs).TORRENTER_<SERVICE>_KEY(e.g.TORRENTER_TORBOX_KEY) adds a read-only account, "TorBox (env)", that is never written. Android keeps each account's key encrypted with the Keystore, iOS in the Keychain (both by account id; names stay in the app's settings). Add one in settings (Test shows "premium until …" or the error) or withtorrenter debrid add torbox. - Route: default (none) on a fresh install; pick an account in the route dropdown (or
--debrid <account>, or MCPdebrid) and it is remembered like seed (MCP always defaults to off). With one account per provider, the provider name (torbox) works too. Debrid jobs never seed. Moving a job to another account of the same provider counts as leaving its torrent behind, so it asks first. - While the service fetches the row reads
MAGNET → TorBox · fetching %, with an as torrent action to download from peers instead. There is no automatic fallback. If the service's progress does not move for 30 minutes (time paused does not count), the job fails with "TorBox made no progress on this torrent for 30 minutes" so its download slot frees; it stays failed on the next launch, and restart waits again or as torrent switches to peers. Then it readsHTTP · via TorBoxwithfile i/n, files one after another. - Connections: the setting (Auto = 4) is capped per service (Premiumize 1; AllDebrid, Debrid-Link, Real-Debrid 8; TorBox 16).
- Downloads use only HTTPS links from the service. Two files that would land on the same path (names the same after making them safe, or differing only by case) are both saved, each with a short tag from its service file id before the extension (
01 [3fa2c1d9].flac), plus(2)in the rare case that still clashes. - Resume: jobs keep the service's torrent id and file ids, never links. Restarting asks the service for fresh links and continues the saved parts; an expired link is refreshed (twice in a row with no new bytes fails the job).
- Remove from service after download (off by default) deletes only torrents torrenter added, after every file landed. Clearing an unfinished debrid job, or switching it to as torrent or another service, asks whether to remove it from the service too (only when torrenter added it); nothing is removed without a yes. MCP never removes anything from a debrid account.
- Blocked content (for example Real-Debrid's "infringing file") fails the job with the service's message. torrenter does not work around it.
- Downgrades: torrenter 3.7.1 and older drop debrid jobs from the list (the files stay on disk). From this release on, job records this build cannot run (an unknown kind or service) are kept as-is.
Opt-in. The updater downloads only https://github.com/danted4/torrenter/releases/download/<tag>/<name> (tag in the path must match the release), checks SHA256SUMS, caps size, and times out. GitHub then 302s to objects.githubusercontent.com; that redirect is followed because the first hop is pinned. The binary uses the same Range transfer as HTTP jobs (gzip/brotli off, exact 206 bodies, merge through a .merge.tmp then rename) but stages beside the running exe — not dest/.resume, and it does not resume a partial install. If the CDN ignores Range, it is a single GET. The GUI install toast shows the job-row progress bar until install finishes; torrenter update uses the CLI bar.
SHA256SUMS is same-publisher integrity, not a signature. A stolen GitHub token can still ship a binary and a matching sums file.
Startup auto-update is skipped when stdin is not a TTY (scripts, pipes). torrenter update always runs when you ask. The GUI binary only replaces itself with torrenter-gui-* assets; the CLI binary only replaces itself with torrenter-* assets. The binary directory must be writable. Auto and manual install are the same: the new Mach-O overwrites this executable (Windows first renames the running file to *.old). Startup deletes leftover *.old, .*.update, .*.update.part-*, merge temps, and .*.sha256sums next to it. If you launched from torrenter.app, that bundle stays; only Contents/MacOS/torrenter-gui is swapped, then Info.plist is restamped and the app is ad-hoc signed again. Other copies (Downloads, an old zip) are not searched or deleted.
[████████████████░░░░] 75% | Peers: 12 | D: 750.45 MB @ 2.5 MB/s | T: 1.0 GB | ETA: 2 minutes
[████████████████████] 100% | Peers: 8 | U: 120.00 MB @ 1.1 MB/s | T: 1.0 GB
flowchart TD
start[torrenter] --> entry{Args?}
entry -->|none| menu{Menu}
entry -->|magnet| torrent
entry -->|magnet --debrid| debridAdd
entry -->|http| httpStart
entry -->|update| updater
menu -->|1 Magnet| torrent
menu -->|2 Direct URL| httpStart
menu -->|3 Toggle auto-update| menu
menu -->|4 Update now| updater
menu -->|5 Toggle seed| menu
menu -->|6 Change download folder| menu
menu -->|7 Debrid route, next account| menu
menu -->|8 Debrid accounts| menu
menu -->|9 Connections| menu
subgraph debridFlow [Magnet via a debrid account]
debridAdd[add or reuse on your account]
debridAdd --> fetch{fetched?}
fetch -->|no| poll[poll 3s to 30s] --> fetch
fetch -->|no progress 30 min| stalled["fail, slot freed, no fallback"]
fetch -->|yes| files[each file: fresh link]
files --> debridParts["Range parts, capped per provider"]
debridParts --> removeAfter{remove after download?}
removeAfter -->|yes and torrenter added it| deleteRemote[delete from the account]
removeAfter -->|no| magnetDir
deleteRemote --> magnetDir
end
subgraph magnetFlow [Magnet]
torrent[librqbit session]
torrent --> dht[DHT in memory no persistence]
dht --> metadata[fetching metadata from peers]
metadata --> verify[verifying data on disk]
verify --> upload{share?}
upload -->|no| leech[disable upload]
upload -->|yes| listen[listen TCP]
leech --> waitComplete["connecting to peers, downloading: wait_until_completed"]
listen --> waitComplete
waitComplete --> after{share?}
after -->|no| stopSession[session.stop]
after -->|yes| seedUntilStop[seed until Stop]
seedUntilStop --> stopSession
stopSession --> magnetDir
end
subgraph httpFlow [Direct HTTP]
httpStart[HEAD plus Range bytes 0-0]
httpStart --> sized{Known size?}
sized -->|no| single[Single GET stream]
sized -->|yes| parts[N parallel Range parts, Auto 4]
parts --> resumeDir["dest/.resume hashed-url parts"]
resumeDir --> honor{"HTTP 206?"}
honor -->|no| wipe[Wipe parts] --> single
honor -->|short body| fail[Fail incomplete no zero pad]
honor -->|yes| merge[Copy exact bytes to temp then rename]
merge --> httpDir
single --> httpDir
end
magnetDir["dest/torrent-name"]
httpDir["dest"]
updater[GitHub Releases plus SHA256SUMS]
HTTP resume keeps {sha256(url)[0..16]}.part-N plus a small JSON manifest under <dest>/.resume/ (debrid files key it by service, torrent id and file id instead, under <dest>/<torrent-name>/.resume/). Oversized parts are truncated before append; a short 206 is an error, not a zero-filled hole. Merge writes .{filename}.merge.tmp then replaces the final file.
- Download folder:
<OS Downloads>/torrenteruntildownload_diris set (src/paths.rs) - Parallel HTTP parts:
connectionsinconfig.json(unset = Auto =PART_COUNT= 4, else 1–16), fixed per job when it is created - GUI concurrent jobs: 4
- Progress format:
BAR_TEMPLATEinsrc/progress.rs - HTTP and updater timeouts: 20s connect, 60s between reads
- Auto-update, magnet seed, GUI
theme, GUIglass_tint(macOS only), and optionaldownload_dir:~/.config/torrenter/config.json(macOS:~/Library/Application Support/torrenter/config.json, Windows:%APPDATA%\torrenter\config.json).seeddefaults to on.themeisphosphor,amber,ice,scarlet, orviolet(default phosphor). On macOS,glass_tintis 40–210 (default 60% of that range) and tints the frosted window; native fullscreen locks the wash at 100% without writing that override. Labels and the settings cog keep a light brush-stroke wash behind the glyphs so 0% tint stays readable on a light wallpaper. Windows and Linux stay opaque (no tint slider). On Windows, an existingglass_tintin config is rewritten to 100%. Missingdownload_dirkeeps following the live OS Downloads path. Auto-update stays on the GUI header (mirrored in settings); theme and tint sit on the settings page behind the cog.debrid_routeremembers the debrid control,debrid_remove_afterthe remove-after setting. Saves are atomic, keys from newer builds are kept, and a file that no longer parses moves toconfig.json.bak. - Debrid accounts:
credentials.jsonnext toconfig.json(owner-only, atomic;{"accounts":[{"id","name","service","key"}]}), plus a read-only account perTORRENTER_<SERVICE>_KEY.debrid_routeinconfig.jsonholds the chosen account's id. - GUI job list:
jobs.jsonin that same folder, with copies of opened.torrentfiles intorrents/next to it (removed when their job is cleared). Each row keeps its own dest and share/leech. Corrupt files are moved tojobs.json.bak.torrenter mcpuses that same file — see MCP. - Android: dest is always public
Download/torrenter. Job list isjobs.jsonunder the app files dir. Theme, seed, the chosen debrid account, the account list (names and providers only), connections and remove-after are SharedPreferences (theme,seed,debridRoute= account id,debridAccounts,connections,debridRemoveAfter); each account's key is Keystore-encrypted intorrenter_keysunder the account id (excluded from backup). Noconfig.json, no glass tint, no updater. - iOS: dest is always
Documents/torrenter(Files: On My iPhone / torrenter). Job list isjobs.jsonunder Application Support. Theme, keep alive, the parked job list, the chosen debrid account, the account list (names and providers only), connections and remove-after are UserDefaults (theme,keepAlive,parkedJobs,debridRoute= account id,debridAccounts,connections,debridRemoveAfter); each account's key is a Keychain item under the account id. Leech only, no seed preference, noconfig.json, no glass tint, no updater.
Rust 1.85+. No tag is required for doc-only changes on main.
git clone https://github.com/danted4/torrenter.git
cd torrenter
cargo build --release
cargo build --release --features gui --bin torrenter-gui
./target/release/torrenter # Windows: .\target\release\torrenter.exe
./target/release/torrenter-gui # Windows: .\target\release\torrenter-gui.exe
# Android (needs rustup Android targets, NDK, cargo-ndk, Android SDK, JDK 17)
cargo run --features android-ndk --bin android-ndk
# AGP 8.7 needs JDK 17 (Java 21+ / 27 fails). Then:
cd android && gradle assembleDebug
# iOS (macOS + full Xcode, rustup iOS targets)
cargo run --features ios-xcframework --bin ios-xcframework
open ios/torrenter.xcodeprojcargo test --all-features
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warningsCI on every push and pull request to main: fmt, clippy (-D warnings), tests on Linux, macOS, and Windows (--all-features so the GUI compiles), the Android ffi cdylib plus the app's Kotlin unit tests and debug APK, and on macOS the iOS xcframework plus unsigned Simulator XCTest (FormatTests). Linux CI (and local --all-features builds) need GTK 3 + xcb dev packages: libgtk-3-dev libxkbcommon-dev libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev pkg-config.
Release: git tag vX.Y.Z && git push origin vX.Y.Z (commit must already be on main). That publishes CLI + GUI binaries, macOS torrenter-gui-*.app.zip, torrenter-android.apk, and SHA256SUMS. Doc-only changes on main do not need a tag.
| Problem | Fix |
|---|---|
Invalid magnet URL |
Must start with magnet:?xt=urn: and a 32-char base32 or 40-char hex hash |
| No peers / slow torrent | Wait for DHT; try a seeded magnet; check firewall/UDP |
| Share magnet, no upload | Keep the app open; allow the firewall prompt; leech mode never uploads and does not listen |
Too many open files |
torrenter raises the process limit when it can; otherwise ulimit -n 10240 and retry |
Invalid HTTP(S) URL |
Full http:// or https:// URL required |
| Multipart not used | Server did not return HTTP 206 — single stream is used instead |
| Resume not working (HTTP) | Same URL and same dest folder; state is in <dest>/.resume/ |
| Incomplete part | Server closed a Range early; retry the same URL |
| Linux GUI missing GTK/xcb | Install GTK 3 and xcb (see Linux) |
| GUI list empty after restart | Jobs live in jobs.json next to config.json; a corrupt file is renamed jobs.json.bak |
| Saved row says files missing | Payload is gone from that row’s dest; Restart starts over there, or Clear drops the row |
| GUI says already downloading | Same magnet info-hash or HTTP URL is already active |
| Auto-update did nothing in a script | Startup check is TTY-only; use torrenter update |
| Update hash / URL refused | Asset must be this repo’s release for that tag, with a matching SHA256SUMS line |
| Rust version error | Recent stable toolchain if building from source (rustup update) |
| Windows: “Windows protected your PC” | Click More options, then Run anyway (see Windows). Builds are unsigned; this is expected |
| Windows: firewall / network prompt | Click Allow (see Windows); repeats after updates |
| macOS: cannot be opened / unidentified developer | xattr -dr com.apple.quarantine on torrenter.app or the Mach-O, then right-click Open or Privacy & Security → Open Anyway (see macOS) |
| macOS: local network / incoming connections | Click Allow (see macOS); repeats after updates |
| Linux: no permission popup | Normal — Linux usually allows outbound with no prompt (see Linux) |
| Android: "Harmful app blocked" / Play Protect | Only for torrenter-android.apk from this repo's Releases: check its signing certificate and SHA256SUMS first, then tap Install anyway and Install (see Android). Allow Install unknown apps for the browser or file manager first. "App not installed" over 3.9.0 or older: uninstall that version once (different signing key) |
| Android: cannot write downloads | Grant All files access; dest is Download/torrenter |
| Android: jobs die in the background | Allow notifications and ignore battery optimizations; a reboot does not autostart the app |
Android: share magnet, U 0.00 |
Keep the app open; allow UPnP on the LAN; CGNAT still blocks inbound peers |
| iOS: helper fails, no iphoneos SDK | Install full Xcode (not CLT), then sudo xcode-select -s /Applications/Xcode.app/Contents/Developer (see iOS) |
| iOS: Xcode license / first launch | sudo xcodebuild -license accept then sudo xcodebuild -runFirstLaunch |
| iOS: destination says iOS X.Y is not installed | Click Get in Xcode and wait for the platform download |
| iOS: Keychain password rejected | Use the Mac login password, not Apple ID / iPhone passcode; Always Allow |
| iOS: Developer Mode missing in search | Settings → Privacy & Security, scroll to the bottom; not under General |
| iOS: app icon will not open | Settings → General → VPN & Device Management → Trust the developer (see iOS) |
| iOS: cannot install from GitHub | There is no IPA on Releases; build on a Mac (see iOS) |
| iOS: jobs stop when you leave | Expected after the ~20 s grace window; reopen and they restart. Turn on keep alive to keep downloading in the background |
| iOS: VLC cannot see files | Open Files → On My iPhone → torrenter, or share on the idle row |
| Debrid: "add a TorBox API key in settings first" | Add an account in settings, torrenter debrid add torbox, or set TORRENTER_TORBOX_KEY |
| Debrid: "this job's TorBox account key is not available" | The account it ran through was removed (add it again), or its key could not be read this launch (reopen the app); or use as torrent |
| Debrid: "no single debrid account matches" (CLI / MCP) | Two accounts share that provider; pass the account name (torrenter debrid list) |
| Debrid: "API key rejected" | Copy the key again from the service's account page; Test shows the service's own message |
| Debrid: stuck at "fetching" | The service is still downloading it (or the torrent is dead); wait, or use as torrent to download from peers |
| Debrid: "refused by the provider" | The service blocks that content; torrenter shows its message and does not retry |
| Debrid: route dropdown greyed / no accounts | Debrid applies to MAGNET mode only; add an account first |
Download only content you have the legal right to access. Generic tool — not affiliated with rqbit beyond using their OSS library.
Debrid support uses your own account with a third-party service. torrenter is not affiliated with any debrid provider, and that provider's terms apply, including its content policies and its rules on sharing keys and IP addresses.



