Open
Conversation
Adds a native Uptime Kuma monitor type for Syncthing instances, accessed via the Syncthing REST API.
Two check modes:
- health: verifies API reachability, active system errors, and folder sync state (idle/syncing/error). A folder stuck syncing/scanning beyond a configurable threshold is reported as a failure.
- peers: checks device connectivity. Disconnected peers are reported if their last-seen time exceeds a configurable timeout (default 24h). Peers that have never connected are always reported.
Both modes support a unified glob filter (comma-separated patterns) with include/exclude semantics. Paused folders and paused devices are silently ignored in both modes.
Syncthing API key is intentionally never returned to the frontend.
The Syncthing API key always grants full, unrestricted access to the instance — there is no read-only scope or capability restriction. Returning it to the frontend (even behind includeSensitiveData) creates unnecessary exposure: anyone who gains access to a Kuma session would also obtain credentials that can reconfigure or disrupt Syncthing. Once saved, the key is excluded from toJSON() entirely. On save, the key is only overwritten if the client sends a non-empty value, so editing a monitor without touching the key field preserves the existing one. The edit form reflects this with a conditional placeholder and a conditional required attribute.
New columns in the monitor table:
syncthing_url, syncthing_api_key, syncthing_check_type,
syncthing_filter, syncthing_filter_mode,
syncthing_peer_timeout, syncthing_folder_sync_threshold
Contributor
|
Hello and thanks for lending a paw to Uptime Kuma! 🐻👋 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new Syncthing monitor type that checks a Syncthing instance via its REST API (
X-API-Keyauthentication).In this pull request, the following changes are made:
README.mddb/knex_migrations/2026-04-23-0000-add-syncthing-monitor.jsserver/model/monitor.jstoJSONserver/monitor-types/syncthing.jsserver/server.jsserver/uptime-kuma-server.jssrc/lang/en.jsonsrc/pages/EditMonitor.vuetest/backend-test/monitors/test-syncthing.jsI've followed this checklist to avoid unnecessary back and forth
I understand that I am responsible for and able to explain every line of code I submit.
AI disclosure: The implementation was developed with Claude (Anthropic) as a coding assistant, working from a specification I defined. I have manually reviewed every changed file, run the tests locally, and verified the monitor against a real Syncthing instance. I own and can explain all the code submitted here.
Further details
Check modes
Health
Checks overall system health: API reachability, active system errors, and folder sync status. A folder stuck in
syncing/scanningstate beyond a configurable threshold is treated as a failure.Peers
Checks device connectivity. Devices that are disconnected for longer than the configured peer timeout (default: 24 h / 86 400 s) are reported. Devices that have never connected are always reported.
Common features to both modes
*and?wildcards, case-insensitive) on folder labels/IDs or device names/IDsinclude(only check matching items) orexclude(skip matching items)Security note: API key is write-only
The Syncthing API key always grants full, unrestricted access to the Syncthing instance — there is no read-only scope or per-capability restriction. Returning it to the frontend would mean that anyone who gains access to an Uptime Kuma session also obtains credentials capable of reconfiguring or disrupting Syncthing entirely.
For this reason the key is excluded from
toJSON()under all circumstances and is never sent to the browser. The edit form shows a placeholder ("API key saved — leave blank to keep it") when a key is already stored, and omits therequiredvalidation in that case. Submitting the form without changing the field leaves the existing key untouched in the database.This is a deliberate departure from how other credentials are handled in Uptime Kuma, justified by the unusually broad access the Syncthing API key provides.
Known limitation - no re-notification on partial recovery or degradation
Because this monitor reports multiple peers/folders as a single UP/DOWN status, Uptime Kuma only notifies on the first failure and on full recovery. Intermediate changes — a second peer going down, or one peer coming back while others remain down — do not trigger a new notification, even though the failure message changes.
As a workaround, create one monitor per peer or folder using the include filter with a single name/ID.
This is a core Kuma limitation, not specific to this monitor. A proper fix would require like a
notifyOnMessageChangehook in the heartbeat processor. Tracked for a future PR.Test plan
node --test test/backend-test/monitors/test-syncthing.js)npm run lintpasses (no new errors)npm run fmtappliedScreenshots