Vynl
Documentation
·
v0.6.39·open beta
Search docs — installation, AI, Sonos…⌘ K
SetupConfiguration

Configuration

10 MIN READLast updated: todayv0.6.36

Vynl is configured two ways: environment variables (set at container start) and the Settings UI (live-editable, stored in the SQLite DB). Settings UI always wins over env vars.

Environment variables

Set these in .env (loaded by docker compose) or in your docker-compose.yml environment: block.

Core

Variable Default Purpose
VYNL_DB_DIR process.cwd() Where the SQLite DB lives. Use /app/data in Docker.
VYNL_COVERS_DIR /app/public/covers Where downloaded album covers are stored. Maps to the vynl-covers volume.
VYNL_ARTISTS_DIR /app/public/artists Where artist images live.
VYNL_FIRESTORAGE_ROOT /volume1/Tron/Vynl/firestorage Where soft-deleted files are vaulted. See Backup & Restore.
VYNL_FIRESTORAGE_RETENTION_DAYS 90 How long soft-deleted items are recoverable before auto-purge. Clamped to [7, 365].
VYNL_FIRESTORAGE_PAUSE_AUTO_PURGE (unset) Set to 1 to disable expiry sweeps entirely. Items stay in FireStorage forever until manually purged.
VYNL_USER_AGENT Vynl/1.0 (...) User-agent for outbound HTTP (MusicBrainz, Wikipedia, etc.). Set to something identifying your install so APIs can rate-limit you fairly.

Network / integration

Variable Default Purpose
NEXT_PUBLIC_VYNL_HOST (unset) The LAN-reachable URL Sonos speakers will fetch audio from. Must be the LAN IP, not a Tailscale hostname — Sonos can't reach tailnets. Example: http://192.168.74.79:3101.

API keys (prefer Settings UI over env)

The Settings → API Keys panel is the source of truth for these. You can still set them as env vars; the DB value wins if both are set.

Variable Settings key Purpose
ANTHROPIC_API_KEY anthropicApiKey AI Discovery, Library Doctor, AI Generate Playlist
SPOTIFY_CLIENT_ID spotifyClientId Spotify migration
SPOTIFY_CLIENT_SECRET spotifyClientSecret Spotify migration
ACOUSTID_API_KEY acoustIdApiKey Track identification (Shazam-style)
LIDARR_URL (in Lidarr panel) Lidarr push
LIDARR_API_KEY (in Lidarr panel) Lidarr push

To use the Settings UI: open Vynl → Settings → API Keys → fill in fields → Save.

Settings UI

Located at /settings. The page is organized into sections that map roughly 1:1 with feature areas. Each section's changes are persistent (written to the app_settings SQLite table).

Sections

  • API Keys — all integration credentials
  • File Watcher — auto-import folder paths + debounce. Auto-delete on success has been permanently disabled (see project rule)
  • Library — manual scan trigger, beets DB path, full re-import
  • Lidarr — URL, API key, root folder path, quality profile
  • Sonos — discovered speakers, room groupings
  • LLM — provider (Anthropic / local / OpenAI-compatible), model, endpoint, max tokens
  • FireStorage (coming v0.7) — retention slider, pause auto-purge, purge-now (2FA gated)

Why the Settings UI exists at all

Most self-hosted apps make you edit YAML files for every integration tweak. Vynl deliberately makes everything editable in the browser:

  • You don't have to restart the container after an API-key swap
  • Non-CLI users (your family) can change Sonos rooms without filing a Jira ticket
  • Mistakes are reversible from the same UI that made them

Configuration precedence

When Vynl reads a setting like anthropicApiKey, it checks:

  1. SQLite app_settings table (from Settings UI)
  2. Environment variable (e.g. ANTHROPIC_API_KEY)
  3. Default (usually empty / feature disabled)

So you can:

  • Set a key once in Settings UI → it sticks across container restarts
  • Or bake it into .env for unattended deploys → still overridable from UI later

Backing up your configuration

The entire Vynl config lives in vynl-data/vynl.db. Snapshot that file (the volume mount is /app/data in the container) and you've snapshotted every setting, every API key, every playlist, every track rating.

See Backup & Restore for the proper backup workflow.

Next steps

← Previous
Docker Installation
Next →
AI Discovery