🇬🇧 English · 🇫🇷 Français

Applies to Hydranos 4.4.

For anyone who wants Hydranos to act on torrents without a script: stop seeding after a while, tag torrents, call a webhook on completion, add trackers. You will learn what each trigger, condition and action does, how to test a rule, and what is still missing in 4.4. Terms: Concepts and Glossary.

A workflow has three parts:

• a trigger (the Runs field): on a timer, when a download completes or when a torrent is added;
• a condition tree (When): field comparisons grouped with AND / OR / NOT;
• a list of actions (Then), carried out in order on every torrent that matches.

Workflows live in the store (hydra.db), not in default.toml. A workflow saved without "enabled": true is off. They act on the torrents of this instance's engines (race, hoard, extras), never on rows merged from a declared node.

flowchart LR
    T1["Timer (every interval_secs, min 60)"] --> ALL["Every torrent copy in every local engine"]
    T2["A download completes"] --> EV["Event queue (store table workflow_events)"]
    T3["A torrent is added"] --> EV
    EV --> ONE["That one torrent"]
    ALL --> WHEN["When: condition tree"]
    ONE --> WHEN
    WHEN -->|no match| NOP["Nothing, nothing logged"]
    WHEN -->|match| DONE{"Every non-webhook action<br/>already as asked?"}
    DONE -->|"yes, and no webhook to send"| SKIP["Skipped, nothing logged"]
    DONE -->|"yes, event trigger with a webhook"| THEN
    DONE -->|no| CAP{"Timer: At most reached<br/>this pass?"}
    CAP -->|yes| STOP["Rest of the pass left for next time"]
    CAP -->|no| THEN["Then: actions still to do, in order,<br/>webhooks last"]
    THEN --> ACT["Activity log: applied or failed"]
    THEN -.->|"move files to a folder"| JOB["Jobs tab: move_data job"]

Tab Workflows, button + New workflow: Name, Runs, for timers Runs every (seconds, minimum 60, default 900) and At most (torrents per pass, default 500), then When, Then, and Preview / Save / Cancel. Translated in every language: Name, Save, Cancel, the list's Actions header; in French also Runs, the trigger choices, Preview, Every (on completion, when added), none of these (NOT), the hardlink checkbox of move files to a folder, the action notes and a group's Remove. List buttons, a row's Remove, all of these (AND) / any of these (OR), and field, operator and action labels stay English.

Details that matter:

• A timer workflow converges: a torrent already "as asked" (stopped, tagged…) is skipped and not logged, until it drifts back (start by hand a torrent a workflow stops, and the next pass stops it again).
• The last run is recorded before the pass, so a slow pass is never started twice. A newly enabled timer workflow that never ran is due at the next tick.
• Events are written to the store first, so a restart loses none. An event whose torrent is not loaded yet waits up to one hour, then is dropped. Event workflows have no interval and no cap.
• On an event trigger, an empty When is allowed and means "every download that completes" or "every torrent added". To get one in the editor, click Remove on the condition row that a new workflow starts with. On a timer, an empty When is refused (it would match the whole catalogue).
• Hardlink fields (link_count, external_links, freeable_bytes, data_missing) are refused on event triggers: the index has not measured a torrent that just arrived.

When starts with one root group. Each group is all of these (AND), any of these (OR) or none of these (NOT). Inside it, + Condition adds a row (field, operator, value) and + Group adds a nested group. Remove deletes a row or a group (the root group cannot be removed). Empty groups are dropped when you save.

