Cloudflare Tunnel Monitor smart home integration, free and open source
Monitor your Cloudflare tunnels: status, connections, alerts and scenes.
Published by prohand
- Devices
- Version 0.0.1
- Requires Gladys >=5.1.0
- ★ 0
This integration watches your Cloudflare tunnels (cloudflared) from
Gladys: is each tunnel up, how many connections does it hold, and is the
cloudflared running in your home still connected? Every tunnel becomes a
Gladys device, a status change can start a scene, and a dashboard widget shows
everything at a glance.
It only reads: it never creates, changes or deletes a tunnel.
Two sources, use one or both
| Source | What you need | What you get |
|---|---|---|
| Cloud | A Cloudflare API token and your account ID | Every tunnel of the account, with the status Cloudflare computes |
| Local | The metrics address of a cloudflared on LAN | That connector's own state — still answering when the Internet is down |
Use both for the best result: the cloud sees every tunnel, the local connector keeps answering when the Internet link is what broke.
Cloud: create the API token
- Open the Cloudflare dashboard, then My Profile → API Tokens (https://dash.cloudflare.com/profile/api-tokens).
- Create Token → Custom token → Get started.
- Give it a name (e.g.
Gladys), and add one permission: Account → Cloudflare Tunnel → Read. - Under Account Resources, include the account that holds your tunnels.
- Continue to summary → Create Token, then copy the token. Cloudflare shows it only once.
The token is read-only: even if it leaked, nobody could change a tunnel with it.
Cloud: find the account ID
In the Cloudflare dashboard, open your account: the Account ID is shown on
the Overview page (right column), or in the account menu → Copy account
ID. It is 32 characters, digits and letters a to f.
Local: expose the metrics of cloudflared
cloudflared has a small metrics server. By default it only listens on the
machine itself, on a random port: give it a fixed address Gladys can reach.
- Command line: add
--metrics 0.0.0.0:2000, for examplecloudflared tunnel --metrics 0.0.0.0:2000 run --token <tunnel token>. config.yml: add the linemetrics: 0.0.0.0:2000.- Docker: same option in the command, and publish the port (
-p 2000:2000).
Check from another machine: curl http://<cloudflared host>:2000/ready must
answer something like {"status":200,"readyConnections":4,"connectorId":"…"}.
The metrics server shows no secret, but keep it on your local network: do not open that port to the Internet.
Configuration
| Field | Meaning |
|---|---|
| Cloudflare API token | The token created above. Leave empty to use local connectors only. |
| Cloudflare account ID | The 32-character ID found above. |
| Local cloudflared connectors | Metrics addresses, separated by commas: http://192.168.1.10:2000, http://nas.lan:2000. |
| Check interval (s) | Seconds between two checks, 30 to 3600 (default 60). |
The Prefer the local connection switch, shown by Gladys under the form, decides which source is shown for a tunnel that has both (see below).
Then click Test the connection: the answer says, for each source, what answered and what to fix.
Devices
The devices appear in the Discover tab of the integration: add the ones you want to follow.
One device per tunnel (cloud)
| Feature | Values |
|---|---|
| Status | healthy, degraded, down or inactive |
| Online | 1 when the tunnel carries traffic (healthy or degraded), 0 otherwise |
| Active connections | Number of connections to the Cloudflare edge |
What the statuses mean, as Cloudflare defines them:
- healthy: the tunnel works normally;
- degraded: it still carries traffic, but some connections or connectors are missing;
- down: no connection left, the tunnel cannot carry traffic;
- inactive: the tunnel has never been run.
Renaming a tunnel in Cloudflare keeps its Gladys device: the device is tied to the tunnel ID, not to its name.
One device per local connector
| Feature | Values |
|---|---|
| Ready | 1 when the connector holds at least one connection |
| Ready connections | Number of connections it holds (4 by default) |
The badge on each device
- local: the state comes from a
cloudflaredon your network; - cloud: it comes from the Cloudflare API;
- unreachable: no source answers for this device.
When a local connector serves a tunnel of your account, the integration links them on its own (through the connector ID Cloudflare reports). Then, with Prefer the local connection on, the tunnel shows the local view; off, the Cloudflare view. If the preferred source fails, the other one stands in and the badge gets an orange dot with the reason.
Scenes
Triggers
- A Cloudflare tunnel changes status — filter on the tunnel and on the new
status. Variables: tunnel name, new status, previous status, active
connections. Example: "when the
hometunnel becomes Down, send me a message". - A local cloudflared connector changes status — filter on the connector
and on
Ready,Not ready,Unreachable. - The Cloudflare API stops answering — fired once when the API starts failing (token refused, unknown account, no Internet…), not at every check.
Each trigger fires once per change. The last known status is kept on disk, so a change that happens while Gladys restarts is still caught.
Actions
- Check the Cloudflare tunnels now — runs a check at once. Gives: number of tunnels, healthy tunnels, tunnels with an issue, and "all tunnels healthy" (yes/no), to test in the next actions.
- Read the status of a tunnel — gives the name, status, online (yes/no) and active connections of a tunnel or a local connector, from the last check.
Dashboard widget
Add the Cloudflare tunnels widget to a dashboard. It shows:
- the number of healthy tunnels, and of tunnels with an issue;
- the number of local connectors ready (when you have some);
- one line per tunnel (issues first) and per connector, with its status and connections;
- a Check now button.
Troubleshooting
| Message | What to do |
|---|---|
| Cloudflare refused the API token | Check the token, and its permission Account → Cloudflare Tunnel → Read. |
| Cloudflare does not know this account ID | Copy the account ID again; check the token includes this account. |
| The Cloudflare API cannot be reached | Check that Gladys has Internet access (DNS, firewall). |
| A connector shows no answer | Check --metrics 0.0.0.0:<port> on cloudflared, the port, and curl http://host:port/ready. |
| A connector answers but holds no connection | cloudflared runs but cannot reach Cloudflare: check its own logs. |
Privacy
The token is stored in Gladys and sent only to api.cloudflare.com, over
HTTPS. It is never written to the logs. Local connectors are read on your
network, without any token.
Configuration settings
These are the settings Cloudflare Tunnel Monitor asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Getting started | section | No | Two sources, use one or both. Cloud: a Cloudflare API token with the permission Account › Cloudflare Tunnel › Read, and your account ID — every tunnel of the account becomes a device. Local: the metrics address of a cloudflared connector on your network (started with --metrics 0.0.0.0:2000) — it keeps answering when the Internet link is down. |
| Cloudflare API token | secret | No | Read-only token: Account › Cloudflare Tunnel › Read. Leave empty to use local connectors only. |
| Cloudflare account ID | string | No | 32 hexadecimal characters, shown on the Overview page of the Cloudflare dashboard. |
| Local cloudflared connectors | string | No | Metrics addresses of your cloudflared instances, separated by commas. Leave empty to use the Cloudflare API only. |
| Check interval (s) | number | No | Seconds between two checks of every tunnel and connector (30 to 3600). |
How to install Cloudflare Tunnel Monitor in Gladys
- In Gladys, open Integrations: Cloudflare Tunnel Monitor appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/prohand/gladys-cloudflaretunnelmonitor:0.0.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/prohand/gladys-cloudflaretunnelmonitor.
Cloudflare Tunnel Monitor requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Cloudflare Tunnel Monitor is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by prohand, not by the Gladys core team.
- Browse all integrations, native and community
- Build and publish your own external integration
- Source code on GitHub — source of this documentation