Categories and Routing

Categories & Routing

A category in Hydra is more than a label — it decides which engine(s) host a new torrent and where on disk each one saves it. This is what makes multi-engine / multi-agent placement work without any per-add plumbing.

What a category holds

• mode / role — race or hoard (the default engine role for this category).
• placement — which engines/agents host new torrents in this category (defaults to the local engine of the right role).
• strategy — when placement lists several engines, how to choose:
  • all — fan out to every listed engine (multi-home the torrent),
  • least_torrents — pick the least-loaded by count.
• save-path per engine — each engine can save this category somewhere different (e.g. a distinct disk per agent). A category with no explicit path derives <data-root>/<category>.

Categories are edited from the Categories tab in the UI, or via the API, and persist in categories.json.

How routing works

• Native / UI add with a category → resolved server-side to the category's placement, strategy and per-engine save-path.
• qBit-shim add (/api/v2/torrents/add) → the category field drives the same routing, so autobrr / *arr just set a category and Hydra places it.
• A category with no placement degenerates to the local engine — i.e. a single-box setup behaves exactly as you'd expect, and the same model generalizes for free to multi-agent.

Changing a category's save-path affects new torrents only; existing torrents are not moved automatically.

Multi-homing

With strategy = all, the same info-hash is added to several engines and each seeds it independently (native BitTorrent, no coordination). If those engines are separate seedboxes on a private tracker, make sure the tracker allows multi-client seeding of one account before you fan out.

See Deployment Topologies for how engines/agents are wired, and Adding Torrents and Existing Data for how data-on-disk interacts with placement.