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_timeoutwith no new connections. So a phone that is connected but idle runs no tests.intervalmust not be longer thanidle_timeout, or sing-box refuses the config withinterval 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 asoutbound de-1 available: 182ms. At the usualinfolevel, 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. Set204to 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:
- 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.
- 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.
- 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. - 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".
- 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. - 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.


