Skip to content

lampac-nextgen/TorrServer

BranchesTags
 
 

Repository files navigation


Simple and powerful tool for streaming torrents.

GitHub Go Reference CodeFactor CI GitHub release (latest SemVer) GitHub tag (latest SemVer pre-release)

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.

AI Documentation

Ask DeepWiki

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
  • Optional GStreamer HLS transcoding support (-gst builds from release 141.10))

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.

Standard binaries are named TorrServer-<platform>-<arch> (for example, TorrServer-linux-amd64). From release 141.10, an optional GStreamer (gst) build is also available as TorrServer-gst-<platform>-<arch> with transcoding support (published for amd64 and arm64 only). The install scripts below can install either variant.

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
  • GStreamer build: For releases 141.10+ on amd64/arm64, choose the gst build with transcoding support (or pass --gst)
  • 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

  • Install GStreamer build (141.10+):

    sudo bash ./installTorrServerLinux.sh --install --gst
sudo bash ./installTorrServerLinux.sh --update --gst --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)
  • --gst - Install GStreamer build with transcoding support (141.10+, amd64/arm64 only)
  • --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

The macOS install script supports the same commands as the Linux script, including --install, --update, --remove, --reconfigure, and --gst for the GStreamer build (141.10+).

Command-line examples:

  • Install latest version:

    bash ./installTorrServerMac.sh --install

  • Install GStreamer build:

    bash ./installTorrServerMac.sh --install --gst

  • Update silently:

    bash ./installTorrServerMac.sh --update --silent

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)

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 persistent data, mount a local directory and set paths explicitly:

docker run --rm -d --name torrserver \
  -v ./ts:/opt/ts \
  -e TS_CONF_PATH=/opt/ts \
  -e TS_LOG_PATH=/opt/ts/torrserver.log \
  -e TS_TORR_DIR=/opt/ts/torrents \
  -p 8090:8090 \
  ghcr.io/yourok/torrserver:latest

Environments

  • TS_HTTPAUTH - 1, and place auth file into ./ts (config dir) 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 overridden command:

docker run --rm -d --name torrserver \
  -v ./ts:/opt/ts \
  -e TS_PORT=5665 \
  -e TS_DONTKILL=1 \
  -e TS_HTTPAUTH=1 \
  -e TS_RDB=1 \
  -e TS_CONF_PATH=/opt/ts \
  -e TS_LOG_PATH=/opt/ts/torrserver.log \
  -e TS_TORR_DIR=/opt/ts/torrents \
  -e TS_PROXYURL=socks5h://user:password@example.com:2080 \
  -e TS_PROXYMODE=tracker \
  -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)

  1. Install Media Station X on your Smart TV (see platform support)

  2. Open it and go to: Settings -> Start Parameter -> Setup

  3. Enter current ip and port of the TorrServe(r), e.g. 127.0.0.1:8090

Development

See docs/BUILD.md for Makefile commands, CI, tagged releases, GHCR images, and fork setup.

Go server

Run from source:

make run
# or
cd server && go run ./cmd

Web development

cd web && yarn start

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

Build

Use the Makefile (wraps GoReleaser and .goreleaser.local.yaml):

make help              # command overview
make install-tools     # goreleaser v2 + swag
make start-build       # build host binary, sync to data/, run
make build             # all local platforms + flatten → dist/
make update            # web embed + swagger
make release-snapshot  # local snapshot (binaries + docker, no publish)

Install Go toolchain wrappers used by GoReleaser:

go install golang.org/dl/go1.26.4@latest && go1.26.4 download
go install golang.org/dl/go1.25.7@latest && go1.25.7 download   # Android (release only)

Tagged releases (.goreleaser.yaml, workflow .github/workflows/release.yml) use the MatriX.* tag scheme and publish to ghcr.io/<owner>/<repo> where <owner>/<repo> is the GitHub repository lowercased. Override locally with REGISTRY_IMAGE=owner/repo make ….

Direct GoReleaser (without Make):

goreleaser build --snapshot --clean --config .goreleaser.local.yaml
make flatten
TARGET=linux_amd64 goreleaser build --snapshot --clean --single-target --id torrserver \
  --config .goreleaser.local.yaml

Web UI build inside gen_web.go needs Node 16–18, or Node 17+ with OpenSSL legacy (NODE_OPTIONS=--openssl-legacy-provider, set in Makefile / GoReleaser).

