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.

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, Update, and Remove are available from the same panel. 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.

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. The remaining three (schedule, config-edit, switch-provider) do not yet have a dashboard control and are run from the CLI; config-edit and switch-provider are 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>

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