Skip to content

Kobo Integration & Sync

Jump to bottom Edit New page
crocodilestick edited this page Jan 26, 2026 · 8 revisions

CWA's Integrations with Kobo ❤️

Calibre-Web Automated (CWA) integrates with Kobo e-readers, allowing you to sync your library, reading progress, and manage your collection directly from your device. This guide covers both user setup and information for developers.

🚀 Quick Start

Prerequisites

  • Kobo e-reader (Clara HD, Libra 2, Sage, etc.)
  • Calibre-Web Automated instance accessible from your network
  • Administrator access to enable Kobo sync
  • Books in EPUB or KEPUB format

Admin Configuration

  1. Enable Kobo Sync

    • Navigate to Admin → Basic Configuration → Feature Configuration
    • Check "Enable Kobo sync"
    • Optionally, enable "Proxy unknown requests to Kobo Store" if you want to use CWA and the Kobo Store
    • Save settings

  2. User Permissions

User Setup

Step 1: Generate Kobo Authentication Token

  1. Go to your User Settings or have an admin navigate to Admin → Edit Users → [Your User]
  2. Click "Generate Kobo Auth URL"
  3. Copy the displayed api_endpoint URL

⚠️ Important: Access CWA from a non-localhost address to get a valid endpoint for your Kobo device.

Step 2: Configure Your Kobo Device

Set the api_endpoint key in [OneStoreServices] to your generated auth URL.

  1. Connect your Kobo to a computer via USB
  2. Navigate to .kobo/Kobo/ folder on your device
  3. Open Kobo eReader.conf in a text editor
  4. Find the [OneStoreServices] section, or add it if it is not there.
  5. Edit the api_endpoint key under the [OneStoreServices] section, or add it if it is not there: 
    [OneStoreServices]
api_endpoint=https://yourserver.example/kobo/<your-auth-token>
  6. Save and safely eject your Kobo

Step 3: Initial Sync

  1. Restart your Kobo device
  2. Connect to WiFi
  3. The initial sync will begin automatically
  4. Check your library - CWA books should appear

Sync Modes

Feature Full Library Sync (Default) Shelf-Only Sync
Use case Having your entire library on the Kobo Curated syncing of selected books
Books synced All books in CWA library Only books in designated "Kobo Sync" shelves [1]
Setup Unselect "Sync only books in selected shelves" Select "Sync only books in selected shelves"
"Remove from collection" on Kobo Removes book from shelf in CWA Removes book from shelf, removes book from Kobo on next sync
"Remove download" on Kobo No change in CWA, can re-download on Kobo No change in CWA, can re-download on Kobo
"Remove from my books" on Kobo Archives the book in CWA and removes from shelf (if any) [2] Unsyncs the book and removes from shelf [3]
Removal from CWA shelf Removes book from Kobo collection, book stays on Kobo Removes book from Kobo collection and from My Books
Archiving in CWA Removes book from Kobo Removes book from Kobo
  • [1] Public shelves created by other users are not considered for shelf-only sync. Only shelves owned by the user performing the sync are used.
  • [2] If the book is in a Kobo collection, restoring it from the archive in CWA will not automatically return it to the shelf.
  • [3] in V3.1.4 and below, the book will also be archived in CWA.

Setting Up Shelf-Only Sync

  1. Enable Feature

    • Go to User Settings → Check "Sync only books in selected shelves with Kobo"
    • Save settings

  2. Create Sync Shelves

    • Navigate to Your Shelves → Create Shelf
    • Name your shelf (e.g., "Kobo - To Read")
    • Check "Sync this shelf with Kobo device"
    • Save shelf

  3. Add Books to Sync Shelves

    • Add books to your sync-enabled shelves
    • Only these books will appear on your Kobo after the next sync

🔄 Two-Way Sync Features (New in CWA)

Calibre-Web → Kobo Deletion Sync

When using shelf-only sync:

  • Remove a book from a sync shelf in CWA
  • The book is automatically deleted from your Kobo on the next sync
  • Creates seamless library management from the web interface

Kobo → Calibre-Web Deletion Sync

The behavior depends on your sync mode:

Full Library Sync:

  • Delete book from Kobo → Book is archived in CWA
  • Book remains in library but marked as archived

Shelf-Only Sync:

  • Delete book from Kobo → Book is removed from sync status
  • Book remains in library and shelves, simply unsynced

📖 Reading Progress Sync

Automatic Sync

  • Reading position, bookmarks, and statistics sync automatically
  • Progress updates when you:
    • Turn pages
    • Close a book
    • Switch between books
    • Connect to WiFi

