Guides, Nov 21, 2026

# sing-box urltest and Clash url-test: what health checks miss

sing-box \`urltest\` and Mihomo \`url-test\` send a small HTTP request through each outbound every few minutes and route traffic through the fastest one that answered. That is a good way for a client to choose a server. It is not monitoring: the test runs on the user's device, through the user's network, only while the user is active, and you never see the results. Use it for failover on the client, and check your servers from outside with something that can alert you.

Tahir Mehmood, 8 min read

Everything below about behaviour comes from reading the code, not only the docs: sing-box's `stable` branch (the 1.14 releases) and Mihomo's `Meta` branch (the v1.19 releases). The docs describe the fields; the code shows what a test actually does, and a few details matter for operators.

## What does sing-box urltest actually test?

For each outbound in the group, sing-box opens a connection through that outbound to the host of the test URL, sends one HTTP `HEAD` request, and measures the time in milliseconds until the response headers arrive. It does not follow redirects, and it does not look at the status code: any HTTP response counts as success. A test that takes longer than 15 seconds fails.

The fields and their defaults, from the [urltest documentation](https://sing-box.sagernet.org/configuration/outbound/urltest/):

| Field | Default | Meaning |
| --- | --- | --- |
| `url` | `https://www.gstatic.com/generate_204` | What to request through each outbound |
| `interval` | `3m` | How often to test |
| `tolerance` | `50` | Milliseconds a new outbound must beat the current one by before sing-box switches |
| `idle_timeout` | `30m` | Stop testing after this long without traffic |
| `interrupt_exist_connections` | `false` | Close existing connections when the selection changes |

A few behaviours that are not obvious from the table:

-   **Testing follows traffic.** sing-box tests once at startup. The regular loop starts the first time a connection goes through the group, and stops after `idle_timeout` with no new connections. So a phone that is connected but idle runs no tests. `interval` must not be longer than `idle_timeout`, or sing-box refuses the config with `interval must be less or equal than idle_timeout`.
-   **Failures are quiet.** A failed test is logged at debug level as `outbound de-1 unavailable: ...`, and a success as `outbound de-1 available: 182ms`. At the usual `info` level, neither appears.
-   **When everything fails, it still picks one.** If no outbound in the group has a successful result, sing-box sends traffic to the first outbound in the list.

A typical client config puts a `selector` in front of the `urltest`, so the user can still pick a server by hand:

```json
{
  "log": { "level": "info" },
  "outbounds": [
    {
      "type": "selector",
      "tag": "proxy",
      "outbounds": ["auto", "de-1", "nl-1"],
      "default": "auto"
    },
    {
      "type": "urltest",
      "tag": "auto",
      "outbounds": ["de-1", "nl-1"],
      "url": "https://www.gstatic.com/generate_204",
      "interval": "3m",
      "tolerance": 50,
      "idle_timeout": "30m"
    },
    {
      "type": "vless",
      "tag": "de-1",
      "server": "176.61.144.21",
      "server_port": 443,
      "uuid": "3b2f9c1e-7a4d-4e8b-9c6f-2d1a5e0b7c94",
      "tls": { "enabled": true, "server_name": "vpn.yourdomain.com" }
    },
    {
      "type": "trojan",
      "tag": "nl-1",
      "server": "176.61.144.22",
      "server_port": 443,
      "password": "k9Qe2rTz7mVx4pLs",
      "tls": { "enabled": true, "server_name": "vpn.yourdomain.com" }
    }
  ],
  "route": { "final": "proxy" }
}
```

The selector's `default` is the outbound it starts with. As the docs note, a selector can only be switched through the Clash API, which is what graphical clients use under the hood.

## How do Mihomo url-test and fallback work?

Mihomo (Clash Meta) has the same idea as proxy groups, with two types that matter here. `url-test` picks the fastest node; `fallback` picks the first node in your list that is alive, so it respects your order instead of the latency:

```yaml
proxy-groups:
  - name: auto
    type: url-test
    proxies: [de-1, nl-1]
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    timeout: 5000
    expected-status: 204
  - name: failover
    type: fallback
    proxies: [de-1, nl-1]
    url: https://www.gstatic.com/generate_204
    interval: 300
```

