Hydranos

A self-hosted BitTorrent daemon built for scale and seeding: one Rust process ("Typhon") holding a very large catalogue and keeping every torrent of it announced. Hydranos runs over a million torrents in a single instance in production today. It exposes a live web UI, a native REST API, and a qBittorrent-compatible shim so your existing *arr / autobrr / cross-seed setup keeps working unchanged.

Status: opened up from a private homelab project. It is used in production but some rough edges remain; issues and PRs welcome.

---

Why Hydranos?

Most BitTorrent clients are designed around a few thousand torrents, and do that very well. At hundreds of thousands the constraints change: how long the client takes to start, and whether every torrent is still announced on schedule. A torrent the tracker has not heard about is a torrent nobody downloads from you. Hydranos is built around those two constraints, and around three uses of one instance:

• Hoard. Seed a very large library and keep all of it announced: over a million torrents in production today.
• Race. Grab and seed new releases fast. Hydranos runs a race engine and a hoard engine side by side in one process, each tuned for its job, so a large library never slows a race down.
• Stay light. Holding 290,000 torrents took 2.8 GiB of RAM (about 10 KiB per torrent, measured on 4.2), where the other clients we measured needed 12 to 31 GiB.

How Hydranos and three other clients behave at 290,000 torrents, measured on the same machine.

And your automation keeps working: the qBittorrent v2 API shim means Sonarr/Radarr, autobrr and cross-seed talk to Hydranos unchanged.

If you seed a few hundred torrents, qBittorrent or Transmission will serve you with less to learn.

Also in the box:

• Networking per engine: managed WireGuard (a tunnel per engine, with port forwarding), gluetun, SOCKS5 or a PROXY-v2 relay, an interface pin, and a kill switch that keeps an engine off the network when its way out is down.
• qBittorrent's day-to-day features: the download queue (including "do not count slow torrents"), share limits, speed limits, RSS feeds with automatic download rules, file priorities, sequential download, magnets, UDP trackers and LSD.
• Several machines behind one UI: engines on other machines enrol as nodes, and torrents move between them.
• Existing data: an add hash-checks what is already on disk instead of downloading over it, and a qBittorrent library can be imported as is.
• Observability: Prometheus /metrics, a benchmark tab with a line speedtest and before/after comparison, and an MCP server for AI assistants.
• Linux (Docker or bare metal) and Windows.

---

For tracker operators

What Hydranos puts on the wire is documented, rule by rule, in docs/BITTORRENT-CONFORMANCE.md. Every claim there names the test that asserts it: the unit suite runs offline in seconds, and tools/interop/run.sh runs the client against opentracker, Torrust in private mode and qBittorrent/libtorrent, reading the verdict from their state rather than ours. Both run on every push. In short:

• Session counters. uploaded/downloaded count from started, never the lifetime total; left comes from the pieces held.
• BEP 3 events per tracker. started, completed (once, to every tracker that saw us leech, retried if one is down) and stopped; a cross-seed is never a snatch.
• Your floors hold. min interval, BEP 31 retry in and Retry-After are obeyed per tracker, races included. Only a re-announce a person forces crosses min interval, as qBittorrent's does. An unregistered race is retried every 5 s for 6 minutes (registration_retry_minutes), the window autobrr uses. BEP 12 tier order is respected, and tracker id is echoed back.
• One identity. Peer id -HY####-, the same to every tracker and every peer, User-Agent: Hydranos/<version>, a stable secret key. No client spoofing.
• Private torrents stay private (BEP 27): no DHT, PEX, hole punching or LSD, and peers named by other peers are ignored.
• Scrape only for what is not announced yet. Swarm counts come from the announce response; a torrent no tracker has answered for (queued at boot, stopped) is scraped (BEP 48 / BEP 15) for its counts and nothing else.

---

Screenshots

All screenshots below are taken with incognito mode on: torrent names, categories, paths, IPs and tracker hostnames are replaced by stable fakes.

Overview — live dashboard: global up/down, seeding/leeching counts, per-session throughput.

Race — one finished race in detail: where it placed in the swarm, how the download went, which peers it came from, and what it has uploaded since.

Hoard — the long-term seeding library, filtered by tracker, state and category.

Trackers — one row per tracker actually announced to: passkey override, announce IP family, seed obligation, and the errors seen in the last hour.

Benchmark — traffic per engine, disk and cache health, and whether the announces keep up with the catalogue, from fifteen minutes to thirty days; plus a line speedtest and a before/after comparison around a change.

Workflows — rules over the library, built from conditions and actions and previewed before they run. Here: tag every torrent in the media categories whose files have no hardlink outside Hydranos, i.e. that can be deleted without losing anything.

---

Documentation

Install steps, architecture, every networking mode and the edge cases live in the Wiki:

• Installation & First Run
• Migrating from qBittorrent
• Architecture
• Networking Modes
• Deployment Topologies
• Categories & Routing
• Adding Torrents & Existing Data
• qBittorrent Shim & Automation
• Queue, Share and Speed Limits
• RSS & Automatic Downloads
• VPN & Egress · Managed WireGuard
• Prometheus Metrics
• Configuration Reference
• Troubleshooting · Known Limitations

API reference: docs/API.md. Companion VPS relay: hydra-relay.

---

License

Hydranos is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE. In short: you're free to run, study, modify, and share it, including self-hosting a modified version, but if you offer a modified Hydranos to others over a network, you must make your source available under the same license.