Kobo Sync

Kobo Sync

Read your CWA library on a Kobo e-reader, with reading progress syncing both ways. Sync runs against your own server, so your library never leaves your network.

1. In Admin → Edit Basic Configuration, turn on Enable Kobo sync.
2. Open your user page (Admin → Users → your user, or your own profile) and click Create/View next to Kobo Sync Token. The dialog shows the exact api_endpoint= line for your account.
3. Plug the Kobo into a computer over USB and open .kobo/Kobo/Kobo eReader.conf in a text editor. Add or replace the api_endpoint= line with the one from the dialog, save, and eject the device cleanly.
4. On the Kobo, sync. Books on your Kobo Sync shelves appear on the device, and progress flows back to CWA.

To confirm the device is reaching your server, watch the logs while you sync — you should see requests to /kobo/<token>/v1/...:

docker logs -f calibre-web 2>&1 | grep /kobo/

Behind a reverse proxy (nginx, Nginx Proxy Manager, Caddy, Cloudflare Tunnel)

Kobo devices sync over HTTPS, so the api_endpoint has to be your public https:// address. Put a proxy with a valid certificate in front and point it at the container's plain HTTP port:

• Proxy target is http://<container-host>:8083. The proxy terminates TLS on 443; the connection from the proxy to CWA stays HTTP. WebSocket support is not needed for Kobo sync.
• Generate the token while visiting CWA through the HTTPS address, so the api_endpoint= line the dialog shows already carries your public hostname.
• If you stack proxies (for example Cloudflare Tunnel in front of nginx), set TRUSTED_PROXY_COUNT to the number of proxies.

nginx buffer sizes (important for Kobo sync)

Kobo's /v1/library/sync response carries large headers (auth, sync tokens, library state). Nginx's default proxy_buffer_size (4 KB) and proxy_buffers (8 × 4 KB) are too small; the response is silently dropped before it reaches the device, and the Kobo shows "Sync failed, please try again" with no error in the CWA log. The nginx error log shows upstream sent too big header while reading response header from upstream. Add these to the location / block proxying CWA:

proxy_buffer_size       32k;
proxy_buffers           4 32k;
proxy_busy_buffers_size 64k;

(Larger libraries may need 128k / 4 256k / 256k.) Reload nginx after the change. On Synology DSM, the built-in reverse-proxy GUI doesn't expose these directives — drop a custom config at /etc/nginx/conf.d/http.calibre_web.conf that mirrors the DSM entry plus the buffer lines, then disable the DSM entry. DSM rewrites nginx.conf on reboot, so a Task Scheduler boot-event job that runs nginx -s reload reapplies the custom file. Nginx Proxy Manager users: add the three lines under the proxy host's Advanced tab.

See examples/nginx-reverse-proxy.conf for a complete reference snippet.

If you keep a Kobo account signed in

Signing into a Kobo account, or doing a factory reset, can rewrite the api_endpoint= line back to Kobo's own server, which sends sync to Kobo instead of your library. After signing in, re-check the conf line over USB and set it back if it changed. Many sideloaded setups sign out of the Kobo account so the device stops resetting the endpoint.

To keep the Kobo Store and your library working at the same time, turn on Proxy unknown requests to Kobo Store in Admin → Edit Basic Configuration. With it off (the default), any request CWA doesn't recognize gets an empty response — fine for a sideload-only device, but store features won't load.

---

Stuck on "Sync failed, please try again"? The full checklist is in Troubleshooting.