Kobo sync for Bookshelf

Last updated: May 14, 2026

What it does

The Bookshelf Kobo mod is a small piece of software that runs on your Kobo eReader and pushes your reading activity back into Bookshelf every time you finish a reading session. It syncs:

  • Reading progress (pages/percent) per session
  • Highlights → Quotes
  • Annotations → Notes
  • Star ratings
  • Reviews you write on the device

Communication is one-way (Kobo → Bookshelf) over HTTPS, authenticated with a sync token you generate in the app. No cloud account on the Kobo, no Goodreads or third-party service in between.

Requirements

  • Any Kobo running recent firmware (Clara, Libra, Sage, Elipsa, Forma, Aura - anything from the last few years).
  • A USB cable and a computer (Windows, macOS or Linux).
  • A Bookshelf account on the mobile app - that's where you generate the sync token.

You do not need to jailbreak the Kobo, install KOReader, or sideload anything else. The mod ships as a single KoboRoot.tgz archive that the Kobo applies during its normal boot sequence - exactly the same mechanism Kobo's own firmware updates use.

Step 1 - Generate a sync token

In the Bookshelf app:

  1. Open Settings → Customization → Kobo sync.
  2. Tap Generate token.
  3. Copy the token. It looks like bks_<uid>_<hex>. You can only see it once - if you lose it, just generate a new one and revoke the old one.

The token is what authenticates your Kobo to your account. Treat it like a password: don't paste it into chats, screenshots, or public forums. You can revoke it any time from the same page.

Step 2 - Download the mod

Download bookshelf-kobo-sync-latest.zip and unzip it on your computer. Inside you'll find:

  • KoboRoot.tgz - the installer. Contains the in-Kobo UI mod plus the small bookshelf-kobo sync agent.
  • config.ini.example - a template config you'll edit in the next step.

The mod is open source (MIT). If you'd rather build from source or audit the code, see the "Open source" section at the bottom of this page.

Step 3 - Copy the files to the Kobo

  1. Plug the Kobo into your computer via USB and tap Connect on the device. It will mount as a USB drive called KOBOeReader.
  2. Show hidden files on the Kobo drive (View → Show hidden files on Windows; ⌘ ⇧ . in Finder on macOS).
  3. Copy KoboRoot.tgz into .kobo/ on the Kobo drive. Don't extract it - the device unpacks it itself on next boot.
  4. Create the folder .adds/BookshelfSync/ on the Kobo drive (next to .kobo/, not inside it).
  5. Copy config.ini.example into that folder and rename it to config.ini.

Step 4 - Paste your token into config.ini

Open .adds/BookshelfSync/config.ini in any text editor and replace REPLACE_WITH_YOUR_TOKEN on the authorization = line with the token you generated in Step 1. The rest of the file is fine as-is.

; Lines starting with ; are comments. Don't wrap values in quotes.

; Your Bookshelf sync token (Settings → Kobo sync → Generate token).
authorization = bks_paste_your_token_here

; Default Bookshelf backend. Don't change unless you're self-hosting.
server_url = https://us-central1-bookshelf-a829b.cloudfunctions.net

; Path to Kobo's reading database (the default works for all stock Kobos).
sqlite_path = /mnt/onboard/.kobo/KoboReader.sqlite

; When the same book has progress on both sides, who wins?
;   kobo       - Kobo is the source of truth
;   bookshelf  - never overwrite Bookshelf
;   auto       - keep the most recent (default)
conflict_resolution = auto

; When to upload highlights/annotations:
;   always     - every sync (default)
;   finished   - only once a book is marked finished on the Kobo
;   never      - don't sync highlights at all
sync_bookmarks = always

; Verbose logs to .adds/BookshelfSync/log.txt
debug = false

Save the file. Make sure your editor uses plain UTF-8 - Notepad on Windows is fine, so is TextEdit on macOS if you switch it to plain text first (Format → Make Plain Text). Two common mistakes that cause "no token configured" errors: leaving a ; at the start of the authorization line, or wrapping the token in quotes.

Step 5 - Eject and let the Kobo install

Safely eject the Kobo from your computer. The device will show the usual "Updating your Kobo" screen for about a minute while it unpacks KoboRoot.tgz and then reboots. Once you're back at the home screen, the mod is live.

Step 6 - First sync

  1. Make sure the Kobo is connected to Wi-Fi.
  2. Open the menu and tap Bookshelf → Sync now.
  3. You should see a toast like "Synced 12 books, 4 highlights". Open Bookshelf on your phone - the matching books should now show the new reading sessions, highlights, ratings and reviews.

After this first run, the mod will sync automatically every time your Kobo connects to Wi-Fi after a reading session - you do not need to open the menu manually.

For epub books, open the book in Bookshelf and look for the book icon in the top-right corner of the app bar. Tapping it lets you manage the Kobo integration for that specific book - link it to a different Kobo title, view sync history, and more.

How books are matched

For every book on your Kobo, the sync agent tries to find a matching book in your Bookshelf library:

  1. If you've manually linked this Kobo book before, that link wins.
  2. If the ISBNs match, that's used.
  3. Otherwise, Bookshelf will surface the book in the Unmatched tab of the Kobo sync page on the phone - tap one to either pick an existing book or create a new one. The next sync will then push the data into the right place.

Privacy & data handling

  • Sync is initiated by the Kobo and goes directly to Bookshelf's Firebase backend over HTTPS. Nothing is routed through any third party.
  • The token is stored in plain text on the Kobo (that's how Kobo apps work). On the server we only store its sha256 hash, never the token itself.
  • You can revoke a token at any moment from Settings → Customization → Kobo sync. Revoked tokens stop authenticating immediately.
  • The Kobo never receives data from Bookshelf - the sync is one-way upload.

Troubleshooting

The Kobo never showed the "Updating" screen.
Double-check the path: KoboRoot.tgz must be inside the hidden .kobo/ folder, not in .adds/ or the drive root. Re-copy it, eject, and unplug.
Sync fails with "unauthorized".
The token in config.ini is wrong, revoked, or surrounded by extra characters (smart quotes from a rich-text editor are a common culprit). Generate a new token and paste it again in a plain-text editor.
Some books don't show up in Bookshelf.
Books without ISBNs in the Kobo database (typically side-loaded EPUBs) need a manual link the first time. Go to the Unmatched tab on the phone and link them - subsequent syncs will use that link automatically.
I want to uninstall the mod.
Connect the Kobo via USB, create an empty file called bookshelfsync_uninstall in the root of the KOBOeReader drive, and eject. The mod will remove itself on the next boot.

Open source

The Kobo mod is open source under the MIT license and is a fork of NickelHardcover by StrayRose. If you want the source, build instructions, or to report a bug, email support@tcreations.app.