Polaris (agersant/polaris): a self-hosted music server for large collections

What Polaris actually solves for people with a music folder

Polaris is a self-hosted music streaming server. The README states the intent plainly: enjoy your music collection from any computer or mobile device, with no premium tier. The stated goals are performance, first-class support for large collections (100,000+ songs), ease of installation and deployment, and a user interface the author considers beautiful.

The audience is narrow and specific. You already have audio files on a disk you control. You want to reach them from a laptop, a phone, or another machine on your network or over the internet, and you do not want to upload the library to a third party or pay a subscription. Polaris is not a store, not a discovery service, and not a metadata provider. It reads what you have, indexes it, and serves it.

That framing matters when you compare it to streaming services. There is no catalogue here. If your library is thin, Polaris will faithfully serve a thin library. The project's own demo at demo.polaris.stream uses Creative Commons tracks, which tells you the intended shape: a personal collection, not a licensed catalogue.

How the Rust server indexes files and serves them

The dependency list in Cargo.toml is the clearest description of the mechanism available without running it. Format support is not hand-rolled per codec: symphonia is pulled in with the all-codecs and all-formats features, plus opt-simd. Metadata parsing is split across dedicated crates, including id3, metaflac, mp4ameta, and a fork of opus_headers pointed at a multivalue branch. That fork exists to support multi-value fields, which the README lists as a feature: multiple artists per song.

The storage layer uses native_db and native_model, with bitcode and serde for serialization. File watching is handled by notify and notify-debouncer-full, so the index can react to changes on disk rather than requiring a manual rescan. Parallel work runs through rayon, and the HTTP layer is axum with axum-extra and axum-range. The range support is what makes seeking and partial playback possible in a browser player. Compression is enabled through tower-http with the compression-gzip feature.

Two smaller details say a lot. The trie-rs dependency suggests prefix-based lookup, which is how a search box stays responsive against a very large index. And icu_collator indicates locale-aware sorting rather than plain byte ordering, which matters for artist names with accents. Authentication uses branca tokens and pbkdf2 for password hashing.

The server also ships its own API documentation. The README states that every installation distributes interactive OpenAPI documentation at http://localhost:5050/api-docs/. That port, 5050, is the only default endpoint the README names.

Installing Polaris and reaching the web interface for the first time

The README does not inline installation steps. It links to docs/SETUP.md for installation and docs/DDNS.md for streaming from remote devices, and it points at a Repology badge showing distribution packages. So the authoritative instructions are in the repository docs, not the front page. Treat anything below as orientation, then read docs/SETUP.md.

Docker is one of the supported deployment paths the README names, alongside Windows, Linux, and BSD. The README itself does not print a docker command, so check docs/SETUP.md for the image name and volume layout before running anything.

Once the server is running, the configuration is plain text and, per the README, also editable from the built-in UI. That is the first thing to open in a browser:

# The README states the API documentation is served by every installation.
# Replace localhost with your server's hostname if you are not on the same machine.
http://localhost:5050/api-docs/

If that page loads, the HTTP layer is up and you can inspect the API surface directly. If it does not, the process is not listening on 5050, and the next place to look is the configuration file described in docs/CONFIGURATION.md.

The demo credentials in the README are for the public demo only, not for your install:

Username: demo_user
Password: demo_password

Do not reuse those. They exist so you can evaluate the interface at https://demo.polaris.stream before committing to a deployment. For your own server, the README states that you set up multiple users, each with their own playlists.

Where Polaris is the wrong tool

The hardest limitation is the one the README does not address: upgrades. There is a CHANGELOG.md and a docs/MAINTENANCE.md runbook, but the README does not document rollback. If you deploy a new version and the on-disk index format changes, the documented recovery path is not on the front page. Before you put a large library behind Polaris, read docs/MAINTENANCE.md and confirm what a downgrade would involve.

Second, the native desktop UI is conditional. In Cargo.toml, the ui feature pulls in native-windows-gui and native-windows-derive. Those are Windows-only crates. A build without that feature is a headless server, which is the normal shape on Linux, BSD, and Docker. Do not expect the packaged Windows build's UI on a Linux container.

Third, Polaris assumes you are the operator. There is no hosted option, no managed tier, and the README says there is no premium version. If you want someone else to run the server, handle TLS, and take backups, this is the wrong project. Similarly, if your collection is small and lives on one laptop, a local player is less work than a server plus a client.

Finally, the mobile story is partly third-party. The README lists an official Polaris Android app on Google Play and F-Droid, but Polarios for iOS and Polarity are explicitly marked third-party. Their maintenance schedules are not Polaris's.

How Polaris differs from Navidrome and other Subsonic-style servers

The obvious comparison is Navidrome, another self-hosted music server with a web UI and mobile clients. The difference in approach is the client protocol. Navidrome implements the Subsonic API, which is why it works with a long list of existing Subsonic-compatible players. Polaris exposes its own HTTP API, documented through OpenAPI at /api-docs/, and its mobile clients are written against that API. The README links an Android app, Polarios, and Polarity, all built for Polaris specifically.

That trade-off cuts both ways. A Subsonic-compatible server gives you a wide choice of clients on day one, including players the project did not write. A bespoke API gives the author freedom to model multi-value metadata, waveform data, and per-field search queries without bending them into someone else's schema. The README lists per-field search queries and audio-waveform visualization as features, and those are easier to design when you own the API.

A second difference is implementation language. Polaris is Rust, and the dependency list leans heavily on Rust-native audio crates: symphonia for decoding, metaflac and id3 and mp4ameta for tags. That is a different maintenance profile from a Go server, mostly in how many upstream crates you depend on for format correctness. Note the Cargo.toml comment about an upstream PR for opus_headers, with the project temporarily pointing at a fork. That is a real, visible supply-chain detail worth knowing before you build.

Licence, maintenance, and what an upgrade costs you

Polaris is MIT licensed, per the README badge and the LICENSE file in the repository root. MIT is permissive: you can run it, modify it, and redistribute it, subject to the licence text. That covers Polaris itself. It does not cover your music, and it does not cover the third-party clients. Polarios and Polarity are separate projects with their own repositories and, presumably, their own licences. Check those separately if you plan to redistribute anything. This is a description of the licence, not legal advice.

The repository is not archived, and the last push was on 2026-05-08. The most recent release, 0.16.1, was tagged the same day. Before that, 0.16.0 landed on 2026-03-05, and 0.15.0 on 2025-02-05. The gap between 0.15.0 and 0.16.0 is roughly thirteen months, which tells you releases are not on a fixed cadence. Plan upgrades around the CHANGELOG rather than a schedule.

The maintenance cost you should budget for is not the binary. It is the index. notify and notify-debouncer-full watch the filesystem, so a library that changes constantly will keep the server busy. If you mount a network share, confirm that filesystem events actually propagate, because polling behaviour is not described in the README. And read docs/MAINTENANCE.md before your first upgrade, since it is the only maintenance material the README points to.

Editorial conclusion

Adopt Polaris if you own a large local music library and want a browser and mobile front end without a subscription, and if you are comfortable following docs/SETUP.md rather than a one-line installer. Do not adopt it if you need a hosted service, a documented upgrade or rollback procedure, or Windows UI features on a headless Linux box, since the Cargo.toml gates the native UI behind a feature flag. Before committing, verify that your files land in the formats listed in the README, check the configuration keys in docs/CONFIGURATION.md against the version you install, and confirm the port your deployment exposes matches what the API docs URL expects.

Frequently asked questions

Official sources

1. agersant/polaris on GitHub
2. Issues
3. License: MIT
4. README
5. Releases