InkSync

CWA's built-in Hardcover sync never worked reliably. InkSync fixes that by sitting between your Kobo and CWA, intercepting WiFi sync traffic and pushing your reading progress to Hardcover automatically — no manual entry, no broken syncs.

As a side effect: because InkSync rewrites the Kobo's initialization response to route all traffic through itself, book covers show up correctly in the Kobo store instead of the generic white placeholders you get with a direct CWA sync.

Kobo ──WiFi sync──▶ InkSync ──▶ CWA
                        │
                        └──▶ Hardcover

---

Requirements

• Docker and Docker Compose
• A running Calibre-Web Automated instance
• A Hardcover account with an API token

---

Setup

1. Get your Hardcover API token

Go to hardcover.app/account/api and copy your token. Tokens reset on January 1st each year.

2. Create your .env file

curl -o .env.example https://raw.githubusercontent.com/kvenanzi/inksync/master/.env.example
curl -o docker-compose.yml https://raw.githubusercontent.com/kvenanzi/inksync/master/docker-compose.yml
cp .env.example .env

Edit .env:

CWA_URL=http://your-cwa-host:8083        # your CWA server, reachable from Docker
HARDCOVER_TOKEN=your-hardcover-api-token
KOBO_TOKEN=your-cwa-kobo-sync-token      # from CWA Admin → Kobo Setup
LISTEN_PORT=8787                         # optional, default 8787

If InkSync and CWA are on the same Docker network, you can use the CWA container name as the hostname (e.g. http://calibre-web-automated:8083).

3. Start InkSync

docker compose up -d
docker logs inksync  # should show {"event": "starting", ...}

4. Point your Kobo at InkSync

Connect your Kobo via USB and edit (or create) .kobo/Kobo/Kobo eReader.conf:

[OneStoreServices]
api_endpoint=http://your-inksync-host:8787/kobo/your-cwa-kobo-sync-token

• your-inksync-host — IP or hostname of the machine running InkSync, reachable from your Kobo over WiFi
• your-cwa-kobo-sync-token — your Kobo sync token from CWA (Admin → Kobo Setup)

Eject the Kobo and do a WiFi sync. You should see request logs in docker logs inksync.

---

Configuration

Variable	Required	Default	Description
CWA_URL	✅	—	Full URL of your CWA server
HARDCOVER_TOKEN	✅	—	Hardcover API token
KOBO_TOKEN	✅	—	Kobo sync token from CWA (Admin → Kobo Setup)
LISTEN_PORT	—	8787	Port InkSync listens on
LOG_LEVEL	—	INFO	DEBUG, INFO, WARNING, or ERROR

---

Logs

docker logs -f inksync

Key events: hardcover_sync_success, hardcover_sync_skip (with reason), hardcover_api_error. Set LOG_LEVEL=DEBUG for human-readable console output during development.

---

Known limitations

• Books without metadata in CWA are skipped with a hardcover_sync_skip log line.
• One-way sync only: Kobo → Hardcover.
• No web UI — monitoring is log-based.