Schedule rclone backups from a web UI. Built for TrueNAS SCALE, runs in Docker.
Jobs are plain rclone commands. Rclone Runner runs them on a schedule, keeps the logs, and
emails you when something goes wrong. A built-in terminal runs rclone directly, so you set up
remotes with rclone config as usual.
- Jobs with a cron schedule, or run by hand only
- Each job is a list of rclone commands run in order, with shared flags and variables
- Dry runs, and running a single step
- Change the bandwidth limit or pause a job while it runs
- Source sizes and upload time estimates for each step
- Run history and logs
- Email on success, failure or cancel, over any SMTP server (Gmail works with an app password)
git clone https://github.com/Tiaxi/rclone-runner.git
cd rclone-runner
cp .env.example .envIn .env, set:
RCLONE_RUNNER_ADMIN_PASSWORD_HASHto the output ofuv run python -c "from app.auth import hash_password; print(hash_password('your-password'))"RCLONE_RUNNER_SECRET_KEYto a long random string, such as the output ofopenssl rand -hex 32RCLONE_RUNNER_MEDIA_PATHto the folder you want to back up
Then start it and open http://localhost:8000:
docker compose up -d --buildWithout a password hash the login is admin / admin. That's fine for a quick try, not for
anything else.
Clone the repository into a dataset, for example /mnt/tank/apps/rclone-runner, and add to .env:
# 568 is TrueNAS's built-in "apps" user
RCLONE_RUNNER_UID=568
RCLONE_RUNNER_GID=568
RCLONE_RUNNER_DATA_PATH=/mnt/tank/apps/rclone-runner/data
RCLONE_RUNNER_RCLONE_CONFIG_PATH=/mnt/tank/apps/rclone-runner/rclone-config
RCLONE_RUNNER_MEDIA_PATH=/mnt/tank/mediaThe apps user must be able to write to the data and rclone-config folders and read the media
folder. Then install a custom app with Install via YAML and paste:
include:
- /mnt/tank/apps/rclone-runner/docker-compose.ymlUpgrading from an older version that ran as root? Hand the files to the new user first, while no job is running:
sudo chown -R 568:568 /mnt/tank/apps/rclone-runner/data /mnt/tank/apps/rclone-runner/rclone-configThe settings you're most likely to change. .env.example has the rest.
| Variable | What it's for |
|---|---|
RCLONE_RUNNER_HOST_PORT |
Port for the web UI (default 8000) |
RCLONE_RUNNER_UID, RCLONE_RUNNER_GID |
User the container runs as (default 1000:1000) |
RCLONE_RUNNER_ADMIN_USER |
Login name |
RCLONE_RUNNER_ADMIN_PASSWORD_HASH |
Login password hash |
RCLONE_RUNNER_SECRET_KEY |
Signs login sessions |
TZ, RCLONE_RUNNER_TIMEZONE |
Time zone for schedules and timestamps |
RCLONE_RUNNER_RETENTION_DAYS |
Logs older than this are removed when you prune them in Settings (default 30) |
RCLONE_RUNNER_DATA_PATH |
Host folder for the database and logs, mounted at /data |
RCLONE_RUNNER_RCLONE_CONFIG_PATH |
Host folder for rclone.conf, mounted at /config/rclone |
RCLONE_RUNNER_MEDIA_PATH |
Host folder to back up, mounted read-only at /media |
Back up the data and rclone-config folders. Together they hold your jobs, history and remotes.
The schedule is a standard five-field cron expression, such as 0 2 * * 1-5 for 02:00 on
weekdays. Weekdays are 0-7 (0 and 7 are Sunday) or sun-sat. Set either the day of
the month or the weekday, not both. Leave it empty to run the job by hand only.
Each step is a name and an rclone command, separated by |:
Music|sync /media/Music crypt:/Music
Photos|sync /media/Photos crypt:/Photos
Common arguments are added to every step:
--transfers=4 --stats 10s --bwlimit ${BW_LIMIT}
Transfer steps (sync, copy, move, bisync, delete, purge and the like) log rclone's
progress every minute and its totals at the end, which the run pages and emails show. --stats 10s
updates the progress more often, --verbose also logs each file, and --quiet turns it all off.
Environment variables go one per line:
BW_LIMIT=8M
${RUN_DATE} (2026-11-15) and ${RUN_TIME} (05-00-00) are set when a run starts. For
example, --backup-dir crypt:versions/${RUN_DATE}/Music keeps each day's replaced and deleted
files in their own folder. An environment line such as RUN_DATE=2026-11-01 sets it for the job
instead, and prune-dated then counts days from that date too, so it must be a YYYY-MM-DD
date in a job with a prune-dated step.
Those dated folders pile up. rclone delete --min-age can't clear them, because moved files keep
their original modification times. The built-in prune-dated step goes by the folder names
instead. Put it last, after the syncs:
Music|sync /media/Music crypt:/Music --backup-dir crypt:versions/${RUN_DATE}/Music
Prune versions|prune-dated crypt:versions --keep-days 30 --keep-min 7
It lists the folders in crypt:versions and purges each one named YYYY-MM-DD that is more
than 30 days before the run's ${RUN_DATE}, oldest first, logging each one. Anything else in
that folder is left alone.
- The newest
--keep-mindated folders are always kept, whatever their dates, so a wrong clock can't empty it. - It refuses an empty path, the root of a remote or of the file system, paths with
.., and connection string options in the path (remote,opt=x:): set those in the remote's config. - A dry run lists what it would purge and deletes nothing. So does
--dry-runin the step. For any step, a dry run refuses to start if the step or the common arguments contain--dry-run=false(or-n=false), since that would make it a real run. It also refuses rclone commands that make changes even with--dry-run, such asconfig delete,gendocsortest, and those not known to respect it, and flags that write a file, such as--output-file,--combinedor--log-file. Transfers, deletions and listings can be dry-run, exceptbisync, which writes its listings even in a dry run. The same goes for any run with--dry-runor-nin its arguments, orRCLONE_DRY_RUNin its environment. A dry run changes none of the files and remotes the command works on; rclone may still update its own state, such as refreshed login tokens inrclone.confor a backend's cache. - A failed purge stops the step and fails the run. The step runs only if the steps before it succeed, and a folder that doesn't exist yet counts as nothing to prune.
- The common arguments, and any other flags in the step, go to
rclone lsfandrclone purge. Give a flag's value with=in the step, like--b2-hard-delete=true. Filters such as--exclude,--files-fromor--min-age, and--max-depth, are left out, from the arguments and from the environment (RCLONE_EXCLUDE): they are meant for the syncs, andrclone purgerefuses them. - Symlinks are never followed, even with
-L: a dated folder that is a link isn't purged, and links inside a purged folder are deleted as links, not what they point to.
Pausing a running job slows rclone right down instead of stopping it, so it resumes in a couple of seconds. To stop for longer, use Stop: the next run skips files already copied.
Anyone who can log in has full control of the container and every configured remote. The terminal and job steps only accept rclone commands, but rclone can run other programs and print its stored credentials, so this is not a sandbox.
- Set a strong password and your own secret key.
- Don't expose it to the internet. For remote access, put it behind HTTPS or a trusted reverse
proxy that passes the original
Hostheader (or setsX-Forwarded-Host). - Never commit
.env,data/orrclone.conf.
To report a vulnerability, see SECURITY.md.
Needs Python 3.14 and uv.
uv sync --dev
uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
uv run pytest
uv run ruff check . && uv run ruff format --check .MIT. See LICENSE.