Koito: a ListenBrainz-compatible scrobbler for people who want their own instance
Koito is a modern, themeable scrobbler that you can use with any program that scrobbles to a custom ListenBrainz URL
At a glance
- What is it?
- Koito is a self-hosted scrobbler written in Go that accepts anything pointing at a custom ListenBrainz URL and can relay those scrobbles onward. It is MIT-licensed, still labelled unstable by its author, and aimed at self-hosters who want to own the listening data rather than hand it to a hosted service.
- Who is it for?
- Adopt Koito if you already run Docker and want a ListenBrainz-compatible endpoint you control, and start with the relay so your existing scrobbler keeps receiving plays. Do not adopt it if you need a stable API surface for other tools to depend on, since the README states the main branch can be unusable and breaking changes may occur.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 55 days ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem Koito addresses: scrobblers that hold your data
Most scrobbling setups end at a hosted service. Your player sends a play event to someone else's endpoint, that service stores it, and you get back whatever charts and statistics it chooses to render. Koito inverts that arrangement. It presents itself as a ListenBrainz-compatible target, so any client that lets you set a custom ListenBrainz URL can point at your own server instead. The listening history then lives in your infrastructure, and the web UI you browse is one you host. The README frames the audience directly: self-hosters who want control over their data and insights into their listening habits. There is a secondary motivation stated in the notes, where the author says roughly half the reason for building Koito was accumulated grievances with Maloja, and that contributing upstream was considered but rejected in favour of building a separate tool with a UI the author prefers. That origin matters when reading the feature list, because the project is shaped by one person's opinions about how a scrobbler should look and behave rather than by a committee. The topics attached to the repository (docker, listenbrainz, navidrome, subsonic, scrobble, self-hosted) tell you what ecosystem it expects to sit inside: people running Navidrome or another Subsonic-compatible server who want plays recorded somewhere they control.
How the relay model changes the adoption decision
The single design choice that separates Koito from a straight replacement is relaying. Koito can forward scrobbles it receives to another ListenBrainz-compatible scrobbler, which means you can run it alongside your current setup rather than migrating in one step. The README describes this as the recommended path while the project is unstable, and the author states he has been using a relay from Koito to another scrobbler for the entire development of the app and that it has not failed him once. That is a personal account, not a benchmark, but it explains the intended workflow: your player points at Koito, Koito records the play and passes it on, and your existing service keeps its history intact. If Koito breaks or you decide against it, you remove it from the chain and nothing downstream notices. Set up a relay is documented at koito.io/guides/scrobbler, and the README also names multi-scrobbler as an alternative if you would rather not use Koito's relay at all. The relay also means the compatibility claim is doing real work. The project does not need a plugin per player; it needs to behave enough like ListenBrainz that clients accept it as a target. That is a narrower compatibility surface than supporting each player's native protocol, and it is why the feature list can say it is compatible with anything that scrobbles to ListenBrainz in a single line.
Getting a Koito instance running with Docker Compose
The README gives a minimal compose file rather than a long installation narrative. The service is named koito, the image is gabehf/koito:latest, the container is named koito, port 4110 is published on the host, the host directory ./koito is mounted at /etc/koito, and the restart policy is unless-stopped. Those five lines are the whole quick start. The mount point is worth pausing on: configuration lives under /etc/koito inside the container, so ./koito on the host is where you will place configuration and where any state tied to that path will persist. The README does not spell out in the excerpt which files belong there, and it points to the configuration reference at koito.io/reference/configuration for the full list of options. If you want to know what keys exist, that page is the source, not the repository README. The installation guide at koito.io/guides/installation is the longer path if the compose snippet is not enough for your environment. Two things the README does make explicit: image sources are configurable, and you are advised to set up the image sources you want before importing data, because the importing guide at koito.io/guides/importing assumes that ordering. That is a real sequencing constraint. If you import first and configure artwork sources afterwards, you are choosing to redo work.
Import paths and the instability warning
Koito lists import support for Maloja, ListenBrainz, Last.fm, and Spotify. For anyone leaving a hosted scrobbler, that list covers the common histories: a Last.fm account, a ListenBrainz account, a Spotify listening record, or a self-hosted Maloja instance. The importing guide is separate from the configuration reference, which suggests the import process has its own steps rather than being a single toggle. The README does not describe the import format, how duplicates are handled, or whether imports are resumable, and I cannot confirm any of that from the material here. What the README does state plainly is the stability posture: the project is under active development and still considered unstable, the main branch can be unusable at times, and some breaking changes may occur. That warning is unusual in how direct it is, and it should be read literally. If you pull from main rather than a tagged image, you are opting into a branch the author describes as sometimes unusable. The release history supports the active-development claim: v0.3.0 and v0.3.1 landed on the same day in late May 2026, with v0.3.2 following in early June. Two releases in one day is the signature of a project still settling its interfaces, not one in maintenance mode.
Where Koito is the wrong tool
The instability warning is not boilerplate, and it defines the cases where Koito is a poor fit. If other software depends on your scrobbler's API, breaking changes between releases are a direct cost to you. If you want to install once and forget, a project whose main branch is described as sometimes unusable is the wrong choice, regardless of how the UI looks. There is also a bus factor question the README answers implicitly. The project has a primary developer, a Ko-fi link, and a note that donations go to the author's travel and rent. That is a candid funding model, and it means maintenance capacity tracks one person's available time. The README also acknowledges known issues that are being worked on and asks for contributions, specifically mentioning more testing as a wanted contribution. A project asking for testing help is telling you its test coverage is not where the author wants it. None of this makes Koito unusable. It makes it a tool to run behind a relay and to pin to a tagged image rather than tracking main, and it makes the relay setup less of a convenience feature and more of a risk control.
Maloja and multi-scrobbler as the realistic alternatives
The README names two alternatives, and they differ from Koito in ways that matter. Maloja is the scrobbler the author was using before building Koito, and the stated grievances with it are the reason this project exists. Maloja is also one of the import sources Koito supports, which tells you the two are close enough in purpose that a migration path was worth writing. The practical difference described in the README is the interface: the author says he likes Koito's UI considerably more, and describes it as sleek and themeable. That is an aesthetic judgement from the person who wrote both the complaint and the replacement, so weigh it accordingly. The second alternative, multi-scrobbler, is a different kind of tool. The README raises it as an option if you do not want to replace your current scrobbler, which places it alongside Koito's relay as a way to run multiple destinations rather than as a direct substitute for Koito itself. The distinction to hold onto is that Maloja is a competing scrobbler you would run instead of Koito, while multi-scrobbler is a fan-out layer you might run in front of or beside it. If your goal is a single self-hosted scrobbler with a UI you prefer, the comparison is Koito against Maloja. If your goal is to send the same plays to several services, multi-scrobbler and Koito's relay overlap, and the README does not argue for one over the other.
Licence, upgrades, and what to check before committing
Koito is MIT-licensed. That is a permissive licence, and it means you can run, modify, and redistribute the code with few conditions, but the licence text itself is the authority and this is not legal advice. For a self-hosted tool the practical implication is that forking is straightforward if the project stalls, which partially offsets the single-maintainer concern. Upgrades are where the instability warning bites. The image referenced in the README is gabehf/koito:latest, and latest moves. If you want to control when breaking changes reach you, pinning to a version tag such as v0.3.2 is the obvious lever, and the release history gives you tags to pin to. The README does not describe a migration or rollback procedure for schema changes between versions, so before upgrading a populated instance, the safe move is to back up the host directory mounted at /etc/koito and read the release notes for the version you are moving to. What I would verify first, given only this material: that the container can write to ./koito, that port 4110 is reachable from every player you intend to point at it, that your image source configuration is set before any import, and that the relay to your existing scrobbler is working before you send real listening history into Koito. The relay is the feature that makes trying Koito low-risk, and it is the one to configure before anything else.
Editorial conclusion
Adopt Koito if you already run Docker and want a ListenBrainz-compatible endpoint you control, and start with the relay so your existing scrobbler keeps receiving plays. Do not adopt it if you need a stable API surface for other tools to depend on, since the README states the main branch can be unusable and breaking changes may occur. Before importing anything, verify that ./koito is writable by the container, that port 4110 is reachable from your scrobbling clients, and that the image source options in the configuration reference match the artwork you expect.
Community notes