Rclone

Cloud storage sync and mount — Dropbox, Google Drive, or Uloz.to with optional encryption

Overview

Rclone is a command-line program for syncing files and directories between local storage and cloud providers. QuickBox installs it per user and builds a working directory that includes a cache folder, links to the cloud mounts, and scheduled upload scripts.

Rclone is not a media server or download client — it focuses on syncing, mounting, and optionally encrypting storage paths.

Key features

When to use it

Installation

Install from the Dashboard

Open App Dashboard → Package Management (/dashboard?mode=packages), find rclone in the catalog (browse the File Management category or search), and click Install. The install dialog handles everything in the browser — no manual token copying:

1. Select your Cloud Provider:
   • Dropbox — OAuth-based. Enter your App Key (Client ID) and App Secret (Client Secret), then click Authorize Dropbox. Your browser navigates to Dropbox’s consent page; after you approve, the dashboard redirects back and shows Authorized ✓. See Creating OAuth apps below.
   • Google Drive — Same OAuth flow. Enter Client ID and Client Secret, click Authorize Google Drive. See Creating OAuth apps below.
   • Uloz.to — Direct credentials (no OAuth). Enter your Uloz.to username, account password, and app token. See Generating a Uloz.to app token below.
2. Pick the release channel — Stable (default) or Beta.
3. Toggle Encrypt remote contents if you want server-side encryption. When enabled, enter an encryption password and a separate salt (both must be remembered — there is no recovery).
4. Click Install. The dashboard streams progress and rclone appears in your service control panel when complete.

Reinstall and Remove are in the same Package Management panel. To update, use the amber Update badge on the rclone row in the App Dashboard. What you see is gated by your account: admins manage any user’s apps; regular users manage their own. See App Management for the full flow and Channels & Versions for how Stable/Beta resolve.

Install from the CLI (automation)

The CLI runs the same scripts as the Dashboard and is suited to automation and scripting. The flag-driven form passes credentials non-interactively and is what the dashboard uses internally:

# Google Drive (flag-driven, non-interactive)
qb install rclone --gdrive \
  --client-id <client_id> --client-secret <client_secret> \
  --token '{"access_token":"...","refresh_token":"...","token_type":"Bearer","expiry":"..."}' \
  -u username
 
# Dropbox
qb install rclone --dropbox \
  --client-id <app_key> --client-secret <app_secret> --token '...' -u username
 
# Uloz.to (direct credentials)
qb install rclone --uloz \
  --uloz-user <username> --uloz-pass <password> --uloz-app-token <token> -u username
 
# Add encryption to any provider
qb install rclone --dropbox ... --encrypted --enc-pass <pass> --salt-pass <salt> -u username
 
# Beta channel (install or update)
qb install rclone --dropbox --beta -u username
qb update rclone --beta -u username
 
# Lifecycle
qb reinstall rclone -u username
qb remove rclone -u username

Full flag reference: CLI Reference.

Creating OAuth apps

Dropbox and Google Drive require you to create a developer app to get your Client ID and Client Secret. This is a one-time setup per QuickBox installation.

Dropbox

1. Go to https://www.dropbox.com/developers/apps  and click Create app.

2. Choose Scoped access, then Full Dropbox access. Give the app a unique name — Dropbox app names are globally unique across the entire Dropbox platform, so common names like rclone are already taken. Use something like QuickBox-rclone-yourname.

3. On the app’s Settings tab, find OAuth 2 → Redirect URIs and add:

   https://<your-dashboard-domain>/api/packages/rclone/oauth/dropbox/callback

   Replace <your-dashboard-domain> with the actual domain your QuickBox dashboard is reachable at — the same domain you open in your browser to access the dashboard.

4. Open the Permissions tab on the same app settings page and enable the following scopes (these are what rclone needs to read/write files and metadata):

   • account_info.read
   • files.metadata.write
   • files.content.write
   • files.content.read
   • sharing.write

   Click Submit at the bottom of the Permissions tab. Without these scopes enabled, rclone will fail with permission errors when you try to upload or list files even though the OAuth handshake completes successfully.

