Skip to content

Configuration Reference

Kheopsian edited this page Oct 12, 2026 · 11 revisions

🇬🇧 English · 🇫🇷 Français

Configuration Reference

Applies to Hydranos 4.4.

This page is for anyone who opens default.toml or the Config tab and wants to know what a setting really does before changing it. By the end you will know where the file is, how it is laid out, when an edit takes effect, what the web editor can change, which missing keys change behaviour, and which keys do nothing in 4.4 (Hydranos names them at startup). The key-by-key reference is on three sub-pages: Configuration: Daemon, Auth and Global Sections, Configuration: Engines and Race Drain and Configuration: Environment Variables, CLI and Signals.

The configuration file

Hydranos reads one TOML file, default.toml, given by --config <path>. Without --config the path is /config/default.toml, except on Windows, where it is the default.toml beside hydranos.exe.

Install Config file data_dir written on first start
Docker (stock image) /config/default.toml (the entrypoint passes --config $HYDRANOS_CONFIG_DIR/default.toml, default /config) /config
Linux, packaging/install.sh + systemd /etc/hydranos/default.toml /var/lib/hydranos
Any binary started with --config /some/dir/default.toml that path /some/dir/data
Linux or macOS binary started without --config /config/default.toml /config/data
Windows zip, started without --config default.toml beside hydranos.exe; if there is none there but a 4.3 install left \config\default.toml on the current drive, that one is still used <folder of hydranos.exe>\data
Windows zip, started with --config C:\Hydranos\default.toml (recommended) C:\Hydranos\default.toml C:\Hydranos\data

Per-platform details: Install with Docker, Install on Linux (bare metal), Install on Windows. On Windows, either edit from Config › Advanced settings (default.toml), or quit Hydranos from the tray, edit the file in Notepad, and start Hydranos again. Which files Hydranos keeps beside the config (store, resume state, log): Architecture.

When the file is missing, Hydranos writes it from the template compiled into the binary (the same text as configs/default.toml in the repository) and replaces data_dir = "/config" with the data folder next to the config file. The Docker entrypoint does the same before the binary starts, but sets data_dir to the config folder itself. So a Docker install keeps everything in /config, and a binary install has a data/ subfolder.

When the file cannot be parsed, Hydranos exits at startup with the parse error. A value of the wrong type (api_port = "8199" instead of api_port = 8199) is a parse error too.

Rules of the file:

  • Top-level keys come before the first [table] header. In 4.4 there is only one, auto_port_forward. Appended at the end of the file, it lands inside the last table and is silently ignored.
  • Keys Hydranos knows to be dead are named at startup, one WARN line each (see Keys that do nothing in 4.4). Any other unknown key is still accepted without a warning: a typo (enable_dth = true) is not an error, the key is simply never read. Check spelling against the sub-pages.
  • Windows paths: TOML treats \ inside double quotes as an escape. Write "C:/Hydranos/data" or 'C:\Hydranos\data'.
  • Engine blocks use the TOML array-of-tables syntax (an engine block, see the example below). They are the only way to add an engine beyond race and hoard; their keys are on Configuration: Engines and Race Drain.

Where settings live

Not every setting is in default.toml. Many things you configure in the web UI are stored in the store, <data_dir>/hydra.db, and some only in your browser.

flowchart LR
    subgraph FILE["default.toml (config dir)"]
        F1["daemon: address, port, API key, data_dir,<br/>egress, kill switch"]
        F2["auth: admin account"]
        F3["race, hoard, engine blocks: engine settings,<br/>queue, share and speed limits"]
        F4["race_drain"]
        F5["tracker host tables: passkeys, IP family,<br/>minimum seed, mute, hide"]
        F6["network mode, proxy"]
        F7["dedup, mcp, rss, vpn_speedtest, auto_port_forward"]
    end
    subgraph STORE["hydra.db (data_dir)"]
        S1["categories"]
        S2["nodes and enrol tokens"]
        S3["workflows"]
        S4["watched folders"]
        S5["IP filter lists and bans"]
        S6["per-volume drain policy"]
        S7["jobs"]
        S8["RSS feeds, rules and their history"]
        S9["per-torrent share limits"]
        S10["client-wide speed cap"]
    end
    subgraph BROWSER["browser localStorage"]
        B1["language, theme, hidden tabs"]
        B2["display units"]
        B3["copy of the API key"]
    end
    UI["Web UI and REST API"] --> FILE
    UI --> STORE
    UI --> BROWSER
