Migrating from Navidrome
Navidrome is fantastic, incredible software, and I owe a huge amount for bringing self-hosting music into the modern age. However, there were a lot of neat things I wanted to try out and experiment with which required tighter integration between client and server. In order take full advantage of these things (see the features page), there are a variety of OpenSubsonic extensions that are specific to kōan (but by no means closed off to other clients), which are available by running kōan as your server.
A kōan server does the job Navidrome does: it indexes a music folder, serves it over the Subsonic API with OpenSubsonic extensions, and gives each person an account. Subsonic apps that work with Navidrome work with kōan.
You do not have to switch to use kōan's apps. The macOS, iOS, Android and Apple TV apps and the terminal UI play from a Navidrome server as they do from a kōan one, so a move can be gradual: run kōan beside Navidrome on the same read-only music folder, try it, and move clients one at a time.
What you gain
- Apps that control each other. kōan's apps keep a connection open to a kōan server. Any device can see what another is playing, take over its queue, or hand the music to it, across networks. Against Navidrome they can only find each other on the local network. See Playing on another device.
- Changes arrive without polling. A kōan server tells linked apps when the library or a playlist changes. Against Navidrome, apps check on a timer.
- An assistant can drive it. The server is an MCP server with its own OAuth sign-in. Claude and other assistants connect as a kōan account and can search the library, build playlists and play music on that account's devices. See MCP integration.
- Native players. The desktop app and terminal UI play bit-perfect where the device allows, gapless, and cache what they stream so it plays again offline. The server itself needs no sound card.
What you give up
These Navidrome features have no kōan equivalent today:
- Serving under a sub-path (
ND_BASEURL). kōan expects its own hostname. - Per-library permissions. Every account sees the whole library.
- Internet radio, which is not planned. Clients that use it lose the feature against kōan; the rest of the client works.
Translating a Navidrome setup
The container
A typical Navidrome compose file:
services:
navidrome:
image: deluan/navidrome:latest
ports: ["4533:4533"]
environment:
ND_SCANSCHEDULE: 1h
ND_ENABLESHARING: "true"
volumes:
- ./data:/data
- /mnt/music:/music:roThe kōan equivalent:
services:
koan:
image: ghcr.io/radiosilence/koan:latest
ports: ["4000:4000"]
environment:
KOAN_LIBRARY__FOLDERS: '["/music"]'
KOAN_GRAPHQL__ALLOWED_HOSTS: '["music.example.com"]'
KOAN_SERVER__URL: https://music.example.com
KOAN_SUBSONIC__ENABLED: "true"
volumes:
- koan-config:/config
- /mnt/music:/music:rowith koan-config declared under volumes:. As in Navidrome, the first visit to the web UI makes the admin: until an account exists it shows a setup page instead of sign-in. To keep that window shut, set KOAN_GRAPHQL__SETUP_WIZARD: "false" and create the admin from a shell in the container (see The first account):
docker compose exec koan koan auth setupDocker Compose has a complete file with Caddy in front for TLS.
| Navidrome | kōan |
|---|---|
/data |
/config: config, database, signing keys and the cover cache. The image runs as uid 1000, so a bind mount must be writable by it |
ND_MUSICFOLDER |
KOAN_LIBRARY__FOLDERS, a list; several folders form one library |
ND_SCANSCHEDULE, ND_SCANNER_WATCHERWAIT |
Nothing to set. The server scans at start and watches the folders for changes |
ND_ENABLESHARING |
Always on; server.url sets the address links are built on |
ND_BASEURL |
Not supported; give kōan its own hostname |
ND_REVERSEPROXYUSERHEADER, ND_REVERSEPROXYWHITELIST |
KOAN_GRAPHQL__PROXY_AUTH_HEADER, KOAN_GRAPHQL__PROXY_AUTH_FROM, for the web UI; see Behind an authenticating proxy |
| Port 4533 | Port 4000, which serves the web UI, the Subsonic API (/rest), GraphQL and MCP |
kōan only reads the music folder, as Navidrome does. Both can mount the same folder at once while you try kōan out.
The reverse proxy
Point the proxy at port 4000 instead of 4533, and list the hostname in allowed_hosts: kōan refuses requests for any Host it was not given. The linked apps hold a WebSocket open at /rest/koanLink, so the proxy must pass WebSocket upgrades. Caddy does this by default:
music.example.com {
reverse_proxy koan:4000
}
Accounts
Navidrome's accounts do not carry over. With the admin account made, create the rest on the web UI's Users page, or from the shell:
koan auth create-user --username alice --role user
koan auth invite alice --server https://music.example.comThe invite is a link that signs kōan's apps in directly and shows the details for any other Subsonic app. The web UI's Users page does the same. Roles are admin, user and readonly; Navidrome's admin and regular users map to the first two.
Subsonic clients
Change the server URL and sign in with the kōan account. kōan accepts every way Subsonic clients sign in:
- Password, plain or hex-encoded.
- Token and salt, which most clients use by default, with an app password in place of the account's password.
- API key (OpenSubsonic
apiKeyAuthentication).
Make API keys and app passwords on the web UI's Account page, one per client; kōan's Mac, iOS and Android apps make and revoke both under Settings → Account too. A client that reports error 41 is using token auth with the account's own password, which kōan cannot check because it keeps only a hash: give it an app password instead. See Authentication.
Favourites, play counts and playlists
There is no importer for Navidrome's database yet; #651 tracks one. Until then, favourites, ratings, play counts and the playlists made in Navidrome stay there and start empty in kōan.
Covers kept as image files beside the tracks carry over. kōan looks for cover.*, folder.* and front.* (JPEG, PNG or WebP, any case) in that order, then for art embedded in the files, which is Navidrome's default CoverArtPriority. A different CoverArtPriority is not read; kōan always uses this order.
Playlists kept as files in the music folder carry over: kōan reads Navidrome's smart playlists (.nsp) and .m3u/.m3u8 files when it scans. See Smart playlists.
Running both
To keep Navidrome running while moving across:
- Run kōan beside it on the same read-only music mount, on its own hostname.
- Sign kōan's apps in to the kōan server, and leave other clients on Navidrome.
- Move the remaining clients once kōan covers what they use, then stop Navidrome.
kōan's apps can stay pointed at Navidrome throughout. They sync its library, favourites and playlists, so nothing about them has to change until the server does.