5. Copy the App key (this is your client_id) and App secret (this is your client_secret) from the Settings tab.

6. Paste both values into the dashboard install dialog, then click Authorize Dropbox.

Google Drive

1. Go to https://console.cloud.google.com/apis/credentials  — create or select a project for your QuickBox install.
2. Enable the Google Drive API first. Navigate to APIs & Services → Library, search for Google Drive API, and click Enable. Without this step the OAuth handshake will succeed but every rclone API call returns a 403.
3. Configure the OAuth consent screen at APIs & Services → OAuth consent screen:
   • User type: Select External for most QuickBox installs (any Google account can authorize). Choose Internal only if you are a Google Workspace admin and want to restrict the app to users in your own organization.
   • App information: Provide an app name (e.g., QuickBox-rclone), a User support email, and Developer contact information. These values appear on the consent screen users see during authorize.
   • Scopes: Click Add or Remove Scopes and add the three scopes rclone uses:
     • https://www.googleapis.com/auth/docs
     • https://www.googleapis.com/auth/drive
     • https://www.googleapis.com/auth/drive.metadata.readonly
   • Publishing status — choose one path BEFORE you connect:
     • Option A — Publish to production (recommended for QuickBox installs). Click Publish app. Google will warn that the auth/drive scope is “sensitive” and may require verification — for a private personal-use install you can ignore the verification request. Your refresh tokens will not expire and rclone will work indefinitely. The trade-off is that during authorize the user sees an “unverified app” warning screen — proceed via Advanced → Go to (your-app-name) (unsafe).
     • Option B — Keep in Testing mode. Add yourself (and any other authorized users) under Test users. No unverified-app warning during authorize, BUT every grant expires after 7 days, after which you must run qb user rclone -o reauth -u username (or click Re-authorize on the dashboard control card).
4. Create the OAuth client at APIs & Services → Credentials → Create Credentials → OAuth client ID:

   • Application type: Select Web application (NOT Desktop — rclone.org’s general docs mention Desktop because rclone runs its own local listener, but QuickBox uses the dashboard as the OAuth redirect target which requires a Web application client).

   • Name: any identifier you choose (e.g., QuickBox-rclone).

   • Authorized redirect URIs: click Add URI and enter:

     https://<your-dashboard-domain>/api/packages/rclone/oauth/gdrive/callback

   • Click Create.

5. Copy the Client ID and Client Secret from the confirmation dialog and paste both into the dashboard install dialog, then click Authorize Google Drive.

Generating a Uloz.to app token

Uloz.to uses direct credentials — no OAuth flow. You need three values:

• Username — your Uloz.to account login name
• Password — your Uloz.to account password
• App token — a separate per-application token, distinct from your password

To generate an app token, log in to Uloz.to and go to https://uloz.to/in-settings  (the Application tokens section). Create a new token and copy it into the dashboard install dialog or the --uloz-app-token CLI flag.

Configuration and files

QuickBox creates a per-user config directory and a working folder with cache, mounts, and upload scripts.

Where the cloud mount lives

QuickBox mounts each cloud drive as root, in a folder outside your home, and runs rclone itself as your account.

The folder is owned by root. Your account and its group can read it, nobody can change it, and the web server is denied. The entries in /home/username/rclone are links to it, so keep using the paths under /home/username/rclone in your apps. The mergerfs overlay is mounted by the systemd unit run-qbrclone-username-gmedia.mount (dmedia or umedia for the other providers). A username with a hyphen is written with systemd escapes, so list the exact name with systemctl list-units 'run-qbrclone-*'.

QuickBox also keeps user_allow_other off in /etc/fuse.conf: on each update it comments out every setting in that file except mount_max. FUSE then refuses allow_other for a mount an account starts by hand, so such a mount stays private to that account.

