docs/environment-variables.md
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.
:::info 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.
:::
| 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) |
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) |
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) |
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) |
| 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 |
| 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 |
| 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 |
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) |
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) |
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) |
| 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.
| 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 |