Koel: a self-hosted music streaming server built on Laravel and Vue

What Koel actually replaces, and for whom

Koel is a music streaming solution that runs on a server you own. The README describes it as turning a personal collection into a web-based listening experience, and the package.json description is blunter: "A personal music streaming server that works". The audience is narrow and specific. It is someone with a directory of audio files, a machine that stays on, and a preference for a browser tab over a synced desktop library. The repository topics list audio, laravel, music, music-player, streaming and vue, which matches the split you find in the code: a Laravel backend that indexes and serves tracks, and a Vue frontend that plays them.

The feature list goes past playback. The README names playlists, smart playlists, scrobbling, podcasts, radio, Last.fm, Spotify and MusicBrainz integrations, and an AI assistant that responds to natural-language commands. A mobile client exists as a separate repository, koel/player, which the README says supports both iOS and Android without the limitations of the mobile web version. That matters: the browser interface is the product, and the native app is a companion project with its own release cycle.

The problem it solves is ownership. If your library lives on a NAS and you want to reach it from a laptop, a phone or a browser on the same network, Koel is the layer that turns files into a catalog with metadata, artwork and playback state. It is not a storefront and it does not supply music.

Laravel on the back, Vue on the front, and a database in between

The architecture is visible from the top-level layout. The app/ directory holds the Laravel application, resources/ holds the Vue frontend, routes/ defines the HTTP surface, config/ holds the configuration, and database/ holds migrations and seeders. The build is split too: composer.json and composer.lock drive the PHP side, while package.json and pnpm-lock.yaml drive the JavaScript side. Vite is the bundler, with vite.config.ts and a separate vite.config.sw.js, which suggests a service worker build alongside the main one.

Data flow is conventional for a Laravel app. The .env file selects a database connection, Koel stores its catalog there, and the media itself stays on a filesystem the server can reach. The .env.example defines STORAGE_DRIVER with the values local, sftp, s3, dropbox and webdav, and notes that s3, dropbox and webdav are Koel Plus only, while local and sftp are available in the open source build. MEDIA_PATH is described as the absolute path to your media, and the comment says it can be changed later through the web interface.

That split is the design decision worth noticing. The catalog is in the database, the audio is on disk or on a remote filesystem, and Koel only ever holds a pointer to the second. Move the files without updating the path and the catalog still lists tracks that will not play. The .env.example also carries a TRUSTED_HOSTS key, a comma-separated list of hostnames accepted to access Koel, with the comment that leaving it empty allows any hostname. That is a real security setting, not a convenience one, and it sits in a file most people copy once and stop reading.

Installing Koel and scanning a first library

The README does not inline installation steps. It points to the Official Documentation at docs.koel.dev for system requirements, installation and upgrade guides, and troubleshooting. What the repository does provide is .env.example, and one line in it is load-bearing: the comment on DB_CONNECTION says the value must be present for the `composer koel:init` script to work. That script is the entry point the repository names.

Start by copying the environment file and setting the values the comments require.

cp .env.example .env

Then edit the database block. The .env.example lists mysql as the default, with mariadb, pgsql, sqlsrv and sqlite-persistent as the other accepted values, and it warns that DB_CONNECTION has to be set before the init script will run.

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=koel
DB_USERNAME=koel
DB_PASSWORD=

Set STORAGE_DRIVER and MEDIA_PATH next. The comment in .env.example is explicit that MEDIA_PATH is required when STORAGE_DRIVER is local, and that the value must be an absolute path.

STORAGE_DRIVER=local
MEDIA_PATH=/absolute/path/to/your/music

With the environment in place, run the init script the comment refers to. The README does not reproduce its output, so treat the command as the documented starting point rather than a script whose prompts are described here.

composer koel:init

After initialization the application is served, and the first real use is a scan: point Koel at the media directory and let it index the files into the catalog. The README does not document the scan command or its flags, so follow the documentation for that step rather than guessing at one. What you should expect afterwards is the catalog populated with the tracks under MEDIA_PATH, and playback happening in the browser while the audio streams from the storage driver you chose.

Where the open source build stops

