Monitoring your tunnel health — what the dot means, and how to roll your own

Every proxy row in the Nodetonet panel has a small coloured dot next to it. That dot is not decoration — it is the live output of a background daemon called the Proxy Health Refresher, which probes every active tunnel every five seconds and writes the result back to the database. If your scraper is getting connection refused and you do not know why, that dot is your fastest diagnostic.

This guide explains what each colour means at the protocol level, how to read the underlying data via the API, how to wire up an external alert that pages you when something breaks, and when to use webhooks instead of polling. If you have never set up a proxy on Nodetonet, start with the pillar guide first.

How the Health Refresher works

The Refresher runs inside the panel process, completely separate from the proxy data path. On every 5-second tick it iterates every active proxy and, for each one, runs a three-step check:

1. Port probe. The panel opens a TCP connection to the proxy port on the edge server. A successful SYN-ACK confirms the listener is bound. No reply within the timeout means the port is dead.
2. Device heartbeat. The panel checks whether the mobile device's WebSocket last-ping timestamp is under 30 seconds old. Older than that and the device is considered offline.
3. Upstream ping (optional). For proxies that forward to an external residential or datacenter upstream, the Refresher can issue a HEAD to a known target through the upstream chain and confirm a 200 comes back.

After each check it writes { status, lastCheckAt, lastError, consecutiveFailures } back to the proxy row. The panel UI polls every few seconds for any rows currently visible, so the dot reflects reality within roughly five seconds of any change. You can verify what your own connection looks like right now with our free What is my IP tool — it shows the exact IP and ASN a server reads from you.

What each colour means

Green — healthy. The port is bound on the edge server, the device's WebSocket heartbeat is fresh (under 30 seconds old), and the last end-to-end probe completed inside the refresh window. Traffic sent through this proxy will reach its destination normally.

Yellow — degraded. The port is bound and accepting TCP connections, but the mobile device behind it is currently unreachable — its WebSocket has gone silent. This is the most common state in the wild. Phones go into deep sleep, briefly lose signal while changing towers, or drop Wi-Fi for a minute during network switching. While the device is offline, your client will receive a clean 502 Bad Gateway rather than a TCP-level connection refused, because the edge port is still listening. As soon as the device's WebSocket reconnects the dot flips green again with no intervention needed.

Red — broken. The port is not bound at all. The edge server process did not create or has since dropped the listener — usually caused by a port collision, a server reboot that happened mid-creation, or (rarely) the edge server itself going offline. Your client gets a hard connection refused; no traffic can flow. Red always requires intervention: use the Recreate port action in the panel, or delete and recreate the proxy on a different edge server if the server itself is the problem. See choosing the right edge server for guidance on picking a reliable one.

Rule of thumb: yellow is the device's fault and heals itself. Red is the port's fault and will not heal without action.

Status at a glance

Querying health via the API

The same data is available over the REST API. To fetch health for a single proxy:

curl -H "Authorization: Bearer $KEY"   https://nodetonet.com/api/v1/proxies/8f3a/health

# Response:
# {
#   "status": "green",
#   "portBound": true,
#   "deviceOnline": true,
#   "lastCheckAt": "2026-03-26T11:02:14.302Z",
#   "lastError": null,
#   "consecutiveFailures": 0
# }

To fetch health for your entire fleet in one call, append ?include=health to the proxies list endpoint:

curl -H "Authorization: Bearer $KEY"   "https://nodetonet.com/api/v1/proxies?include=health"

The status field is one of green, yellow, or red. The consecutiveFailures counter is the most useful field for alerting: each failed probe increments it and a successful probe resets it to zero. A value above 3 means the proxy has been in a bad state for over 15 seconds; above 12 means over a minute. Use the counter to distinguish a genuine outage from a one-off blip before you fire an alert.

For details on authenticating your first API call, see REST API: your first call and understanding your API key.

Building an external monitor

Keeping the panel open in a browser tab is not a monitoring strategy. Here is a minimal shell script that polls every 30 seconds and pages a Pushover notification if any proxy stays red for over a minute:

#!/bin/bash
# probe-all.sh

while true; do
  curl -s -H "Authorization: Bearer $KEY"     "https://nodetonet.com/api/v1/proxies?include=health"     | jq -r '.proxies[] | select(.health.status=="red") |
             "(.id) (.health.consecutiveFailures)"'     | while read id failures; do
        if [ "$failures" -gt 12 ]; then
          # 12 consecutive failures x 5s probe interval = 60 s down
          curl -s -F "token=$PUSHOVER_TOKEN" -F "user=$PUSHOVER_USER"                -F "message=Proxy $id has been red for over 60 seconds"                https://api.pushover.net/1/messages.json
        fi
      done
  sleep 30
done

The same JSON endpoint drops straight into a Grafana dashboard as a JSON datasource, or you can push the values to PagerDuty, Opsgenie or any other incident management tool. The panel imposes no lock-in on the monitoring stack you choose.

If you run a large fleet and need to act on failures programmatically — for example to automatically migrate a failing proxy to a different edge server — combine the health endpoint with the bulk operations guide.

Using webhooks instead of polling

Polling every 30 seconds works, but it creates unnecessary load on both sides when you have dozens or hundreds of proxies. The panel supports outbound webhooks that push a status-change event immediately rather than waiting for your next poll cycle.

Enable webhooks on the proxy detail page under the Webhooks tab. Every time a proxy transitions between states — green to yellow, yellow to red, red back to green — the panel POSTs a JSON payload to your endpoint. The payload includes the proxy ID, the old and new status, the timestamp, and the current consecutiveFailures count. The payload format is shared with IP-change events; see webhooks for IP change events for the full schema and signature verification.

Webhooks are strictly more efficient than polling for reactive alerting. They are the right choice if you want sub-second notification of a state change. Polling is still useful if you need periodic snapshots regardless of change (for example, to feed a time-series database).

Edge servers and why they matter for health

Red status is almost always an edge-server problem rather than a device problem. Mobile proxies and rotating proxy pools run their data plane on edge servers — the machines that terminate your client connections and forward traffic to the paired mobile devices. If an edge server restarts, all ports on it briefly go red until the engine process recreates them.

A few practices that reduce red incidents:

• Spread proxies across more than one edge server so a single reboot does not knock out your whole fleet.
• Use the Recreate port action as your first response to red — it is faster than deleting and recreating the proxy entirely.
• For critical workflows, consider enabling the upstream forwarding option so traffic can fall back to an upstream residential provider if the primary device goes yellow.

If you are interested in how traffic actually moves between your client, the edge server and the mobile device, how traffic is routed walks through the full path. For device-side health — what causes yellow on the Android agent specifically — see device health: what online means.

Pairing health with audit logs

Health data tells you whether a proxy was reachable at a given moment. Audit logs tell you what was attempted through it. When a client reports intermittent failures, cross-referencing the health timeline with the audit log lets you confirm whether the failures lined up with actual yellow or red periods, or whether the problem is elsewhere (for example, per-client thread limits — see thread limits per client).

Get started

If you do not have proxies running yet, create a free account and follow your first token and Android pairing to have your first mobile proxy live in minutes. Once it is running, the health dot will tell you everything you need to know at a glance — and the API and webhooks above give you the same signal wherever you need it.