none of these (NOT) matches when not one of its rows holds; it is saved as {"kind":"not","of":{"kind":"any","of":[…]}}. A NOT written through the API opens as a none of these (NOT) group (whatever it wraps becomes that group's one child when it is not an OR), so saving it from the editor keeps its meaning.

The editor builds its lists from GET /api/workflows/fields. These are all the fields:

Operators (the editor shows the label, the API takes the id):

Values:

• Durations: 2d, 36h, 90m, 45s or plain seconds (the editor has a unit selector).
• Sizes: KB/MB/GB/TB are powers of 1000, KiB/MiB/GiB/TiB powers of 1024: 500GB ≠ 500GiB.
• Bools: true, yes or 1 mean true; anything else means false.
• Text: comparisons ignore case, except matches, which is a case-sensitive regular expression (Rust regex syntax; prefix (?i) to ignore case). Tag comparisons are exact, case included.
• For category, tags, tracker and engine, the editor offers a drop-down of known values.
• "Never happened" matches nothing. A torrent that never completed fails every completed_age comparison, is not included. A torrent the hardlink index has not measured yet fails every link_count, external_links and freeable_bytes condition; data_missing reads false for it, so data_missing is false matches it. Inside a none of these (NOT) group the result flips: NOT completed_age is newer than 1d or NOT external_links is more than 0 matches every torrent never completed or not measured yet. Write the positive form (external_links is 0) instead of a NOT.

Hardlink index. Hardlink fields come from a background index (starts ~3 min after boot, re-measures entries older than 24 h; HYDRANOS_LINK_SCAN_THREADS, default 16). The line Hardlink index: X of Y torrents measured under the list shows its progress. A pass re-measures its candidates before acting, and a delete decided on hardlink facts is refused if a new link appeared since.

How actions run:

• A torrent's actions run in order. The first failure stops the rest for it, and it counts as failed.
• Webhooks always run after the other actions, whatever their position in Then.
• On a timer, a webhook is sent only in a pass where another action of the same workflow changes the torrent. A timer workflow whose only actions are webhooks is refused (it would call the URL on every pass). On an event trigger, the webhook is always sent, and a webhook alone is allowed.
• If the webhook fails after a tag was written, the tag stays, and the next pass (torrent "as asked") does not retry the webhook.
• Each try has a 10 s timeout; a failure is retried after 2 s and 5 s, a 4xx is not. The URL never appears in errors. A dead endpoint slows the pass.
• When the kill switch leaves the daemon no way out, the webhook is not sent at all (no retry): the torrent counts as failed with webhook: <reason>.
• There is no action to run a command, recheck, reannounce, set limits, or move a torrent to another engine.

Webhook body:

{"event": "completed", "workflow": "Notify on completion", "at": 1790000000,
 "content": "Some.Torrent finished downloading (4.37 GiB)", "text": "…same…", "message": "…same…",
 "torrent": {"info_hash": "0123…", "name": "Some.Torrent", "category": "tv", "tags": [],
   "engine": "race", "save_path": "/data/race/tv", "state": "seeding", "tracker": "tracker.example.org",
   "size": 4692251443, "progress": 100, "ratio": 0.0, "uploaded": 0, "downloaded": 4692251443,
   "seeding_time": 0}}

event is matched (timer), completed or added. The summary is repeated under content (Discord), text (Slack, Mattermost) and message (Gotify), so these take the URL directly. Unknown numbers are null.

Dry-run and Run now are hidden for event workflows (the API answers 400): use Preview. "Would free" adds up each matched torrent's full size: it overstates for hardlinked or shared files. For a hardlink rule, Preview and Dry-run also re-measure the candidates and write the fresh values to the hardlink index. That, plus the dry_run_no_match row, is all they write.

The Activity table under the list shows the workflow log: When, Workflow, Torrent, Action, Outcome, Detail. It loads the latest 500 rows. Rows older than 7 days are pruned every minute.

• One row per torrent acted on. Action joins the actions done with + (pause, resume, category, add_tags, remove_tags, delete, webhook, set_location, add_trackers), e.g. add_tags+webhook.
• The same table holds what RSS rules did: Workflow RSS: <rule name> (RSS: (manual) for the RSS tab's Download), Action rss_add, Torrent the article's title, Outcome applied, skipped (Detail already in this client) or failed with the reason (a transient failure ends with ; tried again at the next pass).
• For a workflow, Outcome is applied or failed. For failed, Detail gives the error (for example webhook: HTTP 500 after 3 tries; a 4xx reads webhook: HTTP 404). A private torrent is never a failure: add trackers skips it as "as asked".
• Torrents already "as asked" and passes that matched nothing are not logged (except a Dry-run with nothing to apply: dry_run_no_match).
• applied for move files to a folder means "job queued"; follow the move on the Jobs tab.

Each example gives the editor steps and the same workflow as API JSON. The API takes "enabled": true; the editor saves a new workflow switched off, so tick Enabled in the list after the first save (saving an edit keeps the workflow's state).

1. + New workflow. Name: Stop after 14 days on tracker.example.org. Runs: on a timer. Runs every: 3600.
2. When (all of these (AND)): tracker · is · tracker.example.org. Click + Condition: time spent seeding · is older than · 14 days.
3. Then: stop the torrent.
4. Preview, then Save, then tick Enabled.

{
  "name": "Stop after 14 days on tracker.example.org",
  "enabled": true,
  "trigger": "schedule",
  "interval_secs": 3600,
  "cap": 500,
  "when": {"kind": "all", "of": [
    {"kind": "cond", "field": "tracker_host", "op": "eq", "value": "tracker.example.org"},
    {"kind": "cond", "field": "seeding_time", "op": "gt", "value": "14d"}
  ]},
  "then": [{"type": "pause"}]
}

tracker reads only the first tracker. Hydranos also has built-in share limits, per engine and per torrent (Queue, Share and Speed Limits); a workflow like this one is for rules they cannot express (per tracker, per category, tags…).

Finds payloads your media library no longer uses (e.g. after Sonarr deleted its hardlink).

1. + New workflow. Name: Tag noHL. Runs: on a timer. Runs every: 21600.
2. When: hardlinks from outside Hydranos · is · 0. + Condition: state · is · seeding.
3. Then: add tags · noHL.
4. Preview. Check the Hardlink index line under the list: torrents not measured yet never match. Then Save and tick Enabled.

{
  "name": "Tag noHL",
  "enabled": true,
  "trigger": "schedule",
  "interval_secs": 21600,
  "cap": 500,
  "when": {"kind": "all", "of": [
    {"kind": "cond", "field": "external_links", "op": "eq", "value": "0"},
    {"kind": "cond", "field": "state", "op": "eq", "value": "seeding"}
  ]},
  "then": [{"type": "add_tags", "tags": ["noHL"]}]
}

The tag stays when the condition stops holding; a second workflow (external_links is more than 0, has tag noHL → remove tags) clears it. Review before deleting.

1. + New workflow. Name: Notify on completion. Runs: when a download completes.
2. When: click Remove on the starting condition row to act on every download, or keep one condition such as category · is · tv.
3. Then: call a webhook · https://hooks.example.org/hydranos.
4. Preview (it runs on the torrents whose progress is under 100, see Preview), Save, tick Enabled.

{
  "name": "Notify on completion",
  "enabled": true,
  "trigger": "completed",
  "when": {"kind": "all", "of": []},
  "then": [{"type": "webhook", "url": "https://hooks.example.org/hydranos"}]
}

The body is the JSON shown under Actions. Torrents added with their data already on disk never fire this trigger.

1. + New workflow. Name: Public trackers on add. Runs: when a torrent is added.
2. When: private · is · false.
3. Then: add trackers. Enter one announce URL per line, e.g. udp://tracker.example.org:6969/announce, or put the URL of a list in the second box.
4. Preview (it shows what would have happened to the last day's arrivals), Save, tick Enabled.

{
  "name": "Public trackers on add",
  "enabled": true,
  "trigger": "added",
  "when": {"kind": "all", "of": [
    {"kind": "cond", "field": "private", "op": "eq", "value": "false"}
  ]},
  "then": [{"type": "add_trackers",
            "urls": ["udp://tracker.example.org:6969/announce"],
            "list_url": ""}]
}

The action skips private torrents even without the condition. Always give a port for udp:// URLs. A failed list fetch falls back to the last good copy; with none, the action fails.

The editor cannot reorder workflows (position is never sent).

Known bug in 4.4: progress looks like it reads 100 for any complete torrent — it reads 0 for a stopped torrent with no piece map: a seed-mode add or cross-seed added stopped, or a complete torrent reloaded after a restart and stopped (only a seeding torrent is known to hold everything without one). A rule such as progress is 100 misses them and progress < 100 catches them — to mean complete, test completed_age (set for a seed-mode add and kept across a restart); state is seeding leaves out stopped torrents.

All routes need the API key (X-Api-Key header or apikey query parameter). Full conventions are on REST API.

Condition tree: {"kind":"all","of":[…]}, {"kind":"any","of":[…]}, {"kind":"not","of":{…}}, {"kind":"cond","field":"…","op":"…","value":"…"}.

Save and Preview also refuse an unknown field, a value that does not parse and a bad regex, besides the shapes listed under Triggers and Actions.

# Preview a draft
curl -s -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d @stop-after-14d.json http://localhost:8199/api/workflows/preview

# Save it (enabled if the file says "enabled": true)
curl -s -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d @stop-after-14d.json http://localhost:8199/api/workflows

To change an existing workflow, GET the list, edit the object and POST it back whole, with its id (last_run is ignored).