Hydrus Image Importer

Hydrus is the free, self-hosted, tag-based image database that people graduate to when their collection outgrows folders - booru-style tags, duplicate filtering, fully local. If you're a heavy ComfyUI user with thousands of renders piling up in output/, this is the bridge you've been missing: drop Hydrus-Image-Importer at the end of a workflow and every render gets pushed to your Hydrus server with its generation metadata as tags, right from the canvas. No exporting, no drag-and-drop, no forgetting to archive the good ones.

It's the flagship node of the ryphon/import-to-hydrus pack, and the whole pipeline is built around it. The importer saves; the pack's exporter pulls files back out with model and prompt intact; the dedupe node keeps upscales from cluttering the library.

What it actually does

Three things, in order: it converts your IMAGE tensor to a PNG and embeds the ComfyUI prompt and workflow chunks into the file - the same workflow-in-the-image convention as ComfyUI's SaveImage, so dragging the archived PNG back onto the canvas rebuilds your graph. Then it uploads the file to Hydrus via the API. Then it tags it. The PNG-embedding half is a port of the WLSH save-with-metadata node, which is why the README points you at WLSH nodes for feeding richer metadata in.

The tags are the important part for round-tripping. The node takes your metadata inputs and stores them as namespaced tags - positive:, negative:, modelname:, seed:, lora: - and it's exactly those namespaced tags the pack's exporter reads back out. Archive with them and you can reconstruct a generation months later; skip them and you get a tagged picture with no provenance.

The inputs that matter

• images (required) - wire from your VAE decode. Batchable.
• positive, negative, modelname, seed, loras - the generation metadata, saved as namespaced tags. All optional, but this is what makes your archive useful.
• tags - a comma-separated list, and namespaces work: namespace:tag. Default is ai, comfyui, hyshare: ai.
• dedupe (boolean) - when on, the node returns the imported file's SHA-256 on its upscale_hash output, ready to feed the pack's Hydrus-Image-Dedupe node. One catch from the code: with dedupe on it returns after the first image, so don't mix batch imports with dedupe. Leave it off for batches.

Its only output is upscale_hash (a STRING), and it's an output node - it runs at the end of your graph, does its thing, shows nothing on screen.

Installing and wiring it up

ComfyUI Manager, search import-to-hydrus, or:

cd ComfyUI/custom_nodes
git clone https://github.com/ryphon/import-to-hydrus

restart ComfyUI. Dependencies are light - hydrus-api, Pillow, numpy - and there are no models to download; the "model" is your Hydrus server. Before it will import, set HYDRUS_KEY and HYDRUS_URL as environment variables (or fill in hydrus_api.txt inside the pack folder), make sure the Hydrus server is running and reachable from the machine running ComfyUI - the README explicitly warns about DNS/reachability if it's not the same box - and give the API key import-files and add-tags permissions. The node verifies both and prints a warning to the console if they're missing.

Where people get burned

The usual suspects: the "API Key is required" or "does not grant all required permissions" console message, which is always env vars or key permissions; and tags landing nowhere, because the node hardcodes the local "my tags" service - if your key is scoped elsewhere, tags silently don't attach. And one design note rather than a bug: per the README, every non-image input is optional, but "without them, the resulting image will have limited metadata." A bare importer still archives the file and the embedded workflow; it just gives the exporter nothing to rebuild from later. The whole pack is a work in progress, but this node is the most complete piece of it - and the reason to install the other two.