This is my opinionated documentation for setting up a Kobo Libra Colour (or any Kobo device) for a native, wireless, self-hosted e-book library (i.e., tap a book on the device and it downloads over WiFi) with Hardcover progress syncing, plus streaming manga with no conversion needed.
Note
I've now added a new CrossPoint 'micro' reader for work/travel/fun, the EegoRead A4. To sync between my Kobo and a Crosspoint device, I replaced Calibre-Web-Automated (Next Gen) with Bookorbit. I've updated the instructions to set up progress sync between that device and my Kobo as the main reader. This should work for any CrossPoint device.
The organizational philosophy here is to keep the book and manga libraries completely separate:
- The native Kobo interface is used exclusively for reading books.
- KoReader is used exclusively as the entry point for the manga library. From the Kobo home screen, NickelMenu provides a quick launch directly into the Rakuyomi manga library, using KoReader and a few supporting plugins. This keeps the manga collection and reading experience completely separate from the native Kobo book library.
- The central library service is BookOrbit, which serves as both my digital library and hub to sync reading progress between all my devices and back to Hardcover.app.
patches/kobopatch.yaml— kobopatch overrides used on this devicenicklemenu/config— NickelMenu configurationbooks/compose.yaml/books/example.env— Calibre-Web-Automated (Next-Gen) Docker Compose stack
Use the latest patches from the MobileRead Kobo Developer forum.
My patches/kobopatch.yaml contains my personal preferences, for example:
- Removing the third row (footer) and increasing cover size on the home screen
- Increasing cover size on the library and series pages
Caution
Make sure the version and source (in:) match your exact firmware!
Copy/merge the overrides: section from patches/kobopatch.yaml into your own kobopatch config, run kobopatch, and install the resulting KoboRoot.tgz on the device.
Install NickelMenu to add custom menu entries (toggles, quick actions, launching KoReader, etc.) to the native Kobo UI.
My config lives in nicklemenu/config and adds a custom icon and entries like dark mode / invert screen quick toggles, manually trigger a USB connection (useful for setup without unplugging the cable), and quick access to reading stats, reboot, and shutdown. These options are available from the home screen, reader, library, and browser menus.
Install KoReader. It's used solely for reading manga through Rakuyomi (see Section 3).
- NickelTypeFix — improves native typesetting/justification
- NickelDissolve — animates page turns
- NickelSync - trigger a sync from within a book, useful for quickly pulling/pushing progress
Tip
See the migration instructions below if you started on Calibre-Web-Automated (Next-Gen).
Self-host BookOrbit. I deployed it in a Proxmox LXC using the Community Helper Script. You can also install it via Docker from their repository.
In the BookOrbit web UI:
- Connect your Hardcover account.
- Add a Kobo device and note the generated Kobo API address. You'll need it on the device in the next step.
- Configure your library and review the book matches before importing reading history.
I migrated the library files from CWA-NG, but deliberately did not migrate its reading history or progress data. Instead, I use Hardcover.app as the source of truth for reading status and history.
- Copy the raw Calibre Library folder from CWA-NG into BookOrbit's books folder.
- Let BookOrbit scan the library and confirm the books have been imported.
- Before importing reading history, remove books you no longer want in the library. Do this first, since reading-history entries can remain even if you later remove a book.
- Tidy up Hardcover before importing anything:
- Confirm read / unread and want-to-read statuses.
- Review reading start and finish dates.
- Remove incorrect or duplicate reading-history entries.
- Pull the Hardcover data into BookOrbit.
I found this much cleaner than importing CWA-NG reading data directly. My previous CWA-NG import introduced conflicting dates and duplicate reads. Cleaning up Hardcover first and using it as the source of truth avoids carrying those problems into BookOrbit.
Matching generally works well when the book already exists in Hardcover, but review unmatched or incorrect matches. Metadata cleanup is optional. I prefer to tidy important matches manually, or configure the automatic matching parameters before running a bulk match.
Warning
If you use Pangolin, you'll need to bypass its authentication for the following integration endpoints. This allows device and app requests through the Access Gate; BookOrbit still performs its own authentication.
Add the following paths as Bypass Auth rules on the BookOrbit resource:
| Path | Purpose |
|---|---|
/api/v1/opds* |
OPDS catalog and downloads |
/api/v1/opds |
no wildcard, OPDS catalog and downloads |
/api/v1/koreader* |
KOReader / KOSync |
/api/v1/kobo/* |
Kobo sync |
/api/v3/* |
Kobo annotations and highlights |
/api/UserStorage/* |
Kobo device storage |
/api/v1/auth/* |
Login/authorization |
/api/v1/books/* |
Also used for sync |
/api/v1/reading-progress* |
CrossPoint Sync progress reads and writes |
The last path is particularly important for the CrossPoint Sync BookOrbit connector. The connector uses BookOrbit's newer reading-progress API for both reading and writing progress. Without this bypass, Pangolin's authentication can interfere with synchronization.
For the iOS app, create a Shareable Link from Pangolin's main navigation and associate it with the BookOrbit resource.
In the app's custom HTTP headers, add the Shareable Link's Token ID and Token:
| Header | Value |
|---|---|
P-Access-Token-Id |
Shareable Link Token ID |
P-Access-Token |
Shareable Link Token |
The Pangolin token gets the request through the Access Gate; BookOrbit still performs its own user authentication. Treat the token like a password.
Mount the Kobo over USB and edit:
.kobo/Kobo/Kobo eReader.conf
Replace the api_endpoint value with the generated Kobo API address from BookOrbit's Kobo device configuration.
After unmounting and reconnecting to WiFi, the Kobo will sync against BookOrbit. Books can then be tapped to download directly on-device.
Tip
Large libraries often take multiple syncs the first time. If you have errors, force a full resync in BookOrbit's settings.
All manga reading happens inside KoReader via the Rakuyomi plugin, kept fully separate from the native book library.
- Install the Rakuyomi KoReader plugin, and use the Kindle release build.
- Install stretch.koplugin so manga pages fill the available screen without extra scrolling.
- Install startrakuyomi.koplugin so launching KoReader drops you straight into your Rakuyomi library.
- simpleui.koplugin — simple menu bar actions similar to tapping the top of the screen in the native Kobo UI (quit back to Nickel, brightness, etc.)
- appstore.koplugin — easier plugin discovery, installation, and updates
Launch KoReader from the NickelMenu entry, which should bring you right into Rakuyomi's library view. Add your manga sources, and add titles into Rakuyomi's library. Quit to return to Kobo to read.
The EEGO A4 is my secondary reader for work, travel, and general use. It runs CrossPoint firmware and uses BookOrbit as its library and progress-sync hub.
I self-host CrossPoint Sync separately from the BookOrbit LXC, on my books host.
Deploy it using the CrossPoint Sync Docker image. Configure its persistent data storage and expose the service through Pangolin if you need remote access.
In CrossPoint Sync, add BookOrbit as a connector using:
- Server: your BookOrbit URL
- Username: your regular BookOrbit account username
- Password: your regular BookOrbit account password
This is the native BookOrbit connector, not the KOReader plugin or the OPDS account. Complete the connector setup and verify that it can connect to BookOrbit.
Install CrossPoint on the EEGO A4 using the official web installer.
Connect the reader over USB, select the EEGO A4 in the installer, and follow the prompts to flash the firmware. Complete the initial setup and connect the reader to WiFi.
I used the following unauthenticated paths
/users/auth*
/users/create*
/syncs/progress*
/api/v1/account/*
/api/v1/bookmarks/*
/api/v1/clippings/*
/api/v1/connectors/*
/api/v1/documents*
/api/v1/profile
/api/v1/progress
/api/v1/progress/*
/api/v1/stats/*
/healthz
Note
I'm not sure if the /api/v1/ endpoints are needed, more teesting required
On the reader, configure CrossPoint Sync with:
- Server type: CrossPoint
- Server URL: your self-hosted CrossPoint Sync URL
- Credentials: your CrossPoint Sync account
Save the settings and run a manual sync to verify the connection. I also mapped a long press of the Home button to trigger a sync.
OPDS is separate from CrossPoint Sync. It lets the reader browse and download books from BookOrbit.
In BookOrbit, enable OPDS and create an account with the opds_access permission.
On the EEGO A4, add an OPDS server using:
https://<bookorbit-host>/api/v1/opds
Enter the OPDS account credentials and save. The catalog should then be available from the reader for browsing and downloading books.
BookOrbit acts as the central hub for reading progress across both devices and for updates to Hardcover. The goal is to read on one device, sync, then pick up on the other device where I left off.
For example:
- Read on the Kobo or EEGO A4.
- Trigger a sync on that device.
- Pick up the other reader and trigger a sync.
- Continue reading from the synchronized position.
The sync paths are:
- Kobo Libra Colour: Uses BookOrbit's native Kobo sync API. Sync from the Kobo home screen.
- EEGO A4: Uses CrossPoint Sync, with BookOrbit configured as its connector. Sync by long-pressing the Home button.
BookOrbit receives the progress updates and coordinates synchronization between the devices and Hardcover.