🇬🇧 English · 🇫🇷 Français

Applies to Hydranos 4.4.

This page is the ten-minute mental model of Hydranos for someone who has never run it. Read it before the install pages if you want to know what you are installing. At the end you will know what an engine, a category, a node and a job are, where Hydranos keeps its state, and which word the rest of the wiki uses for each idea (the glossary at the bottom).

An instance is one running hydranos process with its config file and its store. Everything happens inside that one process: the web UI, the APIs and every BitTorrent session. There is no separate engine process to start or supervise.

An engine is one BitTorrent session inside the process. Each engine has its own listen port (TCP, and uTP on the same port number), its own outgoing connections, its own DHT node (on unless enable_dht = false), its own announce scheduler, its own peer id and its own resume state. Its name is the engine id. Each engine also has its own way out: everything it sends (peer connections, announces, DHT, LSD) leaves by its interface, its managed WireGuard tunnel or its proxy, so two engines on two tunnels are two separate identities in the swarm (see VPN and Egress).

• Every instance always has two engines, race and hoard, even if the config file has no [race] or [hoard] section.
• You can add extra engines (for example vpn1) with engine blocks in the config file (TOML array of tables, see Configuration: Engines and Race Drain) or Nodes › This node › + Add an engine. Engines are built at boot, so a new engine only starts after a restart.
• Each engine has a role, race or hoard. The role is a behaviour, not a name: an extra engine vpn1 with role = "race" behaves like the race engine (race announcing, race drain).

Details, defaults and extra-engine recipes: Engines: Race and Hoard. How the process is built: Architecture.

flowchart LR
    B["Browser (web UI)"] --> P
    A["Sonarr, Radarr, autobrr, cross-seed<br/>qBittorrent shim /api/v2"] --> P
    S["Scripts<br/>REST API /api"] --> P
    M["AI client<br/>MCP: POST /mcp"] --> P
    P["hydranos process<br/>port 8199, one API key"] --> R["engine race"]
    P --> H["engine hoard"]
    P --> X["extra engines (optional)"]
    R --> T["Trackers and peers"]
    H --> T
    X --> T

The two built-in engines exist because torrents that come and go and torrents that stay want opposite things. Neither engine transfers faster than the other: peers, pieces and disk are the same code, and a race torrent downloads and uploads exactly as fast as a hoard torrent. What differs is everything around a torrent's life: how it announces, and whether it is meant to leave.

• Race is the engine for churn: torrents grabbed the moment they are posted, raced in the swarm while it is young, then let go to make room for the next ones. It announces to every tracker of the torrent so it sits in every swarm, and the race drain frees its disks when they fill up: it deletes torrents whose tracker's seed obligation is met, and graduates the others if their category names a Graduate to category on another engine; a torrent with neither stays in place and is counted as stuck.
• Hoard is for the torrents that stay: a library seeded for months, at any size. Its announces stop at the first tier of trackers that answers, which keeps announce traffic proportionate when you seed a very large number of torrents. The race drain never touches it. One sweep does delete hoard torrents with their data: the transit sweep, and only in a category marked Transit area that another category graduates into, once the seed obligation is met. A plain hoard category is never emptied automatically.

If unsure, file your categories as Hoard. Race is for racing fresh uploads, and the race drain can delete race torrents together with their data. Torrents imported from qBittorrent or Transmission always land in hoard, whatever their category's mode.

The full comparison is on Engines: Race and Hoard. The drain, graduation and seed obligations are on Race Drain and Graduation.

A category is a name with a Mode (race or hoard) and a Save Path. You manage them on the Categories tab. When a torrent is added:

• a category with mode hoard sends it to the hoard engine; any other mode sends it to race;
• an unknown category (or no category) sends it to race;
• the save path is the one given in the request, else the category's save path;
• there is no default save path: with neither, the add is refused (no save path: …).

A category mode cannot name an extra engine. To place a torrent on vpn1, give an explicit engine on a native REST API add, an MCP add or a watched folder: it wins over the category's mode. The native add routes and the Add tab can also give a mode (race or hoard), which picks the engine of that role. The qBittorrent shim has no way to name an engine. An engine name that does not exist is refused with HTTP 400 by both native add routes (POST /api/torrents/upload and POST /api/torrents, magnets included), refused by an MCP add of a file (a tool result with isError: unknown engine …), and saving a watched folder that names one is refused (400 no engine "…"); an MCP magnet ignores it and falls back to the category (as does a watched folder whose engine was removed after it was saved).

