Hymount

Mount a Hydrus database or client API as a small, read-only drive on Linux and Windows — like rclone mount, but for Hydrus.

Hymount indexes the files matched by a Hydrus search and exposes them under a naming scheme you control, using the same placeholders as Hydrus's export menu ({file_id}, {hash}, {tags}, [namespace], (tag), …). Files are streamed on demand over the Hydrus client API, or read directly from an offline database directory.

Features

• Read-only by design: every write, rename, delete or attribute change is refused with EROFS / STATUS_MEDIA_WRITE_PROTECTED.
• Two source kinds:
  • Hydrus API: connect with an access key; no filesystem access to the database required. Byte ranges are fetched lazily and cached.
  • Offline database: point at a Hydrus db/ directory (the one containing client.db and the file store). The database is opened read-only.
• Multiple sources and multiple mounts, each with its own search, file domain, tag domain, naming pattern and optional file cap.
• Dynamic naming exactly like Hydrus export phrases, including subdirectories created by / and by [namespace] values.
• Tray icon with mount toggles, a settings window (egui, no webview), and optional start-at-login.
• Windows network-drive mode (drive letters only): Explorer treats the mount as a remote drive, so it skips thumbnail and index generation.
• Search helpers in the settings window: tag autocompletion from the source's own predicates, plus a "Check search" button that flags unknown tags.
• Headless CLI: mount, list, test, preview, doctor.
• Small dependency footprint; no GTK or webview required on Linux.

Requirements

• Linux: the fuse3 package (for fusermount3) and access to /dev/fuse. Debian/Ubuntu: sudo apt install fuse3.
• Windows: the WinFsp driver. Hymount detects a missing driver and tells you what to install.
• Hydrus API sources: an access key with the search for and fetch files permission. The key is stored in the plain-text config file (mode 0600 on Unix), so treat it as a secret.

Quick start

Create a config file, then run hymount:

[general]
cache_bytes = 67108864   # 64 MiB read cache per API mount
chunk_bytes = 1048576    # 1 MiB HTTP range chunks

[[sources]]
kind = "api"
id = "home"
name = "home hydrus"
url = "http://127.0.0.1:45869"
access_key = "paste-your-access-key-here"
# optional: restrict to one file/tag domain (hex service keys)
# file_service_key = "6c6f63616c2066696c6573"
# tag_service_key = "6c6f63616c2074616773"

# [[sources]]
# kind = "offline"
# id = "archive"
# name = "archive database"
# db_dir = "/path/to/Hydrus/db"
# snapshot = false        # true copies the DBs to a local cache first

[[mounts]]
id = "artists"
source_id = "home"
name = "artists"
mount_point = "/home/you/hydrus"    # Windows: "H:" or C:\HydrusMount
name_pattern = "[creator]/{file_id}"
auto_mount = true
network_drive = true                 # Windows: network drive, no thumbnails
search = { predicates = [ "system:everything" ], max_files = 5000 }

The config lives at:

• Linux: ~/.config/hymount/config.toml
• Windows: %APPDATA%\hymount\config.toml

Use --config <path> or HYMOUNT_CONFIG_DIR to override it.

Run the settings window with no arguments (hymount), or mount from the console:

$ hymount list
$ hymount test home --search "creator:someone"
$ hymount preview artists --count 10
$ hymount mount artists          # foreground; Ctrl+C unmounts
$ hymount doctor                 # environment checks

Naming patterns

The phrase engine mirrors Hydrus's export phrases:

Token	Expands to
{hash}	lowercase SHA-256
{file_id}	Hydrus internal file id
{#}	1-based index in this mount
{tags}	all tag subtags, sorted, , -joined
{nn tags}	only tags without a namespace
[namespace]	subtags in that namespace
(tag)	the subtag, but only if the file has that tag
literal text	copied as-is; / and \ create folders

Unknown {...} tokens expand to nothing, as in Hydrus. The mime extension is appended automatically; an empty result falls back to the hash. Names are sanitized and length-limited per platform, and collisions get a deterministic (1), (2) suffix.

Read-only guarantees

• FUSE mounts use the ro flag and every mutating callback returns EROFS.
• WinFsp volumes are created with read_only_volume(true) and mutations return STATUS_MEDIA_WRITE_PROTECTED.
• Offline databases are opened with SQLite mode=ro; if the filesystem cannot host WAL shared memory (network shares, WSL /mnt/c, …), Hymount falls back to immutable=1 or to a local snapshot (snapshot = true).

Known limitations

• Offline searches support plain and negated tags, OR groups, and system:everything. Other system: predicates are API-only.
• Offline tag lists use storage tags (tag siblings/parents are not applied).
• Thumbnails are not exposed yet.
• Split storage across multiple locations is best-effort.
• macOS is not supported.

Building

$ cargo build --release

Linux needs fuse3 at runtime; building does not require libfuse headers. Windows builds link against the WinFsp import library included by winfsp-rs and delay-load the driver at runtime.

CI and releases run on Forgejo Actions (.forgejo/workflows/). Pushing a tag such as v1 builds Linux and Windows artifacts, attaches SHA-256 sums, and publishes the release (tags containing a hyphen, e.g. v1.1.0-rc.1, are marked as pre-releases).

License

Hymount is released under the ISC license (see LICENSE). The Windows build links winfsp-rs, which is GPL-3.0; see THIRD_PARTY.md for details. Hydrus itself is WTFPL and only referenced for format compatibility.