Home

🇬🇧 English · 🇫🇷 Français

Hydranos Wiki

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.

Start here

I am… / I want to…	Go to
On Docker or a NAS (Synology and similar)	Install with Docker, then First run on Installation and First Run
On Unraid, maybe behind gluetun	Install with Docker (sections Unraid and Unraid behind gluetun), then VPN and Egress
On Linux without Docker (systemd)	Install on Linux (bare metal)
On a Windows PC (zip, tray icon)	Install on Windows
Replacing qBittorrent behind Sonarr/Radarr	Migrating from qBittorrent, then qBittorrent Shim and Automation
Running Hydranos 3.x today	Upgrading from 3.x
Running Hydranos 4.3 today	Upgrading from 4.3 to 4.4
Seeding data I already have on disk	Adding Torrents and Existing Data
Grabbing new episodes from a tracker's RSS feed	RSS and Automatic Downloads
Capping active torrents, stopping seeds after a ratio or a time, limiting speed	Queue, Share and Speed Limits
Putting a VPN in front	VPN and Egress (read it before you rely on a tunnel)
One WireGuard tunnel per engine, built by Hydranos from a provider .conf	Managed WireGuard
Opening ports, port forwarding	Networking: Ports and Port Forwarding
Planning a large library or several machines	Deployment Topologies, then Nodes and Multiple Machines
Watching it (health, logs)	Monitoring and Logs
Scraping it with Prometheus, alert rules	Prometheus Metrics
Automating seeding rules	Workflows
Scripting it, or plugging in an AI client	REST API · MCP Server
Fixing a problem	Troubleshooting, then Known Limitations in 4.4

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

Loading

What is new in 4.4

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.

How the wiki is organised

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.

What 4.4 does not do yet

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.

Project links

• 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)