HYPHAby S33D
Documentation › Integrations

Self-hosted apps: Nextcloud, Jellyfin, Syncthing, Immich, Forgejo, Matrix, Home Assistant, Mastodon

Eight applications people host themselves, read through their native interface: health, users, job queues, storage, synchronisation, with monitor templates and a ready-made dashboard for each.

At a glance

Each application is read the most direct way it offers: its API when its Prometheus metrics miss the essentials (Nextcloud, Jellyfin, Syncthing, Immich), otherwise a profile of the OpenMetrics reader. Everything was tested against the real software running in a container in a S33D test environment (last column).

ApplicationCollectionActivationNamespaceTested on
Nextcloudprobe: status.php and serverinfo APIonce url is setnextcloud.*Nextcloud 35.0.3 (serverinfo 7.0.0)
Jellyfinprobe: /health and server APIauto on 127.0.0.1:8096jellyfin.*Jellyfin 12.4.0
Syncthingprobe: REST APIauto on 127.0.0.1:8384syncthing.*Syncthing 2.1.7 (two linked devices)
Immichprobe: server APIonce url is setimmich.*Immich 3.4.2
Gitea and Forgejogitea or forgejo profile (/metrics)to declaregitea.*Gitea 28.4.0, Forgejo 13.0.5
Matrix Synapsesynapse profile (/_synapse/metrics)to declaresynapse.*Synapse 1.165.0
Home Assistanthomeassistant profile (/api/prometheus)to declarehomeassistant.*Home Assistant 2026.11.2
Mastodonmastodon and mastodon_streaming profilesto declaremastodon.*, mastodon_streaming.*Mastodon 4.7.6 (web, Sidekiq, streaming)

The probes only read: no write, no job started, no call that would make the application contact an outside service. Keys are best put in a file only the agent can read (api_key_file, token_file), read again at each collection: a changed key is picked up without restarting the agent. hypha-agent check-config shows them masked.

integrations:
  nextcloud: {url: "https://cloud.example", token_file: /etc/hypha/nextcloud.token}
  jellyfin: {api_key_file: /etc/hypha/jellyfin.key}          # default url: http://127.0.0.1:8096
  syncthing: {api_key_file: /etc/hypha/syncthing.key}        # default url: http://127.0.0.1:8384
  immich: {url: "http://127.0.0.1:2283", api_key_file: /etc/hypha/immich.key}
  openmetrics:
    - profile: forgejo                                       # or gitea
      bearer_token_file: /etc/hypha/forgejo-metrics.token
    - profile: synapse
    - profile: homeassistant
      bearer_token_file: /etc/hypha/homeassistant.token
    - {profile: mastodon, name: mastodon-web, url: "http://127.0.0.1:9394/metrics"}
    - {profile: mastodon, name: mastodon-sidekiq, url: "http://127.0.0.1:9395/metrics"}
    - profile: mastodon_streaming

The four probes accept instances (several Nextcloud or Syncthing on one machine, each with its name, tag instance_name).

Nextcloud

The probe reads status.php without an account (installed, maintenance mode, database upgrade pending, version), then the API of the serverinfo app (shipped and enabled by default). The simplest is a token of serverinfo's own, which only gives access to these statistics:

sudo -u www-data php occ config:app:set serverinfo token --value "$(openssl rand -hex 24)"

The same token goes into token_file (header NC-Token). Otherwise, an administrator account and an app password (username, password).

File and storage counts are those serverinfo keeps up to date through its background job (occ serverinfo:update-storage-statistics refreshes them). App updates are not read: the probe keeps serverinfo's defaults (skipApps, skipUpdate) so that Nextcloud is never made to query the app store.

Nextcloud 35 (seen in the test) also publishes /metrics in OpenMetrics format (active users, sessions, background jobs), limited to the loopback by default (openmetrics_allowed_clients in config.php): the generic reader can read it, the probe covers the essentials.

Jellyfin

Without a key, the probe reads /health (Healthy, Degraded, Unhealthy) and the public version. With an API key (Dashboard › API Keys), it also reads sessions, libraries and scheduled tasks. Jellyfin 12.4 only accepts the key in the Authorization: MediaBrowser Token="…" header (X-Emby-Token and ?api_key= are refused): that is what the agent sends.

Jellyfin's /metrics (EnableMetrics in system.xml) only publishes .NET runtime and HTTP request metrics: the generic reader can read it as well.

Syncthing

Without a key, the probe reads /rest/noauth/health. With the GUI key (Actions › Settings › GUI › API Key, header X-API-Key), it reads devices, connections, folders and errors every minute. As /rest/db/status is costly for Syncthing, the probe makes one request per folder per minute, and stops at 100 folders.

