Synchronize reading progress between KOReader and a Bookshelf (Varbook) server.
Read on your Kobo in the evening, then pick up where you left off the next morning on the web reader -- and vice versa.
- Automatic local tracking: every page turn is recorded in a local SQLite database, no network needed
- One-tap sync: push all accumulated positions and pull the latest server progress in a single action
- Gesture support: assign sync to any tap zone, swipe, or long-press for quick access
- Offline-first: positions are stored locally and synced whenever you're ready
- Cross-device: works alongside the Bookshelf web reader, Moon+ Reader (WebDAV), and other Varbook-compatible clients
- KOReader on a Kobo (or other supported device)
- Bookshelf (Varbook) server with the
/api/varbook/endpoints enabled - An API token generated from the Bookshelf web interface
- Books must be the same EPUB files on both devices (same file = same hash). The easiest way is to download books via the Bookshelf OPDS catalog.
The easiest way to install is through the KOReader App Store:
- Install the App Store plugin if you don't have it yet (see its README for instructions)
- Open KOReader
- Go to Search > Plugin store
- Search for Varbook Sync
- Tap Install
- Restart KOReader
Updates will be available directly from the App Store.
Connect your e-reader via USB and copy the varbook.koplugin folder into KOReader's plugins directory:
<KOBO>/.adds/koreader/plugins/varbook.koplugin/
Restart KOReader after copying.
- Log into the Bookshelf web interface
- Go to Profile
- In API Tokens, click Generate new token
- Name it (e.g. "Kobo Libra") and copy the token -- it won't be shown again
- Open any book in KOReader
- Open the menu (tap the top of the screen)
- Tools > Varbook > Server URL: enter your server URL (e.g.
https://bookshelf.example.com) - Tools > Varbook > API Token: enter the token
Menu > Tools > Varbook > Sync now
The plugin enables WiFi if needed, fetches the server's latest position, navigates there if it's more recent, and pushes all local positions in a batch.
Assign Varbook Sync to any gesture for one-tap access:
- Settings > Taps and gestures > Gesture manager
- Pick a gesture (e.g. top right corner tap)
- Select Varbook Sync
Menu > Tools > Varbook > Status shows the configured URL, pending positions count, and last sync date.
EVENING (Kobo):
Read for an hour → page turns recorded locally
Sync now → 50 positions pushed to server
MORNING (Web/phone):
Open book in web reader → picks up at last synced position
Read to 52%
EVENING (Kobo):
Sync now → server says 52%, KOReader navigates there
Continue reading
Synchronization is percentage-based (page-level accuracy, within 1-2 pages).
Books are identified by a partial MD5 hash (KOReader's native algorithm). For sync to work, the EPUB must be identical on both devices.
The simplest approach:
- Upload the book to Bookshelf via the web interface
- Download it onto the Kobo via the OPDS catalog (
https://your-server/opds)
- Positions:
varbook_positions.sqlite3in KOReader's settings directory (auto-cleanup after 30 days) - Settings:
varbook.luain the same directory
| Problem | Solution |
|---|---|
| "Authentication failed" | Check the token. Generate a new one if needed. |
| "Book not found on server" | The book isn't on the server or the hash doesn't match. Re-download via OPDS. |
| "Network error" | Check WiFi. Positions are kept locally and will sync next time. |
| Plugin menu doesn't appear | Ensure varbook.koplugin is in the plugins directory. Restart KOReader. |
| Position off by a few pages | Expected -- sync is percentage-based. |
Delete varbook.koplugin from the plugins directory. Optionally remove varbook_positions.sqlite3 and varbook.lua from the settings directory.
MIT