Tonkatsu Box
Your personal collection manager for games, movies, TV shows, anime, visual novels, manga, books, music and podcasts
---
This app is in active development. Updates may include database migrations that change data format. Please create a backup before updating (Settings → Backup → Create Backup). Alternatively, you can manually copy the app data folder:
- Windows:
%APPDATA%\Roaming\Tonkatsu Box\Tonkatsu Box
- Linux:
~/.local/share/tonkatsu_box (or $XDG_DATA_HOME/tonkatsu_box)
- macOS:
~/Library/Application Support/com.hacan359.tonkatsuBox
- Android: use the built-in backup feature (Settings → Backup)
Tonkatsu Box is a free, open-source app to organize your media collections. Search millions of titles across fifteen catalogs, track your progress episode by episode, rate everything, see your library in numbers, build visual boards, tier lists and mood grids, and bring in what you already track elsewhere.
Search fifteen catalogs
|
|
|
|
|
|
|
IGDB |
TMDB |
TVmaze |
VNDB |
AniList |
Kitsu |
MangaBaka |
MangaDex |
OpenLibrary |
Fantlab |
Google Books |
Hardcover |
ComicVine |
MusicBrainz |
Podcast Index |
|
|
|
|
|
|
Bring your library from
|
|
|
|
|
|
Steam |
IGDB list |
Trakt.tv |
Simkl |
Kinorium |
RetroAch. |
MyAnimeList |
AniList |
Hardcover |
📁
JSON / CSV |
📦
.xcollx |
|
Contents
Languages · Screenshots · Features · Download · Quick Start · Ready-made Collections · Import Your Data · Sync & Backup · Data Sources · Platform Support · Self-Hosting · Building from Source · Contributing
Languages
The whole interface is localized with runtime switching. Pick your language in Settings → App Language, no restart needed.
|
Language |
Status |
| 🇬🇧 |
English |
✅ Complete |
| 🇷🇺 |
Русский (Russian) |
✅ Complete |
| 🇨🇳 |
简体中文 (Simplified Chinese) |
✅ Complete |
| 🇪🇸 |
Español (Spanish) |
✅ Complete |
| 🇧🇷 |
Português (Brazilian Portuguese) |
✅ Complete |
| 🇫🇷 |
Français (French) |
✅ Complete |
Screenshots
| Home |
Collections |
 |
 |
| Search |
Title Preview |
 |
 |
| Item Details |
Filters |
 |
 |
| Episode Tracker |
Tier List |
 |
 |
| Genre Cloud |
Import |
 |
 |