flowchart TD
    A["Torrent added, with or without a category"] --> E{"Explicit engine given?<br/>(REST, MCP, watched folder)"}
    E -- "yes, and it exists" --> EX["That engine"]
    E -- "yes, but unknown" --> UK{"Which add path?"}
    UK -- "native add routes, MCP file, saving a watched folder" --> R400["Refused: no engine with that name"]
    UK -- "MCP magnet, watched folder whose engine was removed" --> K
    E -- no --> MO{"mode given?<br/>(native routes, Add tab)"}
    MO -- yes --> ROLE["The engine with that role"]
    MO -- no --> K{"Category known?"}
    K -- "yes, mode hoard" --> HO["Engine hoard"]
    K -- "yes, any other mode" --> RA["Engine race"]
    K -- no --> RA
    EX --> SP{"Save path in the request?"}
    ROLE --> SP
    HO --> SP
    RA --> SP
    SP -- yes --> U["Use it"]
    SP -- no --> CP{"Category has a save path?"}
    CP -- yes --> UC["Use the category save path"]
    CP -- no --> REF["Refused: no save path"]

The complete placement rule, including the race add-block refusal and the path claim (a torrent whose files another torrent already holds), is on Categories and Routing.

What happens after placement depends on what is already in the save path.

• Download. No file of the torrent exists at the save path: the engine downloads it.
• Recheck existing data. At least one file already exists: Hydranos hash-checks what is on disk, seeds the pieces that verify and downloads the rest. This is the default on every add path, so pointing a torrent at existing data is safe; it only costs disk reads.
• Seed mode. The caller asserts the data is complete (seed_mode, or skip_checking on the qBittorrent shim): the torrent starts seeding at once, with no hash check and no check that the files even exist. Use it only when you are sure. On the + Add Torrent tab it is the box Skip the hash check, the data is already on disk; the import wizard applies it automatically to torrents that are complete in the old client and whose data it finds.

Torrents that download wait for a free slot when the engine runs a queue (active_downloads, Queue, Share and Speed Limits). Details, magnets, watched folders and duplicate-data hardlinking: Adding Torrents and Existing Data.

data_dir is a key of [daemon]. In the Docker image it is /config, so everything sits in the one /config folder. When the binary writes its own first config elsewhere, data_dir is the data folder next to the config file.

The store is the only copy of the metainfo Hydranos reads at startup: it does not fall back to .torrent files. Back up hydra.db and the engine folders together. Files per platform and the startup order: Architecture. Backups and clean shutdown: Operating Hydranos.

Everything is served by the one process on port 8199 ([daemon] api_port), and one credential opens all of it: the API key ([daemon] api_key, generated at startup if empty, as shipped, or still set to the old published placeholder change-me-in-production). A session cookie from a username/password login (the web UI, the qBittorrent shim's login) is accepted on the same routes.

curl -s -H 'X-Api-Key: YOUR_API_KEY' http://127.0.0.1:8199/api/categories

How the key, the admin account and the shim login fit together: Security and Access.

A node is another complete Hydranos instance, on another machine, that this instance knows about. There is no special node mode: the node runs the same hydranos, with its own engines, store and API key. The instance where you added it is its controller. You either enrol a new machine (+ Enrol a machine: a one-time token and an install command) or declare a running instance (+ Declare an existing one: URL and its API key).

The controller calls the node's normal HTTP API with the node's key, and the node never calls the controller, with one exception: at the end of an enrolment, the install script registers the new machine once with the controller (POST /api/nodes/register), using the one-time token instead of an API key. The controller shows the node's health and merges its torrents into the hoard list, and torrents can be pushed to or pulled from a node. Data travels between the engines over BitTorrent, never through the API. A few per-torrent actions (Edit tags ›, Force download, Share limits…) are not relayed to rows that belong to another node: see Nodes and Multiple Machines.

• Workflows (tab Workflows): a trigger (on a timer, when a download completes, when a torrent is added), conditions in a When tree, and actions in Then. See Workflows.
• RSS (tab RSS): feeds fetched on their own interval, and automatic download rules that add matching articles through the normal add pipeline. See RSS and Automatic Downloads.
• Queue and share limits: per engine, how many torrents run at once and when a seed is stopped or removed (ratio, seeding time). See Queue, Share and Speed Limits.
• Jobs (tab Jobs): persistent background data moves (move_data, graduate) that survive a restart. The word "job" means only these.
• Bulk actions: context-menu actions on a selection of torrents. They run as an in-memory bulk task with a progress panel, are not listed on the Jobs tab, and are lost on restart.

Jobs and bulk actions: Jobs, Bulk Actions and Moving Data.

One name per concept; every page of this wiki uses the Term column. "UI label" is what you click; "Config / API name" is what you type.