Tonkatsu Box tracks fifteen catalogs and your own play progress

One app for a shelf of mixed media

Tonkatsu Box is described as a personal collection manager for games, movies, TV shows, anime, visual novels, manga, books, music and podcasts, and the scope is broader than the usual retro game backlog tracker. The README frames the workflow as searching millions of titles across fifteen catalogs, tracking progress episode by episode, rating everything, seeing the library in numbers, building visual boards, tier lists and mood grids, and importing what you already track elsewhere. The visual side is where it differs from a spreadsheet approach, because tier lists and mood grids are the kind of thing people make in an image editor and then lose, and here they are attached to the collection itself. The interface is fully localized with runtime switching, with the language picked in Settings, App Language and no restart required, and the language table lists English, Russian, Simplified Chinese, Spanish, Brazilian Portuguese and French as complete. The build badge asks for Flutter 3.38 or newer, and the application ships for Windows, Linux, macOS and Android, with a RuStore listing for the Android build.

Fifteen catalogs, each with its own key

The catalog list is the most concrete part of the feature set, and it is worth reading as a compatibility statement rather than a feature count. The supported search sources are IGDB, TMDB, TVmaze, VNDB, AniList, Kitsu, MangaBaka, MangaDex, OpenLibrary, Fantlab, Google Books, Hardcover, ComicVine, MusicBrainz and Podcast Index. The mix explains the scope, since games, film and television come from the general media databases, anime from the anime trackers, books from the book catalogues, and music and podcasts from their own indexes. Each of these is a separate service with its own API, and the self-hosting configuration shows the cost of that in practice. The .env example lists a separate key variable for each one, including TMDB, TVDB, the IGDB client id and secret, SteamGridDB, ComicVine, Google Books, Hardcover, the RetroAchievements username and key, the Simkl client id, and four SteamShorts values. Every one of those lines is optional, and an unset key means that catalog is unavailable rather than broken.

Importing the library you already have

The import list is what makes this practical for anyone who already tracks their backlog somewhere else. The sources are Steam, an IGDB list, Trakt.tv, Simkl, Kinorium, RetroAchievements, MyAnimeList, AniList, Hardcover, plus JSON and CSV files and the .xcollx format. The two file formats are the escape hatch that matters most, because they work with any catalog the app does not support and with a list you maintain yourself. The project also ships ready-made collections according to the table of contents, so a new user can start from a curated set rather than from an empty shelf. The design assumption throughout is that your collection is the source of truth and the external services are lookups. You search a catalog to find a title, attach it to your shelf, and then the progress you record belongs to you rather than to the service.

Self-hosting the server with Docker

The project ships a server component and a web build, and the compose file wires them together. The service is built from the repository itself and published under a local image name, with the host port configurable.

    ports:
      - "${TONKATSU_PORT:-8080}:8080"
    volumes:
      # Database, covers cache, snapshots and keys.json — back up by copying
      # this one folder. Configure the host side in .env (see .env.example).
      - ${TONKATSU_DATA_PATH:-./data}:/data

Everything the server keeps, the database, the covers cache, snapshots and keys.json, lives under that single mounted folder, so a backup is a copy of one directory. The compose file also passes the API keys from .env into the container, and a comment there explains the precedence, that an empty value reads as absent and a set one overrides the same key in keys.json. There is a second compose file, docker-compose.caddy.yml, and a Caddyfile in the repository root, which is how the project puts a reverse proxy in front of the web interface. The Dockerfile shows how the two halves are assembled. The web side is a Flutter web build on the cirruslabs Flutter image, and the server side is a Dart CLI compiled on a dart image, with clang installed because the sqlite3 package builds its native library through a build hook, and the final runtime image carries only TLS roots because the bundle ships its own libsqlite3.

The environment file is the whole configuration surface

The .env example is short and every line is optional, with the defaults in parentheses. The host data path defaults to ./data, the web UI port to 8080, and PUID and PGID to 1000, which set the owner of the files in the data folder so a container running as a different user can still write to it. The rest of the file is the API key list, and the comment says the same names override the values in keys.json, which means you can keep keys in the mounted data folder and override them at the container level without editing files. The compose file is where this becomes visible, with a restart policy of unless-stopped and the key variables passed through with empty defaults, so the same compose file runs whether or not you have any keys at all. The two files together, .env for the host and keys.json inside the data folder, are the difference between a configuration you can change without touching the container definition and one you cannot.

Backups matter because updates can migrate the data

The warning at the top of the README is the most operationally important paragraph in the project. The app is in active development, updates may include database migrations that change the data format, and you should create a backup before updating through Settings, Backup, Create Backup. If you would rather copy the files yourself, the documentation lists where the app data folder lives on each platform: on Windows it is under the Roaming folder in the app data, on Linux it is in the local share directory or under XDG_DATA_HOME, on macOS it is in the Library Application Support directory for the app's bundle identifier, and on Android the built-in backup feature is the route. The warning is not a sign of a broken product, it is a sign of a young one, and the cost of respecting it is a directory copy. The release names follow the same convention, with v0.45.0 Midnight Shinigami, v0.44.0 dated with a Japanese phrase and v0.43.0 Tonkatsu Box, so the version string carries a subtitle that changes with the release.

Where Tonkatsu Box is the wrong choice

Three limits. The first is that the self-hosted mode is a second thing to run, with a database, a web build and a reverse proxy in front of it, and the docker-compose.yml is convenient but it is still a service with keys to configure and a data folder to back up. If you want something that opens and works with no setup, the desktop applications are the path, and the app store and release downloads cover Windows, Linux, macOS and Android. The second is the catalog dependency, and it cuts both ways. Fifteen searchable sources is a lot of coverage, but every one is a third-party API you may need a key for, and the data you see is whatever that service returns, so a missing key means a missing catalog rather than a degraded one. The third is the maturity, which the project states plainly. The app is in active development, the version numbers are still in the 0.4x range, and the licence is MIT with the LICENSE file in the repository root, so the code is free to use but the data format is not yet frozen. That is a reasonable trade for a personal collection manager and a poor one for a shared database that other people depend on.

Editorial conclusion

Adopt Tonkatsu Box if you want one local app for the games, shows and books you have finished or are working through, and you are willing to plug API keys into the catalogs you use, since each one is configured separately. Skip it if you want a server you do not have to run, because the self-hosted mode is a second process on your machine, and skip it if your data must be stable across upgrades, since the project warns that updates may include database migrations that change the data format. Before you update an existing install, take a backup through Settings, Backup, Create Backup, and note the platform specific data folder paths the documentation lists if you prefer to copy the files yourself.

Frequently asked questions

Official sources

1. hacan359/tonkatsu_box on GitHub
2. License: MIT
3. Project website
4. README
5. Releases