syncthingctl is a command-line tool designed to manage and interact with Syncthing instances. It provides developers and system administrators with a powerful way to monitor and control Syncthing operations without relying on its web-based interface.
Key Features:
Check the status of Syncthing instances
Trigger rescan, pause, resume, or restart operations
View and modify raw configuration files
Add items to ignore patterns for specific folders
Support for Bash completion with folder and device names
Audience & Benefit:
Ideal for developers and system administrators who need precise control over Syncthing configurations. It enables efficient management of file synchronization tasks, streamlining workflows and allowing for custom-tailored integrations.
This tool can be installed via winget, making it accessible for users to integrate into their existing development environments.
README
Syncthing Tray
Syncthing Tray provides a tray icon and further platform integrations for
Syncthing. Checkout the
website for an overview and
screenshots.
The following integrations are provided:
Tray application (using the Qt framework)
Context menu extension for the Dolphin file manager
Checkout the official forum thread for discussions
and announcement of new features.
This README document currently serves as the only and main documentation. So read on for details about
the configuration. If you are not familiar with Syncthing itself already you should also have a look at
the Syncthing documentation as this README is only going to cover the
Syncthing Tray integration.
Syncthing Tray works with Syncthing v1 (and probably v0). Note that Syncthing Tray is maintained, and
updates will be made to support future Syncthing versions as needed.
Supported platforms
Official binaries are provided for Windows (for i686, x86_64 and aarch64) and GNU/Linux (for x86_64) and can be
download from the website and the
release section on GitHub. This is only a fraction of
the available downloads, though. I also provide further repositories for some GNU/Linux distributions. There are
also binaries/repositories provided by other distributors. For a list with links, checkout the
"Download" section of this document.
Syncthing Tray is known to work under:
Windows 10 and 11
KDE Plasma
Openbox using lxqt/LXDE or using Tint2
GTK-centered desktops such as Cinnamon, GNOME and Xfce (with caveats, see remarks below)
COSMIC (only simple tray menu works, see remarks below)
Sway/Swaybar/Waybar (with caveats, see remarks below)
Android (still experimental and in initial development)
This does not mean Syncthing Tray is actively tested on all those platforms or
desktop environments.
For Plasma 5 and 6, there is in addition to the Qt Widgets based version also a "native"
Plasmoid. Note that the latest version of the Plasmoid generally also requires the
latest version of Plasma 5 or 6 as no testing on earlier versions is done. Use the Qt
Widgets based version on other Plasma versions. Checkout the
"Configuring Plasmoid" section for further details.
On GTK-centered desktops have a look at the
Arch Wiki
for how to achieve a more native look and feel. Under GNOME one needs to install
an extension for tray icon support (unless
one's distribution already provides such an extension by default).
Limitations of your system tray might affect Syncthing Tray. For instance when using the mentioned GNOME
extension the Syncthing Tray UI shown in the screenshots is only shown by double-clicking
the icon. If your system tray is unable to show the Syncthing Tray UI at all like on COSMIC you can still use
Syncthing Tray for the tray icon and basic functionality accessible via the menu.
Note that under Wayland-based desktops there will be positioning issues. The Plasmoid is not affected
by this, though.
The documentation on known bugs and workarounds
contains further information and workarounds for certain platform-specific issues like the positioning issues under
Wayland.
Documentation on how to use Syncthing Tray on Android can be found in a separate document.
Features
Provides quick access to most frequently used features but does not intend to replace the official web-based UI
Check state of folders and devices
Check current traffic statistics
Display further details about folders and devices, like last file, last
scan, items out of sync, ...
Display ongoing downloads
Display Syncthing log
Trigger re-scan of a specific folder or all folders at once
Open a folder with the default file browser
Pause/resume a specific device or all devices at once
Pause/resume a specific folder
View recent history of changes (done locally and remotely)
Shows "desktop" notifications
The events to show notifications for can be configured
Uses Qt's notification support or a D-Bus notification daemon directly
Provides a wizard for a quick setup
Allows monitoring the status of the Syncthing systemd unit and to start and stop it (see section
"Configuring systemd integration")
Provides an option to conveniently add the tray to the applications launched when the desktop environment starts
Can launch Syncthing automatically when started and display stdout/stderr (useful under Windows)
Browsing the global file tree and selecting items to add to ignore patterns.
Provides quick access to the official web-based UI
Can be opened as regular browser tab
Can be opened in a dedicated window utilizing either
Qt WebEngine/WebKit
the "app mode" of a Chromium-based browser (e.g. Chrome and Edge)
Allows switching quickly between multiple Syncthing instances
Also features a simple command line utility syncthingctl
Check status
Trigger rescan/pause/resume/restart
Wait for idle
View and modify raw configuration
Supports Bash completion, even for folder and device names
Also bundles a KIO plugin which shows the status of a Syncthing folder and allows to trigger Syncthing actions
in the Dolphin file manager
Allows building Syncthing as a library to run it in the same process as the tray/GUI
English and German localization
Does this launch or bundle Syncthing itself? What about my existing Syncthing installation?
Syncthing Tray does not launch Syncthing itself by default. There should be no interference with your existing
Syncthing installation. You might consider different configurations:
If you're happy how Syncthing is started on your system so far just tell Syncthing Tray to connect to your currently
running Syncthing instance in the settings.
When starting Syncthing via systemd it is recommended to enable the systemd integration in the settings (see section
"Configuring systemd integration").
When starting Syncthing by other means (e.g. as Windows service) there are no further integrations provided. Hence,
Syncthing Tray cannot know whether Syncthing is expected to be running or not. It will therefore unconditionally
attempt to connect with Syncthing continuously as-per the configurable re-connect interval. It will also
unconditionally notify when disconnecting from Syncthing if this kind of notification is enabled (so it makes perhaps
most sense to disable it).
If you would like Syncthing Tray to take care of starting Syncthing for you, you can use the Syncthing launcher
available in the settings. Note that this is not supported when using the Plasmoid.
The Linux and Windows builds provided in the release section on GitHub
come with a built-in version of Syncthing which you can consider to use. Note that the built-in version of Syncthing
will be only updated when you update Syncthing Tray (either manually or via the its updater). The update feature of
Syncthing itself is not available this way.
In any case you can simply point the launcher to the binary of Syncthing which you have to download/install separately.
This way Syncthing can be (but also has to be) updated independently of Syncthing Tray, e.g. using Syncthing's own
update feature.
It is also possible to let Syncthing Tray connect to a Syncthing instance running on a different machine.
Note that the experimental UI tailored for mobile devices is more limited. So far it can only start a built-in
version of Syncthing or connect to an externally started Syncthing instance. It will set a custom config/data
directory for Syncthing so any Syncthing instance launched via the mobile UI will not interfere with existing setups.
Installation and deinstallation
Checkout the website for obtaining the executable
or package. This README also lists more options and instructions for building from sources.
If you are using one of the package manager options you should follow the usual workflow of that package manager.
Otherwise, you just have to extract the archive and launch the contained executable. Especially on Windows, please
read the notes on the website before filing any issues. Note that automatic updates haven't been implemented yet.
To uninstall, just delete the executable again.
For further cleanup you may ensure that autostart is disabled (to avoid a dangling autostart entry). You may also
delete the configuration files (see "Location of the configuration file"
section below).
Configuration
You need to configure how Syncthing Tray should connect to Syncthing itself. The previous
section "Does this launch or bundle Syncthing itself…" mentions available options. Additionally,
a wizard is shown on the first launch which can guide though the configuration for common
setups. If you have dismissed the wizard you can still open it at any point via a button on the
top-right corner of the settings dialog.
It may be worthwhile to browse though the pages of the configuration dialog to tweak Syncthing
Tray to your needs, e.g. to turn off notification you may find annoying.
Location of the configuration file
The configuration file is usually located under ~/.config/syncthingtray.ini on GNU/Linux and
under %appdata%\syncthingtray.ini on Windows. For other platforms and further details,
checkout the
Qt documentation
(Syncthing Tray uses the "IniFormat"). For portable installations it is also possible to place
an empty file called syncthingtray.ini directly next to the executable.
You may remove the configuration file under the mentioned location to start from scratch.
Note that this only counts for Syncthing Tray. For Syncthing itself, checkout
its own documentation.
The Plasmoid is using the same configuration file but in addition also Plasma's configuration
management for settings specific to a concrete instance of the Plasmoid.
The experimental UI tailored for mobile devices is using a distinct configuration which is
located under ~/.config/Martchus/Syncthing Tray on GNU/Linux and
/storage/emulated/0/Android/data/io.github.martchus.syncthingtray on Android and
%appdata%\Martchus\Syncthing Tray on Windows. The configuration and database of Syncthing
itself are also located within this directory when Syncthing is launched via the mobile UI.
Connect to Syncthing via Unix domain socket
When using a Unix domain socket as Syncthing GUI address (e.g. by starting Syncthing with
parameters like --gui-address=unix://%t/syncthing.socket --skip-port-probing) you need to
specify the path to the socket as "Local path" in the advanced connection settings. This
setting requires Qt 6.8 or higher. You still need to provide the "Syncthing URL" using the
unix+http as scheme (e.g. unix+http://127.0.0.1:8080 where the host and port are not
actually used). The web view will not work with this, though.
Syncthing Tray is a single-instance application. So if you try to start a second instance the
second process will only pass arguments to the process that is already running and exit. This
is useful as is prevents one from accidentally launching two Syncthing instances at the same
time via the built-in Syncthing launcher. It also allows triggering certain actions via launch
options, see "Configuring hotkeys" for details.
Besides that there are a few other notable launch options:
--connection [config name] …:
Shows tray icons for the specified connection configurations (instead of just a single tray
icon for the primary connection configuration). Syncthing Tray will still behave as a
single-instance application so a single process will handle all those tray icons and the
built-in Syncthing launcher will launch Syncthing only once.
--replace:
Changes the single-instance behavior so that the already running process is existing and
the second process continues to run. This is useful to restart Syncthing Tray after
updating.
--new-instance:
Disables the single-instance behavior. This can be useful to run two instances of
Syncthing itself via the built-in launcher in parallel. This only makes sense if those
two Syncthing instances use a different configuration/database which can be achieved with
a portable configuration.
--single-instance:
Avoids the creation of a second tray icon if Syncthing Tray is already running. (Without
this option, Syncthing Tray will still show another tray icon despite its single-instance
behavior.)
--help:
Prints all launch options.
Those were just the options of the tray application. Checkout
"Using the command-line interface" for an
overview of available tooling for the command-line.
Configuring Plasmoid
The Plasmoid requires installing Syncthing Tray via distribution-specific packaging. It is
not available via the generic GNU/Linux download or the Flatpak. Checkout the relevant notes
on the downloads page for
available options and details on package names. For further information about supported versions
of Plasma, checkout the "Supported platforms" section.
The built-in Syncthing launcher is not available in the Plasmoid as it is recommended to rely on
the systemd integration instead.
Once installed, Plasma might need to be restarted for the Plasmoid to be selectable.
The Plasmoid can be added/shown in two different ways:
It can be shown as part of the system tray Plasmoid.
This is likely the preferred way of showing it and may also happen by default.
Whether the Plasmoid is shown as part of the system tray Plasmoid can be configured
in the settings of the system tray Plasmoid. You can access the settings of the
system tray Plasmoid from its context-menu which can be opened by right-clicking on
the arrow for expanding/collapsing.
The list of entries in the system tray Plasmoid settings might show an
invalid/disabled entry for Syncthing in some cases. There should always nevertheless
also be a valid entry which can be used. See the
related issue for details.
This way it is also possible to show the icon only in certain states by choosing to
show it only when important and selecting the states in the Plasmoid's settings.
Configuring the size has no effect when the Plasmoid is displayed as part of the
system tray Plasmoid.
It can be added to a panel or the desktop like any other Plasmoid. Note that under
recent Plasma versions the configuration no longer seems to be stored persistently.
So I recommend using the previous option or following the
related issue for workarounds.
This allows you to add multiple instances of the Plasmoid but it is recommended to pick
only one place. For that it makes also most sense to ensure the autostart of the
stand-alone tray application is disabled. Otherwise you would end up having two icons
at the same time (one of the Plasmoid and one of the stand-alone application).
The Plasmoid cannot be closed via its context menu like the stand-alone application.
Instead, you have to disable it in the settings of the system tray Plasmoid as explained
before. If you have added the Plasmoid to a panel or the desktop you can delete it like
any other Plasmoid.
The Dolphin integration can be enabled/disabled in Dolphin's context menu settings. It will
read Syncthing's API key automatically from its config file. If your Syncthing config file is
not in the default location you need to select it via the corresponding menu action.
Configuring systemd integration
The next section explains what it is good for and how to use it. If it doesn't work on your
system please read the subsequent sections as well before filing an issue.
Using the systemd integration
With the system configured correctly and systemd support enabled at build-time the following
features are available:
Starting and stopping the systemd unit of Syncthing
Consider the unit status when connecting to the local instance to prevent connection attempts
when Syncthing isn't running anyways
Detect when the system has just been resumed from standby to avoid the "Disconnect"
notification in that case
However, these features are optional. To use them they must be enabled in the settings dialog
first.
It is recommended to enable "Consider unit status …". Note that Syncthing might still not be immediately
ready to serve API requests when the systemd unit turns active. Hence it is still required to configure
a re-connect interval. The re-connect interval will only be in effect while the systemd unit is active.
So despite the re-connect interval there will be no connection attempts while the systemd unit is
inactive. That's all the systemd integration can optimize in that regard.
Be aware that Syncthing Tray assumes by default that the systemd unit is a
user unit. If you are using
a regular system-wide unit (including those ending with …@username) you need to enable the
"System unit" checkbox in the settings. Note that starting and stopping the system-wide Syncthing
unit requires authorization (systemd can ask through PolicyKit).
Required system configuration
The communication between Syncthing Tray and systemd is implemented using systemd's D-Bus service.
That means systemd's D-Bus service (which is called org.freedesktop.systemd1) must be running on
your D-Bus. For user units the session D-Bus is
relevant and for regular units (including those ending with …@username) the system D-Bus is relevant.
It seems that systemd's D-Bus service is only available when D-Bus itself is started via systemd. That
is by default the case under Arch Linux and openSUSE and likely most other modern distributions where
it is usually started via "socket activation" (e.g. /usr/lib/systemd/user/dbus.socket for the session
D-Bus).
All of this counts for the session D-Bus and for the system D-Bus although the startup of the session
D-Bus can be screwed up particularly easy. One easy way to screw it up is to start a second instance of
the session D-Bus manually e.g. via dbus-run-session. When starting the session D-Bus this way the
systemd integration will not work and you will likely end up with two session D-Bus processes. It is
also worth noticing that you do not need to set the DBUS_SESSION_BUS_ADDRESS variable manually
because the systemd file dbus.socket should take care of this.
The built-in launcher can be accessed and configured within the settings dialog. It is not available
in the Plasmoid. It allows you to launch Syncthing
as an external process by leaving "Use built-in Syncthing library" unchecked.
When launching Syncthing this way you have to specify the path to an executable, e.g. one you
have downloaded from the upstream Syncthing website. It is also
possible use the Syncthing version built into Syncthing Tray by pointing it to the Syncthing Tray
executable and specifying the arguments syncthing serve.
as part of the Syncthing Tray UI process by checking "Use built-in Syncthing library".
This will always use the Syncthing version built into Syncthing Tray.
Launching Syncthing as part of the UI process will interfere with
Syncthing's configuration for lowering the priority.
You should therefore avoid using this configuration option or start Syncthing as external process
instead. Otherwise the configuration option might have no effect or will affect the UI of Syncthing
Tray as well causing it to become slow/unresponsive.
This option might not be available on your build of Syncthing Tray, e.g. it is disabled on the
packages I provide for GNU/Linux distributions as it makes most sense to use the
distribution-provided version of Syncthing there.
It is recommended to enable "Consider process status …". Note that Syncthing might not be immediately
ready to serve API requests when started. Hence it is still required to configure a re-connect interval.
The re-connect interval will only be in effect while the Syncthing process is running. So despite the
re-connect interval there will be no connection attempts while the Syncthing process is not running.
Configuring hotkeys
Use the same approach as for launching an arbitrary application via a hotkey in your graphical
environment. Make it invoke
syncthingtray --trigger to show the Qt Widgets based tray menu.
syncthingtray --webui to show the web UI.
syncthingctl [...] to trigger a particular action. See syncthingctl -h for details.
The Plasmoid can be shown via a hot-key as well by configuring one in the Plasmoid settings.
Using the command-line interface
Checkout syncthingctl --help and syncthingtray --help for available options. More details
can be found in the CLI documentation.
RPM *.spec files and binaries are available via openSUSE Build Service
remarks
Be sure to add the repository that matches the version of your OS and to keep it
in sync when upgrading.
The linked download pages might be incomplete, use the repositories URL for a full
list.
Old packages might remain as leftovers when upgrading and need to be cleaned up
manually, e.g. zypper rm libsyncthingconnector1_1_20 libsyncthingmodel1_1_20 libsyncthingwidgets1_1_20.
openSUSE Leap 15, Fedora 27, Debian 10 and Ubuntu 18.04 are recent enough (be sure
the packages libglx0, libopengl0 and libegl1 are installed on Debian/Ubuntu)
Supports X11 and Wayland (set the environment variable QT_QPA_PLATFORM=xcb to disable
native Wayland support if it does not work on your system)
The executable is signed in addition using ECDSA for verification by the updater. The public key can be found
in the source code and verification
is possible with stsigtool or OpenSSL.
Windows SmartScreen will likely block the execution (you'll get a window saying "Windows protected your PC");
right click on the executable, select properties and tick the checkbox to allow the execution
Antivirus software often wrongly considers the executable harmful. This is a known problem. Please don't create
issues about it.
The Qt 6 based version is stable and preferable but only supports Windows 10 version 1809 and newer.
The Qt 5 based version should still work on older versions down to Windows 7 although this is not regularly checked.
On Windows 7 the bundled Go/Syncthing will nevertheless be too new; use a version of Go/Syncthing that is older
than 1.21/1.27.0 instead.
The executable is signed in addition using ECDSA for verification by the updater. The public key can be found
in the source code and verification
is possible with stsigtool or OpenSSL.
or, using Winget, type winget install Martchus.syncthingtray in a Command Prompt window.
or, using Scoop, type scoop bucket add extras & scoop install extras/syncthingtray.
All code - unless stated otherwise in a comment on top of the file - is licensed under GPL-2-or-later. This does not apply
to code contained in Git repositories included as Git submodule (which contain their own README and licensing information).
Attribution for 3rd party content
Syncthing Tray contains icons from various sources:
All other icons found in this repository are taken from the KDE/Breeze project.
None of these icons have been (intentionally) modified so no copyright for modifications is asserted.
Some of the code is based on code from other open source projects:
Code in tray/gui/quick/quickicon.cpp and the corresponding header file originates from
Kirigami. The comments at the beginning of those files state the original
authors/contributors.