Features
|
|
|
| 📦 |
Collections |
Organize by platform, genre, or any way you like. Grid, list, table and board views, manual drag-and-drop order, bulk actions over a selection |
| 🔍 |
Search |
Fifteen catalogs behind one search field, each with its own filters and an empty-query browse mode. Add a result to several collections at once |
| ✅ |
Progress tracking |
Status, ratings 1-10, start and finish dates, replays, time spent. Reading progress by page for books, chapters for manga, a listened-track checklist for albums |
| 📺 |
Episode tracker |
Season accordion with posters, episode stills, air dates and synopses. Mark an episode, a whole season, or the next unwatched one in a tap. TMDB, TVmaze and Kitsu titles |
| ❤️ |
Likes & notes |
Like and annotate a single episode, season, chapter, volume or page, and filter the list down to what you starred |
| 🏷️ |
Tags |
Global tags with their own manager, grouping and filtering — add or remove them across a whole selection |
| 📊 |
Statistics |
Your library in numbers, for all time or one year: counters, per-type breakdowns, a month-by-month ribbon, platforms, formats, tags, best vs worst, and a shareable summary card |
| ☁️ |
Personalization |
A genre / platform / decade cloud built from your library, and recommendations from what you completed and rated |
| 🔔 |
Releases & calendar |
Follow a show and its upcoming episodes land on a month / week / day calendar, together with any date you add yourself |
| 📝 |
Wishlist |
Dedicated top-level list for what you want to play, watch, or read next — importers park anything they could not match here |
| 🎨 |
Visual boards |
Drag-and-drop canvas with posters, notes, and connections |
| 🏆 |
Tier lists & mood grids |
Rank items into S/A/B/C tiers, or arrange them on a visual N×M board with labels — export either as PNG |
| 📥 |
Import |
Simkl, Steam, IGDB list CSV, Trakt.tv, Kinorium CSV, RetroAchievements, MyAnimeList XML, AniList and Hardcover by username, plus your own cards from JSON / CSV |
| 🎬 |
Kodi sync |
Pull watched status and ratings for your movies from a Kodi media server over JSON-RPC |
| 🎧 |
Discord Rich Presence |
Show what you’re playing/watching/reading in Discord (desktop) |
| 👤 |
Profiles |
Several people on one install — separate collections, boards and covers per profile, with the API keys and app language shared |
| 💾 |
Export & share |
.xcoll / .xcollx files with full offline support, device-to-device sync, one-click backups |
| 🎮 |
Gamepad |
Navigate with Xbox controller (desktop and Android handhelds) |
Download
On Linux the AppImage is the easy route: chmod +x and run (x86_64 only). The .tar.gz is a plain bundle: unpack it anywhere and run tonkatsu_box. Both need GTK 3 from your distribution, plus zenity for the file dialogs and xdg-utils for opening links.
macOS support is experimental. That build has not been tested by the maintainers yet, so expect rough edges. It is also unsigned, so macOS will warn about an unidentified developer on first launch.
On Android you have three options: grab the APK from Releases, install from RuStore, or set up Obtainium for auto-updates (below). RuStore handles updates for you through its own store.
Auto-updates on Android (Obtainium)
Obtainium checks GitHub Releases and installs new APKs for you, so you don’t have to download updates by hand.
- Install Obtainium.
- Tap Add App and paste this into App source URL:
https://github.com/hacan359/tonkatsu_box
- Tap Add.
- The first time it updates, Android asks you to allow installs from Obtainium. Allow it once.
- In the app settings, pick how often Obtainium checks for releases and turn on auto-update, or just refresh manually whenever you want.
When a new release ships, Obtainium downloads the APK and shows the system install dialog to confirm. Silent background installs are not possible on Android without root.
Quick Start
- Download and install from the links above
- Launch the app — Welcome Wizard guides you through setup
- Start adding items from Search, or import ready-made collections
The app works offline after setup. API keys are built-in.
Full guide on Wiki
Ready-made Collections
Tonkatsu Collections — 25,000+ games across 23 platforms, top movies, TV shows & anime. Download .xcollx → Import → Done.
Import Your Data
Already tracking elsewhere? Bring your data:
|
Source |
What’s imported |
|
Steam |
Owned games, playtime, last played date |
|
IGDB |
A game list exported as CSV — matched by IGDB id, with a status you pick for the list |
|
Trakt.tv |
Watch history, ratings, watchlist, episode progress |
|
Simkl |
Movies, TV shows and anime from one account, signed in with a short code — statuses, ratings, notes and the episode watch history with its original dates |
|
Kinorium |
Movies, TV & animation from a CSV export — ratings and watch dates |
|
RetroAchievements |
Retro game library, achievement progress, awards |
|
MyAnimeList |
Anime and manga lists with scores, status and progress from an XML export |
|
AniList |
Anime and manga directly by a public username — no API key required |
|
Hardcover |
Book library by username — statuses, ratings, dates and re-reads |
| 📁 |
Your own cards |
A JSON or CSV file of custom entries — titles, types, covers, notes, tags and personal fields; with the source lookup on, rows that match one catalog record become real cards. File format and lookup rules |
| 📦 |
.xcollx files |
Collections shared by others |
Import guides on Wiki
Sync & Backup
Everything lives on your device. Nothing here needs an account or a cloud.
|
What |
Where |
| 🔄 |
Device-to-device sync — copy the whole database to another device over your home network |
Settings → Database → Device-to-device sync |
| 💾 |
Backup & restore — one archive with collections, tags, boards, tier lists, mood grids, wishlist, watch progress, calendar and settings |
Settings → Backup |
| 📁 |
Custom data folder — keep the database on an SD card or any folder you pick |
Settings → Database → Storage location |
 |
