Concepts

🇬🇧 English · 🇫🇷 Français

Concepts

Three ideas explain almost everything in Hydra. Read this before you install — it's what lets you pick the setup that fits you instead of copying someone else's.

1. One brain, one or more muscles (front vs agent)

Hydra splits into a control plane ("front") and a data plane ("agent"):

• The front serves the Web UI and the APIs, routes torrents, and aggregates results. It never talks to peers.
• An agent runs the actual torrent engine(s): it connects to peers, announces to trackers with its own IP / egress, and owns persistence.

By default both live in one process (the "monolith") and you never think about it. But because they're separate, you can put agents on other machines or behind different VPNs and have a single front aggregate them all. That's the whole basis of Deployment Topologies.

2. Two engine roles: hoard vs race

An engine is one Typhon (Rust) process. Hydra runs two by default — the same core tuned for opposite jobs:

	hoard	race
Job	long-term seeding of a big library	grab hot new releases fast
Optimised for	cheap upload at scale (100k+ torrents)	low latency, aggressive download
Storage	large and slow (HDD / array)	small and fast (NVMe)
Lifetime	keeps torrents for months	short-lived, churns often

They're separate processes — separate ports, resume data, and durable stores — so one can't stall the other. Some operations (recheck / verify, per-torrent category moves) are hoard-only by design; race is a lean download path that deliberately omits them. You can add more engines and shard.

What lands a torrent on one engine or the other = its category (Categories and Routing). The category decides the engine and the save path. Through the qBit shim, an unknown category defaults to race.

3. How you talk to it

• Native API /api/* (with an API key) — the real, full interface. Use it by default.
• qBittorrent shim /api/v2/* — makes Hydra look like qBittorrent so autobrr / Sonarr / Radarr / cross-seed work unchanged. This is the integration surface for automation (qBittorrent Shim and Automation).

Everything is a default.toml

Configuration is one TOML file, and most keys are also editable live from the Config tab (Configuration Reference). No hidden state.

---

Where to next

Now that the model is clear, pick your install and shape it to your case — Docker, bare-metal or Windows, plus the networking / VPN / topology that matches your situation. Start at Installation and First Run.

For the wiring under the hood (processes, sockets, persistence), see Architecture.