The defaults, from the [Mihomo proxy group docs](https://wiki.metacubex.one/en/config/proxy-groups/) and the parser source:

-   `url`: `https://www.gstatic.com/generate_204`.
-   `interval`: in seconds. If you leave it out, url-test and fallback groups use 300.
-   `timeout`: 5000 milliseconds.
-   `lazy`: `true`, which means no test runs while the group is not in use.
-   `expected-status`: `*`, any status. Set `204` to require the real answer from the test URL.
-   `max-failed-times`: 5 failures trigger a forced health check.
-   `tolerance`: no default in the code, so it is 0 unless you set it. The docs' example uses 50.

Mihomo also sends `HEAD`. With `unified-delay: true` in the general settings, it measures after the connection handshake, to remove the differences between protocols from the number. One more catch from the docs: a group's `url` only applies to the nodes listed under `proxies`. Nodes that come from a proxy provider through `use` are tested by the provider's own health-check settings.

## sing-box urltest vs Mihomo url-test and fallback

|  | sing-box `urltest` | Mihomo `url-test` | Mihomo `fallback` |
| --- | --- | --- | --- |
| Picks | Lowest delay, with tolerance | Lowest delay, with tolerance | First alive node in list order |
| Default test URL | gstatic generate\_204 | gstatic generate\_204 | gstatic generate\_204 |
| Default interval | 3 minutes | 300 seconds | 300 seconds |
| Test timeout | 15 seconds | 5000 ms (`timeout`) | 5000 ms (`timeout`) |
| Default tolerance | 50 ms | 0 | not used |
| Idle behaviour | Stops after `idle_timeout` (30m) | `lazy: true`, no test when unused | `lazy: true` |
| Checks HTTP status | No | Only with `expected-status` | Only with `expected-status` |

## Why can't client health checks replace server monitoring?

Because they answer a different question. A client health check asks "which of these servers works best for me, right now, from here". Monitoring asks "is each of my servers working for everyone". The design of urltest gets the first one right and cannot answer the second:

1.  **The results stay on the device.** Nobody is paged. When a server dies, clients quietly move to the others. Users don't notice, so nobody reports it, and you find out when the remaining servers are overloaded or the last one fails.
2.  **They test the user's network as well as your server.** A failed test on hotel Wi-Fi says nothing about the server. A good result on a fast home line says nothing about users in another country.
3.  **They only run when the user is active.** sing-box stops after `idle_timeout`, Mihomo skips tests while the group is unused. A server can be down all night with no test anywhere.
4.  **A failure doesn't say which part broke.** The test passes through your server's handshake, its authentication, its own DNS and its outbound route to gstatic. A failure could be any of them, and the client only records "unavailable".
5.  **The status code is ignored by default.** sing-box never checks it, and Mihomo only does when you set `expected-status`. With the HTTPS default URL this is mostly fine, since nothing on the path can fake Google's TLS answer, but it means an error page from a plain-HTTP test URL counts as healthy.
6.  **The delay number is not comparable across protocols.** Some protocols finish their handshake before the request and some during it, which is exactly why Mihomo has `unified-delay`.

None of this is a reason to drop urltest. Automatic failover on the client is valuable; it is the reason a dead server costs you capacity instead of users. It just means the failover and the alert have to come from different places. The [VPN server monitoring guide](https://tunnelhq.com/blog/vpn-server-monitoring-guide/) covers what the server side should check, and the [post on checking a VLESS key](https://tunnelhq.com/blog/how-to-check-vless-key/) explains why a client's latency number can say "fine" when the key is broken.

## How do I pair client health checks with server-side checks?

The simplest server-side check uses the same tool. Run sing-box on a monitoring host you control, with the same outbounds your users get and the Clash API turned on, and ask it to test each outbound on a schedule. No inbound is needed:

```json
{
  "log": { "level": "warn" },
  "experimental": {
    "clash_api": {
      "external_controller": "127.0.0.1:9090",
      "secret": "b7f3c91e5d2a"
    }
  },
  "outbounds": [
    {
      "type": "vless",
      "tag": "de-1",
      "server": "176.61.144.21",
      "server_port": 443,
      "uuid": "3b2f9c1e-7a4d-4e8b-9c6f-2d1a5e0b7c94",
      "tls": { "enabled": true, "server_name": "vpn.yourdomain.com" }
    },
    {
      "type": "trojan",
      "tag": "nl-1",
      "server": "176.61.144.22",
      "server_port": 443,
      "password": "k9Qe2rTz7mVx4pLs",
      "tls": { "enabled": true, "server_name": "vpn.yourdomain.com" }
    }
  ]
}
```

The [Clash API](https://sing-box.sagernet.org/configuration/experimental/clash-api/) has a delay endpoint per outbound, `GET /proxies/{name}/delay`, which runs the same test as urltest. sing-box requires the `timeout` parameter in milliseconds, ignores `http://` test URLs (it falls back to the default), and answers in a way that is easy to script: `200` with `{"delay": 182}` on success, `503` when the test fails, `504` when it times out, and `400` when the request is malformed. The secret goes in an `Authorization: Bearer` header.

```sh
#!/bin/sh
# /usr/local/bin/probe-outbounds.sh: exit 1 if any outbound fails
API=http://127.0.0.1:9090
SECRET=b7f3c91e5d2a
fail=0
for tag in de-1 nl-1; do
  code=$(curl -s -o /dev/null -w '%{http_code}' -m 20 \
    -H "Authorization: Bearer $SECRET" \
    --get --data-urlencode "url=https://www.gstatic.com/generate_204" \
    --data-urlencode "timeout=10000" \
    "$API/proxies/$tag/delay")
  if [ "$code" != 200 ]; then
    echo "$tag failed: HTTP $code"
    fail=1
  fi
done
exit $fail
```

Run it every few minutes from cron and chain a heartbeat ping after it (`probe-outbounds.sh && curl -fsS -m 10 --retry 5 -o /dev/null "$HEARTBEAT_URL"`), or turn the output into metrics for Prometheus. Mihomo has the same endpoint at `/proxies/{name}/delay`, and it also accepts an `expected` parameter for the status code.

This setup has two limits you should know. It tests from one place, so a problem with the monitoring host's own network looks like every server failing at once; check a known-good site from the same host before you page anyone. And it tests the same path as urltest, so a failure still doesn't tell you whether it was the handshake, the authentication or the server's outbound route.

If your servers come from a subscription, keep the monitoring host's outbounds in sync with it, or the probe slowly drifts from what users get. The [subscription monitoring post](https://tunnelhq.com/blog/monitoring-v2ray-subscription-urls/) covers the other ways a subscription goes wrong.

Full disclosure: TunnelHQ is the hosted version of this second half. You paste a subscription URL or individual `vless://`, `trojan://`, `hysteria2://` and other links, it keeps the server list in sync, and every 1 to 5 minutes, depending on plan, its checkers complete each server's real protocol handshake, with alerts to Slack, email and 18 other channels when one fails. The [VLESS monitoring page](https://tunnelhq.com/vless-monitoring/) explains the check, and every plan has a 14-day free trial. Leave urltest on in your users' configs either way.

Source: https://tunnelhq.com/blog/sing-box-urltest-clash-health-check/
