Guides

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 Mehmood8 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:

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:

{
  "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:

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 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 covers what the server side should check, and the post on checking a 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:

{
  "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 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.

#!/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 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 explains the check, and every plan has a 14-day free trial. Leave urltest on in your users' configs either way.