Manual Sync

  • Go to Settings → Sync and Share → Sync Now on your Kobo
  • Or simply connect to WiFi if auto-sync is enabled

Proxy unknown requests to Kobo Store

If enabled, CWA will pass requests to the Kobo Store if they cannot be handled from your CWA library. This lets you use your CWA library and the normal Kobo Store features at the same time. If not enabled, CWA will ignore requests for books that are not in your CWA library or functionality that is not supported.

🔧 Advanced Features

Format Conversion

  • CWA automatically converts EPUB to KEPUB format when possible
  • KEPUB provides better integration with Kobo features
  • Requires kepubify tool to be configured in CWA

Cover Sync

  • Book covers are automatically downloaded and displayed
  • Multiple resolution support for different Kobo models
  • Fallback to Kobo store covers if local covers unavailable

Metadata Sync

  • Title, author, series, and description sync automatically
  • Tags and series information maintained
  • Publication dates and ratings supported

Hardcover Sync

Provided there is a hardcover-slug for the synced books, and there is a Hardcover API key in the user profile; each sync from your Kobo to your server will also update the read status of said books to your Hardcover.app account.

🚨 Troubleshooting

Common Issues

Books not appearing on Kobo:

  • Verify user has download permissions
  • Check that books are in EPUB/KEPUB format
  • Ensure WiFi connection for sync
  • Try manual sync from Kobo settings

Sync shelf not working:

  • Confirm "Sync only books in selected shelves" is enabled
  • Verify shelf has "Sync this shelf with Kobo device" checked
  • Check that books are actually in the sync shelf

Authentication errors:

  • Regenerate auth token if expired
  • Ensure CWA is accessible from non-localhost
  • Verify correct api_endpoint in Kobo config

Reading progress not syncing:

  • Check WiFi connectivity
  • Verify user permissions
  • Try manual sync from device

Books appear in Kobo but covers do not appear

Check the value of image_host in Kobo eReader.conf. It should be a URL like https://yourserver.example that is accessible over the network from your Kobo. If it looks like https://yourserver.example:8083, but your CWA server's external address is actually https://yourserver.example, try this:

  • For troubleshooting, edit the keys in Kobo eReader.conf. Reboot your Kobo after making changes, reconnect to WiFi, and check if covers appear. 
    image_host=https://yourserver.example:443
image_url_quality_template=https://yourserver.example:443/kobo/0a3b03aecafebabef27ff99d1b33f/{ImageId}/{width}/{height}/isGreyscale/image.jpg
image_url_template=https://yourserver.example:443/kobo/0a3b03aecafebabef27ff99d1b33f/{ImageId}/{width}/{height}/false/image.jpg
  • When you get it working, change the value of Server External Port (for port forwarded API calls) in CWA's Admin → Basic Configuration to match the port you used in the Kobo eReader.conf file. On your next sync, CWA will update the image_host and URL templates on your Kobo automatically.

If you have fixed it and covers are working, but book downloads are not working, go to User Settings and choose "Force Full Sync". On the next sync, CWA will send the correct download URLs for all books to your Kobo.

The situation is more complicated if you are using a reverse proxy or SSL termination (such as Cloudflare) in front of CWA. In that case, you can also try:

  • Using 80 or 443 as the Server External Port (try 80 even if you are using https)
  • Turn off "Proxy unknown requests to Kobo Store" in CWA Admin settings, see what happens
  • Check Calibre-Web Kobo Integration Documentation for more ideas

Sync timeouts, especially with a tunnel or reverse proxy:

Verifying whether your Kobo can reach the api_endpoint URL is a good first step. This cuts your troubleshooting in half: if the Kobo cannot reach the URL, the problem is network-related; if it can, the problem is likely on the CWA side. Try this:

  1. Add your /v1/initialization endpoint to the Kobo Auth URL, e.g. https://yourserver.example/kobo/your-auth-token/v1/initialization
  2. Set that URL as the homepage in your Kobo's web browser in Kobo eReader.conf: 
    [Browser]
homepage=https://yourserver.example/kobo/your-auth-token/v1/initialization
  3. Open the browser on your Kobo and see if it can load the page. You should see a JSON response with settings similar to the [OneStoreServices] section of your Kobo eReader.conf.

Reset Sync Status

If you need to reset your sync status:

  1. Admin can force full sync in user settings
  2. Or delete auth token and regenerate

🔧 Database Maintenance & Migrations

