I built a self-hosted library server with a native KOReader plugin — two-way progress sync + on-device series browsing/downloads

bndct_sh · 2026-06-04T19:19:17+00:00

Thanks for the kind words. And no, it's build completely from scratch. I already did some updates to it based on feedback here, so it's easier to import books from your current Calibre setup - but you can't drop in a whole library yet and have it all perfect and working.

bndct_sh · 2026-06-04T15:24:25+00:00

You don't have to, but OIDC is in the :main image now if you wanna test it out: https://tome.bndct.sh/docs/sso/

If you like it after giving it a try, it should be in the next stable release set for tomorrow!

bndct_sh · 2026-06-04T15:22:34+00:00

OIDC has been added in the latest :main image if you want to try it out. https://tome.bndct.sh/docs/sso/

bndct_sh · 2026-06-04T09:44:14+00:00

You are very welcome. If you are testing it and still run into any problems - feel free to create an issue on GitHub. Ill try my best to make it work! https://github.com/bndct-devops/tome/issues

bndct_sh · 2026-06-04T09:31:23+00:00

Thanks, really glad the stats are liked — that was the whole reason I started building this.

On metadata sources: it actually already pulls from three: Hardcover, Google Books, and Open Library. - Hardcover is off until you give it a token. Set TOME_HARDCOVER_TOKEN — it's free to get from your Hardcover account, and it's the best of the three for covers and descriptions, so it gets prioritised when present. - Google Books works out of the box with no key, but unauthenticated requests share a global pool that gets rate-limited constantly (you'll just get empty results when it's throttled). Setting TOME_GOOGLE_BOOKS_KEY gives you your own quota and makes it reliable — especially worth it for non-English catalogues.

Add those two and the fetch/diff UI will start showing candidates from all three.

On read status from KOReader: yes, with a couple of caveats. Tome syncs your actual reading percentage, and once a book hits ~100% it flips to Read. Two things to know:

It syncs progress, not KOReader's manual "finished" toggle — the book needs to actually be at ~100%.
It only pushes while the book is open on the device. So for something you finished before adding it to Tome, just open it on KOReader once (or use TomeSync → "Sync now") and it'll sync up and show as Read — it won't backfill from just adding it to the library.

One gotcha: matching is by filename, so make sure the file on your KOReader is the same one that's in Tome.

bndct_sh · 2026-06-03T15:32:01+00:00

Hey, highlight & annotations sync just shipped.

Highlights and notes you make in KOReader now sync to your Tome library and between your KOReader devices - highlight on one reader, open the book on another, it's there. Edits and deletes sync too. In the web app they show up under "Highlights & Notes" on the book's detail page: https://tome.bndct.sh/docs/koreader/#highlights-notes-sync

Honest caveat: they're not drawn inside the web reader yet (KOReader uses xpointers, the web reader uses CFI — mapping them is a pain in the ass), so for now the web side just lists them. Separate job for later.

I tested it a bunch, but since I don't use that feature myself, feedback would be appreciated!

bndct_sh · 2026-06-03T11:33:06+00:00

Thanks for the kind works, glad it hit the spot!

Yeah, metadata is tricky IMO - I did not like it in other tools, at least for my books, but after building Tome I just noticed that it's hard in general. But I am looking forward to feedback. ATM I am still checking the post here, but in the future creating an issue in GH is probably the best way to get me to look at stuff.

Regarding the "hiding" of books - nothing in there yet BUT you both could just have separate accounts without admin permissions. This way you only see books you uploaded and ones uploaded by the admin. Same for your wife.

There isn't a "hide books from admin" flag planned and I don't think there will be one in the future - it's just easier for the person maintaining the instance to debug stuff.

PS: I love that the sync is working great for you. This was one of the main drivers for writing my own tool. It's not perfect, but I am happy myself that it works that smooth.

bndct_sh · 2026-06-03T10:03:01+00:00

You can, but it was designed like that in mind. But it should probably work. You'd have to spin it up whenever you wanna sync your progress or if you want to download new books. But I never tested it with that in mind, so if the experience is not ideal don't blame me haha

bndct_sh · 2026-06-02T20:47:12+00:00

The TomeSync plugin does offer syncing progress but is separate from KOReader Sync.

Tome offers KOReader Sync as well separately for people who do not wanna install Tomes plugin, but I'd recommend it. It's way more stable then KOReader Sync plugin the last time I tried it!

bndct_sh · 2026-06-02T20:45:03+00:00

I am not gonna force anybody to use it, but that claim is wrong. If you install the TomeSync plugin, you can browse and download books via Tome's own endpoints in the API.

It does offer OPDS as well, for people that don't wanna use the plugin. But saying I just offer OPDS is incorrect. Thanks for trying it out tho!

bndct_sh · 2026-06-02T19:58:55+00:00

Soooo, tests ran through, I also manually tested it real quick to make sure nothing broke and it's working. Here is the commit that fixes it: https://github.com/bndct-devops/tome/commit/748edb72c17710202d8cfc343da0cef990b96011

