Web UI Tour

🇬🇧 English · 🇫🇷 Français

Web UI Tour

Applies to Hydranos 4.4.

This page is for anyone opening the web UI on port 8199 for the first time. It walks through the header, the fourteen tabs, the torrent lists, the context menu and the detail panel, and says which wiki page covers each part in depth. At the end you will know where everything is, what runs in the background while a tab is open, and what still has limits in 4.4.

Header

The top bar shows HYDRANOS, the subtitle Torrent Daemon and the running version. When a newer release exists, an update {v} link appears next to the version; the check reads the tags of Kheopsian/Hydranos on GitHub (see Operating Hydranos).

The figures to the right are for the whole instance (race + hoard engines added together):

Label	FR label	What it shows	On a phone
Uptime	Temps de fonctionnement	how long the daemon has been running: Xd Yh, or Xh Ym / Xm under a day	hidden
Upload	Envoi	current upload rate	shown
Download	Téléchargement	current download rate	shown
UL Day	UL du jour	bytes uploaded today	hidden
DL Day	DL du jour	bytes downloaded today	hidden
UL total	UL total	lifetime uploaded	hidden
DL total	DL total	lifetime downloaded	hidden
Ratio	Ratio	lifetime upload / lifetime download	hidden
Exit IP	IP de sortie	the public address traffic leaves from; {n} exits when engines leave through different addresses	hidden

Lifetime counters and where they come from are explained on Monitoring and Logs.

• Exit IP: refreshed every 2 minutes; click it to refresh now (tooltip Refresh the IP now). The figure is not drawn at all when the instance runs no engine.
• Incognito (the eye icon, tooltip Anonymize names, categories & IPs for screenshots): replaces torrent names, categories, IPs, paths and trackers by hashes in every table, so you can take a screenshot safely. It is stored in this browser only and reloads the page when toggled. It changes the display, nothing on the server.
• Network polygon (the small shape right of Incognito): one dot per engine of this instance; its tooltip reads {n} engines — followed by the worst state. The dot's colour only says whether the outbound exit-IP check for that engine answered: green (exit probe answered) = an outside echo service returned an address; amber (no answer yet from its interface) = the engine is pinned to an interface (Linux only in 4.4) and no answer came back through it yet, for example while a tunnel comes up; red (exit probe got no answer) = no answer at all. Green does not mean peers can connect to you. Click the polygon to open the Network panel: one row per engine, named by its engine id, then the role, the interface it is pinned to (or default route), port {port} and its exit IPv4/IPv6. Escape closes it. The page re-reads these values every 30 seconds; the server re-measures them every 3 minutes, or at once when you click Exit IP. Whether peers can reach an engine is shown nowhere in the page in 4.4 (the row tooltip refers to a "health dot" the page does not draw): read it from GET /api/port-forward (engines[].reachable, inbound_peers). What these values mean and how to change them: Networking and VPN and Egress.
• Sign out (the door-and-arrow icon at the far right, FR Se déconnecter): forgets the API key this browser holds and reloads to the login dialog; a qBittorrent-shim session cookie, if this browser has one, is ended too (POST /api/v2/auth/logout). The key itself stays valid, so other browsers and the *arr stack keep working (see Signing in and out below).

A banner Startup pause: {engines} not announcing with a Start now button appears above the tabs, on every tab, while start_paused holds engines after a start: no announce and no peer connection leaves until you click Start now; torrents you stopped yourself stay stopped (see Queue, Share and Speed Limits and Engines: Race and Hoard).

If data_dir sits on network storage (NFS, SMB/CIFS or FUSE on Linux; a network drive or UNC path on Windows; never detected on other systems), an orange bar Config on network storage detected ({kind})… asks you to keep backups of data_dir; Got it hides it in this browser.

Tabs

