mirror/rclone
1
0
Fork 0
mirror of https://github.com/rclone/rclone.git synced 2026-05-12 10:03:35 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs: update the GUI docs to reflect the new rclone gui

Browse Source
This commit is contained in:
Nick Craig-Wood
2026-04-30 16:46:31 +01:00
parent bd62357998
commit 7400a811fd
2 changed files with 91 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
cmd/gui/gui.go
View File

@@ -88,6 +88,8 @@ Use --user and --pass to set specific credentials:
Use --no-auth to disable authentication entirely:
rclone gui --no-auth
For more help see [the GUI docs](/gui/).
`,
Annotations: map[string]string{
"versionIntroduced": "v1.74",

167
docs/content/gui.md
View File

@@ -2,111 +2,122 @@
title: "GUI"
description: "Web based Graphical User Interface"
versionIntroduced: "v1.49"
status: "Beta"
---
# GUI (Experimental)
# rclone gui
Rclone can serve a web based GUI (graphical user interface). This is
somewhat experimental at the moment so things may be subject to
change.
The `rclone gui` command starts the official Web GUI that comes
bundled with rclone.
Run this command in a terminal and rclone will download and then
display the GUI in a web browser.
With this command, rclone can serve a web-based GUI (graphical user
interface) that is accessible from a normal web browser.
Run it in a terminal and rclone will initialize and then start the
GUI.
```console
rclone rcd --rc-web-gui
rclone gui
```
This will produce logs like this and rclone needs to continue to run to serve
the GUI:
This will produce logs like this. The terminal window needs to stay
open to continue to run the GUI:
```text
2019/08/25 11:40:14 NOTICE: A new release for gui is present at https://github.com/rclone/rclone-webui-react/releases/download/v0.0.6/currentbuild.zip
2019/08/25 11:40:14 NOTICE: Downloading webgui binary. Please wait. [Size: 3813937, Path : /home/USER/.cache/rclone/webgui/v0.0.6.zip]
2019/08/25 11:40:16 NOTICE: Unzipping
2019/08/25 11:40:16 NOTICE: Serving remote control on http://127.0.0.1:5572/
```console
2026/04/14 11:36:04 NOTICE: Serving remote control on http://127.0.0.1:50803/
2026/04/14 11:36:04 NOTICE: Serving GUI on http://127.0.0.1:50802/
2026/04/14 11:36:04 NOTICE: GUI available at http://127.0.0.1:50802/login?pass=XXX&url=http%3A%2F%2F127.0.0.1%3A50803%2F&user=gui
```
This assumes you are running rclone locally on your machine. It is
possible to separate the rclone and the GUI - see below for details.
If you wish to check for updates then you can add `--rc-web-gui-update`
to the command line.
If you find your GUI broken, you may force it to update by add `--rc-web-gui-force-update`.
By default, rclone will open your browser. Add `--rc-web-gui-no-open-browser`
to disable this feature.
You can also add debugging flags when running the GUI, such as `-v`,
which will show more logging output from the rc server.
## Using the GUI
Once the GUI opens, you will be looking at the dashboard which has an overall overview.
Once the browser opens, you will be presented with the Dashboard, the
main screen where you can see the status of your remotes and system.
On the left hand side you will see a series of view buttons you can click on:
At the top, starting from the left, you will see a series of tabs you
can click on. On the right side you will have the logout button and
potentially an "Update available" message if a new rclone version has
been released.
- Dashboard - main overview
- Configs - examine and create new configurations
- Explorer - view, download and upload files to the cloud storage systems
- Backend - view or alter the backend config
- Log out
### Dashboard
(More docs and walkthrough video to come!)
See live metrics, learn if your remotes are near capacity, and read
the changelog for the current version.
### Explorer
Explore and manage both local disks and remotes, download files and
directories and start transfers.
### Remotes
Scroll the list of remotes and tap on it to navigate to the explorer.
There you can navigate the contents of your remotes, transfer,
download, and even upload files.
### Mounts
Mount remotes as local drives on your computer and check on your
existing mounts.
### Serves
Get quick info about your active serve instances, and start new ones.
### Settings
Edit your `rclone.conf` file directly, set logging flags, and
performance parameters.
## How it works
When you run the `rclone rcd --rc-web-gui` this is what happens
When you run `rclone gui` this is what happens
- Rclone starts but only runs the remote control API ("rc").
- The API is bound to localhost with an auto-generated username and password.
- If the API bundle is missing then rclone will download it.
- rclone will start serving the files from the API bundle over the same port as
the API
- rclone will open the browser with a `login_token` so it can log straight in.
- Rclone starts the remote control API ("rc").
- Rclone starts a second server to serve the Web GUI.
- If a port, username or password is not specified, then missing
values will be auto-generated.
- Unless `--no-open-browser` is passed, a browser window will open.
- The URL already contains the username & password, in which case the
GUI will use those values and log you in automatically.
## Advanced use
## Security
The `rclone rcd` may use any of the [flags documented on the rc page](https://rclone.org/rc/#supported-parameters).
It's important to think first about what rclone has access to and what
you might be sharing.
The flag `--rc-web-gui` is shorthand for
A few good measures:
- Download the web GUI if necessary
- Check we are using some authentication
- `--rc-user gui`
- `--rc-pass <random password>`
- `--rc-serve`
- Don't use `--no-auth` (this is for testing only).
- Do not expose to the local network (eg with `--api-addr :5572 --addr
:8080`) unless you trust all devices on your local network. Prefer
`127.0.0.1` or `localhost` (the default).
- Use a strong password and non-obvious usernames like "admin" or
"rclone" if you are using `--user` and `--pass`.
- If you want to host it on a server and access it remotely, make sure
you're only exposing the GUI and not the RC API. They listen on
different ports.
These flags can be overridden as desired.
If you want to access it remotely but want to avoid running a proxy
and exposing ports, you can use Cloudflare Tunnels or localhost.run or
Tailscale (all free).
See also the [rclone rcd documentation](https://rclone.org/commands/rclone_rcd/).
## Options
### Example: Running a public GUI
```console
--addr stringArray IPaddress:Port for the GUI server (default auto-chosen localhost port)
--api-addr stringArray IPaddress:Port for the RC API server (default auto-chosen localhost port)
--enable-metrics Enable OpenMetrics/Prometheus compatible endpoint at /metrics
-h, --help help for gui
--no-auth Don't require auth for the RC API
--no-open-browser Skip opening the browser automatically
--pass string Password for RC authentication
--user string User name for RC authentication
```
For example the GUI could be served on a public port over SSL using an htpasswd
file using the following flags:
## History
- `--rc-web-gui`
- `--rc-addr :443`
- `--rc-htpasswd /path/to/htpasswd`
- `--rc-cert /path/to/ssl.crt`
- `--rc-key /path/to/ssl.key`
### Example: Running a GUI behind a proxy
If you want to run the GUI behind a proxy at `/rclone` you could use these flags:
- `--rc-web-gui`
- `--rc-baseurl rclone`
- `--rc-htpasswd /path/to/htpasswd`
Or instead of htpasswd if you just want a single user and password:
- `--rc-user me`
- `--rc-pass mypassword`
## Project
The GUI is being developed in the: [rclone/rclone-webui-react repository](https://github.com/rclone/rclone-webui-react).
Bug reports and contributions are very welcome :-)
If you have questions then please ask them on the [rclone forum](https://forum.rclone.org/).
In v1.74 the GUI was redone and embedded within rclone for ease of use.