Install it, then connect your first cloud

1. Get the installer for your architecture (x64 or Arm64) from the download page.
2. Run the installer and follow the on-screen prompts.
3. When it finishes, a CloudDrive2 shortcut appears on your desktop. Double-click it, or just open http://localhost:19798 in a browser.

Windows 7 is no longer supported — the TLS stack and runtime it ships with cannot meet what the current version needs. Older machines can run the Linux or Docker build instead.

1. Check that your kernel supports FUSE by looking for the /dev/fuse device. Without FUSE support you cannot mount clouds as local directories.
2. To run CloudDrive2 as a non-root user, install fuse3 the way your distribution's manual describes, confirm that the fusermount3 command runs, then edit /etc/fuse.conf and remove the leading # from the user_allow_other line.
3. Download the archive for your CPU architecture from the download page.
4. Open a terminal and change into the directory holding the archive.
5. Extract it:

   tar zxvf clouddrive-2-linux-$ARCH-$VERSION.tgz

6. Change into the extracted directory and run:

   ./clouddrive

7. You can add clouddrive to your system's startup items or register it as a system service. See your distribution's documentation for how.

1. Arch Linux and its derivatives can install from the AUR package or a third-party repository:

   yay -Syu clouddrive

2. Start clouddrive with systemd and enable it at boot:

   # as root
   systemctl enable --now clouddrive.service
   
   # as your user
   systemctl --user enable --now clouddrive.service

3. Check that clouddrive is running:

   # as root
   systemctl status clouddrive.service
   
   # as your user
   systemctl --user status clouddrive.service

4. Open the management interface in your default browser:

   # recommended
   xdg-open http://localhost:19798
   
   # IPv4
   xdg-open http://127.0.0.1:19798
   
   # IPv6
   xdg-open http://[::]:19798

5. If the page loads slowly or stutters, open it in your browser's private or incognito window.
6. Mounting a local disk after signing in asks for a UID and GID:

   # current user
   id -u
   id -g
   
   # another user
   id -u username
   id -g username

7. The AUR package's local disk mount point: /media/clouddrive.
8. The AUR package's WebDAV mount point: /media/clouddrive-dav. This one needs the davfs2 package.
9. Put your WebDAV username and password into /etc/davfs2/secrets, for example:

   cat << EOF | sudo tee -a /etc/davfs2/secrets
   # personal webdav, application password
   /media/clouddrive-dav user@email.com  mypassword
   EOF

10. Start clouddrive-dav with systemd and enable it at boot (as root):

    systemctl enable --now clouddrive-dav.service

11. Check that clouddrive-dav is running (as root):

    systemctl status clouddrive-dav.service

With Homebrew (recommended)

1. Make sure Homebrew is installed.
2. Install macFUSE before running CloudDrive2, and approve its kernel extension in System Settings — an Apple silicon Mac needs a trip to Recovery first, described in letting macFUSE through. Homebrew can install it too:

   brew install --cask macfuse

3. Install CloudDrive2:

   brew tap cloud-fs/clouddrive2
   brew install clouddrive2

4. Start CloudDrive2:

   brew services start clouddrive2

   This creates a background service that starts again the next time you log in.
5. Open http://localhost:19798 in a browser to reach the management interface.
6. Stop CloudDrive2:

   brew services stop clouddrive2

7. Uninstall CloudDrive2:

   brew services stop clouddrive2
   brew uninstall clouddrive2

8. Upgrade CloudDrive2:

   brew services stop clouddrive2
   brew update
   brew upgrade clouddrive2
   brew services start clouddrive2

Manual install

1. Install macFUSE first and approve it as described in letting macFUSE through.
2. Download the archive for your CPU architecture from the download page.
3. Open a terminal and change into the directory holding the archive.
4. Extract it:

   tar zxvf clouddrive-2-macos-$ARCH-$VERSION.tgz

5. Change into the extracted directory and run:

   ./clouddrive

6. You can add clouddrive to your login items or register it as a system service. See the macOS documentation for how.

For what differs between the Mac App Store build and the direct download, see CloudDrive2 for macOS.

1. Take the .apk from the "core service" section of the download page, install it and open it. It carries its own web management interface.
2. An un-rooted device cannot mount clouds into the local file system. Everything else still works, including multi-cloud backup and the WebDAV service. Without root you can also go through Android's Storage Access Framework, which lets any SAF-aware app read and write files in CloudDrive2 directly.

The CloudDrive2 app with the player is a different package — from Google Play or the app section of the download page.

