# Project pack: Koel @ fac6f8d

Facts about **Koel** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v4.md). Pinned to one version; never changes after publication.

> Koel is a personal music streaming server and web app. Point it at a folder of MP3, FLAC and other audio files and you get a library with albums, artists, playlists, a visualiser and mobile-friendly playback. It can also play podcasts and radio stations.

## Setup path (checked 2026-11-03)
- **Needs Docker.** Tell the person before any setup work; no light non-Docker route is documented upstream. Docker Desktop on Windows may need a computer restart and an admin-only Windows feature (virtualisation); say so and let the person decide.
- Verdict source: https://docs.koel.dev
- You may be unable to download source archives or run commands in this session. The person downloads and runs things; if you cannot fetch something, give any changed file in full in chat with its path.

## Version and source
- Repository: https://github.com/koel/koel
- Pinned commit: `fac6f8d4a8ffff01597efc4613c1de315cd1564a`. Use exactly this version.
- Zip the person can download in a browser: https://github.com/koel/koel/archive/fac6f8d4a8ffff01597efc4613c1de315cd1564a.zip
- Fresh checkout (only if you have a shell and git): use the commands below in an empty folder. If this exact source is already checked out, keep your branch and use the development command; do not clone again or reset local changes.
- Official docs: https://docs.koel.dev
- Live demo: https://demo.koel.dev/. Shared demo. Don't enter real data.
- Licence: **MIT**. Free to use, change and share, even commercially. Keep the original copyright notice.

## Commands from the pinned source
- Developer commands (they may use Docker):

  ```sh
  git clone https://github.com/koel/koel bespoke-koel
  cd bespoke-koel
  git checkout --detach fac6f8d4a8ffff01597efc4613c1de315cd1564a
  # Prepare development requirements and local configuration first.
  composer install
  pnpm install
  cp .env.example .env
  php artisan koel:init
  pnpm dev
  ```

- Separate trial of the current upstream release (not your changes; sample data and a separate data directory only):

  ```sh
  Follow the Docker guide at https://docs.koel.dev/guide/getting-started, which provides a compose file with the official image.
  ```
- Tools these commands use: Docker, or PHP 8.2+, Composer, Node 22 and a database for development
- Develop: `pnpm dev`
- Test: `php artisan test`
- Check/lint: `pnpm lint`
- Stack: php, typescript (Laravel, Vue, Vite, Tailwind). Difficulty for a non-developer with an AI: **moderate**. A Laravel back end with a Vue single-page front end. Themes and settings are easy; features follow the standard Laravel structure.
- The project's own AI instructions, in the repository: `AGENTS.md`, `CLAUDE.md`.
Personal data: **yes**. Stored in: A database for the library plus covers on disk; your music files stay in your own folder. Secrets are entered by the person, never in chat.

---
Later, only when a step needs it: [reference.md](https://handoff.bespokeai.software/p/koel/fac6f8d/r3/reference.md) (customisation points, must-keep-working, data and costs, coding conventions) · [hosting.md](https://handoff.bespokeai.software/p/koel/fac6f8d/r3/hosting.md) (long-term hosting; hosts are paid third parties) · [bespoke.yaml](https://handoff.bespokeai.software/p/koel/fac6f8d/r3/bespoke.yaml) · [SKILL.md](https://handoff.bespokeai.software/p/koel/fac6f8d/r3/SKILL.md)