rTorrent

High-performance ncurses BitTorrent client with Unix socket SCGI

rTorrent is a quick and efficient BitTorrent client built on the libTorrent library (not to be confused with libtorrent-rasterbar). Written in C++ with an ncurses text interface, rTorrent excels at headless operation via screen sessions and XMLRPC/SCGI for remote control. QuickBox Pro globally installs rTorrent with dynamic multi-version support and per-user configuration via Unix sockets.

Installation

Install from the Dashboard

Open App Dashboard → Package Management (/dashboard?mode=packages), find rTorrent in the catalog (browse Download Clients or search), and click Install. The install dialog lets you pick the rTorrent version — the available builds are resolved from the compiled-packages catalog for your distro, and the matching libtorrent-rakshasa version is paired automatically. The dashboard streams the install log live and rTorrent appears in your Application Control panel when it finishes. Reinstall, Update, and Remove are available from the same panel.

What you see and can manage is gated by your account: admins manage any user’s apps; regular users manage their own. See Channels & Versions for how version resolution and beta channels work, and App Management for the full package flow.

Install from the CLI (automation)

The CLI runs the same install and is suited to automation and scripting. Without a version it installs the latest available build; pass -o to pin a specific version:

qb install rtorrent -u username
qb install rtorrent -u username -o '0.16.23'

The paired libtorrent-rakshasa version is resolved automatically for the version you select (e.g., -o '0.10.0' installs libtorrent 0.14.0, -o '0.9.8' installs libtorrent 0.13.8).

CLI Commands

Available Versions

Available versions are resolved dynamically from the compiled-packages catalog for your distro and update automatically as new builds are published.

Current versions include: 0.16.23This is the current recommended version, 0.16.11, 0.15.7, 0.15.6, 0.15.5, and the older rakshasa builds 0.10.0, 0.9.8These versions are not recommended for new installs and will eventually be removed.

Hide Update (Dashboard)

When a newer rTorrent version is available in the compiled-packages manifest, the v4 dashboard shows an update badge on the rTorrent app card. Non-admin users do not see this badge (the hideUpdateForNonAdmin flag is set for rTorrent). Any user can dismiss the update notification for their account via the dashboard, and it will reappear only when a newer version becomes available.

Accessing rTorrent

rTorrent itself has no web interface—use ruTorrent or Flood for web-based management.

Attach to Screen Session

To access the ncurses interface directly:

screen -r rtorrent

Detach with:

• Windows: Ctrl+A , D
• Mac: ⌃ Control+A , D

Browser Download Index

Separate from ruTorrent and Flood, QuickBox installs a per-user browser file index that lists the finished-download folder of your rTorrent in a dark-themed fancyindex view. Useful for quickly grabbing a single finished file without loading a web client.

https://your-server-ip/username.rtorrent.downloads

• The listing is the folder rTorrent downloads to (directory.default in ~/.rtorrent.rc, which is download/ under cfg.basedir unless you changed it), not the whole base directory. The watch/ and log/ folders and the .sessions/ metadata are not part of the listing. Change the download folder in ~/.rtorrent.rc and QuickBox re-renders the index on its own, usually within seconds, with an hourly check as a safety net. If the folder can’t be served (it is a symlink, it is outside your home folder, /mnt and /media, it doesn’t exist, or the web server can’t read it), the index keeps serving the default folder and the dashboard shows a note beginning “Showing the default folder.” See Open download folder for each note.
• Removing rTorrent keeps your finished downloads. qb remove rtorrent deletes the client’s configuration, session and watch folders but never the download folder or what is inside it, and the remove output names the folder it kept. A reinstall leaves ~/.rtorrent.rc alone, so your download folder stays as it was.
• The index is stitched together per user: if you also have qBittorrent, Deluge, Transmission, NZBGet, or SABnzbd installed, their completed-download locations are appended into the same username.dlindex.conf so each client gets its own URL. It is one shared browse-index config covering all of that user’s download clients, not an rTorrent-only feature.
• The feature has no service of its own — it is pure nginx. If the page fails to load — returns a 502 or 404, shows blank, or errors — while the rest of the dashboard works normally, the per-user config is broken or missing. Rebuild it with qb fix dlindex (see Troubleshooting).

Initial Configuration

1. Unix Socket Communication

QuickBox automatically configures:

• SCGI socket: /var/run/username/.rtorrent.sock
• Listening port range: Random from 2000-61000 (1500 port range per user)

The socket is used by ruTorrent, Flood, and *arr applications for communication.

2. Install Web Interface (Optional)

Install a web interface for remote management:

# ruTorrent (recommended for rTorrent)
qb install rutorrent -u username
 
# Flood (modern alternative)
qb install flood -u username

3. Connect to *arr Applications (Optional)

When configuring Sonarr, Radarr, or other *arr applications, use the nginx SCGI route:

