github.com/mmaljutin/torrserver on Go

Simple and powerful tool for streaming torrents.

Introduction

TorrServer is a program that allows users to view torrents online without the need for preliminary file downloading. The core functionality of TorrServer includes caching torrents and subsequent data transfer via the HTTP protocol, allowing the cache size to be adjusted according to the system parameters and the user's internet connection speed.

✦ Fork Enhancements

This is a fork of YouROK/TorrServer with additional features focused on HDD-based media storage and improved UX.

📌 Pin Torrents (KeepFiles)

A star button on every torrent card lets you pin a torrent. Pinned torrents are truly persistent: their downloaded pieces are never evicted by the LRU cache and stay on disk even when the file is larger than the cache. Pinned data lives outside the CacheSize budget — it is bounded only by free disk space (a safety reserve keeps the disk from filling up). Unpin (toggle the star off) and the torrent rejoins normal LRU cleanup. Ideal for content you want to keep long-term on an HDD media store.

🗄️ HDD-Optimized Pre-cache on Add

When a torrent is added in Disk mode, TorrServer sequentially caches the first N MB of each large file (>50 MB — skips subtitles, NFOs, etc.). Configurable via Pre-cache on add (MB per file), default 50 MB. Files are processed one by one to minimize HDD head seeks, so any episode can start playing instantly without waiting for buffering.

⬇️ Auto Full Download on Play

Optional toggle (Download fully when opened): when a file is opened in a player (VLC, browser, etc.), TorrServer auto-pins the torrent and downloads the entire file to disk in the background. So while you're watching episode 1, episode 1 finishes downloading fully and stays on disk for offline playback later.

Because the file is auto-pinned, its pieces persist beyond the cache size instead of looping forever — a file bigger than the cache downloads to 100% and then stops (no endless re-downloading saturating your channel). Before starting, TorrServer checks free disk space and skips the download if it would leave less than a safety reserve (~2 GB) free.

🎚️ Precise Playback Buffer (MB)

The Buffer Before Playback setting is now in megabytes instead of percent. With 100 GB caches, 1% was 1 GB — too coarse. Now you can set an exact buffer size independent of total cache (default 150 MB).

📋 Per-File Playlist Export

In the torrent details dialog, every file row now has a checkbox. Select specific files (e.g. only the episodes you want to download) and click Download Selected to get an .m3u with just those files. Subtitle tracks are automatically included.

☑️ Multi-Torrent Playlist Export

A checkbox is always visible on every torrent card poster. Select multiple torrents and click Download Playlist in the bottom selection bar — the M3U combines all playable files from all selected torrents, with direct stream URLs ready for VLC/Infuse/etc.

🧹 Clear All Cache Button

Sidebar action: Clear All Cache drops every active torrent and wipes its on-disk cache directory, while keeping the torrent entries in the library (re-downloads on next play). Has a 5-second confirmation guard to prevent accidental clicks. Handy when disk space runs low.

💾 Disk Cache up to 100 GB

The cache size slider in Disk mode now goes up to 100 GB (was 20 GB). RAM mode is capped at 4 GB. Switching modes automatically clamps the value to a reasonable range.

⚙️ Sensible Defaults for HDD Mode

Reset to Default now configures TorrServer for disk-based media storage: 4096 MB cache, 95% readahead, 150 MB playback buffer, 50 MB pre-cache per file, UseDisk on, save path /opt/ts. The Pro Mode toggle has been removed — all advanced settings are always visible.

📊 Traffic Counters

See exactly how much bandwidth each torrent uses. In the torrent details dialog three new widgets show:

Internet ↓ — data actually downloaded from peers (real internet usage in).
Internet ↑ — data uploaded to peers (seeding).
Served to player — bytes streamed to your players over the LAN (playback traffic).

The sidebar shows a server-wide total (↓ / ↑ / served), refreshed live. Counters are session-scoped: per-torrent values reset when a torrent is dropped or the server restarts; the global served total persists across drops until restart. Exposed via the GET /trafficstat API.

📈 % Cached Indicator

Each torrent card shows how much of the torrent is currently on disk as a percentage (bytesCompleted / totalSize), so you can tell at a glance what's fully downloaded.

Versioning

This fork uses its own version string, set in server/version/version.go:

MatriX.141.<y>-hdd

Rule: every commit bumps <y> by 1 (e.g. MatriX.141.1-hdd → MatriX.141.2-hdd → …). The 141 base tracks the upstream YouROK/TorrServer MatriX.141 release this fork is based on; the -hdd suffix marks the HDD-storage fork.

AI Documentation

Features

Caching
Streaming
Local and Remote Server
Viewing torrents on various devices
Integration with other apps through API
Torznab search (Jackett, Prowlarr, and similar indexer managers)
Cross-browser modern web interface
Optional DLNA server

Getting Started

Installation

