SyncYomi: a self-hosted sync server for TachiyomiSY and Komikku libraries

The problem: reading progress that never leaves one phone

Manga readers built on the Tachiyomi codebase keep their library, read chapters and reading position in local app storage. Install the app on a tablet and a phone and you have two independent libraries. The usual workaround is the manual backup file: create a backup on one device, move it to the other, restore it, and repeat whenever the two drift apart. That is fine for a one-time migration and poor for daily use.

SyncYomi exists to replace the file shuffle with a server. You run it yourself, point each client at it, and the clients push and pull library state over the network. The intended user is someone who already self-hosts something (a NAS, a small VPS, a home server) and reads on more than one device. It is not aimed at people who want a hosted account, and it is not a source of manga. It stores what your client tells it.

The README is explicit that this targets TachiyomiSY and Komikku, and adds a blunt parenthetical about Mihon: the client is not implemented, probably never will be. That sentence should decide the question for a lot of readers before they read any further.

What the repository shows about the architecture

The stack is Go on the server and Vue in the browser, and the project describes itself as lightweight and portable across Linux, FreeBSD, Windows and macOS on x86 and ARM. Two database engines are supported, PostgreSQL and SQLite, so a single-user instance can live in one file while a busier one can point at a Postgres server.

The README points to a docs/ directory for architecture, API reference, operations and development notes, which suggests the maintainers keep design material out of the top-level README rather than duplicating it. The repository layout also shows a default branch named develop, with releases cut from it: v1.5.2, v1.5.3 and v1.5.4 all landed within about a week of each other in September 2026. That cadence tells you patches arrive quickly and that you should expect to update.

The operational surface is modest and visible in the compose example: a single container, a /config volume, port 8282, and a TZ environment variable. Notifications are supported through Discord, Telegram, ntfy and Notifiarr, and the server supports a base path or subfolder for reverse proxies. There is a web UI for administration, described as mobile-optimized, which is where you create API keys.

Getting a container running on port 8282

The README's compose file is short enough to quote in full. It declares one service using the image ghcr.io/syncyomi/syncyomi:latest, restarts unless stopped, passes TZ from the environment, mounts ${BASE_DOCKER_DATA_PATH}/syncyomi/config at /config, and maps 8282:8282. The accompanying notes tell you to change BASE_DOCKER_DATA_PATH to match your setup (./data is offered as sufficient) and to change the host port mapping if 8282 collides with something else. For podman users there is a specific note: you may need to update the host address to 0.0.0.0.

Start it with docker compose up -d. On the first run the service generates files in the running directory, including config.toml. Two settings in that file matter immediately. The default listen address is 127.0.0.1, and the README recommends putting a reverse proxy such as caddy, nginx or traefik in front. If you are not using a proxy and connect by IP instead, you must change host to 0.0.0.0, otherwise the server will not accept connections from other machines.

For a subfolder deployment the baseUrl value has to be updated and the proxy has to strip that suffix. The README gives an nginx example: a location /syncyomi/ block that proxies to http://127.0.0.1:8282, sets proxy_http_version 1.1 and X-Forwarded-Host, and rewrites ^/syncyomi/(.*) to /$1. Restart the service after editing the config. There is also a systemd path for non-container installs, using a templated unit at /etc/systemd/system/syncyomi@.service with ExecStart=/usr/bin/syncyomi --config=/home/%i/.config/syncyomi/, enabled with systemctl enable -q --now --user syncyomi@$USER.

One API key is one user, and that is the whole account model

SyncYomi has no conventional login for clients. You open the web UI at http://<your-server-address>:8282, go to Settings > API Keys, and create a key. The client then takes a host and that key, entered by hand or scanned from a QR code, under More > Data and Storage where the sync option is switched from Off to SyncYomi.

The README states the consequence plainly: treat each API key as a unique user, and use the same key on every device you want synchronized. Two keys means two separate libraries on one server. This is simple and it is also the design's sharpest edge. There is no per-device identity, no way to revoke one device without revoking the account, and no separation between two people sharing a server except by issuing them different keys. If you want your partner's library and yours to stay apart, keys are the only boundary, and if you want to know which device wrote what, the model does not appear to record it.

Before touching any of this, the README tells you to make a manual backup in the client under More > Data and storage, then Create backup. That step is not optional advice; it is the recovery path if a first sync goes the wrong way.

Where SyncYomi is the wrong tool

The clearest case is Mihon. The README says the client is not implemented and probably never will be, so anyone on stock Mihon should stop here. The supported clients named in the material are TachiyomiSY and Komikku, and the setup instructions assume one of those two.

A second case is the single-device reader. If you read on one phone, SyncYomi adds a server, a container, a config file, a reverse proxy decision and an upgrade treadmill to solve a problem you do not have. The manual backup file is adequate.

Third, there is a security posture question the README does not answer. The server defaults to 127.0.0.1 and the project recommends a reverse proxy, but the material does not describe TLS termination, rate limiting or what happens to an exposed instance. The README does say to keep the API key secure and consistent, which is the extent of the guidance given. If you set host to 0.0.0.0 on a network you do not control, you are making that call yourself. I cannot confirm from the supplied material whether the server enforces any transport security on its own, and the README does not claim it does.

Finally, the release history shows three patch releases inside a week. Fast patching is good; it also means a self-hosted instance that is never updated will fall behind quickly, and the project offers no described auto-update mechanism beyond restarting the container.

The alternative: a sync server you do not run

The obvious comparison is a hosted sync service for the same client ecosystem, where the trade is reversed. With a hosted option you do not run a container, do not edit config.toml, do not choose between SQLite and PostgreSQL, and do not think about reverse proxy paths. In exchange, your library and reading history sit on someone else's infrastructure, the service's uptime and pricing are outside your control, and the project can change terms or shut down.

SyncYomi inverts each of those. You own the data and the database file, you decide who can reach port 8282, and no third party sees your library. You also own the backups, the upgrades and the proxy configuration. The choice is not about features; both approaches move reading state between devices. It is about whether you want to be the operator.

A narrower alternative is doing nothing and continuing with manual backup files. That is not a joke option for a two-device household that syncs once a month. It costs nothing, requires no server, and cannot break because a container did not restart. SyncYomi earns its place when the sync happens often enough that the manual step becomes friction.

Licence, maintenance and what running it actually costs

SyncYomi is licensed under GPL-2.0. If you run it for yourself, the practical effect is that you can use, modify and redistribute it under the same terms. If you plan to modify it and ship the result, or to embed it in a product, the copyleft obligations apply to the distributed work, and that is a question for a lawyer rather than for this article. Nothing in the README suggests a separate commercial licence.

Maintenance cost is mostly version drift. The container image is tagged latest in the compose example, which means a restart can pull a different build than the one you tested. Pinning a specific release tag instead of latest is the standard way to avoid that, and the releases page lists concrete versions to pin to. Configuration lives in config.toml under the /config volume, so that file is the thing to back up alongside your database.

If you choose PostgreSQL rather than SQLite, you take on a second service to run and back up, and you need to confirm how SyncYomi is pointed at it, which the supplied README does not show. The docs/ directory is where that detail is said to live. Read it before you decide which engine to use, because switching later means migrating data.

Editorial conclusion

Adopt SyncYomi if you already run a reverse proxy and want your TachiyomiSY or Komikku reading progress on a server you control. Skip it if you read in stock Mihon, since the README states that client is not implemented and probably never will be. Before committing, verify three things: that your client is TachiyomiSY or Komikku and not plain Mihon, that every device you want synced is configured with the same API key, and that config.toml has host set to 0.0.0.0 if you connect by direct IP rather than through a proxy.

Official sources

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