🇬🇧 English · 🇫🇷 Français

Applies to Hydranos 4.4.

Hydranos is a BitTorrent client built to keep a very large library seeding. One program (hydranos) runs two engines out of the box: race for torrents that come and go (racing new releases, then letting them leave), and hoard for the torrents you keep (if unsure, file your categories as Hoard). You drive it from a web UI, a native REST API, a qBittorrent-compatible API (so Sonarr, Radarr, autobrr and cross-seed keep working) and an MCP endpoint for AI clients. All four answer on one port (8199 by default) and accept the same API key. Hydranos can also follow a tracker's RSS feed, queue and limit torrents per engine, and put each engine behind its own VPN tunnel. The words are explained in Concepts and Glossary. This page sends you to the right page.

New install, step by step:

flowchart TD
    A{"Running Hydranos 3.x today?"} -- yes --> U["Upgrading from 3.x"]
    A -- no --> P{"Which platform?"}
    P -- "Docker, NAS, Unraid" --> D["Install with Docker"]
    P -- "Linux with systemd" --> L["Install on Linux (bare metal)"]
    P -- Windows --> W["Install on Windows"]
    D --> F["Installation and First Run<br/>admin account, first category"]
    L --> F
    W --> F
    F --> Q{"Replacing qBittorrent<br/>behind Sonarr or Radarr?"}
    Q -- yes --> M["Migrating from qBittorrent"]
    Q -- no --> C["Categories and Routing"]
    M --> V{"VPN in front?"}
    C --> V
    V -- yes --> E["VPN and Egress"]
    V -- no --> K["Known Limitations in 4.4"]
    E --> K

For someone coming from 4.3. What changes for an existing install (keys now read, new defaults, restart exit code) is on Upgrading from 4.3 to 4.4; the full history is in the changelog (Project links).

• RSS: feeds, folders and download rules in a new RSS tab, also over the qBittorrent API (rss/*). See RSS and Automatic Downloads.
• Queue, share and speed limits: per-engine download and seed ceilings, ratio and seeding-time limits (stop or remove), upload and download caps per torrent, per engine and client-wide, and an optional choker. See Queue, Share and Speed Limits.
• Download order: file priorities (normal, high, maximal), sequential download and first-and-last piece first. See Adding Torrents and Existing Data.
• The five network modes are real: Direct, managed WireGuard, Gluetun, SOCKS5 and SOCKS5 + PROXY-v2 relay, with a kill switch, an engine's interface pinning every one of its sockets, and a separate way out for the daemon's own requests. See VPN and Egress and Managed WireGuard.
• The shim reports real figures: Sonarr, Radarr and autobrr see the real uploaded and ratio, so their seed goals now act. See qBittorrent Shim and Automation.
• Fixed controls: the web UI's restart buttons stop cleanly, Change password stores the password, hydranos reset-password exists, the header has Sign out, and the Add tab's Mode, subfolder (not for a magnet) and skip-check options are applied. See Operating Hydranos, Security and Access, Adding Torrents and Existing Data.

The sidebar follows the order a newcomer reads in.

• Start: this page, Concepts and Glossary, Web UI Tour.
• Install: Installation and First Run (ports, first run), Docker, Linux (bare metal), Windows, Migrating from qBittorrent, Upgrading from 3.x.
• Use: Categories and Routing, Adding Torrents and Existing Data, RSS and Automatic Downloads, Queue, Share and Speed Limits, Engines: Race and Hoard, Race Drain, Graduation and Seed Obligations, Trackers and Announces, Jobs, Bulk Actions and Moving Data, Workflows.
• Integrate: qBittorrent Shim and Automation, REST API, MCP Server.
• Network & machines: Deployment Topologies, Networking: Ports and Port Forwarding, VPN and Egress, Managed WireGuard, Nodes and Multiple Machines.
• Operate: Operating Hydranos (stop, restart, backup, updates), Monitoring and Logs, Prometheus Metrics, Security and Access, Troubleshooting, Known Limitations in 4.4.
• Reference: Architecture, Configuration Reference, Configuration: Daemon, Auth and Global Sections, Configuration: Engines and Race Drain, Configuration: Environment Variables, CLI and Signals.

The gaps you are most likely to hit. Each is explained on the page linked; the full list is on Known Limitations in 4.4.

• No search, no selective download (every file is always downloaded: priority 0 is refused), no alternative or scheduled speed limits, one user only. See Migrating from qBittorrent and Queue, Share and Speed Limits.
• No queue positions: the priority calls answer 409. To run a torrent past the queue, use Force download (Sonarr's or Radarr's Force Start does the same). See Queue, Share and Speed Limits.
• Saving an RSS rule from the web form erases the tags it got through the API or a qBittorrent client, and the form has no priority or tags field. See RSS and Automatic Downloads.
• The web UI never shows whether peers can reach an engine; read GET /api/port-forward. See Networking: Ports and Port Forwarding.

• Repository: github.com/Kheopsian/Hydranos
• Releases: github.com/Kheopsian/Hydranos/releases
• Changelog: CHANGELOG.md
• BitTorrent conformance (what the client sends to trackers, with the tests that check it): docs/BITTORRENT-CONFORMANCE.md
• Licence: GNU Affero General Public License v3.0 (AGPL-3.0)