Download the application for the required platform in the releases page. After installation, open the link http://127.0.0.1:8090 in the browser.

Windows

Run TorrServer-windows-amd64.exe.

Linux

Run in console

curl -s https://raw.githubusercontent.com/YouROK/TorrServer/master/installTorrServerLinux.sh | sudo bash

The script supports interactive and non-interactive installation, configuration, updates, and removal. When running the script interactively, you can:

Install/Update: Choose to install or update TorrServer
Reconfigure: If TorrServer is already installed, you'll be prompted to reconfigure settings (port, auth, read-only mode, logging, BBR)
Uninstall: Type Delete (or Удалить in Russian) to uninstall TorrServer

Download first and set execute permissions:

curl -s https://raw.githubusercontent.com/YouROK/TorrServer/master/installTorrServerLinux.sh -o installTorrServerLinux.sh && chmod 755 installTorrServerLinux.sh

Command-line examples:

Install a specific version:

sudo bash ./installTorrServerLinux.sh --install 135 --silent

Update to latest version:

sudo bash ./installTorrServerLinux.sh --update --silent

Reconfigure settings interactively:

sudo bash ./installTorrServerLinux.sh --reconfigure

Check for updates:

sudo bash ./installTorrServerLinux.sh --check

Downgrade to a specific version:

sudo bash ./installTorrServerLinux.sh --down 135

Remove/uninstall:

sudo bash ./installTorrServerLinux.sh --remove --silent

Change the systemd service user:

sudo bash ./installTorrServerLinux.sh --change-user root --silent

All available commands:

--install [VERSION] - Install latest or specific version
--update - Update to latest version
--reconfigure - Reconfigure TorrServer settings (port, auth, read-only mode, logging, BBR)
--check - Check for updates (version info only)
--down VERSION - Downgrade to specific version
--remove - Uninstall TorrServer
--change-user USER - Change service user (root|torrserver)
--root - Run service as root user
--silent - Non-interactive mode with defaults
--help - Show help message

macOS

Run in Terminal.app

curl -s https://raw.githubusercontent.com/YouROK/TorrServer/master/installTorrServerMac.sh -o installTorrserverMac.sh && chmod 755 installTorrServerMac.sh && bash ./installTorrServerMac.sh

Alternative install script for Intel Macs: https://github.com/dancheskus/TorrServerMacInstaller

IOCage Plugin (Unofficial)

On FreeBSD (TrueNAS/FreeNAS) you can use this plugin: https://github.com/filka96/iocage-plugin-TorrServer

NAS Systems (Unofficial)

Several releases are available through this link: https://github.com/vladlenas
Synology NAS packages repo source: https://grigi.lt

Server args

--port PORT, -p PORT - web server port (default 8090)
--ip IP, -i IP - web server addr (default empty, binds to all interfaces)
--ssl - enables https for web server
--sslport PORT - web server https port (default 8091). If not set, will be taken from db (if stored previously) or the default will be used.
--sslcert PATH - path to ssl cert file. If not set, will be taken from db (if stored previously) or default self-signed certificate/key will be generated.
--sslkey PATH - path to ssl key file. If not set, will be taken from db (if stored previously) or default self-signed certificate/key will be generated.
--force-https - with --ssl, the HTTP listener (--port) answers only with 307 Temporary Redirect to the same path on HTTPS (--sslport). The web UI and API are served on HTTPS only; nothing is served on HTTP except redirects. Requires --ssl (startup fails if --force-https is set without --ssl). Default is off so plain HTTP still works when SSL is disabled.
--path PATH, -d PATH - database and config dir path
--logpath LOGPATH, -l LOGPATH - server log file path
--weblogpath WEBLOGPATH, -w WEBLOGPATH - web access log file path
--rdb, -r - start in read-only DB mode
--httpauth, -a - enable http auth on all requests
--dontkill, -k - don't kill server on signal
--ui, -u - open torrserver page in browser
--torrentsdir TORRENTSDIR, -t TORRENTSDIR - autoload torrents from dir
--torrentaddr TORRENTADDR - Torrent client address (format [IP]:PORT, ex. :32000, 127.0.0.1:32768 etc)
--pubipv4 PUBIPV4, -4 PUBIPV4 - set public IPv4 addr
--pubipv6 PUBIPV6, -6 PUBIPV6 - set public IPv6 addr
--searchwa, -s - allow search without authentication
--maxsize MAXSIZE, -m MAXSIZE - max allowed stream size (in Bytes)
--tg TGTOKEN, -T TGTOKEN - Telegram bot token
--fuse FUSEPATH, -f FUSEPATH - fuse mount path
--webdav - enable web dav
--proxyurl PROXYURL - set proxy URL for BitTorrent traffic (http, socks4, socks5, socks5h), example: socks5h://user:password@example.com:2080
--proxymode PROXYMODE - set proxy mode: "tracker" (only HTTP trackers, default), "peers" (only peer connections), or "full" (all traffic)
--help, -h - display this help and exit
--version - display version and exit

