Tonkatsu Box

Your personal collection manager for games, movies, TV shows, anime, visual novels, manga, books, music and podcasts

[!WARNING] 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.

Screenshots

Home	Collections

Search	Title Preview

Item Details	Filters

Episode Tracker	Tier List

Genre Cloud	Import

Features

Download

Linux and macOS support is experimental. The macOS 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.

1. Install Obtainium.
2. Tap Add App and paste this into App source URL:

   https://github.com/hacan359/tonkatsu_box
   

3. Tap Add.
4. The first time it updates, Android asks you to allow installs from Obtainium. Allow it once.
5. 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

1. Download and install from the links above
2. Launch the app — Welcome Wizard guides you through setup
3. 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
📦	.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:

1. 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.
2. On the device that should receive the data, tap the other device in the list.
3. 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.
4. 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.

[!CAUTION] 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.

[!CAUTION]

• 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

	Type	Source	API Key
	Games	IGDB	Built-in
	Movies & TV	TMDB	Built-in
	TV Shows	TVmaze	Not required
	Visual Novels	VNDB	Not required
	Anime & Manga	AniList	Not required
	Manga	MangaBaka	Not required
	Manga	MangaDex	Not required
	Anime & Manga	Kitsu	Not required
	Books	OpenLibrary	Not required
	Books	Fantlab	Not required
	Books	Google Books	Optional (free key)
	Books	Hardcover	Required (free token)
	Comics	ComicVine	Required (free key)
	Music	MusicBrainz	Not required
	Podcasts	Podcast Index	Built-in
	Artwork	SteamGridDB	Built-in
	Retro media gallery	ScreenScraper	Required (user account)
	Achievements	RetroAchievements	Required

API Keys Setup

Platform Support

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.

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.

Files

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

1. Point the domain at the server: an entry in the router's DNS, or in hosts ( tonkatsu.box) on each device.
2. 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 or passwords — expose it to your LAN only.
• Desktop-only features (VGMaps, Discord Rich Presence, Kodi, gamepad, LAN sync) are hidden in the browser.

Documentation

• Wiki — user guides & FAQ
• Changelog — version history

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.

Community

• Discord — chat & support
• Issues — bug reports

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