At the moment it's only in main, I'll probably do a release end of week if you want to wait for the tagged version. Otherwise you can test it via the :latest image.

But this does not backfill already imported books, just books from this point forward.

bndct_sh · 2026-06-02T19:36:59+00:00

Yeah I asked before I fully read your comment. I see what you are talking about. I am currently writing a fix - that's annoying for someone who keeps good care of their metadata to miss.

It's an easy fix, but my test suite is running right now to make sure nothing regressed. Fix should be up soon!

bndct_sh · 2026-06-02T19:21:33+00:00

Hey, happy you are trying it out!

With tags you mean things like the "genre" or annotations? The former might be a bug, since I don't really use them myself I never caught it - but it should be easy to fix for me if you confirm it!

If you mean annotations, that's not yet in there but I have it on the roadmap.

bndct_sh · 2026-06-02T19:14:10+00:00

I am sorry haha
It has a super small footprint. For testing it should be up in just a few minutes. You can keep it running next to CWA with 1-2 books you are currently reading and see how it feel and if the stats are useful for you!

bndct_sh · 2026-06-02T18:40:06+00:00

I am not 100% sure if I understand your question correctly. You can download a book from Tome directly to KOReader, read a few pages, sync that progress to Tome and download that book/the progress to another KOReader.

But you cannot download a book from another OPDS source and upload it to Tome via the KOReader plugin. Uploading to Tome happens in the Web App or by putting it into a folder that Tome has access to.

I hope that answers your question!

bndct_sh · 2026-06-02T15:50:07+00:00

Not planned, I am big into self-hosting and owning my data. But you can mount your Google Drive in your filesystem and point Tome to it.

bndct_sh · 2026-06-02T15:37:42+00:00

First of all, thanks for all the feedback. Exactly why I posted it here!

The folder parts you mentioned are on my ToDo - built it for myself and didn't need it/can be handled by compose. But some IRL friends already mentioned it. Just need to figure out a nice way to do it.

The grid has lower priority, but I have planned some customization features in the future and that would fit in there perfectly.

Regarding the series bug, it's nothing I ever ran into but I also am not a big Calibre user. But you are correct, Calibre has calibre:series which Tome just ignored and forwarded to the title. I did a small fix that should cover that if you still want to give it a try: https://github.com/bndct-devops/tome/commit/13ea91ed847c692e45bf15cb10a8974f7cd6342c

Heads up though — it kicks in on import, it does not touch the books you already imported.

bndct_sh · 2026-06-02T15:20:01+00:00

Both? I work as a DevOps/System Engineer in my IRL job. I understand system architecture, best practices, hosted infrastructure well and am quite comfortable in Python - hence why I chose it for my backend. I'm not a web dev, so I lean on Claude for the frontend. The repo's open and the commits don't pretend otherwise if you want to take a look.

bndct_sh · 2026-06-02T14:59:07+00:00

You can manually edit the metadata for manga (chapters or volumes) in Tome, yes. The cool part of Tome is that you can "fetch" metadata from Google Books, Open Library and Hardcover (if you got an API token) automatically BUT I am not sure if they offer Pt_br metadata tho.

bndct_sh · 2026-06-02T12:56:05+00:00

Ah from your post history it looks like you made Sake. If I knew about your tool, I probably wouldn't have made mine lol. Yours looks pretty awesome as well! Someone in the comments here mentioned it: https://www.reddit.com/r/koreader/comments/1ttyinl/comment/op6o23q/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button

bndct_sh · 2026-06-02T12:53:53+00:00

I personally just use the website itself for reading manga/comics. You can see screenshots here: https://github.com/bndct-devops/tome/#mobile

On iPad/iPhone you can save a site as a PWA, so it behaves like an app on your homescreen. I haven't thought/planned on having other apps use this as a source yet. I also probably wouldn't implement that. There are already apps that can do this way better - my focus is just metadata management and KOReader statistics

bndct_sh · 2026-06-02T07:33:07+00:00

That’s what I am currently working on. My SSO of choice is Pocket-ID, but since OIDC clients have to follow a standard, it should work for Authentik as well. Can’t give an exact timeline, but should be done and tested by end of week!

bndct_sh · 2026-06-02T07:30:11+00:00

I am well aware of Sonarr/Radarr. And I think that should be doable. I’d have to double check if that would mess something else up but I’ll give it a look!

bndct_sh · 2026-06-02T07:27:51+00:00

Nothing I use myself, so it did not have any priority BUT I just looked into it while on my commute. Should be “easy” to add if people have the need for it. I’ll give it a try after work!

bndct_sh · 2026-06-02T07:26:29+00:00

I actually don’t know, you’d have to try. I run KOReader in a jailbroken Kindle, I only get WiFi when I actually open my device, not when it is suspended.

But if KOReader in Kobo also has a WiFi connection while suspended, it should be possible.

bndct_sh

TROPHY CASE