Example:

TorrServer-darwin-arm64 [--port PORT] [--ip IP] [--path PATH] [--logpath LOGPATH] [--weblogpath WEBLOGPATH] [--rdb] [--httpauth] [--dontkill] [--ui] [--torrentsdir TORRENTSDIR] [--torrentaddr TORRENTADDR] [--pubipv4 PUBIPV4] [--pubipv6 PUBIPV6] [--searchwa] [--maxsize MAXSIZE] [--tg TGTOKEN] [--fuse FUSEPATH] [--webdav] [--ssl] [--sslport PORT] [--sslcert PATH] [--sslkey PATH] [--force-https]

Running in Docker & Docker Compose

Run in console

docker run --rm -d --name torrserver -p 8090:8090 ghcr.io/yourok/torrserver:latest

For running in persistence mode, just mount volume to container by adding -v ~/ts:/opt/ts, where ~/ts folder path is just example, but you could use it anyway... Result example command:

docker run --rm -d --name torrserver -v ~/ts:/opt/ts -p 8090:8090 ghcr.io/yourok/torrserver:latest

Environments

TS_HTTPAUTH - 1, and place auth file into ~/ts/config folder for enabling basic auth
TS_RDB - if 1, then the enabling --rdb flag
TS_DONTKILL - if 1, then the enabling --dontkill flag
TS_PORT - for changind default port to 5555 (example), also u need to change -p 8090:8090 to -p 5555:5555 (example)
TS_CONF_PATH - for overriding torrserver config path inside container. Example /opt/tsss
TS_TORR_DIR - for overriding torrents directory. Example /opt/torr_files
TS_LOG_PATH - for overriding log path. Example /opt/torrserver.log
TS_PROXYURL - set proxy URL for BitTorrent traffic (http, socks4, socks5, socks5h), example: socks5h://user:password@example.com:2080
TS_PROXYMODE - set proxy mode: "tracker" (only HTTP trackers, default), "peers" (only peer connections), or "full" (all traffic)

Example with full overrided command (on default values):

docker run --rm -d -e TS_PORT=5665 -e TS_DONTKILL=1 -e TS_HTTPAUTH=1 -e TS_RDB=1 -e TS_CONF_PATH=/opt/ts/config -e TS_LOG_PATH=/opt/ts/log -e TS_TORR_DIR=/opt/ts/torrents -e TS_PROXYURL=socks5h://user:password@example.com:2080 -e TS_PROXYMODE=tracker --name torrserver -v ~/ts:/opt/ts -p 5665:5665 ghcr.io/yourok/torrserver:latest

Docker Compose

# docker-compose.yml

version: '3.3'
services:
    torrserver:
        image: ghcr.io/yourok/torrserver
        container_name: torrserver
        network_mode: host    # to allow DLNA feature
        environment:
            - TS_PORT=5665
            - TS_DONTKILL=1
            - TS_HTTPAUTH=0
            - TS_CONF_PATH=/opt/ts/config
            - TS_TORR_DIR=/opt/ts/torrents
        volumes:
            - './CACHE:/opt/ts/torrents'
            - './CONFIG:/opt/ts/config'
        ports:
            - '5665:5665'
        restart: unless-stopped

Smart TV (using Media Station X)

Install Media Station X on your Smart TV (see platform support)
Open it and go to: Settings -> Start Parameter -> Setup
Enter current ip and port of the TorrServe(r), e.g. 127.0.0.1:8090

Development

Go server

To run the Go server locally, just run

cd server
go run ./cmd

Web development

To run the web server locally, just run

yarn start

More info at https://github.com/YouROK/TorrServer/tree/master/web#readme

Build

Server

Install Golang 1.20+
Go to the TorrServer source directory
Run build script under linux or macOS build-all.sh

Web

Install npm and yarn
Go to the web directory
Run NODE_OPTIONS=--openssl-legacy-provider yarn build

Android

To build an Android server you will need the Android Toolchain.

Swagger

swag must be installed on the system to [re]build Swagger documentation.

go install github.com/swaggo/swag/cmd/swag@latest
cd server; swag init -g web/server.go

# Documentation can be linted using
swag fmt

API

API Docs

API documentation is hosted as Swagger format available at path /swagger/index.html.

Authentication

The users data file should be located near to the settings. Basic auth, read more in wiki https://en.wikipedia.org/wiki/Basic_access_authentication.

accs.db in JSON format:

{
    "User1": "Pass1",
    "User2": "Pass2"
}

Note: You should enable authentication with -a (--httpauth) TorrServer startup option.

Whitelist/Blacklist IP

The lists file should be located in the same directory with config.db.

Whitelist file name: wip.txt
Blacklist file name: bip.txt

Whitelist has priority over everything else.