Syncthing Tray

Syncthing Tray provides a tray icon and further platform integrations for Syncthing. Check out the website for an overview and screenshots.

The following integrations are provided:

• Tray application
• Context menu extension for the Dolphin file manager
• Plasmoid for KDE Plasma
• Command-line interface
• Android app (still experimental)
• Qt-ish C++ library

This document is the main documentation of Syncthing Tray. It is available on the Syncthing Tray website and on GitHub. If you are not already familiar with Syncthing itself, you should also have a look at the Syncthing documentation as this document only covers Syncthing Tray.

Check out the official forum thread for discussions and announcements of new features.

Issues can be created on GitHub but please check the documentation on known bugs and workarounds before.

Syncthing Tray works with Syncthing v2. It also very likely still works with Syncthing v1 (and even v0) but this is not regularly tested anymore. 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), GNU/Linux (for x86_64) and Android (for x86_64 and aarch64). They can be downloaded from the website and the release section on GitHub. However, this is only a fraction of the available downloads. I also provide further repositories for some GNU/Linux distributions. There are also binaries/repositories provided by other distributors. For a list of links, check out 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)
• Awesome
• i3
• macOS
• Deepin Desktop Environment
• Sway/Swaybar/Waybar (with caveats, see remarks below)
• Android (still experimental, see Android-specific documentation)

This does not mean Syncthing Tray is actively tested on all of these platforms or desktop environments.

For Plasma 5 and 6, in addition to the Qt Widgets based version, there is 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 version on other Plasma versions. Check out 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 your 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 accessible by double-clicking the icon. If your system tray, like on COSMIC, is unable to show the Syncthing Tray UI, 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. However, the Plasmoid is not affected by this.

The documentation on known bugs and workarounds contains further information and workarounds for certain platform-specific issues, such as the positioning issues under Wayland.

Features

This section lists the most important features. Most features are optional and configurable. Some features are platform-dependent.

• Tray icon displaying the overall status of Syncthing
• Quick access to the most used features but no full replacement of the official web-based UI
  • Check state of folders and devices
  • Check current traffic statistics
  • Display further details about folders and devices, such as last file, last scan, items out of sync, etc.
  • Display ongoing downloads
  • Display Syncthing log
  • Trigger a re-scan of a specific folder or all folders
  • Open a folder with the default file browser
  • Pause/resume a specific device or all devices
  • Pause/resume a specific folder
  • View recent history of changes (done locally and remotely)
• Notifications for various events
• Wizard for a quick setup
• Autostart configuration
• Launcher for Syncthing
• Systemd integration
• Suspending synchronization while the network connection is metered
• Browser for the global file tree and selecting items to add to ignore patterns
• Quick access to the official web-based UI
  • Can be opened as regular browser tab
  • Can be opened in a dedicated window using either
    • Qt WebEngine/WebKit
    • the "app mode" of a Chromium-based browser (e.g. Chrome and Edge)
• Switching quickly between multiple Syncthing instances; monitoring multiple Syncthing instances
• App for running Syncthing under Android
• Simple command line utility syncthingctl complementing the official CLI of Syncthing
  • Check status
  • Trigger rescan/pause/resume/restart
  • Wait for idle
  • View and modify raw configuration
  • Bash completion with support for folder and device names
• KIO plugin for the Dolphin file manager
  • Rescan selected items
  • Rescan entire Syncthing folder
  • Pause/resume Syncthing folder
  • See also the screenshots
• Building Syncthing as a library to run it in the same process as the tray/GUI

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 with how Syncthing is started on your system, 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 only be updated when you update Syncthing Tray (either manually or via 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.
  • Check out the "Configuring the built-in launcher" section for further details.
• 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. Currently, 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

Check out the website for obtaining the executable or package. This documentation also lists more options and instructions for building from sources.

If you are using a package manager, you should follow its usual workflow.

Otherwise, you have to extract the archive and launch the contained executable. Especially on Windows, please read the notes on the website before filing any issues. To uninstall, delete the executable again.

Notifications about updates can be enabled in the settings which also allow upgrading to a new version if available. This simply replaces the executable at its location, which needs to be writable. The old executable is renamed/preserved as a backup and you can simply rename it back if you need to go back to the previous version.

For further cleanup, you may want to 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…", describes available options. Additionally, a wizard is shown on the first launch, which can guide you through the configuration for common setups. If you have dismissed the wizard, you can still open it at any time via a button on the top-right corner of the settings dialog.

It may be worthwhile to browse through the pages of the configuration dialog to tweak Syncthing Tray to your needs, e.g., to turn off notifications 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, check out the Qt documentation (Syncthing Tray uses the "IniFormat"). For portable installations, it is also possible to create an empty file called syncthingtray.ini directly next to the executable.

You can remove the configuration file from the mentioned location to start from scratch.

Note that this only applies to Syncthing Tray. For Syncthing itself, check out its own documentation.

The Plasmoid uses the same configuration file but also uses Plasma's configuration management for settings specific to a concrete instance of the Plasmoid.

The experimental UI tailored for mobile devices uses 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 the Syncthing GUI address (e.g., by starting Syncthing with parameters such as --gui-address=unix://%t/syncthing.socket --no-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). However, the web view will not work with this.

Single-instance behavior and launch options

This section does not apply to the Android app, the Plasmoid and the Dolphin integration.

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 then exit. This is useful as it 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.

There are a few other notable launch options:

• --connection [config name] …: Shows tray icons for the specified connection configurations (instead of 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 proc