# Configuration (/docs/configuration)

<!-- generated by `bun scripts/config-docs.ts` from apps/api/src/settings.ts; don't edit by hand -->

| variable | default | what |
|---|---|---|
| `NAVIDROME_URL` | `http://navidrome:4533` | Your Navidrome (or any OpenSubsonic server), as this container reaches it. Usually the internal Docker address. |
| `NAVIDROME_SERVERS` | — | Several servers to choose from at sign-in, as `id=url` pairs separated by commas (`home=http://navidrome:4533,friend=https://music.example.com`). Replaces `NAVIDROME_URL`. The browser can only ever pick from this list. |
| `PORT` | `8080` | Port the server listens on. |
| `DATA_DIR` | `./data` | Where sessions, the search and lyrics index, history and the cover cache live. Mount a volume here (`/data` in the image). |
| `SESSION_SECRET` | — | Encrypts stored Navidrome credentials. Unset: a random one is generated once and kept in `DATA_DIR`. |
| `SESSION_IDLE_DAYS` | `30` | A browser that isn't used for this long is signed out. |
| `COVER_CACHE_MB` | `1024` | Disk for resized covers; least recently used are deleted first. |
| `LRCLIB_URL` | `https://lrclib.net` | Where lyrics Navidrome doesn't have are looked up. Empty turns LRCLIB off. |
| `LYRICS_BACKFILL` | `on` | `on`: walk the library in the background (about one song a second) to fetch lyrics nobody opened yet. `off` to disable. |
| `LYRICS_WRITE_LRC` | `off` | `on`: lyrics found on LRCLIB are also saved as `<track>.lrc` next to the audio file, so other clients get them. Needs `MUSIC_DIR` and Navidrome's "Report Real Path". Never overwrites; undo from the lyrics page. |
| `LYTERION_URL` | — | Lyterion's API, as this container reaches it, to show what of your Spotify library is in Navidrome on the import page, and the artists you follow on Spotify to follow here, daily (admins). Empty: the import page asks for a Spotify export file instead and nothing is synced. |
| `LYTERION_TOKEN` | — | The `LYTERION_PLAYER_TOKEN` set on Lyterion. Needed with `LYTERION_URL`. |
| `MUSICBRAINZ_URL` | `https://musicbrainz.org` | Where new releases by the artists you follow are looked up, once a week (artist names only, one request a second). Empty turns the new releases row off. |
| `RELEASES_AUTO_GET` | `off` | `on`: with Lyterion set up, new releases by followed artists are handed to it on their own (at most ten a week). `off`: they are only listed, and **get it** on a release hands that one over. |
| `GROQ_API_KEY` | — | Turns on playlists from a prompt ("rainy sunday, slow, warm"): Groq picks artists from your library and the player builds the list from songs you own. Also fills missing or garbled tags of uploads for review (needs `UPLOAD_DIR`). Kept server-side. Empty: off. |
| `GROQ_MODEL` | `openai/gpt-oss-120b` | The Groq model for playlists from a prompt and for upload tags. |
| `GROQ_URL` | `https://api.groq.com/openai/v1` | Groq's API, or any OpenAI-compatible one. |
| `AUDIOMUSE_URL` | — | AudioMuse-AI, as this container reaches it: song features (tempo, key, energy, mood) are copied into the index for `bpm:` / `energy:` / `mood:` search filters, smart shuffle and sonic neighbours. Empty: off, everything else works as is. |
| `FEEDBACK_GITHUB_TOKEN` | — | A GitHub token that may open issues and write contents on `FEEDBACK_REPO`: turns on "send feedback" in the user menu, filed as an issue (screenshots go to a `feedback` branch). Empty: off. |
| `FEEDBACK_REPO` | — | Where feedback goes, as `owner/repo`. Needed with `FEEDBACK_GITHUB_TOKEN`. |
| `ONE_SESSION` | `on` | `on`: all of an account's open players share one playback session, like Spotify Connect: one plays, the others are remotes, and the device picker moves playback. `off`: every tab plays on its own. |
| `UPLOAD_DIR` | — | Where music uploaded from the player lands (admins only), mounted writable. An import inbox (beets, Lyterion) or Navidrome's music folder. Empty turns uploads off. |
| `MUSIC_DIR` | — | Navidrome's music folder mounted writable here, for `LYRICS_WRITE_LRC`. Unused otherwise. |
| `INDEX_USER` | — | Navidrome account for background jobs (search index, lyrics backfill). Unset: the admin who signed in most recently. |
| `INDEX_PASSWORD` | — | Password for `INDEX_USER`. |
| `DEMO_SEED` | `off` | `on`: fill `INDEX_USER`'s history with months of generated listening, once (for demos and previews, see docs/previews.md). Needs `INDEX_USER`. |
| `PUBLIC_DEMO` | `off` | `on`: a public demo (docs/public-demo.md). Nobody is an admin here, API and terminal tokens can't be made, and playlists can't be deleted. |
| `REDIS_URL` | — | `redis://…`: keep computed answers (made for you) in Redis, shared by several instances. Unset: in memory, which is all one instance needs. |
| `TRUST_PROXY` | `false` | `true` behind a reverse proxy: client IPs come from `X-Real-IP` / `X-Forwarded-For` (login rate limits). |
| `PUBLIC_URL` | — | The address people reach the player at, e.g. `https://music.example.com`. Link previews (`og:image`, `og:url`) point there. Unset: taken from the request, and from the proxy's `X-Forwarded-*` headers when `TRUST_PROXY` is on. |
| `SHARE_PURGE` | `off` | `on` deletes every shared link at start, e.g. after an owner's account is removed. Turn it off again after one restart. |
| `UPDATE_CHECK` | `off` | `on`: admins see when a newer release is out (one request to GitHub a day). The other outside calls are lyrics lookups (`LRCLIB_URL`), new releases (`MUSICBRAINZ_URL`) and Groq when `GROQ_API_KEY` is set. |