Servers installed before this layout are moved over by the next QuickBox update, which restarts each account’s cloud mount once.

Common tasks — rclone operations

Eight per-user operations are available after install. The five most common — status, upload now, view logs, remove lock, and re-authorize — are buttons on the rclone control card in the dashboard, so day-to-day management never needs the terminal. Switch provider is a sixth button, shown to admins only. The remaining two (schedule, config-edit) do not yet have a dashboard control and are run from the CLI; config-edit is additionally admin-gated. Run a CLI op with -u username to target a specific user.

Switching providers with switch-provider

To move a user from one cloud provider to another without reinstalling:

# Switch to Dropbox (OAuth — requires pre-authorized token)
qb user rclone -o switch-provider -u username \
  --dropbox \
  --client-id <app_key> \
  --client-secret <app_secret> \
  --token '{"access_token":"...","refresh_token":"...","token_type":"Bearer","expiry":"..."}'
 
# Switch to Uloz.to (direct credentials)
qb user rclone -o switch-provider -u username \
  --uloz \
  --uloz-user <username> \
  --uloz-pass <password> \
  --uloz-app-token <token>

What the switch does, in order:

1. Saves a timestamped backup of rclone.conf to ~/.config/rclone/rclone.conf.bak.YYYYMMDDHHMMSS.
2. Writes and checks the new provider’s remote while your current setup keeps running.
3. If the account is encrypted, keeps the crypt remote and points it at the encrypt folder of the new provider.
4. Removes the old remote, swaps the systemd units, installs the matching move.sh, and restarts the services. Syncing pauses briefly.
5. Replaces the old provider’s links in ~/rclone with the new provider’s.

Files are not moved. Anything already stored with the old provider stays there, and the new provider shows only what it already holds.

If any step fails, QuickBox puts the saved rclone.conf, units and move.sh back, starts what was running, and reports the switch failed; the previous provider was restored.

Switch from the dashboard (admins)

On the App Dashboard, open the Cloud Sync row of the Storage card and click Manage, then Switch provider. This button is shown to admins only, and the form switches the provider of the account you are logged in as.

1. Pick the New provider (Dropbox, Google Drive, or Uloz.to).
2. For Dropbox or Google Drive, paste the Authorization token, the JSON that rclone authorize prints for the new provider. Client ID and Client secret are optional and only needed when the token came from your own OAuth app. For Uloz.to, enter the username, password, and app token.
3. Click Switch provider and confirm. The dialog repeats that your files are not moved.

To switch another user’s account, use the CLI command above.

Service management

# Restart the rclone mount service
systemctl restart rclone@username
 
# Check mount service status
systemctl status rclone@username
 
# Check the Google Drive mergerfs mount
systemctl status run-qbrclone-username-gmedia.mount
 
# Check the Dropbox mergerfs mount
systemctl status run-qbrclone-username-dmedia.mount
 
# Check the Uloz.to mergerfs mount
systemctl status run-qbrclone-username-umedia.mount
 
# Clear the upload log
qb clean rclone_logs -u username

Encryption

The --encrypted flag creates a crypt remote layered over the main remote. Files stored in the cloud are encrypted; the local mount path shows them transparently decrypted.

Key facts:

• Encryption is configured at install time only. There is no upgrade path from a plaintext install to an encrypted install — you must reinstall.
• The Encryption password (--enc-pass) and the Encryption salt (--salt-pass) must both be provided and must be different from each other. Store them safely — there is no recovery if they are lost.
• All three providers (Dropbox, Google Drive, and Uloz.to) support encryption.
• Switching provider keeps an encrypted setup encrypted: the crypt remote and its passwords stay, and point at the new provider.
• The dashboard install dialog shows the encryption fields when Encrypt remote contents is set to Yes.

# Verify encryption is active for a user
qb user rclone -o status -u username
# Look for "encrypted: yes" in the output

Troubleshooting

Best practices

FAQ

Resources