SyncYomi: Self-Hosted Sync for TachiyomiSY and Komikku Reading Progress

The gap SyncYomi fills between TachiyomiSY installs

Manga readers built on the Tachiyomi lineage keep their library, read state and categories in local storage on each device. That model breaks down the moment you read on a phone during a commute and open a tablet at home: the second device has no idea what the first one finished. SyncYomi exists to close that gap. It is a server you host yourself, and it stores the library state that TachiyomiSY and Komikku clients push to it.

The audience is narrow and specific. You need a reader that still exposes a Sync option pointing at SyncYomi, which according to the README means TachiyomiSY or Komikku. You need somewhere to run a small service, and you need to be comfortable editing a config.toml or a compose file. Anyone who wants sync without running infrastructure is not the target user; the project's whole premise is that the server belongs to you.

How the sync server is put together

The repository is a Go backend under internal/ and pkg/ with a Vue frontend in web/, built into a single binary. The Dockerfile shows the shape of that build: a Node stage runs pnpm install --frozen-lockfile and pnpm run build, then a Go stage cross-compiles main.go with CGO disabled and copies the web build output into web/dist before linking. The final image is Alpine with the binary at /usr/local/bin/syncyomi and an entrypoint of /usr/local/bin/syncyomi --config /config.

On the server side, go.mod lists go-chi for routing, zerolog for logging, viper for configuration, squirrel for SQL query building, and both lib/pq and modernc.org/sqlite, which matches the README's claim of PostgreSQL and SQLite support. There is a proto/ directory and a Makefile target that runs protoc against proto/syncyomi/backup/v1/backup.proto, so backup data has a protobuf definition rather than an ad hoc JSON shape. Notifications go out through Discord, Telegram, ntfy and Notifiarr according to the feature list.

The client side is deliberately thin. The app talks to the server with a host URL and an API key, and the README is explicit that an API key is a user identity: use the same key on every device you want synchronized, because different keys are treated as different users with separate data.

Installing SyncYomi with Docker and generating the first API key

The fastest path is the compose file from the README. It maps host port 8282 to the same container port and mounts a config volume, which is where the service writes its generated files on first run.

services:
  syncyomi:
    container_name: syncyomi
    image: ghcr.io/syncyomi/syncyomi:latest
    restart: unless-stopped
    environment:
      - TZ=${TZ}
    volumes:
      - ${BASE_DOCKER_DATA_PATH}/syncyomi/config:/config
    ports:
      - 8282:8282

Start it with `docker compose up -d`, then open `http://<your-server-address>:8282` in a browser. The README says the first run generates several files in the running directory, among them config.toml. In the web UI, go to Settings > API Keys and create a key.

The repository also ships a fuller compose file that adds a postgres:15.1-alpine service alongside the app, with the database on host port 5434. Note the comment in that file: Postgres 15 and later require a dedicated database owned by the application user so the app can create its tables.

  postgres:
    image: postgres:15.1-alpine
    environment:
      - POSTGRES_USER=SyncYomi
      - POSTGRES_PASSWORD=SyncYomi
      - POSTGRES_DB=syncyomi
    ports:
      - '5434:5432'

If you skip Docker, the README points at the releases page for a binary, and the Makefile shows `make build` producing bin/syncyomi from source. On Linux the README recommends a systemd unit, and gives this service template, where the ExecStart line passes the config directory explicitly.

[Unit]
Description=SyncYomi service for %i
After=syslog.target network-online.target

[Service]
Type=simple
User=%i
Group=%i
ExecStart=/usr/bin/syncyomi --config=/home/%i/.config/syncyomi/

[Install]
WantedBy=multi-user.target

On the client, install TachiyomiSY or Komikku, open More > Data and Storage, and change the Sync option from Off to SyncYomi. Enter the host URL, either a LAN address like `http://192.168.1.202:8282` or a domain behind TLS, plus the API key you generated, pasted or scanned from the QR code.

The 0.0.0.0 setting that trips up direct-IP setups