To run it in a container on a NAS or server, the image is cloudnas/clouddrive2. The host needs shared mount propagation, which many systems already have. How to check it, how to enable it when needed, and a configuration you can copy as it stands are all in the Docker deployment guide.

The third-party Synology and QNAP packages are on the download page.

Synology users take note: File Station cannot create or delete files on a mounted drive. That is a known issue on Synology's side — the ways around it are under common problems.

My Files puts every connected cloud side by side. Uploading, downloading, renaming, moving, deleting and creating folders all work across clouds, not just within one. There are list, grid and waterfall views, with sorting, search and multi-select.

Once a cloud is mounted as a local disk, the same files behave like local files in Explorer, in Finder or in any other program.

Drag a file from one cloud to another the way you would within a single cloud. The hash is read from the source; if the destination uses the same hash algorithm and the hash is already known there, the copy is instant — the server just records a pointer to data it already holds and nothing moves. If the algorithms differ or the hash is not found, the data streams cloud to cloud without touching your local disk, at whatever your bandwidth allows.

You run it from My Files: select the files or folders, click Move/Copy to…, choose a destination folder in the directory tree and click Copy. The task runs in the background, so you can walk away; progress shows on the Tasks page, under both Copy Tasks and Upload Tasks.

Fast cross-cloud copying is a core membership feature. The slow path is not a fault — it means the destination has nothing to match against.

On the Cloud Storages page, Add Cloud Storage → Local Folder under Local Storages adds a directory from the machine, and a copy can use it as the source or the destination. As long as one end is a local folder — pulling files down from a cloud, or pushing local files up — free accounts can copy too, with no membership needed.

Copying into a local folder appears under Upload Tasks. Nothing is backwards: CloudDrive2 runs every copy as one pipeline — read the source, write the destination — and the writing half is always called an upload.

More about cross-cloud copying

1. Go to Backups, click Add Backup, and use the wizard to pick a source directory and one or more destinations. Local folders and cloud directories can each be either.
2. Set the file filter rules (by extension or by name, applied to files and folders independently) and the completion rules — deleting the source file after upload, for instance.
3. Backup works from real-time filesystem monitoring: a change in the source propagates as it happens. You can also schedule full scans to reconcile periodically.

Full scans are resource-hungry. Backup Resource Limits sets the maximum number of concurrent scans (1 by default) and high and low water marks for the upload queue, so scanning a large tree does not pile up thousands of upload tasks.

Backup on a phone is the same feature as on a computer. Only the source differs: a phone's photo library and folders have to be added as a local folder before a backup can use them as its source.

1. Add the local folder first. On the Cloud Storages page, click Add Cloud Storage, pick Local Folder under Local Storages, and choose the directory you want backed up. iOS asks for photo library permission first, after which the library appears at /Documents/Photos: pick that folder to back up photos and videos only, or its parent /Documents to take the app's other files along with them. Android needs storage permission, and then you pick a directory under /sdcard: the camera roll is /sdcard/DCIM, downloads are /sdcard/Download, or take /sdcard itself to back up the whole of internal storage.
2. Then create the backup. On the Backups page, click Add Backup, set the source to the local folder you just added, and name one or more cloud directories as destinations.
3. The destination can be an encrypted folder. Create an encrypted folder on the cloud first and choose it as the destination: photos and files are then encrypted locally before upload, and what the provider stores is ciphertext. That is an encrypted backup.
4. Turn on File System Watcher. Enable it in the backup's settings and it monitors the source folder for changes in real time, so new photos, new videos and newly saved files are backed up on their own — nothing to trigger by hand.

On iOS the photo library is read on demand: the original is pulled from the system library only when the backup uploads it and released straight afterwards, so the library is never duplicated into the app's own storage.

Right-click any cloud directory and choose Create Encrypted Folder, then set a password. Files you put inside are encrypted locally — names and contents both — before they are uploaded, so the provider stores only ciphertext. Once unlocked, reading and writing is no different from an ordinary folder.

Lock it when you are done and the next access asks for the password again. Tick Save Password at creation and you will not have to enter it after a restart.

More about the encrypted filesystem

CloudDrive2 serves every connected cloud back out over WebDAV, so any WebDAV-capable software can connect to it.

• Server address: http://<ip>:19798/dav
• Username: the email address you sign in with — or just the part before the @.
• Password: the password you sign in with.

Core membership also lets you create separate WebDAV users on the WebDAV page, each scoped to a directory and each read-only or not, so you never have to hand out the main password.