Loading

Consequences:

  • Backing up default.toml alone is not enough. Categories, nodes, workflows, watched folders, the IP filter, RSS feeds and rules are in hydra.db, and the managed WireGuard provider files in <data_dir>/wireguard (Managed WireGuard). Back up the config dir and the data dir together: Operating Hydranos.
  • Each browser has its own language, theme and units. Changing them in one browser changes nothing elsewhere.
  • Environment variables and command-line flags are a fourth source, outside the file: Configuration: Environment Variables, CLI and Signals.

When a change takes effect

Hydranos reads default.toml once, at startup. After that, the file is re-read only when Hydranos itself writes to it (the web editor, the Network tab, the Trackers tab, the Duplicate data card, adding or removing an engine, the speed and share-limit routes, a live port change, Change password, a node API key rotation, Reset to defaults, first-run setup). Each of those writes reloads the whole file into memory, and settings used by the web and API layer apply at once. Most engine settings wait for a restart, because the engines are built at startup; the speed caps, the choker, peer_timeout, the queue and the share limits are the exception and are applied to the running engines when saved.

What you change Takes effect
Anything, by editing the file by hand At the next restart, or as soon as Hydranos itself writes the file (any of the saves listed above reloads the whole file, your edit included, except Reset to defaults, which replaces the file with the template and keeps your version only in its .bak-reset- backup). Edit, save, then restart Hydranos.
[race]/[hoard] upload_rate_limit, download_rate_limit, choking, max_uploads_per_torrent, peer_timeout, active_downloads, queueing, active_seeds, active_limit, the slow-torrent keys and the share limits (web editor) Immediately, on the running engines. The UI says "Applied live, no restart needed": Queue, Share and Speed Limits.
Other [race] and [hoard] keys (web editor) At the next restart. The UI says "Settings changed, restart the engines to apply."; restarting the engines means restarting Hydranos.
Network mode and engine network keys (Network sub-tab) Only when the answer says a restart is needed (a running engine was started with other network keys, or the kill switch now blocks other engines): Networking.
[daemon] egress, bind_interface, kill_switch, [proxy], allow_direct (Network sub-tab, daemon card) For the daemon's own requests, at the next request it sends. For the engines (kill_switch, allow_direct), only after a restart when the answer says one is needed: VPN and Egress.
Adding or removing an engine (Nodes › This node) At the next restart. A removal is refused while the engine still holds torrents; an empty engine that was removed keeps its listener until then: Engines: Race and Hoard.
[daemon] api_host, api_port, data_dir At the next restart.
[daemon] api_key Immediately when saved from the web UI, although the UI asks for a full restart. Every client still using the old key loses access at once: Security and Access.
[daemon] update_check_disabled, [auth], [mcp] allow_destructive, [dedup] enabled Immediately when written through the web UI or API. The Duplicate data card restarts Hydranos anyway.
[race_drain] enabled, high_watermark_pct, low_watermark_pct At the next drain pass (no restart needed, although the UI asks for one).
[race_drain] add_block_enabled, reserve_free_gb At the next torrent added.
[race_drain] check_interval_seconds At the next restart.
[vpn_speedtest] At the next wake of the periodic test (read live, although the UI asks for a restart).
Tracker host tables, from the Trackers tab Immediately. Passkeys and announce IP family are pushed to the running announcers; minimum seed hours apply at the next drain pass.
A live listen-port change (POST /api/race/listen-port, /api/hoard/listen-port, /api/engines/:id/listen-port) Moves the TCP listener and the uTP socket at once, and is saved in the engine's section: Networking.

Apply & restart (and the restart after Reset to defaults or the Duplicate data card) stops Hydranos the same clean way as SIGTERM (departures sent to the trackers, resume state saved), then exits with code 75 so that the supervisor starts it again: a Docker container with restart: unless-stopped, the shipped hydranos.service (Restart=on-failure) and the node enrolment unit (Restart=always) all do. On Windows, Hydranos starts its successor itself before leaving. A binary started by hand in a shell stays stopped. Details: Operating Hydranos and Configuration: Environment Variables, CLI and Signals.

