A BitTorrent Client in your Terminal

Superseedr is a modern Rust BitTorrent client featuring a high-performance terminal UI, real-time swarm observability, secure VPN-aware Docker setups, and zero manual network configuration. It is fast, privacy-oriented, and built for both desktop users and homelab/server workflows.

🚀 Features at a Glance

Experience	Networking	Engineering
🎨 60 FPS TUI + Themes

Fluid, animated interface with heatmaps and 40 live-switchable built-in themes. | 🐳 Docker + VPN

Gluetun integration with dynamic port reloading. | 🧬 BitTorrent v2

Hybrid swarms & Merkle tree verification. | | 📰 RSS Feeds

In-app feed tracking, filtering, and ingest. | 🧩 Cluster Mode

OS-agnostic shared torrent catalog with automatic failover. | 🧠 Self-Tuning

Adaptive limits control for max speed and I/O Stability. | | 🧲 Magnet Links

Native OS-level handler support. | 👻 Private Mode

Optional builds disabling DHT/PEX. | 📡 Integrity Prober

Continuous lightweight background integrity checks with fast recovery reprobes. |

Terminal Torrenting With Superseedr

• Pushing TUI Boundaries: Experience a fluid, 60 FPS interface that feels like a native GUI, featuring smooth animations, high-density visualizations, and 40 built-in themes rarely seen in terminal apps.
• See What's Happening: Diagnose slow downloads instantly with deep swarm analytics, heatmaps, and live bandwidth graphs.
• Set It and Forget It: Automatic port forwarding and dynamic listener reloading in Docker ensure your connection stays alive, even if your VPN resets.
• Crash-Proof Design: Leverages Rust's memory safety guarantees to run indefinitely on low-resource servers without leaks or instability, and shared cluster mode adds automatic failover across hosts.

Installation

Download platform-specific installers from the releases page (includes browser magnet link support): - Windows: .exe per-user installer (no admin) or .msi installer - macOS: .pkg installer
- Debian/Ubuntu: .deb package

Package Managers

• Cargo: cargo install superseedr
• Brew: brew install superseedr
• Arch Linux: yay -S superseedr (via AUR)

Usage

Open a terminal

superseedr

⌨️ Key Controls

Key	Action
m	Open full manual / help
Q	Quit
↑ ↓ ← →	Navigate
c	Configure Settings

[!TIP]
Add torrents by clicking magnet links in your browser or opening .torrent files. Copying and pasting (ctrl + v) magnet links or paths to torrent files will also work.

Troubleshooting

Connection or Disk issues? - Check your firewall allows outbound connections - Increase file descriptor limit: ulimit -n 65536 - For VPN users: Verify Gluetun is running and connected

Slow downloads? - Enable port forwarding in your VPN settings - Check the swarm health in the TUI's analytics view

More help: See the FAQ or open an issue

More Info

• 🤝Contributing: How you can contribute to the project (technical and non-technical).
• ❓FAQ: Find answers to common questions about Superseedr.
• 📜Changelog: See what's new in recent versions of Superseedr.
• 🗺️Roadmap: Discover upcoming features and future plans for Superseedr.
• 🧑‍🤝‍🧑Code of Conduct: Understand the community standards and expectations.

🐳 Running with Docker

Superseedr offers a fully secured Docker setup using Gluetun. All BitTorrent traffic is routed through a VPN tunnel with dynamic port forwarding and zero manual network configuration.

If you want privacy and simplicity, Docker is the recommended way to run Superseedr.

Follow steps below to create .env and .gluetun.env files to configure OpenVPN or WireGuard.

# Docker (No VPN):
# Uses internal container storage. Data persists until the container is removed.
docker run -it jagatranvo/superseedr:latest

# Docker Compose (Gluetun with your VPN):
# Requires .env and .gluetun.env configuration (see below).
docker compose up -d && docker compose attach superseedr

Click to expand Docker Setup

Setup

1. Get the Docker configuration files: You only need the Docker-related files to run the pre-built image, not the full source code.

   Option A: Clone the repository (Simple) This gets you everything, including the source code. bash git clone https://github.com/Jagalite/superseedr.git cd superseedr

   Option B: Download only the necessary files (Minimal) This is ideal if you just want to run the Docker image. ```bash mkdir superseedr cd superseedr

   Download the compose file and example config files

   curl -sL \ -O https://raw.githubusercontent.com/Jagalite/superseedr/main/docker-compose.yml \ -O https://raw.githubusercontent.com/Jagalite/superseedr/main/.env.example \ -O https://raw.githubusercontent.com/Jagalite/superseedr/main/.gluetun.env.example

   Note the example files might be hidden run the commands below to make a copy.

   cp .env.example .env cp .gluetun.env.example .gluetun.env ```

2. Recommended: Create your environment files:

   • App Paths & Build Choice: Edit your .env file from the example. This file controls your data paths and which build to use. bash cp .env.example .env Edit .env to set your absolute host paths (e.g., HOST_SUPERSEEDR_ROOT_PATH=/my/path/seedbox). This is important: it maps the container's shared seedbox root (/seedbox) to a real folder on your computer. Keep superseedr-config/ inside that root for the simplest shared-config setup.

   • VPN Config: Edit your .gluetun.env file from the example. bash cp .gluetun.env.example .gluetun.env Edit .gluetun.env with your VPN provider, credentials, and server region.