More about WebDAV

Third-party applications reach CloudDrive2 with an API token rather than your account password. On the API Tokens page, click Create Token; you can scope it to a root directory, give it an expiry, and set permissions per operation — file read, write and modify, system operations, cloud storage operations and account operations, each with its own sub-items.

The Emby and Jellyfin companion plugin

In a supported cloud's directory, choose Offline download and hand a magnet link or a .torrent file to the provider to fetch. It lands directly in the cloud, using none of your bandwidth and none of your disk. A .torrent can be dragged straight in — it is parsed into a magnet link and added.

115 also has an offline download manager for copying links, deleting tasks, restarting them, or clearing them in bulk by status.

Configuration and data sit in one directory — systemsettings.json, config.toml and log/ are all there. The core service and the apps each have their own location, listed separately below.

The core service

Its location comes from the CLOUDDRIVE_HOME environment variable; with that unset, it is Waytech/CloudDrive2 inside the home directory of the account the service runs as.

The Windows service path sits under System32 because the service runs as the system account, and that is the system account's home directory.

The apps

Every platform app has the same core built in, but its directory is fixed inside the app's own container and does not read CLOUDDRIVE_HOME.

On phones, tablets, TVs and headsets the directory lives inside the app sandbox: uninstalling the app takes it with it, and no file manager can open it. To back up or move a configuration, work from the core service side.

When in doubt, ask the running process. On Linux and NAS boxes: tr '\0' '\n' < /proc/$(pgrep -n clouddrive)/environ | grep CLOUDDRIVE_HOME.

The core service can run a program or script of your choosing once it has started and its mounts are ready. This solves a boot-order problem: anything that depends on a mount path — a Jellyfin or Emby container, or another service — sees an empty directory if it starts before CloudDrive2 does. Having CloudDrive2 restart it afterwards gets the path right.

1. Give the core service the environment variable ENABLE_RUN_AFTER_START=true.
2. Edit systemsettings.json in the configuration directory and add a key:

   "run_after_start": "docker restart jellyfin"

   The value is split on whitespace into a command and its arguments; point it at a script if you need anything more involved.
3. Restart the core service.

The fnOS fpk package already ships with ENABLE_RUN_AFTER_START=true, so there you only need to edit systemsettings.json.

The cause is the reverse proxy buffering the PushMessage gRPC-Web stream: the response headers never arrive, so the front end waits forever, and the dashboard's task count stops refreshing along with it. Turn buffering off for CloudDrive2's location and raise the read timeout:

location / {
    proxy_pass http://127.0.0.1:19798;   # your CD2 HTTP port
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # the important part: a streaming gRPC-Web call must not be buffered
    proxy_buffering off;
    proxy_request_buffering off;
    chunked_transfer_encoding on;
    proxy_set_header Connection "";

    # PushMessage is a long-lived connection, so the read timeout has to be generous
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

macFUSE is not installed. Mounting depends on it for libfuse.2.dylib. Install it from macfuse.github.io, then approve its kernel extension as described in letting macFUSE through — an Apple silicon Mac also needs a trip to Recovery.

Use your own Google OAuth credentials and the block does not apply. In the Google Cloud Console, create a project, enable the Google Drive API, configure the OAuth consent screen and add yourself as a test user, then create an OAuth client ID for its client_id and client_secret. Enter those when you add Google Drive in CloudDrive2, and the authorisation runs through your own application.

The old private "115" interface has been retired: the scan succeeds but the connection cannot be made. Switch to 115open — remove the existing 115, add 115open, then rename it back to the old name. The mount path stays the same, so your existing mount points and backups need no changes.

If instead you get a network error, the machine probably cannot reach the 115 or Tianyi sign-in endpoint. Check DNS and any proxy, then try again.

Most of the time this is a temporary restriction on 115's side, not a CloudDrive2 problem. Too many requests in a short window trips 115's risk control, which usually lifts itself in about half an hour; downloads pinned to a few MB/s are usually a temporary per-account speed limit that clears within 24 hours. Slow in the evening but fine during the day is 115's own policy — no setting changes that.

What you can do: keep the default settings rather than raising concurrency, and use one 115 account from one CloudDrive2 machine — the same account accessed from several machines at once trips risk control much more easily.

123 Pan changed its API endpoint, and older CloudDrive2 releases still talk to the old one. Update to the latest version, then add 123 Pan again.

The browser still holds the first account's session on the cloud's own website. Open CloudDrive2 in an incognito (private) window and add from there, or sign out on the cloud's website first. That is how you add two Baidu Pan or two 115 accounts.

Aliyun Drive and some other providers rate-limit API calls, and this is what the refusal looks like. CloudDrive2 waits and retries automatically until it succeeds, so these log lines need no action. They do not interrupt writes on a mounted drive either: writes land in a local temporary file first, and the upload happens asynchronously in the background.

Work through these in order — most cases give themselves away at the first step.

1. Check the service is running. Press Win+R, open services.msc and find CloudDrive2 Service (service name CloudDrive2). Status should be Running and Startup type should be Automatic. If it is stopped, right-click and start it; if the startup type has been changed to Manual or Disabled, put it back to Automatic under right-click → Properties, or it will not come back after a reboot. The command line shows the same thing:

   sc query CloudDrive2

2. Running, but unreachable from another machine. That is Windows Firewall not allowing the port — 19798 for the core service, plus 19799 if you enabled HTTPS. If http://localhost:19798 works on the machine itself and nothing else can reach it, this is almost always why.
3. The service will not start, or stops right after starting. Usually antivirus. Add CloudDrive2's install directory and WinFSP to the allowlist and try again.

It is a false positive. The installer is code-signed, and the is-XXXX.tmp file being flagged is just Inno Setup's temporary unpacking file, misjudged by a heuristic engine. Add the installer and its target directory to your antivirus allowlist, and report the false positive to the vendor.

It can also be blocked after installation: the service does not start, the mounted drive never appears, or the app is closed outright. Signatures do not stop a heuristic engine, so add CloudDrive2's install directory and WinFSP to the allowlist as well.

Errors carrying "dns error" or "connect error" point at the network of the machine running CloudDrive2: check its DNS and proxy settings, and for Docker deployments check that the container can reach the internet at all. The management page is often open on a different device — your browser being online says nothing about the machine running the service. Test from that machine (or inside the container), for example by curling the URL from the error message.

This is Docker mount propagation: CloudDrive2's FUSE mount appears after the container started, and the default propagation mode hides mounts that arrive later. Add :rslave to the Emby / Jellyfin container's volume mapping — for example -v /mnt:/mnt:rslave — and recreate the container.

Direct links work between two CloudDrives: a remote CloudDrive client asks the server for a direct download URL, and only then does the data bypass the server. Browsing files through the web interface does not use direct links — that traffic still passes through the machine running CloudDrive2.

Check the port first: the service built into the phone and tablet app listens on 29798, not the core service's 19798. Point your player at http://<device IP>:29798 and try again.

Mount points on Windows belong to the account that created them. The core service runs as the system account, so the drives it mounts belong to the system account; the Windows app is an ordinary program running as your signed-in account, so the drives it mounts exist only in your own session. Neither can see the other's — that is how Windows works, not a misconfiguration.

To share a mounted drive over SMB, it has to be mounted by the core service. Windows' SMB server also runs as the system account, so the only mounts it can see, and therefore share, are the ones the system account made. A drive mounted by the app is invisible to it.

Share it as a local disk rather than a network location — to Windows it is a local disk. The same reasoning applies to anything else running as a service: media servers, backup software and scheduled tasks all need the core service's mount, not the app's.

Synology's own File Station does not support write operations on a FUSE-mounted filesystem. This is a known issue on Synology's side and a lot of users hit it: the mount point opens, files read and play, but creating a folder, renaming, deleting, moving and uploading all fail.

The mount itself is fine — the same mount point reads and writes normally over SSH or from another file manager.

Two ways around it: point File Station at CloudDrive2's WebDAV service rather than the FUSE mount path, or use a third-party file manager on the NAS. It is also worth reporting to Synology — the more reports it gets, the likelier it is to be fixed.

The mount point directory has to be empty. This error is most common right after a reboot: some program that also uses the path — Emby, a download tool, a backup script — started before the CloudDrive2 service and wrote into the directory before it was actually mounted, and CloudDrive2 refuses to mount over a non-empty directory.

To fix it, stop whatever is writing there and clear out what was left in the mount point directory — those files are on the local disk, not in the cloud, so check whether anything needs keeping first — then mount again. To stop it recurring, make the programs that depend on the path start after CloudDrive2: set their service to depend on the CloudDrive2 service, or give them a delayed start.

Windows 7 is no longer supported: the TLS stack and runtime libraries it ships with cannot meet what the current version requires for secure connections and its dependencies. Use Windows 10 or 11; if the hardware has to stay, consider the Linux or Docker build instead.