Reading Apps

Plinthio works with three kinds of outside reading app: Mihon, KOReader and OPDS readers. All of them sign in with your username and a Plinthio API key as the password.

1. Open Settings → Apps & API keys.
2. Make an API key for the app, named after it (for example "Mihon on my phone"). Copy it straight away, because it's only shown once.
3. Use the address shown in the Reading apps card for your server.

Make one key per app, so revoking a key signs out just that app. Everything the web app hides from you (content limits, Kids Mode, hidden titles, missing files) is hidden in these apps too. Away from home, the apps need a way to reach the server. See Away From Home.

Mihon

Mihon, and other Tachiyomi forks on Android, read Plinthio through their Komga extension. Plinthio answers the parts of Komga's API that the extension and Mihon's Komga tracker use.

Set Up

1. In Mihon, open Browse → Extensions and install Komga. It's in the Keiyoushi repository, so add that first if you haven't.
2. Open the extension's settings (the cog next to it):
   • Address: your Plinthio address, such as https://media.example.com or http://192.168.1.20:8088. Don't add /api to the end.
   • Username: your Plinthio username.
   • Password: an API key. Or leave username and password empty and put the key in API key.
3. Restart Mihon if it asks, then browse the source.
4. To sync what you read, open Settings → Tracking → Komga and turn it on. Mihon links Komga series automatically, or open a series → Tracking → Komga to link it.

What You Get

• Your comic, manga and PDF series, with covers, descriptions, genres, tags, authors, status and reading direction.
• Latest sorted by last change, search, and filters for library, status, genre, tag, publisher, author and read status.
• Pages stream one by one. PDFs arrive as images rendered by the server.
• EPUBs aren't offered, because the Komga extension can't read them. Use KOReader or the web reader.
• Plinthio's lists aren't offered as Komga read lists or collections.

What Syncs

Mihon's tracker works in chapters. When you finish a chapter in Mihon, it tells Plinthio "read up to N", and every volume numbered N or lower is marked read in Plinthio. When Mihon refreshes tracking, it reads back how far you've got in Plinthio. The count only moves forward: marking something unread in Mihon doesn't unmark it in Plinthio. Positions within a volume don't sync.

The tracker uses a session cookie tied to your API key. It lasts 30 days, is renewed on use, and ends as soon as you revoke the key.

KOReader

Plinthio is a KOReader progress sync server. KOReader keeps your place in each book on Plinthio, so your other KOReader devices, and Plinthio itself, can pick it up. This works on Kobo, Kindle, PocketBook, Android and Linux.

Set Up

1. Open any book in KOReader, then Tools → Progress sync → Custom sync server, and enter https://your-server/api/kosync (the address from the Reading apps card).
2. Choose Register / Login → Login. Don't choose Register: accounts are made in Plinthio, which refuses registration. Enter your Plinthio username, and an API key as the password.
3. Optionally, in the same menu, turn on automatic sync and choose what happens when another device is ahead.

Keep Document matching on its default, Binary. Filename matching works too, but breaks if the file is renamed.

What Syncs

KOReader identifies a book by a fingerprint of the file. When it matches a book in your library, the position also updates Plinthio's progress:

Book	KOReader to Plinthio	Plinthio to KOReader
PDF, CBZ and other comics	Page and percentage	The page, when Plinthio's is newer
EPUB	Percentage (the web reader opens at that point)	Only positions from other KOReader devices

EPUB positions can't go from Plinthio to KOReader, because KOReader records them in its own format.

Books Plinthio doesn't have still sync between your KOReader devices through Plinthio. To sync with Plinthio's own progress, read the same file: download it from Plinthio (OPDS works well) or copy it across. A different copy of the "same" book has a different fingerprint and syncs separately.

KOReader needs an API key made on Plinthio 1.0.0 or later. Older keys are rejected.

OPDS Readers

Any OPDS reader can browse and download from Plinthio, such as Chunky, Panels, KyBook, Moon+ Reader or KOReader's own OPDS browser.

• Catalog address: https://your-server/api/opds
• Sign in with your username and an API key as the password.
• Comics and manga support OPDS page streaming, so readers fetch pages one at a time instead of the whole archive. PDFs stream page by page as rendered images.

OPDS is read-only: readers don't send progress back. Use KOReader sync or Mihon's tracker for that.

Troubleshooting

Symptom	Likely cause
Mihon says "HTTP 401"	Wrong username or key, or the key was revoked. Make a new key
Mihon shows nothing	The account can't see any comic, manga or PDF libraries (check content limits and Kids Mode), or the address ends in /api
Mihon tracking doesn't update Plinthio	Tracking → Komga isn't on, or the series isn't linked. Tracking only records finished chapters
KOReader says "Unauthorized"	The key was made before 1.0.0, you chose Register, or the username is wrong
KOReader syncs between devices but Plinthio's progress doesn't move	The file on the e-reader differs from the one in the library. Download it from Plinthio so the fingerprint matches
The OPDS reader never asks for a password	Use the /api/opds address, not the web address. Some readers need the credentials entered in the catalog's settings