Configuration

This page describes every pt-tools setting in detail: environment variables, global settings, downloaders and RSS subscriptions.

Environment variables

Environment variables set how pt-tools runs, which suits Docker deployments.

Variable	Meaning	Default	Example
PT_HOST	Address the web interface listens on	0.0.0.0	127.0.0.1
PT_PORT	Port the web interface listens on	8080	8888
PT_ADMIN_USER	Admin user name	admin	myadmin
PT_ADMIN_PASS	Admin password	adminadmin	MySecurePass123
PT_ADMIN_RESET	Resets the admin password	-	1 (on)
PT_QBIT_COMPAT_ADDR	Listen address of the qB-compatible entrance; off when unset	-	0.0.0.0:8081
PUID	User ID inside the container	1000	1001
PGID	Group ID inside the container	1000	1001
TZ	Time zone	Asia/Shanghai	America/New_York

Using environment variables

On the Docker command line:

docker run -d \
  -e PT_HOST=0.0.0.0 \
  -e PT_PORT=8080 \
  -e PT_ADMIN_USER=admin \
  -e PT_ADMIN_PASS=your_password \
  -e TZ=Asia/Shanghai \
  sunerpy/pt-tools:latest

Docker Compose:

environment:
  PT_HOST: "0.0.0.0"
  PT_PORT: "8080"
  PT_ADMIN_USER: "admin"
  PT_ADMIN_PASS: "your_password"
  TZ: "Asia/Shanghai"

Resetting the admin password

If you forget the password, reset it with environment variables:

docker run -d \
  -e PT_ADMIN_RESET=1 \
  -e PT_ADMIN_USER=admin \
  -e PT_ADMIN_PASS='your_new_password' \
  -v ~/pt-data:/app/.pt-tools \
  -p 8080:8080 \
  sunerpy/pt-tools:latest

After the reset, remove the PT_ADMIN_RESET environment variable and start the container again.

Proxy settings

There are two ways to set a proxy. In Global settings you can send chosen sites through a proxy; a change takes effect as soon as you save it, without a restart. The standard environment variables work whether pt-tools runs in Docker, under systemd or as a binary you start yourself, and need a restart after a change. You can use both: once the site proxy is on, site requests follow Global settings and all other requests follow the environment variables.

Site proxy in Global settings

In the Site proxy (站点代理) part of the Global settings page:

1. Turn on Send site requests through a proxy (站点请求走代理) and enter the proxy address, for example http://192.168.1.2:7890 or socks5://user:password@host:1080. http, https, socks5 and socks5h are supported.
2. Under Which sites use the proxy (哪些站点走代理), choose All sites (全部站点), Only the selected sites (只有选中的站点) or All except the selected sites (除了选中的站点). For the last two, pick the sites in the list below. The list holds every site pt-tools supports; sites you have not enabled are marked Not enabled (未启用). All except the selected sites with nothing selected means all sites.
3. Click Save settings (保存设置). The change takes effect at once, without a restart.

Notes:

• It covers the requests pt-tools sends to sites: searches and torrent lists, RSS feeds, torrent downloads (from RSS, cross-seeding or by hand), sign-in, user info and site icons. An RSS subscription follows the site it belongs to.
• While it is on, site requests follow only this setting: the selected sites go through this proxy, the other sites connect directly, and the proxy environment variables no longer apply to sites. While it is off, site requests follow the environment variables as before.
• It does not cover downloaders, IYUU, notification channels, TMDB and the other media data sources, the AI assistant and so on; they follow their own settings or the environment variables. CloakBrowser has its own proxy setting.
• The proxy address is stored encrypted in the database. The page shows it with the password replaced by ***; leaving it unchanged keeps the stored address.
• Sites that go through the proxy see the proxy's exit IP. If a site's rules care about your IP (HDSky's seedbox rules, for example), check them before sending it through the proxy.
• Only the web interface can change this setting; the App API and MCP can neither read nor change it.

Proxy environment variables

Variable	Meaning	Example
HTTP_PROXY / http_proxy	Proxy for HTTP requests	http://127.0.0.1:7890
HTTPS_PROXY / https_proxy	Proxy for HTTPS requests	http://127.0.0.1:7890
ALL_PROXY / all_proxy	General proxy, used as a fallback	socks5://127.0.0.1:1080
NO_PROXY / no_proxy	Addresses that bypass the proxy, separated by commas	localhost,127.0.0.1,.lan

Notes:

• Set both HTTP_PROXY and HTTPS_PROXY.
• When neither HTTP_PROXY nor HTTPS_PROXY is set, site access and downloader connections fall back to ALL_PROXY. Fetching RSS feeds and the Telegram channel currently read only HTTP_PROXY/HTTPS_PROXY, so set those two when they need a proxy (a Telegram channel can also have its own proxy URL).
• Torrent files that RSS tasks download used to bypass the proxy. They now follow these variables the same way site access does, ALL_PROXY included.
• NO_PROXY is useful for local addresses: it keeps requests to local services and the LAN off the proxy.
• Once the site proxy in Global settings is on, site requests no longer read these variables; see the previous section.
• Restart pt-tools after changing the environment variables.

Proxy examples

On the Docker command line:

docker run -d \
  --name pt-tools \
  -p 8080:8080 \
  -v ~/pt-data:/app/.pt-tools \
  -e HTTP_PROXY=http://127.0.0.1:7890 \
  -e HTTPS_PROXY=http://127.0.0.1:7890 \
  -e ALL_PROXY=socks5://127.0.0.1:1080 \
  -e NO_PROXY=localhost,127.0.0.1,.lan \
  sunerpy/pt-tools:latest

Docker Compose:

environment:
  HTTP_PROXY: "http://127.0.0.1:7890"
  HTTPS_PROXY: "http://127.0.0.1:7890"
  ALL_PROXY: "socks5://127.0.0.1:1080"
  NO_PROXY: "localhost,127.0.0.1,.lan"

Global settings

These options are on the System → Global settings (系统 → 全局设置) page of the web interface:

Setting	Meaning	Default	Suggested
Default interval in minutes (默认间隔（分钟）)	The default interval for RSS tasks	10	15-30 minutes
Torrent file folder (种子下载目录)	The folder where .torrent files are saved	downloads	As you need
Download speed check (启用下载限速判断)	Used to decide whether a torrent can finish within its free period	Off	On if you need it
Estimated download speed in MB/s (预估下载速度（MB/s）)	Your actual average download speed	-	Your real bandwidth
Maximum torrent size in GB (最大种子大小（GB）)	Torrents larger than this are skipped	No limit	50-100 GB
Minimum free time in minutes (最短免费时间（分钟）)	Torrents with less freeleech time left than this are skipped	30	20-60 minutes
Start RSS tasks automatically (自动启动 RSS 任务)	Whether RSS tasks run when the program starts, including after a container restart; see the next section	No	Yes
Site proxy (站点代理)	Sends the selected sites through a proxy and takes effect when you save; see Site proxy in Global settings	Off	On when a site cannot be reached

Starting and stopping RSS tasks

RSS tasks fetch the RSS feeds of enabled sites at their check intervals and push torrents to the downloader according to the download mode and filter rules; RSS new-item notifications come from them too. Brush tasks, cross-seeding, torrent transfer, auto-delete, freeleech-end handling, sign-in, login reminders and media library organising run on their own and are not affected by starting or stopping RSS tasks. Media subscriptions still search the sites on schedule; only "also download when it appears in RSS" waits for RSS tasks to be running.

• Where: click RSS tasks (RSS 任务) at the left end of the status bar at the bottom to open a panel (on a phone, the panel is under Me (我的) in the bottom tabs, and the status row above the tabs shows the state). The panel shows whether RSS tasks are running and how many feeds are running; when they are not running it says why, for example auto-start is off, they were stopped by hand, there is no default downloader, or the default downloader cannot be reached.
• Start and Stop: Start (启动) runs all RSS feeds with the current settings; Stop (停止) stops them until they are started again. Stopping lasts only until the program restarts; after that the auto-start setting decides whether they run.
• Auto-start: Start when the program starts (程序启动时自动运行) in the panel and Start RSS tasks automatically (自动启动 RSS 任务) on the Global settings (全局设置) page are the same switch, off by default. While it is off, RSS tasks must be started by hand every time the program starts, including after a container restart or an upgrade, and a notice at the top of each page says RSS tasks are not running (RSS 任务没有运行). Turning it on starts them right away with the current settings (unless they were stopped by hand) and makes them start whenever the program starts.
• After a settings change: when sites, RSS feeds, global settings or other settings change, running RSS tasks restart with the new settings; tasks stopped by hand are not started. As at program start, the default downloader must be reachable first; if it is not, RSS tasks do not run and the status bar says why. Click Start once the downloader is back.

Download speed and the free period

With the download speed check on, pt-tools uses this formula to decide whether a torrent can finish within its free period:

estimated finish time = torrent size / estimated download speed
if estimated finish time > freeleech time left, skip the torrent

Minimum free time

Even without the download speed check, pt-tools checks how much freeleech time a torrent has left. When that is less than the Minimum free time (最短免费时间) threshold, 30 minutes by default, the torrent is skipped. This keeps a torrent from being paused soon after it starts, which would waste download quota and bandwidth.

Set it to 0 to turn the check off.

When freeleech ends

Setting	Meaning	Default	Suggested
Act early, minutes before freeleech ends (免费期结束前提前处理（分钟）)	Pauses or deletes unfinished torrents N minutes early, to absorb deletion delay and reporting lag	5 (new installs)	5 minutes or more

Whether a torrent still unfinished when its free period ends is paused or deleted is chosen per RSS subscription, in Unfinished when freeleech ends (免费结束时没下完): Do nothing, Pause or Delete; see RSS subscriptions. This used to be the global Delete when freeleech ends (免费结束自动删除): installs that had it on get Delete on the subscriptions that paused at freeleech end, and torrents already waiting for the end of freeleech are handled as before the upgrade.

Acting early adds a safety margin: the pause or deletion runs at freeleech end time - N minutes. That absorbs the delay of the deletion itself and the lag before the downloader reports to the tracker, so that no non-free download is counted after the free period has ended.

• The range is [0, 60] minutes; a value outside it is clamped.
• 0 acts exactly when freeleech ends. A value you already set before upgrading is kept; new installs default to 5. When it is 0 the settings page warns that billed download may still be counted.
• Pushes that require freeleech (the freeleech path, filter rules with Free only on, subscriptions whose quality profile requires free, brush tasks that only take free discounts, waiting for free) also require more than this much freeleech time left, and at least 5 minutes; otherwise they are not pushed.
• The periodic fallback check runs every 5 minutes, so ≥5 minutes is recommended. Each torrent's own timer is accurate to the second, so the main path is not limited to that interval.
• The margin only moves the freeleech-end action; retries keep their own schedule.

Downloaders

Basic settings

pt-tools supports these downloaders:

Downloader	Supported versions	Recommendation
qBittorrent	4.x+	Recommended
Transmission	3.x+	Supported

Fields of the Add downloader (添加下载器) dialog under Downloads → Downloader settings (下载 → 下载器设置):

Field	Meaning	Example
Name (名称)	A name that identifies the downloader	Home qBit, NAS main
Type (类型)	The kind of downloader	qBittorrent / Transmission
Address (地址)	Web UI address	http://192.168.1.10:8080
User name (用户名)	Sign-in user name	admin
Password (密码)	Sign-in password	password
Set as default (设为默认)	Whether this is the default downloader	Yes/No
Start automatically (自动开始)	Whether a pushed torrent starts downloading at once	Yes/No

Download folders

Each downloader can have several download folders:

Field	Meaning	Example
Path (路径)	The folder's actual path	/data/downloads/movies
Alias (别名)	The name shown for the folder	Movies
Set as default folder (设为默认目录)	Whether this is the default download folder	Yes/No

Keep in mind:

• The path must be valid on the machine the downloader runs on.
• In Docker, make sure the path is mapped correctly.
• Wherever a downloader path is entered (RSS subscriptions, brush tasks, follows, pushing a torrent, transfer path mappings, media library path mappings and organising scope), the field lists this downloader's folders when you open it: pick one, or type another path. Folders with an alias show the alias and the path.

Example folders:

Path: /data/downloads/movies    Alias: Movies    Default: No
Path: /data/downloads/tv        Alias: TV        Default: Yes
Path: /data/downloads/anime     Alias: Anime     Default: No
Path: /data/downloads/music     Alias: Music     Default: No

RSS subscriptions

RSS subscriptions are the core of pt-tools. A feed is added on the RSS subscriptions (RSS 订阅) tab of a site's page, with these fields:

Field	Meaning	Required	Example
Name (名称)	A name that identifies the feed	Yes	HDSky movies, MT series
Link (链接)	The RSS feed URL	Yes	https://site.com/rss?...
Category (分类)	The category in the downloader	No	PT-Auto
Tags (标签)	Task tags, to keep things organised	No	hdsky,movie
Check interval in minutes (检查间隔（分钟）)	How often the feed is fetched	Yes	5-1440 minutes
Downloader (下载器)	The downloader to use	No	The default when not set
Download path (下载路径)	The download folder to use	No	The default when not set
Filter rules (过滤规则)	Filter rules attached to the feed	No	Several can be chosen
Unfinished when freeleech ends (免费结束时没下完)	Do nothing, Pause or Delete	No	Pause

Suggested RSS settings

Situation	Suggested interval	Unfinished when freeleech ends
Everyday ratio building	15-30 minutes	Pause or Delete
Following a series	10-15 minutes	Depends
Grabbing new releases	5-10 minutes	Do nothing

The full RSS guide is in RSS subscriptions.

Where data is kept

pt-tools keeps all of its data in the data folder:

Item	Docker path	Local path	Notes
Data folder	/app/.pt-tools	~/.pt-tools	The root of all the data
Database	torrents.db	torrents.db	The SQLite database file
Torrent files	downloads/	downloads/	Downloaded .torrent files
Log files	logs/	logs/	Logs

Log management

pt-tools' logs come in two parts, which are managed separately.

1. Application log files (~/.pt-tools/logs/)

The application rotates these itself with lumberjack, so they need no manual cleanup:

Item	Default	Meaning
Maximum file size	10 MB	A larger file is rotated into a time-stamped backup
Days kept	30 days	Older backups are removed at the next rotation
Backups kept	10	Each log stream keeps at most 10 old backups
Compression	On	Old backups are stored compressed with gzip

The logs are split by level into all.log, info.log, error.log and debug.log. Together the four are capped at about 440 MB, so they do not grow without limit.

An extra cleanup runs on start and removes backups beyond the retention policy. It covers the case where frequent restarts keep each file below the rotation size, which would otherwise leave old backups behind.

Two environment variables change this behaviour at start-up:

Variable	Default	Meaning
PT_TOOLS_LOG_LEVEL	info	Log level: debug/info/warn/error
PT_TOOLS_LOG_CONSOLE	true	Whether logs also go to the console (stdout). On by default, so you can read them with docker logs or in a NAS console; set it to false to turn stdout output off completely

2. The container's standard output log (important for Docker)

WARNING

Docker log growth: the application also writes its logs to stdout, so that docker logs and NAS consoles can show them, and Docker's json-file log driver has no size limit by default. Over a long run this log can reach several GB (8 GB has been seen). It is kept in /var/lib/docker/containers/<id>/<id>-json.log, is not controlled by the application's lumberjack, and has to be capped on the Docker side.

Console output is on by default (PT_TOOLS_LOG_CONSOLE=true) so that logs can be read straight from the container console of a NAS such as fnOS or Synology. So always cap the container's log; otherwise Docker keeps every line of stdout. If you really do not need console logs, turn them off with PT_TOOLS_LOG_CONSOLE=false.

Choose the setting that matches how you deploy:

Docker Compose (recommended, works on every platform): add a logging block under the service.

services:
  pt-tools:
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

docker run: add these options.

docker run -d \
  --name pt-tools \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  ... \
  sunerpy/pt-tools:latest

fnOS, Synology DSM Container Manager, Unraid and Portainer: For a container created in a graphical interface, most versions do not expose the log driver setting. There are two ways to deal with that: (1) for the long term (recommended), deploy with Docker Compose instead and add logging as shown above (a container already created in the GUI can be recreated with Compose over SSH on the NAS; the data folder is persisted, so nothing is lost); (2) as an immediate fix, clear the accumulated container log by hand (see "Clearing an accumulated container log" below). Changing daemon.json for a single container is not recommended.

Linux, as the global default (applies to every container created afterwards): edit /etc/docker/daemon.json.

{
  "log-driver": "json-file",
  "log-opts": { "max-size": "10m", "max-file": "3" }
}

Then run sudo systemctl restart docker. ⚠️ The setting only applies to containers created after the change; an existing container has to be recreated to pick it up.

Clearing an accumulated container log: docker logs cannot empty it. There are two ways:

• Truncate the log file (the container keeps running):

  truncate -s 0 $(docker inspect --format='{{.LogPath}}' pt-tools)

• Or recreate the container (docker rm, then create it again; the data folder is persisted, so nothing is lost).

Backing up data

What to back up: torrents.db (all settings and history) and secret.key (the key that encrypts site cookies, notification credentials and API keys). Back them up and restore them as one unit: a database restored without its original key leaves every saved cookie, notification credential and API key unreadable.

The database runs in WAL mode, so the latest writes may still be in torrents.db-wal. Stop pt-tools before copying:

# Docker (data folder mounted at ./data)
docker compose stop
tar -czf pt-tools-backup.tar.gz -C ./data torrents.db secret.key
docker compose start

# Local install (systemd)
sudo systemctl stop pt-tools
tar -czf pt-tools-backup.tar.gz -C ~/.pt-tools torrents.db secret.key
sudo systemctl start pt-tools

Restoring: stop pt-tools, put the backed-up torrents.db and secret.key back in the data folder over the existing files, then start it. If you kept the key only as base64 text, write it back with pt-tools secret import --force. The full steps are in Upgrades and backups.

Example configurations

A complete Docker Compose file

services:
  pt-tools:
    image: sunerpy/pt-tools:latest
    container_name: pt-tools
    environment:
      PT_HOST: "0.0.0.0"
      PT_PORT: "8080"
      PT_ADMIN_USER: "admin"
      PT_ADMIN_PASS: "your_secure_password"
      TZ: "Asia/Shanghai"
      PUID: "1000"
      PGID: "1000"
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/.pt-tools
      - /path/to/downloads:/downloads # optional: map a download folder
    restart: unless-stopped

Typical setups

Setup 1: ratio building only

• RSS interval: 15-30 minutes
• Download freeleech torrents only
• Set Unfinished when freeleech ends (免费结束时没下完) to Pause (or Delete)
• Set Maximum torrent size (最大种子大小（GB）)

Setup 2: following series as well as building ratio

• RSS interval: 10 minutes
• Create a filter rule for the series that allows torrents that are not free
• Create a general rule that downloads freeleech only
• Set Unfinished when freeleech ends to Pause (or Delete)

Setup 3: several sites

• Configure RSS separately for each site
• Configure several downloaders (at home and at the office, for example)
• Set different download folders
• Use tags to tell the sources apart

---

Related pages:

• RSS subscriptions
• Cookies and API keys
• Filter rules and TV series