Automatic Database Migration (v3.2.0+)

Starting with v3.2.0, CWA automatically ensures ON DELETE CASCADE exists for progress sync tables. This prevents foreign key constraint errors when books/users are deleted.

What Gets Migrated

CWA adds ON DELETE CASCADE to these tables when missing:

  • book_format_checksums: Book format checksums for KOReader sync
  • kosync_progress: Reading progress data from KOSync protocol

When Migration Happens

  • On startup: If a table exists and its schema matches, CWA checks for ON DELETE CASCADE.
  • If missing: CWA rebuilds the table in place and keeps only rows with valid parent records.
  • If already correct: No changes are made.

Migration Behavior

Normal Case:

  1. Detect missing ON DELETE CASCADE
  2. Create a new table with the correct foreign key
  3. Copy valid rows (drops orphaned rows)
  4. Swap the tables and recreate indexes

If Migration Fails:

  • Error is logged but startup continues
  • Check logs at /config/log_archive/

Data Loss Notice

✅ No data loss for valid rows ⚠️ Orphan rows are dropped (rows whose parent book/user no longer exists) ⚠️ Progress/checksum data is cache/sync data and can be recreated or re-synced

Why This Migration Is Needed

Problem: Calibre Desktop (and other tools) enable SQLite foreign key constraints, which caused deletion errors:

FOREIGN KEY constraint failed

Solution: Add ON DELETE CASCADE so deleting a book/user automatically deletes related progress data.

Result: Full compatibility between CWA, Calibre Desktop, and command-line tools.

Developer Information

API Endpoints

The Kobo integration implements these key endpoints:

  • /kobo/<auth_token>/v1/library/sync - Main sync endpoint
  • /kobo/<auth_token>/v1/library/<uuid>/metadata - Book metadata
  • /kobo/<auth_token>/v1/library/<uuid>/state - Reading state
  • /kobo/<auth_token>/v1/library/<uuid> (DELETE) - Book deletion

Database Schema

Core Tables

  • kobo_synced_books - Tracks which books are synced per user
  • kobo_reading_state - Reading progress and timestamps
  • kobo_bookmark - Current reading position
  • kobo_statistics - Reading time and progress stats
  • archived_book - Archived book status
  • remote_auth_token - Authentication tokens

Key Fields

-- User configuration
users.kobo_only_shelves_sync  -- Enable shelf-only sync mode

-- Shelf configuration  
shelf.kobo_sync  -- Mark shelf for Kobo sync

-- Sync tracking
kobo_synced_books.user_id, book_id  -- Active sync relationships

Two-Way Sync Implementation

Deletion Sync Logic (HandleSyncRequest)

# For shelf-sync users only
if current_user.kobo_only_shelves_sync:
    # Find books on device but not in sync shelves
    synced_book_ids = {books currently on Kobo}
    allowed_book_ids = {books in sync shelves}
    books_to_delete = synced_book_ids - allowed_book_ids
    
    # Send deletion commands to Kobo
    for book_id in books_to_delete:
        send_archive_command(book_id)

Device Deletion Handling (HandleBookDeletionRequest)

if current_user.kobo_only_shelves_sync:
    # Shelf-sync users: just remove sync status
    pass
elif current_user.check_visibility(32768):
    # Full-sync users: archive the book
    kobo_sync_status.change_archived_books(book_id, True)

# Always remove from sync tracking
kobo_sync_status.remove_synced_book(book_id)

Configuration Options

System-wide Settings

  • config.config_kobo_sync - Enable/disable Kobo integration
  • config.config_kobo_proxy - Proxy unknown requests to Kobo store
  • config.config_kepubifypath - Path to kepubify conversion tool

User Settings

  • user.kobo_only_shelves_sync - Enable shelf-only sync mode
  • User permissions for download and archive access

Security Model

Authentication

  • Unique tokens per user via RemoteAuthToken table
  • Tokens embedded in API URLs for stateless authentication
  • No password storage on device

Authorization

  • User permissions checked on each request
  • Download permission required for sync access
  • Archive permission required for deletion handling

🔗 Related Resources

🤝 Contributing

The Kobo integration is actively developed. Key areas for contribution:

  • Enhanced format support
  • Improved sync performance
  • Additional device compatibility
  • Better error handling and user feedback

See the main project repository for contribution guidelines.

This documentation covers Calibre-Web Automated's enhanced Kobo integration. Features may differ from the original Calibre-Web project.

Add a custom footer
Add a custom sidebar

Clone this wiki locally