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 cache, mount points, and scheduled upload scripts.

The dashboard installer is the recommended path for new installs. It guides you through provider selection, OAuth authorization (for Dropbox and Google Drive), and encryption setup in a single dialog. The CLI remains fully supported for scripted or advanced use cases.

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

Quick start — Dashboard

The dashboard installer is the recommended path. It handles OAuth authorization in the browser without any manual token copying.

Steps:

1. Open the QuickBox dashboard and go to System → Packages.
2. Search for rclone and open the install dialog.
3. 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.
4. 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).
5. Click Install. The dashboard streams progress. When complete, rclone appears in your service control panel.

Quick start — CLI

The CLI path is available for advanced users or scripting. The flag-driven form (new) passes credentials non-interactively and is what the dashboard uses internally.

Google Drive

# Interactive (prompts for client ID, client secret, and token)
qb install rclone --gdrive -u username
 
# Flag-driven non-interactive
qb install rclone --gdrive \
  --client-id <client_id> \
  --client-secret <client_secret> \
  --token '{"access_token":"...","token_type":"Bearer","refresh_token":"...","expiry":"2026-06-01T00:00:00Z"}' \
  -u username

Dropbox

# Interactive
qb install rclone --dropbox -u username
 
# Flag-driven non-interactive
qb install rclone --dropbox \
  --client-id <app_key> \
  --client-secret <app_secret> \
  --token '{"access_token":"...","token_type":"Bearer","refresh_token":"...","expiry":"2026-06-01T00:00:00Z"}' \
  -u username

Uloz.to

qb install rclone --uloz \
  --uloz-user <username> \
  --uloz-pass <password> \
  --uloz-app-token <token> \
  -u username

Encrypted variant (any provider)

# Add --encrypted with enc-pass and salt-pass to any provider install
qb install rclone --dropbox \
  --client-id <id> --client-secret <secret> \
  --token '...' \
  --encrypted \
  --enc-pass <encryption-password> \
  --salt-pass <salt-password> \
  -u username

Beta channel

# Installs from https://beta.rclone.org
qb install rclone --dropbox --beta -u username
 
# Update on the beta channel
qb update rclone --beta -u username

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.

Common tasks — qb user rclone

Eight per-user operations are available after install. Run them with -u username to target a specific user. Two operations (config-edit and switch-provider) require admin privileges; the other six can be run by the user themselves.

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>

This operation stops the current rclone service, backs up rclone.conf, removes the old remote, creates the new one, swaps the systemd unit templates, and restarts all services. A timestamped backup is saved to ~/.config/rclone/rclone.conf.bak.YYYYMMDDHHMMSS.

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 home-username-rclone-gmedia.mount
 
# Check the Dropbox mergerfs mount
systemctl status home-username-rclone-dmedia.mount
 
# Check the Uloz.to mergerfs mount
systemctl status home-username-rclone-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.
• 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