The clearest limitation is licensing scope, and the README states it without hedging. The premium Koel Plus adds multi-user libraries, collaboration, SSO, cloud storage drivers, custom themes and white-labeling. The .env.example confirms the storage half of that: s3, dropbox and webdav are marked Koel Plus only, leaving local and sftp for the MIT build.

So a household where everyone wants a separate library, or an organization that needs single sign-on, is not served by the open source version as described. That is not a bug report; it is the product boundary, and it is better to read it before installing than after. The repository is MIT licensed according to both the LICENSE.md file and the package.json license field, and the README's own framing is that Plus is for organizations that want to host their own Spotify-style experience. The two are separate offerings sharing a codebase, not one product with a paywall bolted on.

A second constraint is environmental. Koel is a PHP application with a database and a filesystem dependency. The .env.example supports MySQL, MariaDB, PostgreSQL, SQL Server and a persistent SQLite file, which is broad, but the server still has to run PHP and a web server, and the media has to sit somewhere the process can read. There is nginx.conf.example, Caddyfile.example and .htaccess.example in the repository root, which tells you the project expects you to configure a web server yourself rather than shipping a container that does it for you.

A third is metadata. Koel's integrations with Last.fm, Spotify and MusicBrainz exist because tags are not always right. A library of untagged files will index, but the quality of the result depends on what is in the files, and the README does not promise to repair that.

Koel against Navidrome and Plex

The obvious alternative for the same job is Navidrome, a self-hosted music server that speaks the Subsonic API. The difference in approach is architectural and it changes what you can do with the result. Navidrome exposes a documented streaming API that a long list of existing mobile and desktop clients already implement, so you pick a client rather than a server interface. Koel builds its own Vue frontend and its own mobile app in a separate repository, koel/player, which the README describes as supporting iOS and Android without the limitations of the mobile web version. You get a coherent first-party experience, and you get it only through Koel's own clients.

Plex is the other comparison, and the difference there is scope rather than protocol. Plex handles video as well as music and runs a hosted account layer. Koel is music-focused, and the README's Plus tier is where the multi-user and SSO features that Plex provides by default live. If you want one server for films and albums, Koel is the wrong tool. If you want an album catalog with smart playlists and scrobbling and you do not mind the browser being the primary client, the trade is reasonable.

The honest summary is that Koel bets on its own interface, and Navidrome bets on interoperability. Neither is a defect. They just fail differently when your client of choice is not the one the project ships.

Maintenance, upgrades and what the licence leaves you

The repository is not archived, and the last push was on 2026-09-20. Recent releases are close together: v9.13.0 on 2026-09-17, v9.12.0 on 2026-09-14 and v9.11.3 on 2026-09-09. That cadence, plus the .version file in the repository root, tells you the project ships often and expects you to track versions. The README directs upgrades to the same documentation site as installation, and it does not document a rollback path, so a downgrade is not something the repository describes.

That is the upgrade cost in practice. A Laravel application with database migrations means an upgrade is not only a file replacement; the database schema moves with it. The .env.example is a template, not a contract, and keys in it can change between releases. Anyone running Koel should read the release notes for the version they are moving to rather than assuming the current .env still matches.

The licence is MIT, per LICENSE.md and the package.json license field. That permits commercial and private use and modification, and it comes with no warranty. What MIT does not cover is the Koel Plus tier, which the README presents as a separate premium offering with features the open source build does not include. If your plan depends on multi-user libraries, SSO or S3 storage, the licence question is not the MIT text; it is the terms you agree to for Plus. That is a question for whoever administers the licence, not something this article can settle.

Editorial conclusion

Adopt Koel if you already run a PHP host, keep your audio on a disk you control, and want playlists, scrobbling and podcasts behind a browser instead of a desktop client. Do not adopt it if you need multi-user libraries, SSO or S3-backed storage on the MIT build: the README places those in Koel Plus, so you would be paying for a licence rather than reading the source. Before you commit, verify three things: that your database driver is one the .env.example lists, that MEDIA_PATH is an absolute path the PHP process can read, and that the docs at docs.koel.dev match the version you intend to run.

Frequently asked questions

Official sources

1. koel/koel on GitHub
2. License: MIT
3. Project website
4. README
5. Releases