1. In your *arr app, go to Settings → Download Clients → Add (+)
2. Select rTorrent from the list
3. Enter connection details:
   • Host: yourserver.com
   • Port: 443
   • Use SSL: Yes
   • URL Path: Empty
   • XMLRpc Path: /USERNAME
   • Username: Your QuickBox username
   • Password: Your QuickBox password
4. Test and save

File Locations

rTorrent’s layout is not fixed. Every path derives from cfg.basedir in the user’s ~/.rtorrent.rc, and cfg.basedir is user-configurable — if you relocate the base directory, every dependent path follows it. The values below are the shipped defaults.

Backup and Restore

rTorrent supports both a Full Backup and a Config Only backup from the dashboard (Application Backups tab, or by expanding rTorrent in Application Control). Backups are written to ~/.QuickBox/software/rtorrent/backup/.

For the full backup workflow, owner visibility rules, and where backups live on disk, see App Management → Application Backups.

Service Management

rTorrent runs as a systemd service inside a detached screen session.

systemctl status rtorrent@username     # Check status
systemctl restart rtorrent@username    # Restart service
journalctl -u rtorrent@username -f     # View live logs
systemctl enable rtorrent@username     # Start on boot
systemctl disable rtorrent@username    # Prevent auto-start

Troubleshooting

rTorrent Won’t Start

journalctl -u rtorrent@username -f

Check for configuration errors:

cat ~/.rtorrent.rc | grep -E 'error|warn'

Socket Permission Issues

Downloads or browse index page not loading

The browse index is a single shared per-user nginx config (/etc/nginx/software/username.dlindex.conf) that covers all of that user’s download clients, not just rTorrent. If it fails to load — 502, 404, blank, or error — while rTorrent and the rest of the dashboard work normally, that config is broken or missing. Rebuild it with qb fix dlindex. This is a different problem from the Socket Permission Issues above, which take rTorrent (and therefore ruTorrent, Flood, and the *arr connections) completely offline. This same fix applies to the browse page for every download client — see the Download Clients overview.

Port Range Conflicts

# Check configured port range
grep -E 'port_range|port_random' ~/.rtorrent.rc
 
# Verify no conflicts with other services
ss -tulpn | grep -E '(2000|3000|4000|5000|6000)'

Screen Session Lost

# List all screen sessions
screen -ls
 
# Reattach if session exists
screen -r rtorrent
 
# If no session, restart service
systemctl restart rtorrent@username

VPN routing

rTorrent can route all of its torrent traffic through a VPN tunnel using QuickBox Pro’s app-scoped routing, with either a WireGuard or an OpenVPN backend. When routing is enabled, rTorrent downloads, seeds, and announces to trackers from the VPN peer’s exit IP instead of your server’s real IP.

rTorrent downloads, seeds, and announces its ratio from the VPN exit IP, and all of that keeps working whatever your provider. Whether other peers can start a connection to you depends on the provider, and the routing card shows a Port forwarding section for it: with ProtonVPN (NAT-PMP) or AirVPN (a port from your account) the dashboard keeps rTorrent’s peer port on the provider’s forwarded port; with a provider that forwards none (like NordVPN) your tracker may show you as not connectable, which only means other peers can’t start a connection to you. You may seed to slightly fewer peers, because two peers that are both not connectable can’t reach each other. A provider that forwards a port (ProtonVPN, AirVPN) removes that limit. Port forwarding works with the WireGuard backend. A client routed over OpenVPN works the same way as the NordVPN case above: downloading, seeding and ratio are unaffected.

rTorrent is a per-user template service (rtorrent@<user>), so several users can each route their own instance independently, the same as qBittorrent and pyLoad. It appears in the App-Scoped Routing card once rTorrent is installed and its service is running.

Your web frontends keep working. ruTorrent and Flood reach rTorrent over its per-user Unix socket, not a network port, so they are unaffected when rTorrent moves into its VPN namespace. The ruTorrent and Flood interfaces stay reachable through the dashboard proxy exactly as before.

How to enable VPN routing for rTorrent:

1. Go to System > VPN Control (/system/vpn) in the dashboard
2. Upload at least one WireGuard .conf or OpenVPN .ovpn file if you have not done so already
3. Scroll to the App-Scoped Routing card on the VPN Control page
4. Select rTorrent from the app list
5. Choose the tunnel backend and a peer configuration from the dropdown
6. Click Enable Routing

rTorrent restarts inside its VPN network namespace and its torrent traffic exits through the VPN peer from that point forward.

The default kill-switch stale threshold for rTorrent is 30 minutes, matching qBittorrent and the other downloaders. You can adjust it between 60 seconds and 24 hours on the app row inside the App-Scoped Routing card.

For full details on routing configuration, kill switch settings, and live metrics, see the VPN Control dashboard page.

Best Practices

FAQ

Related Applications

Additional Resources