Environment Variables
This page documents the environment variables specific to Koel. These variables are typically set in the .env file at the root of your Koel installation.
Laravel Variables
Koel is built on Laravel, which has its own set of environment variables (e.g. APP_ENV, APP_DEBUG, APP_KEY, APP_URL, DB_*, CACHE_DRIVER, QUEUE_CONNECTION, SESSION_DRIVER, etc.). These are not documented here — please refer to the Laravel documentation for details.
Storage
| Variable | Description | Default |
|---|---|---|
STORAGE_DRIVER | The storage driver for your media files. Valid values: local, sftp, s3 (Koel Plus), dropbox (Koel Plus). See Cloud Storage Support. | local |
MEDIA_PATH | The absolute path to your media directory. Required when using STORAGE_DRIVER=local. Can also be changed via the web interface. | (empty) |
ARTIFACTS_PATH | The absolute path to store Koel artifacts (transcoded files, podcast episodes, temporary downloads, etc.). If empty, uses the system's temporary directory. | (empty) |
S3 / S3-Compatible
Required when STORAGE_DRIVER=s3. Remember to set your CORS policy to allow access from Koel's domain.
| Variable | Description | Default |
|---|---|---|
AWS_ACCESS_KEY_ID | Your AWS (or S3-compatible service) access key ID. | (empty) |
AWS_SECRET_ACCESS_KEY | Your AWS secret access key. | (empty) |
AWS_REGION | The region of your bucket. Set to auto for Cloudflare R2. | (empty) |
AWS_ENDPOINT | The endpoint URL for S3-compatible services. | (empty) |
AWS_BUCKET | The name of your S3 bucket. | (empty) |
Dropbox
Required when STORAGE_DRIVER=dropbox. Run php artisan koel:setup-dropbox to set all Dropbox-related variables.
| Variable | Description | Default |
|---|---|---|
DROPBOX_APP_KEY | Your Dropbox app key. | (empty) |
DROPBOX_APP_SECRET | Your Dropbox app secret. | (empty) |
DROPBOX_REFRESH_TOKEN | Your Dropbox refresh token. | (empty) |
SFTP
Required when STORAGE_DRIVER=sftp.
| Variable | Description | Default |
|---|---|---|
SFTP_HOST | The SFTP server hostname. | (empty) |
SFTP_PORT | The SFTP server port. | (empty) |
SFTP_ROOT | The absolute path on the SFTP server to store media files. | (empty) |
SFTP_USERNAME | The SFTP username. | (empty) |
SFTP_PASSWORD | The SFTP password. | (empty) |
SFTP_PRIVATE_KEY | Path to the private key for key-based authentication (alternative to password). | (empty) |
SFTP_PASSPHRASE | The passphrase for the private key. | (empty) |
Media Scanning
| Variable | Description | Default |
|---|---|---|
APP_MAX_SCAN_TIME | The maximum scan time in seconds when scanning via the browser. Does not affect koel:sync. | 600 |
MEMORY_LIMIT | The memory limit in MB for the scanning process. Example: 2048. | (empty) |
SCAN_JOBS | The number of parallel worker processes for scanning. Set to 1 to disable parallel scanning. Can be overridden with --jobs flag. | 4 |
IGNORE_DOT_FILES | Whether to ignore dot files and folders when scanning. Greatly improves performance if your media root has folders like .git or .cache. | true |
SYNC_LOG_LEVEL | The verbosity of sync logs (found under storage/logs/). Options: all, error. | error |
Streaming & Transcoding
| Variable | Description | Default |
|---|---|---|
STREAMING_METHOD | The streaming method. Options: php, x-sendfile, x-accel-redirect. See Streaming Music. Using x-sendfile or x-accel-redirect is highly recommended for better performance. | php |
TRANSCODE_FLAC | Whether to transcode FLAC to MP3 on the fly. Set to false to stream FLAC as-is. | true |
TRANSCODE_BIT_RATE | The bit rate (in kbps) for transcoded audio. Higher values mean better quality but slower streaming. | 128 |
FFMPEG_PATH | The full path to the ffmpeg binary. Automatically detected if left empty. | (auto-detected) |
TRANSCODE_TIMEOUT | The maximum time in seconds allowed for transcoding a single file. Increase for very large files. 0 disables the timeout. | 300 |
Downloading
| Variable | Description | Default |
|---|---|---|
ALLOW_DOWNLOAD | Whether to allow song downloading. Multi-song downloads require the zip PHP extension. | true |
DOWNLOAD_LIMIT | The maximum number of songs allowed in a single download. 0 means unlimited. Single-song downloads are always allowed. | 0 |
Service Integrations
Also see Service Integrations for detailed setup instructions.
| Variable | Description | Default |
|---|---|---|
USE_MUSICBRAINZ | Whether to use MusicBrainz for metadata fetching. | true |
MUSICBRAINZ_USER_AGENT | The user agent for MusicBrainz API requests. Auto-generated if empty. | (auto-generated) |
LASTFM_API_KEY | Your Last.fm API key. Required for artist/album info and scrobbling. | (empty) |
LASTFM_API_SECRET | Your Last.fm API secret. | (empty) |
SPOTIFY_CLIENT_ID | Your Spotify application client ID. Used for fetching artist and album images. | (empty) |
SPOTIFY_CLIENT_SECRET | Your Spotify application client secret. | (empty) |
YOUTUBE_API_KEY | Your YouTube API key. See YouTube integration. | (empty) |
TICKETMASTER_API_KEY | Your Ticketmaster API key. See Ticketmaster. | (empty) |
TICKETMASTER_DEFAULT_COUNTRY_CODE | Fallback country code for Ticketmaster when IP-based lookup fails. See ISO 3166-1 alpha-2. | US |
IPINFO_TOKEN | Your IPinfo token, used to look up the user's country for Ticketmaster. | (empty) |
SSO (Single Sign-On)
Koel Plus only. See Single Sign-On.
| Variable | Description | Default |
|---|---|---|
SSO_GOOGLE_CLIENT_ID | Your Google OAuth client ID. | (empty) |
SSO_GOOGLE_CLIENT_SECRET | Your Google OAuth client secret. | (empty) |
SSO_GOOGLE_HOSTED_DOMAIN | The Google Workspace domain users must belong to. | (empty) |
Proxy Authentication
Koel Plus only. See Proxy Authentication.
| Variable | Description | Default |
|---|---|---|
PROXY_AUTH_ENABLED | Whether to enable proxy authentication. | false |
PROXY_AUTH_USER_HEADER | The header containing the unique user identifier. | remote-user |
PROXY_AUTH_PREFERRED_NAME_HEADER | The header containing the user's preferred display name. | remote-preferred-name |
PROXY_AUTH_ALLOW_LIST | A comma-separated list of allowed proxy IPs or CIDRs. If empty, no requests are allowed. | (empty) |
AI Assistant
| Variable | Description | Default |
|---|---|---|
AI_ENABLED | Enable the AI assistant feature. Requires a configured AI provider. | false |
AI_PROVIDER | The AI provider to use. Supported values: openai, anthropic, gemini, ollama, and more. See config/ai.php for the full list. | openai |
OPENAI_API_KEY | API key for OpenAI. Required when AI_PROVIDER=openai. | (empty) |
ANTHROPIC_API_KEY | API key for Anthropic (Claude). Required when AI_PROVIDER=anthropic. | (empty) |
Additional providers (Gemini, Ollama, etc.) can be configured in config/ai.php.
Miscellaneous
| Variable | Description | Default |
|---|---|---|
TRUSTED_HOSTS | A comma-separated list of hostnames allowed to access Koel. Leave empty to allow any hostname. Example: localhost,192.168.0.1,yourdomain.com | (empty) |
FORCE_HTTPS | Force Koel to use HTTPS URLs. Set to true if automatic detection fails. | false |
BACKUP_ON_DELETE | Whether to create a backup of a song when deleting it from the filesystem. | true |
CDN_URL | A CDN URL mapped to Koel's home URL, used to serve media files. No trailing slash. | (empty) |
MEDIA_BROWSER_ENABLED | Whether to enable the media browser (experimental Koel Plus feature). | false |