Syncthing 2.1 also publishes /metrics (key required): folder states and volumes as codes, without errors or missing devices; the REST probe gives them in plain words.

Immich

Without a key, the probe reads /api/server/ping and the version. With an API key (Account Settings › API Keys) holding the server.storage, server.statistics and job.read permissions (and nothing else), it reads the library disk, the number of photos and videos, and the job queues.

Immich's Prometheus metrics (IMMICH_TELEMETRY_INCLUDE=all, ports 8081 and 8082) mostly give internal durations and queue activity, without the disk or the queue state: the generic reader can read them as well. Pitfall seen on Immich 3.4.2: with the default listen address (::), both ports answer "400 Bad Request" to every request; setting IMMICH_HOST=0.0.0.0 makes them readable.

Gitea and Forgejo

In app.ini: [metrics] ENABLED = true (or GITEA__metrics__ENABLED=true, FORGEJO__metrics__ENABLED=true in a container). With [metrics] TOKEN = …, the token goes into bearer_token_file. Forgejo publishes the same gitea_* families as Gitea: the gitea and forgejo profiles are identical and give the same gitea.* names, hence the same dashboards and monitors (instance_name tells them apart).

These are database counts (gauges): the forge's health is followed through openmetrics.can_connect and an HTTP synthetic test on the web interface.

Matrix Synapse

In homeserver.yaml: enable_metrics: true and a dedicated listener, bound to the loopback.

listeners:
  - port: 9000
    type: metrics
    bind_addresses: ['127.0.0.1']

Synapse's public health is followed as well by an HTTP synthetic test on /health (answer OK) of the client listener.

Home Assistant

In configuration.yaml: prometheus: (the native Prometheus integration). Its /api/prometheus route requires a long-lived access token (Profile › Security › Long-lived access tokens), set in bearer_token_file.

A home with several hundred entities goes past the 2,000-series cap of a target (at least two series per entity): raise max_series in the entry, or leave out domains in the configuration of Home Assistant's Prometheus integration (filter). Other families (homeassistant_sensor_unit_*, update times) can be added through metrics and rename.

Mastodon

Mastodon environment variables (seen on 4.7.6): MASTODON_PROMETHEUS_EXPORTER_ENABLED=true, and either MASTODON_PROMETHEUS_EXPORTER_LOCAL=true (web and Sidekiq each serve their own /metrics on MASTODON_PROMETHEUS_EXPORTER_PORT, 9394 by default: one port per service when they run on the same machine), or the bin/prometheus_exporter process that gathers them. MASTODON_PROMETHEUS_EXPORTER_SIDEKIQ_DETAILED_METRICS=true adds the Sidekiq queues (size, latency), MASTODON_PROMETHEUS_EXPORTER_WEB_DETAILED_METRICS=true the HTTP requests. The streaming server publishes /metrics on its port (4000) without any setting.

Puma and Sidekiq queue metrics are gathered by Mastodon at intervals: right after a restart, they are missing for a short while. Public health is followed as well by an HTTP synthetic test on /health (answer OK) and /api/v1/streaming/health.

Monitor templates

In Monitors › New › From a template, family Applications auto-hébergées (self-hosted apps):

Ready-made dashboards

Dashboards › Catalogue, family Applications auto-hébergées: Nextcloud, Jellyfin, Syncthing, Immich, Gitea and Forgejo, Matrix Synapse, Home Assistant, Mastodon (with streaming), installed in one click then editable like any dashboard.

What was tested

Each application ran in a container in the S33D test environment, with test accounts and data created for the occasion. The agent first read it in dry-run mode, then the 0.11 agent of the test host sent its metrics to HYPHA: every check and every metric of the ready-made dashboards was seen there, except synapse.push.processed and synapse.push.failed (no push gateway in the test).

Faults provoked, seen, then back to normal: Nextcloud in maintenance mode (nextcloud.status critical); Jellyfin, Home Assistant and Mastodon's Sidekiq stopped (critical); second Syncthing stopped (syncthing.can_connect critical, and on the first one, device disconnected as a warning with its last connection date); Syncthing folder without its .stfolder marker (critical); Immich queue paused (warning).

Still to be seen on a real installation: Jellyfin transcoding, Synapse pushes and federation between two Matrix servers, a Home Assistant home with several hundred entities (the test had 127), federated Mastodon under load, Immich quotas; Jellyfin failed scheduled tasks and Immich failed jobs are only tested on real responses altered in the tests.

Updated: 21 November 2026