Kodi sync — pull watched status and ratings for your movies from a Kodi media server |
Settings → Kodi |
 |
Discord Rich Presence — show what you’re playing, watching or reading |
Settings → Discord |
Details on the Wiki
Device-to-Device Sync
Move your whole collection from one device to another over your home network. No cloud, no account: the two devices talk to each other directly.
How it works:
- Open Settings → Database → Device-to-device sync on both devices. While the screen is open, each device announces itself on the local network and finds the other one.
- On the device that should receive the data, tap the other device in the list.
- Confirm on both sides: the receiving device shows what it is about to download (device name, date, collection and item counts), and the sending device asks you to allow the transfer.
- The full database is copied over and replaces everything on the receiving device. Restart the app when asked.
This is a full replace, not a merge. Changes made on the receiving device that the sender doesn’t have are gone after the transfer.
Before replacing anything, the app keeps the previous database as a backup. Settings → Database → Backup → Restore swaps the current database with that backup, and restoring again swaps them back.
This feature can destroy data. Read this before using it.
- Receiving a snapshot overwrites your entire local database. Anything you added on this device and nowhere else is lost.
- There is only one backup slot. Receiving a second snapshot overwrites the backup made before the first one — after that, the original data is gone for good.
- The transfer is not encrypted and there is no pairing between devices. Use it only on a network you trust (your home Wi-Fi), never on public or shared networks.
- If the app is killed or the device loses power in the middle of a transfer or restore, the database can end up corrupted. Keep a regular backup (Settings → Backup) before syncing.
Custom Data Folder
By default the database lives in the app’s private folder. Settings → Database → Storage location lets you move it to any folder you pick — for example an SD card or a folder synced by a cloud client.
When you pick an empty folder, the app copies your current data there. When you pick a folder that already holds Tonkatsu Box data, the app switches to that data instead. Either way a restart is required. If the custom folder is missing on startup (unplugged drive, dead network share), the app falls back to the default location instead of failing — Settings shows a warning when that happens.
- Pointing two devices or a cloud client at the same live folder is not supported and can corrupt the database. Sync clients copy files while they are being written; SQLite does not survive that.
- When the custom folder is unavailable, the app silently runs on the default (possibly empty) data. Your collection is not lost — plug the drive back in and restart — but anything you add meanwhile lands in the default folder, not the custom one.
- On Android this feature needs the “All files access” permission, which the app requests only when you actually pick a folder.
Data Sources
API Keys Setup
| Feature |
Windows |
Linux |
macOS |
Android |
| Collections & search |
✅ |
✅ |
✅ |
✅ |
| Progress & episode tracker |
✅ |
✅ |
✅ |
✅ |
| Statistics & personalization |
✅ |
✅ |
✅ |
✅ |
| Visual boards |
✅ |
✅ |
✅ |
✅ |
| Tier lists & mood grids |
✅ |
✅ |
✅ |
✅ |
| Imports (Simkl / Steam / Trakt / RA / …) |
✅ |
✅ |
✅ |
✅ |
| Device-to-device sync & backups |
✅ |
✅ |
✅ |
✅ |
| Kodi sync |
✅ |
✅ |
✅ |
✅ |
| VGMaps browser |
✅ |
— |
— |
— |
| Gamepad |
✅ |
✅ |
✅ |
✅ |
| Discord Rich Presence |
✅ |
✅ |
✅ |
— |
Self-Hosting (Web)
Run Tonkatsu Box as a web app on your own machine or home server. One Docker
container serves the app in the browser and keeps the database on the server,
so every device on your network works with the same library.
Requirements
- Docker with Docker Compose
Install and run
git clone https://github.com/hacan359/tonkatsu_box.git
cd tonkatsu_box
docker compose up -d --build
The first build takes several minutes (it compiles the web app inside Docker —
no Flutter needed on your machine). Then open:
http://<server-ip>:8080
Configuration (optional)
Copy .env.example to .env next to docker-compose.yml and uncomment what
you need. Without a .env everything uses defaults.
| Variable |
Default |
What it does |
TONKATSU_DATA_PATH |
./data |
Host folder with all server data |
TONKATSU_PORT |
8080 |
Port the web UI answers on |
PUID / PGID |
1000 / 1000 |
Owner of the files in the data folder |
TONKATSU_KEY_* |
— |
API keys (e.g. TONKATSU_KEY_TMDB) |
TONKATSU_AUTH |
off |
token makes the web UI ask for an access token |
TONKATSU_AUTH_TOKEN |
generated |
Your own token instead of the generated one |
TONKATSU_BIND |
0.0.0.0 |
Host interface the port is published on |
TONKATSU_IMAGE_HOSTS |
any |
Hosts covers may be fetched from, comma-separated |
API keys can also be entered in the app itself (Settings → API Keys) —
they are stored on the server in data/keys.json. Keys set via .env
override keys.json.
Access token (optional)
By default the server has no login: anyone who can reach the port can use the
library. For a server that other devices can reach, set TONKATSU_AUTH=token
in .env. The server then prints a sign-in link on every start:
docker compose logs tonkatsu | grep "Sign in"
# Sign in: http://localhost:8080/?token=…
Open that link with the server’s address instead of localhost: the browser
stores the token and removes it from the address bar. A browser without the
token is shown a screen to paste it into, and Settings → API Keys lets you
change it later. The token is kept in data/auth_token; delete the file and
restart to issue a new one, or set your own with TONKATSU_AUTH_TOKEN.
TONKATSU_BIND=127.0.0.1 publishes the port on this machine only.
TONKATSU_IMAGE_HOSTS limits which hosts the server fetches covers from, as a
comma-separated list of domains (subdomains included). Leave it empty unless
you need it: a cover host missing from the list shows as a broken image.
Files
| Path |
What |
.env |
Your local configuration (not committed) |
data/tonkatsu_box.db |
The database |
data/keys.json |
API keys entered in the app |
data/auth_token |
The access token, when TONKATSU_AUTH=token |
data/images/ |
Cover cache |
data/snapshots/ |
Automatic DB snapshots taken before migrations |
Backup
Copy the data/ folder while the container is stopped — that is the whole
backup. There is also Settings → Backup in the web UI, which downloads a
portable archive to whatever device you are browsing from.
Update
git pull
docker compose up -d --build
Pending database migrations run on start; a snapshot of the old database is
saved to data/snapshots/ first.
HTTPS and a custom domain (optional)
Caddy in front gives https://tonkatsu.box, HTTP/2 and PWA install support:
# .env: TONKATSU_DOMAIN=tonkatsu.box (default), keep TONKATSU_PORT at 8080
docker compose -f docker-compose.yml -f docker-compose.caddy.yml up -d
- Point the domain at the server: an entry in the router’s DNS, or in
hosts (<server-ip> tonkatsu.box) on each device.
- Trust Caddy’s local root certificate once per device — the file is
data/caddy/caddy/pki/authorities/local/root.crt (on Windows:
double-click → Install Certificate → Trusted Root Certification
Authorities).
Plain HTTP keeps working without any of this — Caddy is an add-on, not a
requirement.
Notes
- The web build has no accounts;
TONKATSU_AUTH=token makes it ask for a
single access token. Keep it on your LAN or behind HTTPS.
- Desktop-only features (VGMaps, Discord Rich Presence, Kodi, gamepad, LAN
sync) are hidden in the browser.
Documentation
Building from Source
git clone https://github.com/hacan359/tonkatsu_box.git
cd tonkatsu_box
flutter pub get
flutter run -d windows # or linux / macos / android
Requires Flutter 3.38+ / Dart 3.10+. See CONTRIBUTING.md for details.
Contributing
Contributions welcome! See CONTRIBUTING.md for build instructions, code style, and PR guidelines.
Credits
Catalogs: IGDB · TMDB · TVmaze · VNDB · AniList · MangaBaka · MangaDex · Kitsu · OpenLibrary · Fantlab · Google Books · Hardcover · ComicVine · MusicBrainz · Cover Art Archive · ListenBrainz · Podcast Index
Imports and extras: Simkl · Trakt.tv · Steam · Kinorium · MyAnimeList · RetroAchievements · SteamGridDB · ScreenScraper · Kodi
This product uses the TMDB API but is not endorsed or certified by TMDB.
License
MIT
评论