What this is
Activists, journalists, and refugees routinely need to know which
VPN / Tor / Lantern variant actually works in their country
right now. The honest historical answer has been “ask in a
forum, try a few, see what survives.” The Voidly
block-evasion success-rate index, shipped the same day as this
endpoint, already exposes the raw per-(country, tool) measurements.
What was missing was a ranked, tier-bucketed recommendation on top
of those numbers — one a user can read in five seconds. That
is /v1/atlas/circumvention/{cc}.
For each measured (country, tool) row we compute
rank_score = success_rate × sqrt(confidence) ×
recency_decay. Recency decay is linear from 1.00 at zero days
since last observed to 0.50 at 30 days, so a tool last measured
three weeks ago weighs less than one measured yesterday. We then
bucket each tool into one of three tiers:
- Try first — success rate ≥ 70% AND confidence ≥ 0.70. High measured success rate with enough probe coverage to be confident.
- Fallback — success rate ≥ 30% OR confidence < 0.50. Worth trying if try_first fails, but expect lower reliability.
- Avoid — success rate < 10% with confidence ≥ 0.50. High-confidence rows that show the tool is effectively blocked.
Conservative gate at 100 probes
A country with three probes per tool is not a measurement, it is a
guess. We refuse to emit tier labels for any country whose total
probe count across all tools is below 100. Those countries get a
response with insufficient_coverage: true, the raw
rows are still returned, and the note explicitly says we cannot
rank this country yet — a missing tool is almost
always an OONI-coverage gap, not a working tool. On the
first run that gates out 11 countries: BH, CU, ET,
IR, KW, OM, QA, SY, TZ, UZ, YE.
Iran being on that gate list deserves a sentence of its own. IR has only 83 total probes across two tools in the last 30 days — Tor (72 probes, 54% success) and Psiphon (11 probes, 0%). Both numbers are real, but the sample size is too small for a recommendation engine. The right surface for IR right now is the upstream evasion table, not a ranking we don’t earn.
What the first run found
Of the 34 countries with any circumvention-tool probe data, 22 cleared the 100-probe floor and got viable recommendations: 13 with at least one try_first tool, 9 fallback-only, 1 (Pakistan) where every measured tool fell into avoid.
Try-first countries — the engine recommends a single specific tool with high measured success and high confidence:
- Algeria (DZ): Tor, 88.2% success
- Indonesia (ID): Tor, 96.4% (also Lantern, Psiphon, ProtonVPN all clear try_first — rare)
- India (IN): Tor, 89.1%
- Iraq (IQ): Tor, 94.3%
- Kazakhstan (KZ): Tor, 91.1%
- Malaysia (MY): Tor, 96.1%
- Russia (RU): generic commercial VPN, 87.0% (ProtonVPN + Psiphon also clear try_first — the surprising one given Russia’s aggressive 2022–2024 VPN crackdown narrative)
- Saudi Arabia (SA): Tor, 80.1%
- Singapore (SG): Tor, 86.5%
- Thailand (TH): Tor, 88.8%
- Turkey (TR): Tor, 96.2%
- Venezuela (VE): Tor, 96.7%
- Vietnam (VN): Tor, 76.4%
Pakistan is the worst case in the dataset.
Every measured tool falls into avoid: Tor 0.3% over 1,495 probes,
generic-VPN 0% over 16 probes, ProtonVPN 0% over 16, Psiphon 0%
over 15, Lantern 0% over 13. The endpoint surfaces Tor as the
least-bad row, with a coverage_note that explicitly warns the
headline is not a working recommendation and suggests
a self-hosted WireGuard / OpenVPN endpoint on a private IP
(invisible to OONI), Cloudflare WARP, or Snowflake-only Tor
(which the OONI tor aggregate cannot differentiate).
Fallback-only countries include China (generic-VPN + ProtonVPN at 61%), Azerbaijan (every tool at 0% — should actually be avoid except confidence is below 0.70), UAE, Belarus, Egypt, Jordan, Morocco, Myanmar, Bangladesh.
Honest caveats
This endpoint exists to inform, not to guarantee.
The response carries a do_not_share_card_without_caveats
flag by design. Every response repeats the same caveat block:
- Probe success is an upper bound on real-user success. DPI vendors increasingly rate-limit real client traffic while letting OONI / Voidly synthetic measurement probes pass. A tool that scores 90% probe success may still fail for a real user on a real ISP behind a real DPI box.
- Recommendations can become stale within hours. Censorship adapts. The cron rebuilds nightly at 06:00 UTC; an operator who blocks a working tool at 09:00 UTC will not show up in the recommendation for 21 hours.
- “Try first” is not “safe.” It means “highest measured probe success, highest probe confidence.” Operational security — unique device, throwaway account, no SIM, no DNS leak — is the user’s responsibility. None of that is captured here.
- Domain-fronted tools are under-estimated.
Snowflake, Lantern, and Psiphon use rotating endpoints; our
static-domain probes only measure the bootstrap surface. A
blocked
getlantern.orgdoes not mean Lantern is blocked. - Self-hosted is invisible. A WireGuard or OpenVPN endpoint on a private IP that you control will not appear in any of these numbers. If you have one, trust it over any commercial recommendation.
- Tor transports are not differentiated. The
OONI
tortest rolls up vanilla / obfs4 / Snowflake / Meek into one signal. Per-transport granularity needs raw OONI nettests, out of scope for v1.
What changes from here
v1.1 should split Tor by transport (vanilla / obfs4 / Snowflake / Meek) using raw OONI nettests, not aggregates. v1.2 should integrate the Voidly probe-network direct measurements (40 nodes, 14 countries) alongside OONI so we can corroborate — or contradict — the OONI rollup. v2 should ingest user-reported success/failure (with operational-security caveats around how that feedback is collected) so the recommendation closes the loop on real-user outcomes, not just probe traffic.
The endpoint is live at
GET /v1/atlas/circumvention/{cc} +
GET /v1/atlas/circumvention/info. Cron daily 06:00
UTC (shared with the upstream evasion sidecar). Schema:
voidly-circumvention-recommendation/v1.