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.org does 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 tor test 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.