Editing from the web UI

Config › Advanced settings (default.toml) shows the file. It is built from GET /api/settings, which returns the whole file as JSON, secrets included (api_key, password_hash, passkeys).

Sub-tab Sections shown
Network Not a key list: a form that writes [network] mode and that mode's keys (listen_port, bind_interface, enable_ipv6, the SOCKS5, PROXY-v2 and gluetun keys) to [race] and [hoard], only listen_port and bind_interface to each extra engine (which inherits the rest), and removes the keys of the other modes everywhere; its WireGuard part writes each engine's wireguard_* keys, extra engines included; its daemon card writes [daemon] egress, bind_interface, kill_switch, [proxy] and allow_direct: Networking, VPN and Egress.
General [daemon]
Session Race [race], [race_drain]
Session Hoard [hoard]
Trackers & Network [announce_passkeys], [announce_ip_modes]
Maintenance [vpn_speedtest] (enabled, iperf3_server only, see below)
Other every other section present in the file: [auth], and [dedup], [mcp], [network], [proxy], [rss], [announce_min_seed_hours], [announce_muted], [announce_hidden] when they exist
Import the Import from another client wizard: Migrating from qBittorrent

Apart from Network and Import, a sub-tab appears only if one of its sections exists in the file. listen_port, bind_interface, enable_ipv6, allow_direct and the proxy and announce keys of [race]/[hoard] are hidden from Session Race and Session Hoard: the Network sub-tab owns them. The gluetun_* and wireguard_* keys are not hidden: the Network sub-tab writes them, but they still show (and can be edited) in both sub-tabs. That hiding applies to [race]/[hoard] only: [daemon] egress, bind_interface, kill_switch show under General, and [proxy] under Other (with a description left from 3.x, "used by the orchestrator (public IP + speedtest)"; the section is the daemon's own proxy). Every key and section of the startup warning list below is hidden. Top-level keys (auto_port_forward) and engine blocks are never shown; engine blocks are managed from Nodes › This node › + Add an engine.

Known bug in 4.4: the editor also hides [vpn_speedtest] iperf3_port, interval_secs and duration_secs, which 4.4 reads. Edit them in default.toml by hand: Configuration: Daemon, Auth and Global Sections.

How Save settings writes the file:

flowchart TD
    A["Save settings"] --> B["POST /api/settings<br/>changed keys only"]
    B --> C{"key already in<br/>that section of the file?"}
    C -- no --> L{"race or hoard key<br/>from the live list, or enable_lsd?"}
    L -- no --> X["error: key not found<br/>file unchanged"]
    L -- yes --> K["key added to that section"]
    C -- yes --> D["value replaced in place<br/>comments and order kept"]
    K --> E
    D --> E{"file still valid TOML?"}
    E -- no --> Y["error<br/>file unchanged"]
    E -- yes --> F["file written<br/>whole file reloaded in memory"]
    F --> G["web and API settings: live<br/>if the file still loads as a config"]
    F --> H["live engine keys: applied to the<br/>running engines now"]
    F --> I["other engine settings: at next restart"]
Loading

What follows from it:

  • The editor changes only keys that are already in the file, with one exception, and never adds a section. The exception: in [race] and [hoard], the live keys (upload_rate_limit, download_rate_limit, peer_timeout, choking, max_uploads_per_torrent, active_downloads, queueing, active_seeds, active_limit, dont_count_slow_torrents, slow_torrent_dl_rate_threshold, slow_torrent_ul_rate_threshold, slow_torrent_inactive_timer, max_ratio, max_seeding_time, max_inactive_seeding_time, share_limit_action) and enable_lsd can be added by a save. The editor lists most of them at their default when the file lacks them (all but peer_timeout, max_uploads_per_torrent and active_downloads), so saving one adds it. To set any other key the file does not contain (enable_webseed, enable_udp_trackers, aio_threads, add_block_enabled, reserve_free_gb, update_check_disabled, auto_port_forward, the [mcp] or [rss] section…), edit default.toml by hand and restart. Upgrading Hydranos never appends new keys to an existing file either. The exceptions are the dedicated forms, which create what they need: the Network sub-tab, the Trackers tab, the Duplicate data card and + Add an engine.
  • Only the TOML syntax is checked, not types or ranges. api_port = 70000 or max_connections = 4000.5 is written to disk; the in-memory reload is then skipped without a message, and Hydranos refuses to start at the next boot. Check a value against its sub-page before saving.
  • Arrays are read-only (tooltip "Array — edit in default.toml"). Edit them in the file.
  • Tracker host tables ([announce_passkeys], [announce_ip_modes] under Trackers & Network, the other three under Other) can be edited here: their quoted host names are matched. Adding a tracker is done from the Trackers tab: Trackers and Announces.
  • api_key has two buttons: ↻ generates a new random key in the browser (nothing changes until Save settings) and ⧉ copies it. Saving a new key also updates this browser's stored copy; other browsers, Sonarr/Radarr and nodes using the old key must be updated by hand.
  • Descriptions and "default:" hints under each row: two still describe keys that do nothing (inactivity_timeout, announce_rate_limit, table below). Some "default:" hints are wrong too: [hoard] max_connections shows 8000 (template 12000), [hoard] max_uploads_per_torrent 20 (template -1), [daemon] create_torrent_folder true (template and code: false). The sub-pages give the real defaults.
  • Reset to defaults (top right of the editor, not the one in Personalisation) writes the template back, keeps only [auth] username, [auth] password_hash, [daemon] api_key and [daemon] data_dir, saves the old file as default.toml.bak-reset-<unix seconds> beside it, and restarts. Everything else is dropped, including engine blocks, tracker host tables (your passkeys and minimum seed hours), [network] mode, [proxy], [daemon] egress and kill_switch, allow_direct, the wireguard_* keys, [rss], [dedup] and [mcp]. An install that ran in WireGuard, SOCKS5 or gluetun mode comes back in Direct mode, with the kill switch off. Copy back what you need from the backup.

Sections

Status: read = every key does something (exceptions named); ignored = nothing reads the section in 4.4; named at startup = present in the file, it gets a WARN line at every start.

Section What it is Status Reference page
top-level auto_port_forward NAT-PMP/UPnP mapping of the listen ports read Global
[daemon] web/API address and port, API key, data dir, the daemon's own way out (egress, bind_interface, kill_switch) read (agent_token named at startup) Global, VPN and Egress
[auth] admin account read Global
[network] mode: the mode the Network sub-tab saved (direct, wireguard, gluetun, socks5, proxy_v2) read Networking
[proxy] SOCKS5 proxy for the daemon's own requests (egress = "proxy") read VPN and Egress
[mcp] MCP server permissions read Global
[dedup] link duplicate payload on add; path_collision read Global
[rss] RSS worker switch and feed defaults; not in the template read RSS and Automatic Downloads
[announce_passkeys], [announce_ip_modes], [announce_min_seed_hours], [announce_muted], [announce_hidden] per-tracker host tables read Global
[vpn_speedtest] iperf3 speed test, on demand or periodic read Global
[bench] benchmark recording ignored, named at startup Global
[metrics], [peer_intel], [arr_cleanup], [notify] 3.x sections, not in the template ignored, named at startup, hidden from the editor Global
[race], [hoard] the two built-in engines, their queue, share limits, speed caps and network keys read, except inactivity_timeout and announce_rate_limit Engines, Queue, Share and Speed Limits
engine blocks (and the legacy agent blocks) extra engines read (token, tls_ca, an engine sub-block and a non-empty addr are named at startup; a block with addr is skipped) Engines
[race_drain] automatic freeing of race volumes read (min_age_minutes named at startup) Engines
[race.custom_choking], [hoard.disk_slots] 3.x choking strategy, per-disk seed slots; no longer in the template ignored, named at startup Engines

Defaults that change when a key is missing

Several keys have one value in the shipped template and a different one in the code when the key is absent. A stock install gets the template's value. A config written by hand, by an old version, or by the node enrolment script, gets the code's value without any warning (only listen_port warns). Full detail: Configuration: Engines and Race Drain.

Key In the template If the key is missing
[daemon] api_key "" (a key is generated and written back at first start) Every API call is refused, the web UI included: Hydranos can only replace an existing api_key line, so it cannot store the generated key. Always keep api_key = "" in [daemon].
[daemon] api_host, api_port "0.0.0.0", 8199 0.0.0.0, 8199 (same)
enable_dht, enable_pex ([race], [hoard]) true true (same); a missing [race] or [hoard] section too
enable_webseed not in the template true: webseeds are used
enable_lsd true (race), false (hoard) on for a race-role engine, off for any other
enable_udp_trackers not in the template true: udp:// trackers are used
max_connections 4000 (race), 12000 (hoard) 0: no cap on outgoing connections
listen_port 16171 (race), 16172 (hoard) 16171 for a race-role engine, 16172 otherwise; if another engine already has that port, the next free one, with the warning listen_port missing or taken: using a free one
peer_timeout 300 300 seconds (0 too; under 120 is raised to 120)
choking, max_uploads_per_torrent false; 100 (race), -1 (hoard) false; 0 = 4 slots, read only while choking = true
upload_rate_limit, download_rate_limit 0 0: no cap
active_downloads 10 (hoard), absent (race) 0: no limit on simultaneous downloads
queueing, active_seeds, active_limit false, -1, -1 off; the two limits are read only under queueing = true
max_ratio, max_seeding_time, max_inactive_seeding_time, share_limit_action -1.0, -1, -1, "stop" off, off, off, stop
registration_retry_minutes ([race]) 6 6
aio_threads not in the template 256 (size of the open-file pool, not a thread count)
[race_drain] enabled true false: off, except on a volume whose own policy (Race tab) enables it
[race_drain] check_interval_seconds 60 300 seconds
[race_drain] high_watermark_pct, low_watermark_pct 95, 85 0, 0 (never leave them out with the drain on)
[race_drain] add_block_enabled not in the template false
[dedup] enabled not in the template true: an incoming torrent is linked onto identical data already held
[dedup] path_collision not in the template isolate (Adding Torrents)
[daemon] egress, kill_switch commented out auto; kill switch armed in every network mode but Direct (VPN and Egress)
[network] mode not in the template deduced from the engine keys, as before 4.4
[rss] enabled, refresh_minutes, max_articles not in the template true, 30, 200
[vpn_speedtest] enabled true false
[vpn_speedtest] iperf3_port, duration_secs, interval_secs commented out 5201, 10, 0 (no periodic test)
[mcp] allow_destructive not in the template false: the MCP removal tools are hidden
auto_port_forward not in the template true: Hydranos asks the router to forward the listen ports

An engine block inherits every key it does not set from [race] or [hoard] (by its role), except allow_direct, wireguard_enabled, gluetun_port_forward and listen_port_proxy_v2, which an extra engine gets only by setting them in its own session; the other defaults carry over to extra engines.

A file written by the node enrolment script has no max_connections and no [race_drain], so such a node runs with no connection cap and no race drain until you copy the lines in (Nodes and Multiple Machines). DHT, PEX and webseeds are on there, as everywhere.

Keys that do nothing in 4.4

Hydranos 4.4 reads the raw file at every start and logs one WARN line for each key it knows to be dead, with the reason and the replacement:

config: race.custom_choking is ignored: a 3.x choking strategy; the engine has one built-in choker and no strategy to pick. Instead: choking = true and max_uploads_per_torrent = <slots> (off by default; read their help first).
config: [[agent]] "de-1" addr is ignored: a 3.x remote agent: 4.x has no agent channel, so this block starts nothing here and reaches nothing there. Instead: enrol that machine as a node: install.sh --register-to <url> --token <token> (the Nodes page gives the full command).

The warning is never fatal and the key stays in the file (a rollback to 3.x still finds it). A file that does not parse gets no warning: the parse error is what you see. The shipped template contains none of these keys, and Advanced settings hides all of them.

Accepted but ignored in 4.4: every key below is accepted without error and has none of the effect its name suggests — the first table is named in the startup log, the second is not — use the replacement in the last column, or delete the key.

Key (location as the warning writes it) Use instead
daemon.agent_token nothing; nodes use API keys, enrol with install.sh --register-to <url> --token <token>: Nodes and Multiple Machines
an agent or engine block's non-empty addr (the block is skipped), token, tls_ca (the warning names the block by its TOML header, then its name or position, then the key: second example above) the same enrolment; history: Upgrading from 3.x
an agent.engine sub-block (3.x per-agent override) the session sub-table of the block: Configuration: Engines and Race Drain
race.listen_interfaces, hoard.listen_interfaces (and in a block's session) bind_interface = "<interface name>": VPN and Egress
file_pool_size (same places) aio_threads
race.custom_choking / hoard.custom_choking choking = true and max_uploads_per_torrent: Queue, Share and Speed Limits
hoard.disk_slots / race.disk_slots nothing; stop torrents yourself if a disk must rest
[bench] nothing; recording and its retention are built in: Monitoring and Logs
[metrics] nothing; /metrics is always served: Prometheus Metrics
[peer_intel] nothing
[arr_cleanup] the *arr's own completed-download handling
[notify] a workflow with a webhook action: Workflows
race_drain.min_age_minutes the tracker's Minimum seed on the Trackers tab: Race Drain
category fields placement, agents, strategy, min_free_bytes (in the store, not the file; one line per field, naming the categories, e.g. config: category field `strategy` (in films, series) is ignored: …) engine= when adding, or Move to engine afterwards: Categories and Routing

Two keys get no warning, because a later version may read them:

Key Status
inactivity_timeout ([race], [hoard], still in the template) read by nothing; the editor describes it as "Seconds before an idle peer is considered inactive." The working idle setting is peer_timeout.
announce_rate_limit not in the template; the editor describes it as a cap on announces per second, but nothing reads it

All other gaps of 4.4 are listed on Known Limitations.

A minimal configuration

The simplest safe start is to let Hydranos write the template and edit that. If you write a file yourself, keep at least the lines below. Every line carries the value a stock install has, so nothing falls back to a "missing key" default.

# Top-level keys first, before any [table].
auto_port_forward = true          # NAT-PMP / UPnP for the listen ports (default when absent: true)

[daemon]
api_host = "0.0.0.0"              # web UI and API on every interface
api_port = 8199
api_key = ""                      # keep this line: Hydranos writes a generated key here at first start
data_dir = "/config"              # holds hydra.db (the store) and bench.db

[auth]
username = "admin"
password_hash = ""                # empty = the web UI asks you to create the account

[race]
listen_port = 16171
bind_interface = ""               # Linux only: pin all of this engine's traffic to an interface, e.g. "wg0"
enable_ipv6 = false
enable_dht = true                 # absent = true as well
enable_pex = true
enable_lsd = true                 # absent = true for race, false otherwise
max_connections = 4000            # absent = 0 = no cap

[hoard]
listen_port = 16172
bind_interface = ""
enable_ipv6 = false
enable_dht = true
enable_pex = true
enable_lsd = false
max_connections = 12000
active_downloads = 10             # torrents downloading at once in hoard; 0 = no limit; applied live

[race_drain]
enabled = true                    # absent = false
check_interval_seconds = 60
high_watermark_pct = 95
low_watermark_pct = 85

# Optional: a third engine, here a hoard-role engine pinned to its own interface.
# Every key not in [engine.session] is taken from [hoard].
# [[engine]]
# name = "vpn1"
# role = "hoard"
# engine_id = "vpn1"
# [engine.session]
# listen_port = 16473
# bind_interface = "wg1"

Webseeds (BEP 19) are on without any line; add enable_webseed = false to turn them off. The queue, share-limit, speed-cap and choker keys are left out: their defaults are "off" (Queue, Share and Speed Limits). The commented engine block is the format + Add an engine writes. On Linux, bind_interface pins all of that engine's traffic (listener, uTP, outgoing peers, announces, DHT, webseeds) to wg1; a socket that cannot be pinned is not opened, so a missing interface at start means no listener and no uTP, never the default route. Interface pinning is refused on Windows and macOS. Read VPN and Egress before relying on it.

Next

Hydranos 4.4 · 🇬🇧

Start

Install

Use

Integrate

Network & machines

Operate

Reference


Hydranos 4.4 · 🇫🇷

Démarrer

Installer

Utiliser

Intégrer

Réseau & machines

Exploiter

Référence


Clone this wiki locally