The tab bar always comes in this order. The active tab is kept in the address bar (http://hydranos.example.org:8199/#hoard), so a bookmark or reload opens the same tab.

Tab (EN)	FR label	What it is for	Where it is explained
Overview	Vue d'ensemble	whole-instance summary: all-time upload, a Race engine card, a Hoard engine card, one Engine {id} card per extra engine (beyond race and hoard), Storage (seed size, data on disk, hardlinks), Records	Monitoring and Logs
Race	Race	the torrents of every race-role engine (heading Race Torrents), per-volume drain cards, the Graduating list	Engines: Race and Hoard, Race Drain, Graduation and Seed Obligations
Hoard	Hoard	the hoard engine's torrents (heading Hoard Torrents), with search, state chips and facets; also merges rows from declared nodes	this page, Engines: Race and Hoard
Categories	Catégories	create and edit categories (name, Mode, Save Path, Transit area, Graduate to (hoard category))	Categories and Routing
Nodes	(stays English)	This node (its engines, + Add an engine) and Other nodes (+ Enrol a machine, + Declare an existing one, per node Edit and Rotate key)	Nodes and Multiple Machines, Engines: Race and Hoard
Workflows	(stays English)	trigger + conditions + actions, with Preview and an Activity log	Workflows
RSS	(stays English)	RSS feeds (Refresh all, + Feed, per feed Articles / Refresh / Edit / Delete, and a Download button per article) and Automatic download rules (+ New rule, qBittorrent's rule syntax, Preview)	RSS and Automatic Downloads
Trackers	Trackers	per-tracker passkey, Minimum seed, announce IP family, Mute / Hide, error counts, per-tracker stats	Trackers and Announces
Config	Config	cards Account, IP filter, Watched folders, Personalisation, Duplicate data, Advanced settings (default.toml) (sub-tabs Network, General, Session Race, Session Hoard, Trackers & Network, Maintenance, Other, Import; the sub-tabs between Network and Import appear only when default.toml has a section for them)	Configuration Reference, Networking (Network sub-tab), Security and Access (Account)
Benchmark	Performances	live cards (plus Upload {id} / Download {id} / Peers {id} per extra engine), announce figures, history charts, Speedtest (▶ Run now), A / B comparison (Compare)	Monitoring and Logs
Changelog	Journal des changements	the release notes (CHANGELOG.md) rendered in the page	CHANGELOG.md in the repository
Logs	Journaux	recent daemon log lines, filtered by module (All modules), level, period and text; Live follows new lines; Copy, Export, Report issue	Monitoring and Logs
Jobs	Jobs	persistent background data moves (move_data, graduate, moves to another node shown as Waiting for the node)	Jobs, Bulk Actions and Moving Data
+ Add Torrent	+ Ajouter un torrent	add by .torrent upload, server-side path or magnet; pending Magnets	Adding Torrents and Existing Data

Two tabs carry a badge when something needs you. Race shows a red badge with the number of stuck torrents (race torrents the drain can neither delete nor graduate, see Race Drain, Graduation and Seed Obligations); clicking it opens the drain history. Trackers shows the number of trackers needing action or throttled/unreachable: the badge is red when at least one needs action, amber when they are only throttled or unreachable. Both badges refresh every 30 seconds.

The import wizard for qBittorrent and Transmission is not a tab: it opens by itself on every page load while nothing has been imported yet, until you click Skip in that browser (the choice is stored in this browser only), and later from Config › Advanced settings (default.toml) › Import › Import…. Its summary lists failures with their reason, and Retry the {n} failed reruns them without retyping the password (see Migrating from qBittorrent).

Working with torrents

The Race and Hoard tabs show a table of torrents. There are no per-row buttons: a click opens the detail panel, a right-click opens the context menu.

Selecting rows

• Click selects one row and opens its detail panel.
• Ctrl-click (Cmd-click on macOS) adds or removes a row; Shift-click selects a range of the rows shown.
• Ctrl+A on the Hoard tab selects every torrent the current search, chips and facets match, not only the rows drawn on screen. The count flashes as {n} selected. The selection is stored as the filter itself: if the filter changes, the selection is dropped; if more torrents match by the time you act, the UI asks again with the new count. Ctrl+A does nothing on the Race tab.
• Escape or a click outside clears the selection and closes the panels.

The context menu

Right-click a selected row. The menu is titled {n} torrent selected ({n} torrents selected for several) and has up to five groups:

Group	Items
State	Stop, Start, Force download, Stop forcing (the force items only for incomplete hoard torrents; forcing marks the torrent for the Forced chip, and the download queue runs it past its ceiling)
Torrent	Reannounce, Recheck (hoard rows only), Change category › (with No category at the top, which clears the label), Change category + move files ›, Set location…, Limit rate…, Share limits…, Sequential download ✓, First/last piece first ✓, Edit tags › (hoard rows only)
Node	Duplicate to engine ›, Move to engine ›. This group appears as soon as this node runs two engines (race + hoard on every default install) or another node is declared on the Nodes tab
Export	Download .torrent files (.zip), Download hash list (.txt), Download as CSV
Remove	Remove torrent, Remove + delete files

• Limit rate… opens Limit rate: {n} torrents with Upload limit (KiB/s) and Download limit (KiB/s): the torrent's own cap, 0 = no cap of its own (the engine's still applies), an empty field keeps the current value. With one torrent selected the fields are prefilled from the daemon.
• Share limits… opens Share limits: {n} torrents with Ratio limit, Seeding time limit (minutes) and Inactive seeding time limit (minutes): -2 = the engine's, -1 = no limit, empty = unchanged. A seed still owing its tracker's minimum seeding time is never stopped or removed. What the limits do: Queue, Share and Speed Limits.
• Sequential download and First/last piece first toggle on the whole selection; the tick shows only when every selected torrent has the setting. The ticks are read from the daemon for up to 50 selected torrents; above that, or after Ctrl+A over a filter, they show unticked and a click turns the setting on. See the Download order section of Adding Torrents and Existing Data.
• Change category + move files › to a category that runs in another engine warns that the torrent stops seeding while its data is copied, then carries on in that engine (follow it on Jobs).

What each item does to data, hardlinks and categories is on Jobs, Bulk Actions and Moving Data; on rows that come from another node, several items fail or act on the local copy (see Nodes and Multiple Machines).

Every menu action is a bulk task

Whether you selected one row or thousands, every context-menu item except the Export group runs the same way: the page sends the selection to the server, which starts a bulk task and returns its id. If the task takes longer than 400 ms, a progress panel opens with a bar and outcome lines such as {n} done, {n} refused (cooldown), {n} not on this node, {n} left in place (hardlinks) or {n} failed.

The three Export items are not bulk tasks: the browser downloads the file straight from POST /api/torrents/export, with no progress panel. Download .torrent files (.zip) first asks whether to Keep trackers or Remove trackers, because a private tracker's .torrent carries your passkey.

flowchart LR
    A["Right-click on selected rows"] --> B["Context menu item"]
    B -->|"any group except Export"| C["POST /api/selection/:action<br/>selection + params"]
    C --> D["Server starts a bulk task<br/>and returns its id"]
    D --> E["Progress panel<br/>shown after 400 ms"]
    E -->|"polls"| F["GET /api/selection/jobs/:id"]
    F --> E
    E -->|"Cancel"| G["POST /api/selection/jobs/:id/cancel<br/>stops between torrents"]

Loading

• Minimize docks the panel in a corner; Cancel stops the task between two torrents; Close dismisses a finished one.
• The panel survives a page reload: the browser keeps the task ids and re-attaches. The server keeps a finished task readable for one hour.
• A bulk task lives in the daemon's memory only. After a restart its outcome is gone, and it never appears on the Jobs tab.
• Above 500 torrents, Stop, Start and the two Remove items ask for confirmation first.

A bulk task is not a job. Jobs are only the persistent data moves listed on the Jobs tab; Change category + move files › and Set location… start such a job for each torrent whose data must move. See Jobs, Bulk Actions and Moving Data.

The Hoard list

The hoard engine is meant for very large libraries, so its list works differently from the race list:

• Server-side. Search, sort, state chips and facets are applied by the server. Only the first 500 matching rows are drawn; refine the filter or sort to see others. Ctrl+A still acts on all matches.
• Search (Search…): words are combined (all must match), ., _ and - count as spaces, and 6 or more hex characters match an info hash.
• State chips (one at a time, with counts): All, Seeding, Actively Seeding, Downloading, Forced, Stopped, Queued, Checking, Tracker Error, Error.
• Facets (the filter lists next to the table): groups Tracker errors (only while some tracker is in error: Dead on the tracker, Bad passkey, Rate-limited, Tracker unreachable, Other error), Trackers, Categories, Tags, plus the chips No tracker, Uncategorized, Untagged. Click a chip to include, right-click to exclude. Several chips combine.
• Reset filters appears as soon as something filters and clears it all.
• Row state badges: stopped (stopped by you, survives a restart), queued (waiting for a download slot, or for a seeding slot when queueing is on), error (its data could not be read).

The Race list is simpler: the whole race engine is fetched at once, search filters it in the browser (same matching rules), and there are no chips or facets. It lists the torrents of every race-role engine of this instance.

Columns

On both lists and both peer tables: click a header to sort, drag it to reorder, drag its edge to resize, and right-click a header for the Columns menu to show or hide columns (for example Save Path, Hardlinks or Checked on the Hoard table). The layout is saved in this browser.

The detail panel

Click a row to open its detail panel below the table. It refreshes every 3 seconds while open.

Panel tab	Race	Hoard	What it shows
Info	yes	yes	cards, peers, trackers (below)
Timeline	yes	no	the race result (Winner! or Lost by {delta}), progress and per-peer download charts, an Events log. It reads the benchmark database (bench.db); with no data for this torrent it stays empty. See Monitoring and Logs
Content	yes	yes	the Files list: Path, Size, Downloaded, Progress (with a bar) and Priority, unfinished files first. – when the engine has no piece map for the torrent yet. The summary line gives {done} downloaded · {missing} missing, plus sequential / first/last piece first when set. Priority is Normal, High or Maximum (qBittorrent's 1, 6, 7) and changes the order files are downloaded in, never whether: every file is always downloaded, there is no do not download. Read-only on a row from another node

On the Info tab:

• General: state, progress, size, downloaded, uploaded, ratio, Save Path, Info Hash.
• Speed & Connections: rates, Speed limits (↑ … · ↓ …: the torrent's own cap, … (engine) when the engine's cap is the tighter one, or unlimited), Share limits (ratio … · seeding … min · inactive … min, none for a field with no limit, (engine) where the value comes from the engine, then → the action, such as stop, when a limit is set), averages, connected peers and seeds, pieces and piece size, added, Seeding Time (the race panel also shows swarm seeds/leechers).
• Connected Peers: a Pieces map and the peer table (IP, Client, Progress, Down, Up, Downloaded, Uploaded, Flags), which scrolls inside its card. Each row has a Ban button: the address is disconnected now and refused from then on. Bans are listed and removed in Config › IP filter (see Networking).
• Trackers: a line Announced as / Next announce with the peer id this engine announces, then the table Tracker / Status / Last / Next / Scrape and the Edit trackers button. The editor takes one URL per line, a blank line starting a new tier. See Trackers and Announces.

On the hoard panel, a torrent whose data cannot be read shows the box This torrent cannot read its data with the advice to restore the files and recheck.

Personalisation

Everything here is stored in this browser only (localStorage): another browser, or another person using the same instance, keeps their own settings. Nothing needs a restart.

Setting	Where	Choices
Language	first-run screen; later Config › Advanced settings (default.toml), top card Language › Interface language	English, Francais, Deutsch, Espanol, Italiano, Portugues, Nederlands. Changing it reloads the page. Default: the browser's preferred language if offered, else English
Theme	Config › Personalisation	Abyss (default), Slate, Ember, Kelp, Daylight. Applies immediately
Tabs	Config › Personalisation	untick a tab to remove it from the bar. It hides the link only: the feature and its API keep working. Overview and Config cannot be hidden
Display units	Config › Advanced settings (default.toml), top card	Sizes: Binary — KiB / MiB / GiB or Decimal — KB / MB / GB; Speeds: Bytes/s — KiB/s, MiB/s or Bits/s — Mbps, Gbps
Column layout, sort, Incognito	the tables, the header	as described above

The Reset to defaults button on the Personalisation card only resets the theme and the hidden tabs. It is not the Reset to defaults of Advanced settings, which rewrites default.toml and restarts. The UI's restart buttons (Restart now, Apply & restart, Save and restart, Reset and restart) stop the daemon the way SIGTERM does (drain, resume state flushed), then exit with code 75, so Docker's restart policy or a Restart=on-failure unit brings it back; on Windows the process starts its successor itself. Started by hand on Linux with no supervisor, it stays down (see Operating Hydranos).

Only French is substantially translated. The other five languages cover a few screens (first run, some tab names) and fall back to English everywhere else; even in French, parts of the UI stay English (the Nodes, Workflows and RSS tab names, the hoard state chips, the Interface per engine heading, the Remove button of a node, many buttons).

Signing in and out

• Starting: while the daemon restores its state, the page shows a startup screen with the phase (Restoring state…, Connecting to the network…, Opening the database…, Starting…) and a {restored} / {total} torrents counter; it gives way to the UI by itself.
• First run: the Welcome to Hydranos screen asks for a language, a username (prefilled admin) and a password of at least 8 characters, then Create account. Details and the local-network restriction: Installation and First Run and Security and Access.
• Later: the Hydranos login dialog (Sign in). It trades your username and password for the instance's API key, which the browser keeps in localStorage (hydra_api_key) and sends with every request. The same key opens the REST API, the qBittorrent shim and the MCP server.
• If any request answers 401 (for example after the key was changed), the login dialog comes back with Session invalid, please sign in again.
• Open on the Nodes tab logs you into another node by passing its key in the address fragment (#key=…); the page stores it and removes it from the address bar.
• Sign out (the icon at the far right of the header) forgets the key in this browser and ends its qBittorrent-shim session cookie, if any (POST /api/v2/auth/logout). The key stays valid for every other browser and client. To cut them all off, change [daemon] api_key: once the new key is in effect, every browser still holding the old one gets the login dialog again. See Security and Access.
• The API key is displayed in one place only: Config › Advanced settings (default.toml) › General, row api_key (with generate and copy buttons).

Mobile layout

Below 768 pixels wide:

• the header keeps only Upload and Download (plus the incognito eye, the network polygon and Sign out);
• tables switch to a short set of columns, each cell labelled: Race Name, Progress, Down, Up; Hoard Name, State, Progress, Up; peers IP, Progress, Down, Up;
• the hoard facets fold behind a ▸ Filters button, which shows the number of active filters, e.g. ▸ Filters (2).

Everything else (tabs, context menu, detail panel) is the same as on a desktop.

UI limits in 4.4

The controls that were stubs in 4.3 (the Add tab's Mode, Change password, the Network sub-tab's VPN and proxy modes, Speedtest ▶ Run now, the Logs filters and Live, Cancel on the Jobs tab) all act in 4.4, and the dead Choking card, Remove Torrent dialog and SEEDBOX badge are gone from the page. What is still partial:

Known bug in 4.4: the page never shows whether peers can reach an engine. The Network panel's colour is the outbound exit probe only, and its row tooltip refers to a health dot that is not drawn. Read GET /api/port-forward (engines[].reachable, inbound_peers) instead.

• Sequential download / First/last piece first ticks are not read for more than 50 selected torrents or after Ctrl+A over a filter: they show unticked and a click turns the setting on.
• A file Priority cannot be do not download: every file of a torrent is always downloaded (by design).
• Cancel on the Jobs tab drops a waiting job, stops a move to another engine after the current file (put back as it was) and stops a move to a node from waiting (both copies kept); any other running move cannot be interrupted and finishes.
• The RSS tab, the Workflows tab's Dry-run and Run now (their result shown as raw JSON) and the peer table's Ban button still confirm and report errors with the browser's own dialogs, not the UI's styled ones. The Workflows tab's Delete and the Network tab's Remove on a WireGuard config file confirm with the browser's dialog too; a failed Remove is reported in the styled result box, a failed workflow Delete is not reported at all.

The complete list is on Known Limitations.

Refresh rate

The page polls the server every 1 second and refreshes only the active tab. What that costs depends on the tab:

Active tab	What is fetched
Race	the whole race list every second, plus the drain status and graduations
Hoard	rows are not refetched every second. Live figures (rates, peers, state) and removals arrive over the /api/events stream about once a second; the 500-row page itself is refetched at most every 20 seconds, and at once when you change search, sort, chips or facets. A torrent added from somewhere else (qBittorrent shim, watched folder, workflow) appears at the next 20-second refresh; one added from this page appears at once
Categories, Trackers, Benchmark, + Add Torrent	that tab's data every second
Jobs	its own 2-second timer, stopped when you leave the tab
Overview, Nodes, Workflows, RSS, Config, Changelog, Logs	loaded when you open the tab; the header and Overview figures come from the /api/events stream, the Overview's extra-engine cards are refetched at most every 3 seconds, and Logs with Live ticked follows new lines over /api/logs/stream
detail panel (when open)	that torrent every 3 seconds

Whatever the tab, the header figures update about once a second, the network polygon every 30 seconds, the Race/Trackers badges every 30 seconds and the Exit IP every 2 minutes. The live stream skips updates while the browser tab is hidden.

With a very large race engine, keep the Race tab closed when you do not need it: it downloads the full list every second. The Hoard tab pages its list server-side instead. Leaving a tab is enough to stop its polling. Sizing figures for large libraries are on Deployment Topologies.

Related pages

• Concepts and Glossary: the words used in this page.
• Adding Torrents and Existing Data, Categories and Routing, Jobs, Bulk Actions and Moving Data.
• Security and Access: the API key, password recovery, exposing the UI.
• RSS and Automatic Downloads, Queue, Share and Speed Limits: the RSS tab and the limit dialogs in depth.
• Known Limitations: every gap of 4.4 in one place.