{"id":13588722,"url":"https://github.com/retifrav/rclone-rc-web-gui","last_synced_at":"2025-08-03T08:16:59.543Z","repository":{"id":56546824,"uuid":"247473666","full_name":"retifrav/rclone-rc-web-gui","owner":"retifrav","description":"Web GUI for rclone rc.","archived":false,"fork":false,"pushed_at":"2025-04-21T13:42:25.000Z","size":1095,"stargazers_count":103,"open_issues_count":1,"forks_count":15,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-21T14:52:20.895Z","etag":null,"topics":["rclone","rclone-gui"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/retifrav.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["retifrav"]}},"created_at":"2020-03-15T13:39:07.000Z","updated_at":"2025-04-21T13:42:29.000Z","dependencies_parsed_at":"2025-01-04T18:19:35.704Z","dependency_job_id":"47397abd-f146-4968-811d-8b4843ab74cc","html_url":"https://github.com/retifrav/rclone-rc-web-gui","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/retifrav/rclone-rc-web-gui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/retifrav%2Frclone-rc-web-gui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/retifrav%2Frclone-rc-web-gui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/retifrav%2Frclone-rc-web-gui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/retifrav%2Frclone-rc-web-gui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/retifrav","download_url":"https://codeload.github.com/retifrav/rclone-rc-web-gui/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/retifrav%2Frclone-rc-web-gui/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268512163,"owners_count":24261889,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-03T02:00:12.545Z","response_time":2577,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["rclone","rclone-gui"],"created_at":"2024-08-01T15:06:53.146Z","updated_at":"2025-08-03T08:16:59.472Z","avatar_url":"https://github.com/retifrav.png","language":"TypeScript","funding_links":["https://github.com/sponsors/retifrav"],"categories":["TypeScript","HarmonyOS"],"sub_categories":["Windows Manager"],"readme":"# Web GUI for rclone rc\n\n\u003c!-- MarkdownTOC --\u003e\n\n- [About](#about)\n    - [Supported rc API commands](#supported-rc-api-commands)\n        - [Sync command isn't supported](#sync-command-isnt-supported)\n    - [An example use-case](#an-example-use-case)\n    - [Comparison with rclone-webui-react](#comparison-with-rclone-webui-react)\n- [Building](#building)\n- [How to use it](#how-to-use-it)\n    - [Launching](#launching)\n        - [With --rc-web-gui](#with---rc-web-gui)\n            - [Authentication](#authentication)\n        - [From local path](#from-local-path)\n    - [Possible issues](#possible-issues)\n        - [Wrong username/password](#wrong-usernamepassword)\n        - [CORS header does not match](#cors-header-does-not-match)\n    - [Configuration](#configuration)\n    - [Queue](#queue)\n- [Deployment](#deployment)\n    - [Docker](#docker)\n    - [Generic GNU/Linux server](#generic-gnulinux-server)\n- [Support](#support)\n- [3rd-party](#3rd-party)\n    - [Dependencies](#dependencies)\n    - [Resources](#resources)\n\n\u003c!-- /MarkdownTOC --\u003e\n\n## About\n\nA web-based GUI for [rclone rcd](https://rclone.org/commands/rclone_rcd/) (*remote control daemon*), somewhat implementing a concept of a two-panel file manager like Norton Commander, Total Commander or Far Manager. It can be used for `rclone rcd` running either on a local machine or on a remote host.\n\nCommands are executed via HTTP requests ([XMLHttpRequest](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest)), which are sent to a running `rclone rcd` using [rc API](https://rclone.org/rc/).\n\n![rclone rc GUI](/screenshot.png?raw=true)\n\n### Supported rc API commands\n\n- listing files and directories\n    + [operations/list](https://rclone.org/rc/#operations-list)\n- copying files and directories\n    + [sync/copy](https://rclone.org/rc/#sync-copy)\n    + [operations/copyfile](https://rclone.org/rc/#operations-copyfile)\n- moving files and directories\n    + [sync/move](https://rclone.org/rc/#sync-move)\n    + [operations/movefile](https://rclone.org/rc/#operations-movefile)\n- deleting files and directories\n    + [operations/purge](https://rclone.org/rc/#operations-purge)\n    + [operations/deletefile](https://rclone.org/rc/#operations-deletefile)\n- creating a new directory\n    + [operations/mkdir](https://rclone.org/rc/#operations-mkdir)\n\n#### Sync command isn't supported\n\nThe [sync/sync](https://rclone.org/rc/#sync-sync) command support isn't implemented, and [that is intentional](https://github.com/retifrav/rclone-rc-web-gui/issues/10). Comparing to moving/deleting, the syncing operation is a weapon of mass destruction and can cause severe data loss, so I decided not to have it available in the GUI. Adding support for it is likely to be very trivial, so you most probably will be able to do it yourself, but don't send it as a pull request to this repository as it will be rejected.\n\n### An example use-case\n\nI have a remote seedbox and a local media server (*running on Raspberry Pi*), and I need to transfer files from seedbox to media server (*via SFTP*). And `rclone` is perfect for that, thanks to its `rc` mode, it only needs to have some remote GUI, so I could conveniently control it from my computers/tablets/smartphones.\n\nMore details about the use-case are in [this article](https://decovar.dev/blog/2019/12/26/appletv-kodi-network-share/#downloading-new-files).\n\n### Comparison with rclone-webui-react\n\nThis project is inspired by another web-based GUI for `rclone rc` - [rclone-webui-react](https://github.com/rclone/rclone-webui-react), which provides a very good and nice-looking GUI - big thanks to its creator. But I was not entirely happy with it, as it has (*or at least had back in March 2020*) several inconveniences:\n\n- no queue, so all the transfers go in parallel;\n- no way to cancel a transfer;\n- the GUI feels a bit overloaded and has several non-functioning controls;\n- transfers list has no sorting, so its elements \"jump\" one position to another on every view update.\n\nSo my goal was to improve these points. ~~Although cancelling a transfer turned out to be the [issue](https://github.com/retifrav/rclone-rc-web-gui/issues/4) that originates in the `rclone` itself.~~\n\nHaving a fancy GUI was the least important thing for me, so expect the GUI to be very basic. Although perhaps one could say not basic but clean and simple.\n\n## Building\n\nSkip this section, if you have downloaded a package from [Releases](https://github.com/retifrav/rclone-rc-web-gui/releases) page, because the scripts there are already in JavaScript, so it is ready to be used out-of-the-box.\n\nOtherwise, the project scripts sources are in TypeScript (*starting with `v0.3.0`*), and so they need to be compiled to JavaScript. For that you'll need to have [tsc](https://typescriptlang.org/download) tool, which is installed with `npm`, which is installed with [Node.js](https://nodejs.org/en/download/). Yes, we all hate Node.js, but that's the easiest way I know for installing TypeScript compiler:\n\n``` sh\n$ npm install -g typescript@latest\n```\n\nThis is the only thing what Node.js is needed for, I promise.\n\nOnce you have the tool, compile the sources:\n\n``` sh\n$ cd /path/to/rclone-rc-web-gui\n$ tsc\n```\n\nResulting JavaScript files will be put to `./js` folder. After that you can use the GUI.\n\n## How to use it\n\nBefore launching the GUI, you need to have your remotes configured in `~/.config/rclone/rclone.conf` on the host where you will be running `rclone rcd`.\n\n### Launching\n\n#### With --rc-web-gui\n\nThe easiest would be to let `rclone` handle [downloading and serving](https://rclone.org/gui/) the latest release:\n\n``` sh\n$ rclone rcd --transfers 1 --rc-allow-origin http://localhost:5572 \\\n    --rc-web-gui \\\n    --rc-web-fetch-url https://api.github.com/repos/retifrav/rclone-rc-web-gui/releases/latest\n```\n\nIf you have used this functionality before, then you might have a different web GUI already downloaded in your system (*for example, on Mac OS it would be here: `~/Library/Caches/rclone/webgui`*), and to replace it you'll need to add `--rc-web-gui-force-update` flag.\n\n##### Authentication\n\nBy default `rclone` will generate a random password and will also compose a Base64-encoded authentication token for the `Authorization` header. That token will be also set as an URL query parameter (*`?login_token=HERE-GOES-THE-VALUE`*), which is how the code will be able to get it.\n\nThe GUI URL will be auto-openned in your web-browser with prepended `gui:AUTO-GENERATED-PASSWORD@` for passing through initial authentication prompt, but if you'll stop `rclone rcd` and launch it again, chances are that your browser (*Firefox in my case*) will still show the authentication prompt, despite having `gui:AUTO-GENERATED-PASSWORD@` in the URL.\n\nIn case of launching it on a remote server, you obviously won't get a web-browser auto-openned with provided credentials, so replace `--rc-web-gui` with `--rc-web-gui-no-open-browser` in the CLI, and then it will print the URL with credentials to the `stdout`.\n\nIf you'd like to set your own username/password, then you need to explicitly set `--rc-user`/`--rc-pass` and edit `settings.js` in the `rclone`'s cache directory (*on Mac OS it would be here: `~/Library/Caches/rclone/webgui/current/build/js/settings.js`*). But of course those values will be overwritten on the next GUI update.\n\nOr you can just set `--rc-no-auth` to disable authentication, which is not recommended.\n\n#### From local path\n\nGet a package from [Releases](https://github.com/retifrav/rclone-rc-web-gui/releases) page (*or [build it](#building) from sources*). Set your `rclone rcd` host, port, username and password in `./js/settings.js`.\n\nLaunch `rclone rcd` and point it to the folder with web GUI:\n\n``` sh\n$ cd /path/to/rclone-rc-web-gui\n$ rclone rcd --transfers 1 --rc-user YOUR-USERNAME --rc-pass YOUR-PASSWORD .\n```\n\nor:\n\n``` sh\n$ rclone rcd --transfers 1 --rc-user YOUR-USERNAME --rc-pass YOUR-PASSWORD /path/to/web/gui\n```\n\nI personally prefer to have only 1 ongoing transfer at a time, hence `--transfers 1`. Of course, that only applies to directory operations, as daemon allows to span as many operations as you want (*for which I implemented the [queue](#queue) functionality*).\n\nIf you want to serve web GUI files with a web-server, then launch `rclone` daemon and allow the origin that you'll have with that server:\n\n``` sh\n$ rclone rcd --transfers 1 --rc-user YOUR-USERNAME --rc-pass YOUR-PASSWORD --rc-allow-origin http://127.0.0.1:5572 /path/to/web/gui\n```\n\nYou might also want to [create a service](#an-example-deployment-on-a-gnulinux-server) for running `rclone` daemon.\n\n### Possible issues\n\n#### Wrong username/password\n\nIf you get `401`/`403` errors for all/some of the requests, then check that the values you've provided in `--rc-user` and `--rc-pass` match the `rcloneSettings.user` and `rcloneSettings.pass` values in your `settings.js`.\n\nIf you didn't intend to use authentication, then make sure that you launched `rclone rcd` with `--rc-no-auth` flag and that `rcloneSettings.user`, `rcloneSettings.pass` (*and `rcloneSettings.loginToken`*) are set to `null`.\n\n#### CORS header does not match\n\nIn certain situations you might get [different origins](https://decovar.dev/blog/2019/10/10/the-fuck-is-this-cors/) between server and client, mostly when serving web GUI from a remote host, but that can also happen while testing it on your local host.\n\nIf you get:\n\n\u003e Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at http://127.0.0.1:5572/core/version. (Reason: CORS header ‘Access-Control-Allow-Origin’ does not match ‘http://127.0.0.1:5572/’).\n\nor:\n\n\u003e Access to XMLHttpRequest at 'http://127.0.0.1:5572/core/version' from origin 'http://127.0.0.1:5572' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: The 'Access-Control-Allow-Origin' header has a value 'http://127.0.0.1:5572/' that is not equal to the supplied origin.\n\ncheck if you ran `rclone rcd` with `--rc-allow-origin http://127.0.0.1:5572` option.\n\nAlso note that with `--rc-web-gui` (*instead of `--rc-web-gui-no-open-browser`*) provided for `rclone rcd` it will automatically open the web GUI in browser at \u003chttp://localhost:5572\u003e location, and that might cause a CORS mismatch. If that happens, then you'll need to either open exactly \u003chttp://127.0.0.1:5572\u003e (*if that is what you've set in `--rc-allow-origin`*) or set `rcloneSettings.host` to `http://localhost:5572` in `settings.js`.\n\n### Configuration\n\nThere are several settings available for you to configure in `./js/settings.js`.\n\nAside from self-explanatory variables like host, credentials and timers, there is an object for storing settings for your remotes. An example:\n\n``` js\nvar remotes = {\n    \"disk\": {\n        \"startingFolder\": \"media/somedisk/downloads\",\n        \"canQueryDisk\": true,\n        \"pathToQueryDisk\": \"media/somedisk\"\n    },\n    \"seedbox\": {\n        \"startingFolder\": \"files\",\n        \"canQueryDisk\": false,\n        \"pathToQueryDisk\": \"\"\n    }\n}\n```\n\nHere:\n\n- we have 2 remotes: `disk` and `seedbox`;\n- both have `startingFolder` set, so that will be the folder opened when the remote is chosen in the files panel;\n- `disk` has `canQueryDisk` set to `true`, so it supports querying information about available disk space;\n  - in case of external disks, you'll also need to set their mounted path (`pathToQueryDisk`).\n\n### Queue\n\nAll operations go to the queue and processed one at a time.\n\nObviously, since the queue is implemented on the client side, it's only your browser who knows about it, so if you add more operations from a different host, browser, or even a different tab in the same browser - all of them will go in parallel.\n\nThat also means that once you close the browser or just this tab, the queue will no longer exist. However, all the ongoing transfers will of course still be there, as they are already being handled by `rclone` (*[_async = true](https://rclone.org/rc/#running-asynchronous-jobs-with-async-true)*).\n\n## Deployment\n\n### Docker\n\nThere is a [Docker image](https://github.com/retifrav/rclone-rc-web-gui/blob/master/docker/README.md), which might be the easiest way of running/deploying the project. But if you'd prefer to launch/deploy it yourself, read the instructions below.\n\n### Generic GNU/Linux server\n\nTLDR:\n\n- `rclone rcd` is run as a systemd service;\n- NGINX is used as a reverse proxy;\n- web GUI is available via custom base URL such as `http://IP-ADDRESS-OR-DOMAIN/rclone/`.\n\nGet a package from [Releases](https://github.com/retifrav/rclone-rc-web-gui/releases) page (*or [build it](#building) from sources*):\n\n``` sh\n$ cd /var/www\n$ sudo wget https://github.com/retifrav/rclone-rc-web-gui/releases/latest/download/rclone-rc-web-gui.zip\n$ sudo unzip ./rclone-rc-web-gui.zip \u0026\u0026 sudo rm ./rclone-rc-web-gui.zip\n$ sudo mv ./build ./rclone-rc-web-gui\n$ sudo chown -R www-data:www-data /var/www/rclone-rc-web-gui\n```\n\nCreate a systemd service:\n\n``` sh\n$ sudo nano /etc/systemd/system/rclone-gui.service\n```\n``` ini\n[Unit]\nDescription=rclone web GUI\n\n[Service]\nWorkingDirectory=/media/\nExecStart=rclone rcd --rc-web-gui-no-open-browser --rc-addr 127.0.0.1:8004 --rc-allow-origin http://IP-ADDRESS-OR-DOMAIN --rc-htpasswd /home/SOME-USER/.htpasswd --transfers 1 --multi-thread-streams 1 /var/www/rclone-rc-web-gui/\nRestart=always\nRestartSec=10\nSyslogIdentifier=rclonewebgui\nUser=SOME-USER-WITH-REQUIRED-DISK-ACCESS\nGroup=www-data\n\n[Install]\nWantedBy=multi-user.target\n```\n\nhere:\n\n- `http://IP-ADDRESS-OR-DOMAIN` - the requests will be coming from the same server, so you need to provide here either the IP address of that server or its domain, if you have one. In my case it's just a server in my local network, so I've set this to `http://192.168.1.11` (*static MAC-binded IP address of my server*);\n- `SOME-USER-WITH-REQUIRED-DISK-ACCESS` - a user from which `rclone` will be run, so perhaps it's a good idea to create a new user for this purpose and limit its access to just one folder such as `/media/`;\n- `WorkingDirectory=/media/` - if you'll have your local filesystem as one of the rclone's remote too, then `/media/` would be a starting folder (*for me that's where I mount external disks*);\n- `.htpasswd` - a slightly better security, instead of providing credentials in plain text they are stored [somewhat encrypted](https://github.com/retifrav/scraps/blob/master/_linux/index.md#basic-authentication).\n\nEnable and start the service:\n\n``` sh\n$ sudo systemctl enable rclone-gui.service\n$ sudo systemctl start rclone-gui.service\n```\n\nNGINX configuration:\n\n``` sh\n$ sudo nano /etc/nginx/sites-enabled/default\n```\n``` nginx\nserver {\n    listen 80 default_server;\n    listen [::]:80 default_server;\n\n    server_name _;\n    \n    # a \"parent\" website or some welcome/home page\n    # that is what will open on http://IP-ADDRESS-OR-DOMAIN/\n    root /var/www/html;\n\n    index index.html;\n\n    location / {\n        try_files $uri $uri/ =404;\n    }\n\n    # rclone rc web GUI, will open on http://IP-ADDRESS-OR-DOMAIN/rclone/\n    location /rclone/ {\n        proxy_pass http://localhost:8004/;\n    }\n}\n```\n``` sh\n$ sudo systemctl restart nginx.service\n```\n\nSet the credentials (*the same ones that are in `/home/SOME-USER/.htpasswd`*) and adjust the host value:\n\n``` sh\n$ sudo -u www-data nano /var/www/rclone-rc-web-gui/js/settings.js\n```\n``` js\nvar rcloneHost = \"http://IP-ADDRESS-OR-DOMAIN/rclone\"; // using port 80, so no need to set it\nvar rcloneUser = \"USERNAME-FROM-HTPASSWD\";\nvar rclonePass = \"PASSWORD-FROM-HTPASSWD\";\n```\n\nAdd some remotes to rclone config, if you haven't yet:\n\n``` sh\n$ rclone config\n```\n\nNow you should be able to access the web GUI on \u003chttp://IP-ADDRESS-OR-DOMAIN/rclone/\u003e.\n\n## Support\n\nI've created this project mostly for myself. So it's better to state right away that there is basically no support and that I am not responsible for any possible data loss you might get from using this project. In fact, I don't recommend you to rely on it for anything important, and certainly don't use it on servers with valuable data.\n\nAlso note, that since I use Mozilla Firefox as my main web-browser, that's where I did all the testing, and I've spent very little to none effort on maintaining cross-browser-ability.\n\nIf you discover any issues/bugs, report them [here](https://github.com/retifrav/rclone-rc-web-gui/issues).\n\n## 3rd-party\n\n### Dependencies\n\nThe project doesn't use any external libraries/frameworks, it's just plain HTML/CSS/JS. Well actually, now it's not JavaScript but TypeScript, so there is a requirement to have `tsc` tool for compiling TypeScript sources to JavaScript.\n\n### Resources\n\n- icons are from [Bootstrap Icons](https://icons.getbootstrap.com/)\n- favicon is from [rclone website](https://rclone.org/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fretifrav%2Frclone-rc-web-gui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fretifrav%2Frclone-rc-web-gui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fretifrav%2Frclone-rc-web-gui/lists"}