Option 1: VPN with Gluetun (Recommended)

Gluetun provides: - A VPN kill-switch - Automatic port forwarding - Dynamic port changes from your VPN provider

Many VPN providers frequently assign new inbound ports. Most BitTorrent clients must be restarted when this port changes, breaking connectability and slowing downloads. Superseedr can detect Gluetun’s updated port and reload the listener live, without a restart, preserving swarm performance.

1. Make sure you have created and configured your .gluetun.env file.
2. Run the stack using the default docker-compose.yml file:

docker compose up -d && docker compose attach superseedr

To detach from the TUI without stopping the container, use the Docker key sequence: Ctrl+P followed by Ctrl+Q. Optional: press [z] first to enter power-saving mode.

---

Option 2: Direct docker run

This runs the client directly without Gluetun. It is useful for advanced users who want to manage networking themselves.

docker run --rm -it \
  -e SUPERSEEDR_DEFAULT_DOWNLOAD_FOLDER=/seedbox \
  -e SUPERSEEDR_SHARED_CONFIG_DIR=/seedbox \
  -e SUPERSEEDR_SHARED_HOST_ID=seedbox-docker \
  -p 6881:6881/tcp \
  -p 6881:6881/udp \
  -v /your/seedbox:/seedbox \
  -v ./docker-data/share:/root/.local/share/jagalite.superseedr \
  jagatranvo/superseedr:latest

Replace /your/seedbox with the shared seedbox root on your host. Keep superseedr-config/ inside that folder so the container sees it at /seedbox/superseedr-config.

🔗 Integrations & Automation

Superseedr is built around a local CLI and a file-based automation model, so you can script, queue, and inspect work without exposing a network control stack. The same command flow works when a client is online, when it is offline, and in shared mode when you are operating against a remote leader through a mounted shared root.

Check out the Superseedr Plugins Repository for plugins (beta testing).

Click to expand automation details

1. File Watcher & Auto-Ingest

Superseedr uses a file-based watch-folder architecture so local automation, scripts, containers, and other processes can control ingestion without needing a separate daemon protocol.

Each node can watch a local watch_folder. In standalone mode, that watch folder feeds the local client directly. In shared mode, followers watch their own local folders and relay supported files into the shared inbox so the leader can process them and update the shared catalog.

Processed watch files are archived after handling so the queue stays deterministic and auditable.

File Type	Action
.torrent	Adds a torrent from a torrent file. In shared mode, follower-side ingest may stage the torrent for leader processing.
.magnet	Adds a torrent from a magnet link stored as text.
.path	Adds a torrent from a referenced torrent-file path. In shared mode, cross-host handling uses portable shared-root-aware staging.
.control	Applies queued control requests such as pause, resume, remove, purge, and priority changes.
shutdown.cmd	Requests graceful shutdown of the running client or shared leader.

See docs/shared-config.md for shared inbox and leader/follower watch-folder behavior.

2. CLI Control

The CLI uses the same file-oriented control model. Depending on mode, commands either:

• write control files for a running client
• queue requests through the shared inbox for the leader
• or apply offline mutations directly when no runtime is available

That makes the CLI easy to script from shells, containers, task runners, and other local automation.

See docs/cli.md for the full CLI guide.

# Add a magnet link
superseedr add "magnet:?xt=urn:btih:..."

# Add a torrent file by path
superseedr add "/path/to/linux.iso.torrent"

# Inspect the current shared launcher selection
superseedr show-shared-config

# Show resolved config, log, status, journal, and watch paths
superseedr show-configs

# Persist shared launcher config for installed/protocol launches
superseedr set-shared-config "/path/to/seedbox"

# Convert local config into layered shared config
superseedr to-shared "/path/to/seedbox"

# Convert the active shared config back into local standalone config
superseedr to-standalone

# Stop the client gracefully
superseedr stop-client

See docs/cli.md for full CLI command behavior, and docs/shared-config.md for shared leader/follower routing.

3. Status API & Monitoring

For external dashboards, health checks, and lightweight automation, Superseedr periodically dumps runtime state to JSON.

• Output Location: a status JSON file in the runtime data area.
• Shared Mode: each host writes its own status file, and shared CLI status follows the current leader snapshot.
• Content: includes transfer stats, runtime metrics, and torrent-level state.

Configuration

You can control how often this file is updated using the output_status_interval setting.

Environment Variable: Set this variable in your Docker config to change the update frequency (in seconds).

# Update the status file every 5 seconds
SUPERSEEDR_OUTPUT_STATUS_INTERVAL=5

4. RSS Feeds & History

Superseedr can track RSS feeds in-app, evaluate feed items against your configured matching rules, and automatically ingest matching releases without needing an external automation stack.

• Feed Tracking: monitor RSS feeds directly from the client.
• Rule-Based Matching: use configured match rules to decide what should be ingested.
• Auto-Ingest: matching items can be queued into the normal torrent ingest path.
• History & Deduplication: downloaded feed history is persisted so the same item is not re-ingested repeatedly.

RSS download history is capped at 1000 entries.

• When the history grows