SyncYomi binds to 127.0.0.1 by default. That is the right default for a service meant to sit behind a reverse proxy, and the README recommends caddy, nginx or traefik rather than exposing the port directly. But it produces a confusing first-run failure for anyone connecting a phone over the LAN: the server is up, the web UI works from the host, and the client cannot reach it.

The README addresses this twice. If you connect by direct IP, set host in config.toml to 0.0.0.0 so the service accepts connections on any interface. If you are not running a reverse proxy at all, the same change applies. There is no authentication layer described in front of the API beyond the key itself, so putting the service on a public interface without a proxy is a decision to make deliberately.

Subdirectory hosting has its own requirement. If your proxy serves SyncYomi under a path, update baseUrl in the configuration and rewrite the prefix so the backend sees clean paths. The README's nginx example does exactly that:

location /syncyomi/ {
    proxy_pass              http://127.0.0.1:8282;
    proxy_http_version      1.1;
    proxy_set_header        X-Forwarded-Host        $http_host;

    rewrite ^/syncyomi/(.*) /$1 break;
}

Mihon is not supported, and the README says so plainly

The single most important limitation is stated in the project description rather than buried: Mihon is not implemented, and the description adds that it probably never will be. Anyone arriving from Mihon and expecting SyncYomi to work has the wrong client. The README's install path names TachiyomiSY and Komikku, and those are the clients to use.

A second constraint is the API key model. Because a key is a user, rotating a key or generating a fresh one for a new device silently splits your library into separate accounts. The README warns about this directly, and it is an easy mistake to make when you are adding a device months after the initial setup.

The backup story is also worth reading carefully. The README instructs you to create a manual backup in the app before installing anything, which is a sensible migration step, and the repository has a protobuf schema for backup data, but the README does not document restoring a backup into SyncYomi or rolling back a bad sync. If your library state matters, treat the pre-install backup as the recovery path and test it before you rely on the server.

SyncYomi against Google Drive sync

The obvious alternative for people already in this ecosystem is syncing the reader's backup through a cloud drive, which is what Tachiyomi clients have long supported. The difference is in what moves. A drive-based flow copies whole backup files, so you get whatever state the last writer produced, and conflict resolution is whatever the drive client does with two versions of a file.

SyncYomi changes the unit of transfer. The client talks to a server over HTTP with an API key, and the server owns the canonical state, which is why the README can promise that using one key across devices keeps them together. That is a real architectural difference, not a packaging one: it requires a running service, a database and a reachable address, and in exchange you get per-user state on hardware you control instead of a file in someone else's storage. The cost is operational. A drive sync has no port to expose, no config.toml to edit and no service to restart.

Maintenance, licensing and what the GPL-2.0 means here

The repository is not archived, and the last push was on 2026-09-10, the same day as the v1.5.4 release. Releases v1.5.2, v1.5.3 and v1.5.4 all landed within the week before that, so the project is being changed at a steady clip right now. That also means upgrade cost is real: the default branch is develop, the Makefile has a proto-check target that regenerates protobuf code and fails on a diff, and release-please configuration sits in the repository root, all of which point at a project that expects its own generated artifacts to stay in step with source.

For self-hosters the practical upgrade path is the container image. Pulling a new tag and restarting is cheap, but schema changes between versions are not documented in the README, so a database backup before an upgrade is the safe habit. SyncYomi is licensed GPL-2.0. If you run it for yourself, that is unremarkable. If you intend to redistribute a modified build or bundle it into something you ship, the copyleft terms apply to the derived work, and that is a question for a lawyer rather than for this article.

Editorial conclusion

Adopt SyncYomi if you run TachiyomiSY or Komikku on more than one device and want the library state on hardware you control. Do not adopt it if your reader is Mihon, since the README says that client is not implemented and probably never will be. Before trusting it with your library, create a manual backup in More > Data and storage, then verify that all your devices share one API key and that config.toml binds to the address your clients actually reach.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. README
4. Releases
5. syncyomi/syncyomi on GitHub