# Working with monitors A monitor is one VPN endpoint that TunnelHQ checks on a schedule. Every check performs a real handshake for one of the 11 supported protocols and then sends traffic through the tunnel, so a healthy result means a client could connect and use it, not only that a port answered. ## Adding a monitor On the Monitors page, click **Add monitor**. The **Add VPN monitor** dialog has two tabs: **One monitor**, described here, and **Bulk import**, for [adding many at once](/docs/import/). ### Paste a config (recommended) Paste a config or share link into the box at the top of the dialog. TunnelHQ recognizes share links such as `vless://`, `vmess://`, `trojan://`, and `ss://`, and the full text of WireGuard and OpenVPN config files. It fills in the protocol, host, and port, and names the monitor ` - `, such as `WIREGUARD - vpn.example.com`. You confirm and save. ### Enter the details manually Click **Enter details manually** to type everything in. | Field | Details | | --- | --- | | Monitor name | Optional, except for OpenConnect. If it's empty when you save, the name is the protocol followed by "Server", such as "WIREGUARD Server". | | Host | Required. The server address, such as `vpn.example.com` or an IP address. | | Port | Required for most protocols. OpenConnect has no port field when you add it; you can set one later in its settings. Config-file protocols such as WireGuard read the port from the config. | | Protocol | Grouped into **Standard** (WireGuard, OpenVPN, IKEv2), **V2ray/Xray** (VLESS, VMess, Trojan, Shadowsocks, Hysteria2, TUIC), and **Obfuscated** (AmneziaWG, OpenConnect). | Choosing a protocol shows its own fields, such as a WireGuard config, an OpenVPN username and password, or a connection URL. [VPN protocols](/docs/protocols/) documents the fields for every protocol. The Add dialog doesn't ask how often to check. A new monitor runs every 3 minutes, or at your plan's fastest interval if that's longer. You can change it in the monitor's settings. ## Monitor settings Open a monitor and go to its **Settings** tab. These settings apply to every monitor, whatever its protocol. ### Locations A monitor tests from **Any** location by default. Add specific locations to confirm that the server is reachable from each one independently. TunnelHQ then tracks a status for each location and combines them into one aggregate status. [Locations and status](/docs/concepts/regions/) explains how. ### Test interval **Test Interval** is how often the monitor runs, in whole minutes, from your plan's fastest interval up to 1,440 minutes (24 hours). The label shows the range your plan allows. | Plan | Fastest interval | Tunnel limit | | --- | --- | --- | | Free | Every 10 minutes | 5 | | Starter | Every 5 minutes | 20 | | Pro | Every 2 minutes | 100 | | Business | Every minute | 500 | If you choose an interval faster than your plan allows, the dashboard tells you and the API rejects the request. Only tunnels count toward the limit. [Uptime checks](/docs/uptime/) are free while Uptime is in beta. ### Timeout and retries | Setting | Default | Allowed | What it does | | --- | --- | --- | --- | | Timeout (seconds) | 60 | 10–120 | How long to wait for a check before counting it as failed. | | Retries | 2 | 1–10 | How many failed checks in a row it takes to mark the monitor **Down**. Until then, it shows **Unknown**. | A monitor is checked again one test interval after its last check, whatever its status. With 2 retries, an outage is confirmed **Down** at the second failed check in a row, one interval after the first. A single-location monitor opens a Degraded [incident](/docs/concepts/incidents/) at the first failed check. ### Notification integrations Choose which of the project's [alert channels](/docs/alert-channels/) receive alerts for this monitor. ### Resend notifications **Resend Notification if Down X times consecutively** repeats the alert while the monitor stays down, on every integration the monitor uses. `0` turns it off. ### Tags Tag monitors to group them by region, customer, environment, or anything else. On the Monitors page, filter by tags: a monitor matches if it has any of the tags you select, and the filter is kept in the page's link, so you can share it. To change many monitors at once, select them on the Monitors page and use the bulk actions bar. It can add tags, set locations, and set the resend setting. ## Managing a monitor Open a monitor to manage it: - **Run Now** runs an on-demand check without waiting for the schedule. - **Pause monitoring** stops checks until you click **Resume monitoring**. The monitor stays in your list, but the scheduler skips it. You can also pause individual locations. - **History** lists every heartbeat with its status, region, connect time, latency, and message. - **Settings** lets you change any setting above, or delete the monitor. :::caution[Paused tunnels still count] A tunnel you pause still counts toward your plan's tunnel limit. Delete tunnels you no longer need. (Tunnels that TunnelHQ pauses itself after a plan downgrade don't count.) ::: ## Connect time and latency Each passing check measures two times, shown on the monitor's page and in its History: | Time | What it measures | | --- | --- | | Connect time | How long the tunnel took to come up. For VLESS, VMess, Trojan, Shadowsocks, Hysteria2, and TUIC, it's the time to first contact with the server. | | Latency | One round trip through the tunnel once it's up. | A failed check measures neither. ## The test journey Every check records the stages it went through, so a failure shows *where* it failed. | Stage | What happens | | --- | --- | | Setup | TunnelHQ prepares the connection test. | | Connect | DNS, reachability, and the protocol handshake. On success, the check records the tunnel IP that was assigned. | | Verify | Real traffic goes through the tunnel, and the check records the exit IP it left from. | Expand any entry under **Recent Test Results**, or any row in **History**, to see the stages with per-stage timings. Failed checks also include a **Diagnostic** from the checker that explains why the check failed. ## What a failed check says Every failed check carries a message. The message tells you whether the problem is your server or TunnelHQ's checker, and what happens to the monitor. | Message | What it means | Effect on the monitor | | --- | --- | --- | | Tunnel unreachable | The tunnel never came up: the server didn't answer, or the handshake failed. | **Down** | | Tunnel established - Internet is stuck | The tunnel came up, but traffic through it didn't reach the internet. The check sends real requests to well-known sites through the tunnel, so the usual causes are the server's forwarding or NAT, its DNS, or an egress firewall. | **Down** | | Server reachable — it rejected the monitor's credentials or certificate. | The server answered and refused the monitor's credentials or certificate. | **Degraded** for that location, with no alert. Exception: an OpenVPN, OpenConnect, or IKEv2 monitor that passed a check in the last 30 days treats the refusal as an outage, and goes **Down** after its retries and alerts. | | Couldn't complete this check — the monitor's configuration or credentials were rejected. The server's status is unknown. | The monitor's configuration couldn't be used, so there's no verdict on the server. | **Unknown**, unless the monitor was already down, in which case it stays **Down**. No alert. | | VPN check failed | Any other failure. | | These messages mean TunnelHQ's checker failed, not your server. The check shows **Unknown**, never **Down**: - Couldn't complete this check — a fault on the monitoring checker, not your server. - Monitoring infrastructure unreachable - Checker returned an error - VPN check timed out - VPN check inconclusive — monitoring infrastructure timed out - Checker resource issue (e.g. disk full) - try again later. Each [protocol page](/docs/protocols/) lists the failures most common for that protocol and what to check.