Skip to content

Cloud Storage Support

In addition to storing your music on the same server as Koel’s installation via the local storage drivers, Koel Plus offers several different file storage options, including SFTP, Amazon S3, S3-compatible services, Dropbox, and likely more in the future. This page will guide you through the process of setting up these storage options.


Though possible, changing storage drivers after you've already stored files is not recommended, as it may break links to your existing media.

Service UI may change

The screenshots and instructions on this page may not be 100% up-to-date as 3rd-party services' UI may change. The general idea, however, should remain the same.


To use SFTP as your storage driver, you need to have an SFTP server set up and running. Many cloud hosting providers offer SFTP access to their storage services. To enable SFTP storage support in Koel, you need to provide the following configuration in your .env file:



# The absolute path of the directory to store the media files on the SFTP server.
# Make sure the directory exists and is writable by the SFTP user.

# You can use either a username/password pair…

# …or private key authentication:

After reloading, Koel will start using SFTP as its storage driver. You can now upload your music files to your SFTP server directly from Koel’s web interface.

Amazon S3 and Compatible Services

Since Amazon S3 and S3-compatible services share the same API, you can use the same configuration (AWS_*) for both. Koel has been tested with Amazon S3, DigitalOcean Spaces, and Cloudflare R2, but it should work with any S3-compatible service given the right configuration.

Amazon S3

Create a new S3 bucket and obtain your access key ID and secret key from the AWS console. Then, populate these values in your .env file:



After reloading, Koel will start using S3 as its storage. You can now upload your music files to your S3 bucket directly from Koel’s web interface.

In order to use S3 for streaming, you'll also need to set up a cross-origin resource sharing (CORS) configuration for your bucket by going to the Permissions tab. Here's a sample policy that allows streaming from any origin:

        "AllowedHeaders": [],
        "AllowedMethods": [
        "AllowedOrigins": [
        "ExposeHeaders": []

DigitalOcean Spaces

To use DigitalOcean Spaces, you can follow the same steps as with Amazon S3. Below are some screenshots to help you get started.

Create DO Spaces bucket screen
Create a DigitalOcean Spaces bucket
DO Spaces bucket settings
DigitalOcean Spaces bucket settings with CORS Configurations

The access key ID and secret key can be generated and obtained via the API -> Space Keys tab in the DigitalOcean control panel:

DigitalOcean Spaces keys

A sample .env configuration for DigitalOcean Spaces may look like this:



Cloudflare R2

Cloudflare R2 is yet another excellent choice for an S3-compatible service. The setup is pretty much similar to the above:

Create CF R2 bucket screen
Create a Cloudflare R2 bucket
CF R2 bucket settings
Cloudflare R2 bucket settings with CORS Policy

A sample .env configuration for Cloudflare R2 may look like this:


AWS_REGION=auto # Cloudflare R2 explicitly uses the `auto` region


Koel Plus also supports using Dropbox as a storage driver, although the setup is a bit different.

  1. First, create a new Dropbox app with the "App folder" access type and set up sufficient permissions to read and write files.
    Create a Dropbox app
    Create a Dropbox app
    Dropbox app permissions
    Set sufficient app permissions
  2. Under your Dropbox app's Settings tab, make a note of the "App key" and "App secret" values. Now, from the root folder of your Koel installation, run the following command:
    php artisan koel:storage:dropbox
    You'll be prompted to enter the "App key" and "App secret" values obtained earlier.
  3. Koel will generate a URL for you to visit and authorize the Dropbox app. Afterward, you'll receive an access code.
  4. Enter the access code back into the command line's prompt. Koel will then finalize the setup automatically and start using Dropbox as its storage.

Now when you upload music files to Koel, they'll be stored in your Dropbox app's folder.

Two-way sync not supported

Koel does not support two-way sync with Dropbox — at least not yet. This means manual changes made to your Dropbox folder will not be reflected in Koel.