torrserver builds use Go 1.26.4; torrserver-android uses Go 1.25.7.

Server

  • Install Golang 1.26+ (1.25.7 additionally for Android via GoReleaser)
  • Go to the TorrServer source directory
  • Run make build-host or GoReleaser as above

Web

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

Android

To build an Android server you will need the Android Toolchain (release workflow / full .goreleaser.yaml).

Swagger

make install-swag
make update-swag
# or manually:
cd server && swag init -g web/server.go
swag fmt

Standard binaries serve a filtered Swagger spec at runtime (only /gst/settings); -gst builds include all /gst/* endpoints.

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.

Example:

local:127.0.0.0-127.0.0.255
127.0.0.0-127.0.0.255
local:127.0.0.1
127.0.0.1
# at the beginning of the line, comment

Torznab

TorrServer can talk to Torznab indexers so you can search for torrents from tools like Jackett and Prowlarr, including searching several configured indexers at once.

Configure it in the web UI: Settings → Torznab.

Indexer parameters

Each Torznab indexer needs:

  • Host URL: full URL to the Torznab API endpoint.

    • Jackett example:
    http://192.168.1.10:9117/api/v2.0/indexers/all/results/torznab/
    • Prowlarr example:
    http://localhost:9696/1
    • Make sure to include the correct trailing slash (/) in your indexer's URL, as required by your Torznab provider. TorrServer will try to properly format the path, but matching your indexer's expected format is best to avoid connection issues.

  • API Key: the key from your Torznab indexer manager.

Enabling Torznab search

  1. Open Settings.
  2. Open the Torznab tab.
  3. Turn on Enable Torznab Search.
  4. Enter Host URL and API Key, then Add Server for each indexer.
  5. Save settings.

GStreamer

GStreamer enables HLS transcoding for Matroska/WebM torrents when the client cannot play the original video or audio codec directly.

The -gst binary (main requirement)

The only way to enable GStreamer in TorrServer is to run a build compiled with the gst tag. There is no on/off switch in settings.json.

Binary GStreamer
TorrServer-gst-<os>-<arch> Yes — /gst/* routes and transcoding
TorrServer-<os>-<arch> (standard) No — GET /gst/settings returns built_in: false; POST is rejected and pipelines do not run

Download TorrServer-gst-* from releases (Windows/Linux amd64+arm64/macOS amd64+arm64), or build:

cd server
go build -tags="nosqlite gst" -trimpath -o TorrServer-gst ./cmd

Windows builds with embedded libs additionally use the embed_gstlib tag (see below).

Per-codec behavior is configured in the gstreamer settings block (TranscodeH264, TranscodeH265, TranscodeAV1, TranscodeVP9).

Linux/macOS install scripts install the standard binary only — for GStreamer, use the -gst release manually.

Bundled vs dynamically loaded GStreamer

TorrServer itself stays a single Go binary. GStreamer is not linked into it at compile time (Linux/macOS/Windows use runtime loading via dlopen / LoadLibrary). What changes is where the GStreamer libraries and plugins come from:

Mode How it works Typical use
Bundled (embedded) GStreamer runtime is packed inside the -gst binary and extracted to cache on first run Windows TorrServer-gst-windows-amd64.exe built with embed_gstlib
Bundled (portable) Place a gst-lib/ directory next to the TorrServer executable (same layout as an extracted GStreamer runtime) Portable installs, custom deployments
Dynamic (system) TorrServer loads libgstreamer / DLLs from OS packages or a system install path (GSTPath, /opt/gstreamer, framework path, etc.) Linux, macOS, Windows with official GStreamer installer

Auto-detection order includes: GSTPath from settings → gst-lib/ beside the binary → common system paths → LD_LIBRARY_PATH / PATH.

Verify whichever mode you use with GET /gst/echo or the status lines on the GStreamer settings tab.

Installing GStreamer for dynamic loading

Only needed when GStreamer is not already bundled (most Linux/macOS -gst builds, Windows without embed_gstlib).

Debian / Ubuntu

sudo apt update
sudo apt install -y \
  gstreamer1.0-tools \
  gstreamer1.0-plugins-base \
  gstreamer1.0-plugins-good \
  gstreamer1.0-plugins-bad \
  gstreamer1.0-plugins-ugly \
  gstreamer1.0-libav

Fedora / RHEL / Rocky / AlmaLinux

sudo dnf install -y \
  gstreamer1-tools \
  gstreamer1-plugins-base \
  gstreamer1-plugins-good \
  gstreamer1-plugins-bad-free \
  gstreamer1-plugins-ugly-free \
  gstreamer1-libav

x264enc (used when transcoding video to H.264) may require RPM Fusion on Fedora.

Arch Linux

sudo pacman -S --needed \
  gst-plugins-base \
  gst-plugins-good \
  gst-plugins-bad \
  gst-plugins-ugly \
  gst-libav

macOS

Official framework or Homebrew:

brew install gstreamer gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugins-ugly gst-libav

Set GSTPath if needed (e.g. /Library/Frameworks/GStreamer.framework/Versions/1.0).

Windows (dynamic)

Install MSVC 64-bit runtime from gstreamer.freedesktop.org (default: C:\Program Files\gstreamer\1.0\mingw_x86_64), or use a gst-lib/ folder next to the exe. Embedded -gst Windows builds may not need a separate install.

Web UI configuration

  1. Open Settings.
  2. Enable PRO mode.
  3. Open the GStreamer tab.
  4. Adjust options and click Save GStreamer Settings.

Settings are stored separately from main BitTorrent settings and take effect immediately for new streams.

settings.json block

GStreamer options are stored in settings.json under the gstreamer key (inside the Settings section). Legacy keys gst and GStreamer are still read on load; saving from the web UI or API writes the gstreamer key.

Example (settings.json):

{
  "gstreamer": {
    "GSTVersion": 1.26,
    "GSTPath": "",
    "Source": "stream",
    "InactiveMinutes": 5,
    "AACBitrateKbps": 256,
    "SegmentSeconds": 6,
    "appsinkBuffers": 1000,
    "TranscodeH264": false,
    "TranscodeH265": false,
    "TranscodeAV1": false,
    "TranscodeVP9": false,
    "VideoBitrate": 10000,
    "tempfs": false,
    "tempfs_ring": 0
  }
}
Field Description
GSTVersion Installed GStreamer version (minimum 1.26, e.g. 1.26, 1.28). Used for pipeline feature selection.
GSTPath Path to GStreamer installation. Empty = auto-detection.
Source Input URL mode: stream (/stream/...) or play (/play/...).
InactiveMinutes Freeze pipeline after this many minutes without playback.
AACBitrateKbps Audio transcoding bitrate in kbps.
SegmentSeconds HLS segment length in seconds.
appsinkBuffers Number of buffers in the appsink queue.
TranscodeH264 Transcode H.264 video when needed.
TranscodeH265 Transcode H.265/HEVC video when needed.
TranscodeAV1 Transcode AV1 video when needed.
TranscodeVP9 Transcode VP9 video when needed.
VideoBitrate Target video bitrate in kbps when transcoding.
tempfs Use memory-backed tempfs for segments (Linux).
tempfs_ring Extra tempfs ring blocks (0 = default).

API

Settings (requires authentication when --httpauth is enabled; read/write only in -gst builds):

  • GET /gst/settings — on -gst builds: built_in, current config, and platform defaults; on standard builds: { "built_in": false } only

  • POST /gst/settings — update or reset config (404 on standard builds)

    { "action": "set", "config": { "GSTVersion": 1.26, "Source": "stream" } }

    Reset to defaults:

    { "action": "def" }

Streaming (available in -gst builds):

Endpoint Description
GET /gst/echo GStreamer / gst-discoverer health check
GET /gst/:hash/probe Probe torrent file codecs (index, id, or fileID query)
GET /gst/:hash/master.m3u8 HLS master playlist
GET /gst/:hash/init.mp4 Initialization segment
GET /gst/:hash/seg/*segment Media segment
GET /gst/:hash/heartbeat Keep-alive for active transcode task
GET /gst/remove Stop transcode task (hash or id query)

Donate

Thanks to everyone who tested and helped

About

Torrent stream server

yourok.ru

Resources

Readme

License

GPL-3.0 license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 6

MatriX.141.12.0 Latest
Jul 3, 2026
+ 5 releases

Packages

 
 
 

Contributors

Languages

  • Go 59.7%
  • JavaScript 26.6%
  • Shell 9.7%
  • Makefile 1.4%
  • HTML 1.3%
  • Nix 1.2%
  • Dockerfile 0.1%