superseedr: a BitTorrent client built as a terminal UI

Why a torrent client in a terminal

The usual BitTorrent clients are GUI applications that expect to own the foreground window. superseedr takes the opposite position: it is a terminal application built with Ratatui, described as a modern Rust client with a high-performance terminal UI and real-time swarm observability. The README claims a 60 FPS interface with heatmaps and 40 live-switchable built-in themes, and points to a browser based live demo that runs entirely client-side without performing real torrent, network or disk operations.

The audience is stated in the summary: desktop users and homelab or server workflows. A seedbox running headless is the case where a terminal client stops being a novelty. The other half of the product is diagnosability. The feature table lists deep swarm analytics, heatmaps and live bandwidth graphs under an experience column, and the troubleshooting section tells you to check the swarm health in the TUI's analytics view when downloads are slow. That is a diagnostic surface few conventional clients surface so prominently.

The project is a mature enough codebase to have a fuzz directory, a workspace member named fuzz, nightly fuzzing badges in the workflow status, proptest regression files and a separate integration test suite with its own requirements file. The repository is not archived and the last push was on 2026-10-20, with v1.0.16 released on 2026-10-17, v1.0.15 on 2026-09-22 and v1.0.14 on 2026-08-30.

What the Cargo features say about peer discovery

The manifest is the clearest statement of how the client's behaviour can be varied. The default feature set is explicit in Cargo.toml:

default = ["dht", "pex", "webtorrent"]

A comment above that line states that native builds include peer discovery and WebTorrent support by default. The individual feature flags dht, pex and synthetic-load are empty markers used for conditional compilation. This matters because the feature table advertises an optional private mode that disables DHT and PEX, and the Dockerfile shows how that is built rather than toggled at runtime: the build argument PRIVATE_BUILD defaults to false, and the builder stage runs xx-cargo with --no-default-features when PRIVATE_BUILD is true. The same argument is threaded into the compose file as a build arg.

So the private build is a compile time decision, not a setting in the interface. A user who wants to run without DHT and PEX cannot flip it in the TUI; they need a separately built image or a local cargo build without default features. The compose file makes that reachable through a build arg, and the .env.example hints at a private image tag for it.

One more feature flag, synthetic-load, exists without an explanation in the visible manifest, and the WebAssembly crate under web/wasm is excluded from the workspace, which is consistent with the browser demo being a separate build target rather than part of the client binary.

Gluetun, the forwarded port and the env file contract

The Docker path is the heart of the privacy story, and it is a two container design. The compose file defines a gluetun service from the qmcgaw/gluetun image with NET_ADMIN and the /dev/net/tun device mapped in, and a superseedr service that joins it through network_mode service:gluetun, with depends_on gated on the gluetun service being healthy. Because the client shares the gluetun network namespace, all torrent traffic leaves through the VPN tunnel.

Port handling is the detail that trips people up. Gluetun publishes the forwarded port through a shared volume mounted at /tmp/gluetun, and the compose file also mounts that volume at /port-data inside the client. The firewall rule inside gluetun reads FIREWALL_VPN_INPUT_PORTS from the CLIENT_PORT variable, and the client itself is told the same value through SUPERSEEDR_CLIENT_PORT with a default of 6881. When the VPN provider reassigns the port, gluetun rewrites the forwarded port file and the client reloads its listener, which is what the summary means by dynamic port reloading.

The .env.example is explicit that CLIENT_PORT should be a static number for providers that do not support programmatic port forwarding, and that RANDOM must not be used there because the VPN and firewall container needs a fixed value. It also warns against pointing the config variables at an existing native config folder such as ~/.config/jagalite.superseedr, because sharing config between a native install and the container causes path errors.

Running the container and reaching the interface

The README gives two Docker commands. The first is the plain container with no VPN:

docker run -it jagatranvo/superseedr:latest

The comment above it notes that this uses internal container storage and that data persists only until the container is removed. That is a real limitation for a torrent client, since the data is the point. The compose route is the one to prefer when the data has to survive:

docker compose up -d && docker compose attach superseedr

This one requires the .env and .gluetun.env files to be created first, which the README covers in a collapsible setup section that is cut off in the copy available here. The compose file maps three host paths into the container, a seedbox path that becomes /seedbox and is where downloads land, a share path mounted at /root/.local/share/jagalite.superseedr, and a windows-watch path. Environment variables set the default download folder to /seedbox and point the watch path at /windows-watch.

The compose file also sets tty, stdin_open and init to true, stop_grace_period to 0s, and the entrypoint to superseedr with an empty command. That combination is what makes an interactive terminal UI work inside a container at all, and it is also why attaching rather than running detached is the documented way to interact with it.

Native install and the key map you actually need

For a native install the README points at the releases page for platform specific installers, with a Windows .exe per-user installer that needs no admin rights or an .msi installer, a macOS .pkg and a Debian or Ubuntu .deb. Package managers are listed as well, with cargo install superseedr, brew install superseedr and yay -S superseedr for Arch.

Once installed, launching the client takes no arguments:

superseedr

The key map is short. `m` opens the full manual, `Q` quits, the arrow keys navigate, `C` opens settings, `R` opens the RSS feed view and `Z` toggles power-saving mode. Add torrents by clicking magnet links in the browser or opening .torrent files, since the Linux bundle metadata registers the application/x-bittorrent and x-scheme-handler/magnet mime types with exec_args %U, and the releases are described as including browser magnet link support. Pasting a magnet link or a path with ctrl+v works too.

The RSS feature is the piece with a hint of scope beyond a plain client: the table describes in-app feed tracking, filtering and ingest. Whether that is a full automation pipeline or a browser for feed items is not spelled out in the visible documentation, and the FAQ at docs/FAQ.md would be the place to look.

Where superseedr is the wrong tool

There are several honest reasons to pick something else. First, a terminal UI is a hard requirement rather than a preference: if you want a window, a system tray icon and a progress bar, a conventional client serves you better, and the browser demo explicitly does not perform real torrent, network or disk operations, so it tells you nothing about whether the client handles your workload.

Second, the container deployment has a fixed topology. The client shares the network namespace of gluetun, which means the VPN container must be healthy before the client starts, and the compose file depends on the qmcgaw/gluetun image being reachable. If your VPN provider does not support the port forwarding model that gluetun expects, the forwarded port file never appears and the client has no port to bind. The .env.example addresses this with a static CLIENT_PORT for providers without programmatic forwarding, which helps, but the setup still assumes a VPN that exposes a forwarded port at all.

Third, the private mode is a build time switch, so changing it later means rebuilding the image rather than changing a setting. Anyone who wants to toggle DHT and PEX at runtime should look elsewhere. Finally, cluster mode, described as an OS agnostic shared torrent catalog with automatic failover, is the most complex feature and the least documented here, and it should be treated as unproven until you have read the docs it depends on.

Editorial conclusion

superseedr fits the operator who wants torrent activity in a terminal on a homelab box, with the Docker and Gluetun path taken seriously enough to route traffic through a VPN tunnel, and who is willing to read docker-compose.yml before deploying. It does not fit someone who wants a one-click desktop client, who needs a UI they can hand to a non-technical streamer, or who plans to run it without a config directory of their own. Before adopting it, check that PRIVATE_BUILD is set correctly for your DHT and PEX needs, confirm the client port in .env matches what your VPN provider forwards, and verify the container shares the path you actually want your downloads in.

Frequently asked questions

Official sources

1. Issues
2. Jagalite/superseedr on GitHub
3. License: GPL-3.0
4. README
5. Releases