Documentation.
Sync, with your
own server.
Kios keeps your reading position in step with the library server you already run — over KOReader sync, Kobo sync or OPDS. Here's what works, and exactly what to type in.
Behaviour.
How sync works
Kios syncs your reading position — one position per book, nothing more. Highlights, notes and statistics stay on your device.
Your position is saved locally on every page turn, but it's only sent to your server when you background the app, close a book, or return to the app with a push still pending. Page turns never touch the network.
When you open a book, Kios asks the server in the background whether another device has read further. If it has — a different chapter, or meaningfully further in the same one — you'll see “Another device is in ‘Chapter 12’ — switch?” with Continue and Stay here. Tiny differences are applied silently, and if you've already started reading, the prompt stays out of your way.
Compatibility.
Servers
Verified means we've run Kios against the server and sync works. Untested means the server implements a protocol Kios speaks, but the pair hasn't been exercised yet — reports very welcome on Discord.
| Server | Browse & download | Progress sync | Status |
|---|---|---|---|
| Grimmory | OPDS 1.2 | KOReader sync · Kobo sync | Verified |
| Calibre-Web-Automated | OPDS 1.2 | KOReader sync · Kobo sync | Verified |
| Komga | OPDS 1.2 + 2.0 | KOReader sync · OPDS progression | Verified |
| BookLore | OPDS 1.2 | KOReader sync · Kobo sync | Untested |
| Calibre-Web | OPDS 1.2 | Kobo sync | Untested |
| Kavita | OPDS 1.2 | KOReader sync (v0.8.7+) | Untested |
| Stump | OPDS 1.2 + 2.0 | KOReader sync (off by default) · OPDS progression | Untested |
| Calibre content server | OPDS 1.2 | — browse only | Untested |
| COPS | OPDS 1.2 | — browse only | Untested |
| Storyteller | OPDS 1.2 | — browse only | Untested |
| Ubooquity | OPDS 1.2 | — browse only | Untested |
Grimmory is a fork of BookLore — their protocol surfaces match, so BookLore should behave identically. Storyteller and Ubooquity sync position only through their own proprietary APIs, which standards-based clients can't reach — browsing still works. Stump's Kobo endpoints deliver books but never sync position; use its OPDS progression or KOReader sync instead.
Progress sync.
KOReader sync
The most widely implemented progress protocol — and Kios's global fallback for any book that isn't tied to a Kobo or OPDS source. Configure it in Settings → Progress sync.
One rule matters more than the rest: enter the full sync URL, including the server's sub-path. Kios appends only the protocol's own routes — it never guesses a server-specific prefix.
Calibre-Web-Automated
Server URL https://your-server:8083/kosync · auth method HTTP Basic · your normal CWA username and password.
Grimmory / BookLore
Server URL https://your-server:6062/api/koreader · auth method KOReader headers.
Use the dedicated KOReader sync user you create in the server's settings — it's separate from your main login. Position only matches books that were downloaded through the server's own catalog.
Komga
Server URL https://your-server:25600/koreader · auth method KOReader headers · username = a Komga API key (generate one in your account settings) · password is ignored — type anything.
Enable “Compute hash for KOReader” on the library and rescan once so books get matchable hashes.
Kavita
Server URL https://your-server:5000/api/koreader/your-api-key — the API key rides in the URL; copy it from your Kavita user settings.
Needs Kavita v0.8.7 or newer. Libraries created on older versions need a one-time forced scan so books get matching hashes.
Stump
Server URL https://your-server:10801/koreader/your-api-key.
KOReader sync is off by default: the server needs ENABLE_KOREADER_SYNC=true and matching user permissions, and the library needs KOReader-compatible hashes enabled (then rescan).
koreader-sync-server (official)
Server URL https://your-server — its routes live at the root · auth method KOReader headers · the username and password you registered with.
Library sync.
Kobo sync
The same protocol a Kobo e-reader speaks — the server keeps Kios, your Kobo and its own web reader in step: catalog, covers and position. Add it in Settings → Library sync → Add source, kind Kobo sync.
There's a single field beyond the display name: the personal sync URL your server generates for you, token included.
Calibre-Web-Automated / Calibre-Web
Enable Kobo sync in the admin feature settings, then generate your token on your user profile page. The URL looks like https://your-server:8083/kobo/your-token.
Grimmory / BookLore
Each user gets a sync token in their settings. Mind the /api prefix: https://your-server:6062/api/kobo/your-token.
Komga (untested)
https://your-server:25600/kobo/your-api-key with a Komga API key. Catalog and download answer correctly in our wire tests, but Kobo position sync against Komga is untested — KOReader sync and OPDS progression are Komga's proven routes.
Catalogs.
OPDS catalogs
Every server on this page publishes an OPDS catalog — browse your library and download books straight into Kios. Add it in Settings → Library sync → Add source, kind OPDS. Username and password are optional: fill both, or neither.
Where the catalog also advertises a Readium progression endpoint — Komga today, Stump experimentally — your reading position syncs through the same source automatically. Nothing extra to configure.
| Server | Catalog URL | Auth |
|---|---|---|
| Calibre-Web-Automated / Calibre-Web | https://your-server:8083/opds | HTTP Basic |
| Grimmory / BookLore | https://your-server:6062/api/v1/opds | dedicated OPDS account |
| Komga | https://your-server:25600/opds/v2/catalog | HTTP Basic — login is your email |
| Kavita | https://your-server:5000/api/opds/your-api-key | key in the URL |
| Stump | https://your-server:10801/opds/v2.0/catalog | HTTP Basic |
| Calibre content server | https://your-server:8080/opds | HTTP Basic, if enabled |
| COPS | https://your-server/feed | install-dependent |
| Storyteller | https://your-server:8001/opds | HTTP Basic |
| Ubooquity | https://your-server:2202/opds-books | install-dependent |
When it doesn't.
Troubleshooting
Every push fails, or the server says “book not found”
Almost always the KOReader sync URL: it must be the full base including the server's sub-path — /kosync on Calibre-Web-Automated, /api/koreader on Grimmory and BookLore. A bare host name can look connected and then fail on every sync.
If the URL is right, check the book: KOReader sync matches by file hash, so the copy in Kios must be byte-identical to the server's. Download it through the server's catalog rather than importing a different copy.
The server never matches any of my books
Several servers only compute matching hashes during a scan. On Komga, enable “Compute hash for KOReader” and rescan. On Kavita, libraries created before v0.8.7 need a one-time forced scan. On Stump, enable KOReader-compatible hashes, then rescan.
Kios and my Kobo show different percentages
Kobo firmware and Kios count whole-book progress differently, so after a handoff the two percentages can disagree while the chapter — and your actual position — are correct. A quirk of the device, not data loss.
Nothing syncs the first time I open a book
Normal: the server has no position for that book yet. Kios pushes yours when you background the app or close the book, and your other device picks it up on its next sync.