jagatranvo/superseedr repository overview

⁠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.

   git clone https://github.com/Jagalite/superseedr.git
   cd superseedr
   

   Copy

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

   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
   

   Copy

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.

     cp .env.example .env
     

     Copy

     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.

     cp .gluetun.env.example .gluetun.env
     

     Copy

     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

⁠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.

⁠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.

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

# Launch from an existing shared root without persisting it
cd "/path/to/seedbox"
superseedr

# 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.

To choose a new available peer-listening port on every start, set client_port = "RANDOM" in settings.toml. You can also launch with SUPERSEEDR_CLIENT_PORT=RANDOM or the shorter PORT=RANDOM. A numeric SUPERSEEDR_CLIENT_PORT takes precedence and selects a fixed port.

⁠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 past 1000, the oldest entries are pruned first.
• This limit applies to persisted runtime history in persistence/rss.toml.

This section is designed for developers, contributors, and AI agents seeking to understand the internal design decisions that drive Superseedr's performance.

⁠⚡ Async Networking Core

Superseedr is built on the Tokio runtime, leveraging asynchronous I/O for maximum concurrency.

• Full-Duplex Streams: Every peer connection is split into independent Reader and Writer tasks (tokio::io::split). This allows the client to saturate download and upload bandwidth simultaneously without thread blocking or lock contention, ensuring the UI remains responsive even with thousands of active connections.
• Actor-Based Session Management: Each peer operates as an isolated Actor. Communication between the network socket and the core logic happens exclusively via mpsc channels, meaning a slow or misbehaving peer cannot block the main event loop or affect other connections.
• Hot-Swappable Listeners: The application runs an async file watcher (notify) on the VPN configuration volume. When Gluetun rotates the forwarded port, Superseedr detects the file change and instantly rebinds the TCP listener to the new port without dropping the swarm state or restarting the process.

⁠👥 Cross-Swarm Peer Manager

The Peer Manager turns per-torrent connection data into a global, IP-centric view of peer behavior without adding continuous work to the TUI render loop.

• Unified Peer Identity: IPv4 and IPv4-mapped IPv6 addresses are normalized and aggregated across torrents, endpoints, and TCP/uTP transports while preserving observed client identities.
• Lifecycle & Transfer Accounting: The manager tracks active and recent peers, torrents and endpoints seen, connection and disconnection counts, total downloaded and uploaded bytes, and last-seen time. The TUI supports filtering, searching, sortable columns, and per-peer evidence details.
• Evidence-Based Restrictions: Excessive transfer behavior and rapid reconnect churn are measured against explicit thresholds. Triggered restrictions expose their strongest evidence and remaining duration instead of presenting an unexplained block state.
• Connection-Boundary Enforcement: A shared peer policy rejects restricted peers on both outbound connection attempts and inbound accepts, including before an inbound handshake is routed to a torrent manager.
• Reactive, Non-Blocking Updates: A dedicated Tokio service reduces torrent metrics in the background and publishes bounded snapshots. The TUI recomputes its derived table only when peer data, filters, sorting, searches, or restriction expiries change.
• Deliberate Persistence Boundary: Active restrictions are atomically checkpointed and restored across launches until they expire. General active/recent peer history remains lightweight runtime telemetry rather than an ever-growing permanent log.

⁠DHT Runtime & Demand Planner

Superseedr ships a first-party Mainline DHT implementation instead of treating DHT as a black-box peer source.

• Dual-Stack Runtime: The internal runtime maintains IPv4 and IPv6 UDP transports, routing tables, peer storage, bootstrap state, and rotating announce tokens while serving inbound find_node, get_peers, and announce_peer traffic.
• Client-Aware Demand: Torrent managers feed demand state and live swarm metrics into the DHT service. The planner prioritizes metadata recovery and peer-starved torrents first, then spends additional query budget on active swarms that are still producing useful peers.
• Pause/Resumable Crawls: Lookup slices can be parked when their wall-time budget expires, preserving traversal state instead of throwing away the crawl frontier. Later planner slices can resume the crawl from the saved state, while the drain path still captures late peers from in-flight queries.
• Adaptive Query Pressure: DHT work is bounded by lookup slots, per-class budgets, late-peer drain handling, and peer-slot pressure. When the client is full, DHT power can ramp down quickly; when capacity returns, it ramps back up gradually.
• Protocol Hardening: The runtime validates response sources, filters unroutable nodes, tracks suspicious identity churn, rate-limits inbound KRPC traffic, and keeps DHT participation disabled entirely in private builds.
• Deterministic Verification: Planner and runtime reducers are covered by deterministic replay tests, invariant checks, and property tests for lookup traversal, scheduling, demand selection, drain behavior, and peer-pressure scaling.

⁠🔒 Security & Privacy Engineering

• VPN Isolation (Kill-Switch): In the Docker Compose setup, Superseedr's network stack is fully routed through Gluetun. This guarantees that 100% of BitTorrent traffic traverses the VPN tunnel. If the tunnel drops, connectivity is cut immediately, preventing any IP leakage over the host connection.
• Binary-Level Private Mode: Private tracker compliance is enforced at compile time, not just runtime. By building with --no-default-features, the DHT and Peer Exchange (PEX) modules are completely excluded from the binary, guaranteeing zero leakage of private swarms.

⁠🏗️ Reactive Actor Model & Verification

The application logic abandons traditional mutex-heavy threading in favor of a Functional Reactive architecture.

• Deterministic State Machine: The TorrentManager operates as a Finite State Machine (FSM). External events (Network I/O, Timer Ticks) are transmuted into Action enums, processed purely in memory, and result in a list of Effects.
• Chaos Engineering: We validate this core logic using Model-Based Fuzzing (via Proptest). Our test suite injects deterministic faults to verify correctness under hostile conditions:
• Network Chaos: Simulates Packet Loss (dropped actions), High Latency (reordered actions), and Duplication (ghost packets).
• Malicious Peers: Fuzzers act as "Bad Actors" that send protocol violations, infinite byte-streams, and out-of-bounds requests to ensure the engine punishes them without crashing.

⁠🤖 Self-Tuning Resource Allocator

Instead of static ulimit values, Superseedr runs a Stochastic Hill Climbing optimizer in the background.

• The Loop: Every 90 seconds, it randomly reallocates internal permits between competing resources—Peer Sockets, Disk Read Slots, and Disk Write Slots—to find the local maximum for performance.
• Universal Optimization: This algorithm dynamically discovers the optimal configuration for any combination of hardware (SSD vs HDD) and network environment (Home Fiber vs Datacenter), automatically scaling concurrency to match capacity.

⁠📡 Integrity Prober

Superseedr automatically and continuously checks completed torrents in the background without falling back to blunt full-library rescans.

• Designed for Scale: Integrity work is split into small bounded batches, keeping checks cheap even across very large collections.
• Fast Fault Detection: Foreground disk-read failures immediately trigger targeted recovery reprobes, surfacing missing or damaged data quickly.