How to Sync Your Kobo e-Reader Wirelessly with Calibre-Web and Nginx Proxy Manager

Cheng Yee L.

5 min read

·

Sep 5, 2026

--

Listen

Share

Press enter or click to view image in full size

Ditch the USB cable and sync your self-hosted ebook library over the air — securely behind an HTTPS reverse proxy.

Why Wire When You Can Sync Over the Air?

While Kobo devices are widely praised across the reading and homelab communities for being far more flexible than closed ecosystems like Amazon Kindle, their native cloud sync remains tethered to Kobo’s retail catalog. Readers who self-host extensive digital collections using Calibre are typically relegated to manual USB sideloading: digging out a cable, plugging into a PC, and dragging files over one by one.

By pairing your device with Calibre-Web’s Kobo Sync API, you can retarget your e-reader to sync directly with your self-hosted library. You get automatic collection/shelf syncing, reading progress tracking, and effortless over-the-air book delivery — all while retaining full access to OverDrive, Pocket, Dropbox, and the native Kobo Store.

The Technical Hurdle

Calibre-Web’s internal Kobo Sync mechanism constructs its book download payload using plain http:// endpoints. When exposing your setup securely to the public internet using an HTTPS reverse proxy (port 443), this protocol mismatch breaks downloads on the e-reader.

In this guide, we will configure Nginx Proxy Manager (NPM) with response-body rewriting to handle SSL termination cleanly, configure Calibre-Web, and point your Kobo at your private cloud endpoint.

Prerequisites

Before starting, make sure you have:

• A Kobo e-reader (e.g., Kobo Clara, Libra Colour, Sage, Elipsa).
• A computer and a USB data cable (needed only once to edit a configuration file).
• Calibre-Web running with your EPUB library.
• Nginx Proxy Manager (NPM) configured with a public domain or subdomain and a valid SSL certificate (e.g., Let’s Encrypt).

Note on File Formats: Kobo’s native sync mechanism only supports EPUB and KEPUB formats. Other formats (like PDF or CBR/CBZ) will not sync over the air and must still be sideloaded manually.

Step 1: Configure Nginx Proxy Manager (NPM)

Because Calibre-Web returns book download URLs formatted as http://, we use Nginx’s sub_filter module to intercept the JSON API response and dynamically rewrite those links to https:// before sending them to your Kobo.

1. Open Nginx Proxy Manager and edit the Proxy Host for your Calibre-Web instance.
2. Ensure your SSL certificate is attached and Force SSL is enabled.
3. Navigate to the Advanced tab and paste the following custom configuration into the Custom Nginx Configuration block:

Nginx

proxy_set_header Host $http_host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header X-Forwarded-Host $http_host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Scheme $scheme;
proxy_set_header X-Script-Name //;
proxy_cookie_path / "/; Secure";
proxy_busy_buffers_size 1024k;
proxy_buffers 4 512k;
proxy_buffer_size 1024k;
client_max_body_size 50M;

# Response body rewrite: convert `DownloadUrls` from `http://` to `https://`
sub_filter_types application/json;
sub_filter 'http://' 'https://';
sub_filter_once off;

Step 2: Configure Calibre-Web

Next, we enable Kobo sync globally and generate a personal sync token for your user account.

2.1 Enable the Kobo Sync Feature

• Log in to Calibre-Web as an administrator.
• Navigate to Admin > Edit Basic Configuration > Feature Configuration.
• Check Enable Kobo Sync.
• Check Proxy unknown requests to Kobo Store (ensures your official store browsing and syncing continue to work normally).
• For Server External Port (for port forwarded API calls), specify 80.
• (Recommended) Check Embed Metadata to Ebook File on Download/Conversion/e-mail.
• Click Save.

2.2 Verify Kepubify Conversion

To take full advantage of Kobo-specific features (like fast page turns, reading statistics, and chapter time estimates), Calibre-Web can convert EPUBs to KEPUB on the fly using kepubify.

• In Admin > Edit Basic Configuration, go to External Binaries.
• Ensure the Path to Kepubify E-Book Converter points to your binary (typically /usr/bin/kepubify or /usr/bin).
• Click Save.

2.3 Generate Your Kobo Sync Token

• Login to Calibre-Web.
• Click on your User Profile (your username in the top navigation bar).
• Check Sync only books in selected shelves with Kobo (this gives you full control over which books land on your device).
• Under Kobo Sync Token, click Create/View.
• Copy the generated URL string. It will look like this:

api_endpoint=http://yourdomain.com/kobo/abcdef123456

(Keep this handy — we will change http:// to https:// in the next step).

2.4 Create a Sync Shelf & Add Books

• Login to Calibre-Web.
• On the left sidebar, click Create a Shelf.
• Name your shelf (e.g., Kobo Shelf).
• Check Sync this shelf with Kobo device, then click Save.
• Browse your library, open any book title’s details, click Add to shelf, and select your newly created shelf.

Step 3: Configure the Kobo e-Reader

Now we direct the Kobo hardware to talk to your Calibre-Web API endpoint instead of the standard Kobo servers.

3.1 Edit Kobo eReader.conf

• Connect your Kobo to your computer using the USB data cable and tap Connect on the e-reader screen.
• Open your file manager and navigate to the root directory of the Kobo.
• Open the .kobo/Kobo folder. (Note: On macOS and Linux, folders starting with a dot . are hidden by default; press Cmd + Shift + . on Mac or Ctrl + H on Linux to reveal them).
• Make a backup: Copy Kobo eReader.conf and rename the copy to Kobo eReader.conf.backup.
• Open Kobo eReader.conf in a plain text editor (e.g., VS Code, Notepad++, or TextEdit in plain text mode).
• Locate the section header:

[OneStoreServices]

• Modify or replace the following lines. Crucial: Ensure the protocol is set to https://:
• Replace the line starting with api_endpoint:

api_endpoint=https://yourdomain.com/kobo/your-token-here

• Replace the image_host line:

image_host=https://yourdomain.com/kobo/your-token-here

• Locate image_url_quality_template and replace https://cdn.kobo.com/book-images with your sync URL:

image_url_quality_template=https://yourdomain.com/kobo/your-token-here/{ImageId}/{Width}/{Height}/{Quality}/{IsGreyscale}/image.jpg

• Locate image_url_template and replace https://cdn.kobo.com/book-images with your sync URL:

image_url_template=https://yourdomain.com/kobo/your-token-here/{ImageId}/{Width}/{Height}/false/image.jpg

• Save the file and safely Eject / Unmount the e-reader before disconnecting the USB cable.

Step 4: Test the Sync

• On your Kobo, ensure Wi-Fi is connected.
• Tap the Sync icon in the top navigation bar.
• Your Kobo will perform its initial handshake. Within moments, you will see a collection created matching your shelf name (e.g., Kobo Shelf), and the EPUB/KEPUB files will download automatically.
• Open the Kobo Store or OverDrive — you’ll find that native device features continue to work without a hitch.

Troubleshooting & Reverting

• Books appear in library but won’t download: Double-check your Nginx Proxy Manager configuration. If the sub_filter directives are missing, the Kobo may try to reach internal http:// URLs that your browser or firewall blocks.
• Cover images are missing: Ensure the image_url_quality_template and image_url_template parameters in Kobo eReader.conf have been updated with https:// and point to the base of your token endpoint.
• How to revert to factory defaults: If you ever want to return the Kobo to its stock syncing configuration, connect via USB, delete Kobo eReader.conf, and rename Kobo eReader.conf.backup back to Kobo eReader.conf.

Check it out here if you prefer it in GitHub Gist.