Skip to content

Cloudflare Ping Relay Setup

Jump to bottom
SU4G3 edited this page Oct 9, 2026 · 2 revisions

Cloudflare Ping Relay Setup

Resolves issue #15: lets the multiplayer screen show live MOTD/player-count/version for every saved server without connecting to each one directly from your own IP. A Cloudflare Worker you deploy does the raw TCP server-list-ping handshake on your behalf and hands the mod back only the parsed status JSON.

This is entirely optional. Nobody but you runs the worker you deploy, so nobody but you (and whichever server you point it at) ever sees which servers you're checking.

Requires Minecraft 1.20.6+. See Known Issues — ServerStatusPinger's callback shape before that version isn't special-cased by the relay.

Option A: deploy from inside the mod (recommended, no CLI needed)

  1. Create a free Cloudflare account if you don't have one.
  2. Get an API token: dash.cloudflare.com → your profile icon (top right) → My Profile → API Tokens → Create Token → use the Edit Cloudflare Workers template → under "Account Resources" select your account → Continue to summary → Create Token → copy it (shown once).
  3. Get your Account ID: it's the first path segment after dash.cloudflare.com/ in your browser's address bar while on the dashboard (a long hex string).
  4. In OpSec's settings → Protection tab → turn on Lazy Server List Ping → turn on Cloudflare Ping Relay → Configure Ping Relay... → paste the API token and Account ID under "Auto-deploy" → Deploy Worker.

The mod uploads the worker, enables its workers.dev route, and fills in the URL for you — both toggles get switched on automatically on success. Neither the token nor the account ID is saved, only the resulting worker URL.

If this fails with a message about a missing workers.dev subdomain, your account doesn't have one registered yet — go to dash.cloudflare.com → Workers & Pages and set one up (one-time, free), then try again.

Option B: deploy manually with Wrangler

The reference worker script lives in the mod's repository at cloudflare-worker/ping-relay.js, with a matching wrangler.toml.

  1. Create a free Cloudflare account if you don't have one.
  2. Install Node.js if you don't have it, then install Wrangler (Cloudflare's CLI): 
    npm install -g wrangler
  3. Grab the two worker files from the repo (either git clone the whole mod repo, or just download cloudflare-worker/ping-relay.js and cloudflare-worker/wrangler.toml into a folder together).
  4. Log in from that folder (opens a browser to authorize against your Cloudflare account): 
    wrangler login
  5. Deploy: 
    wrangler deploy
    Wrangler prints a URL like https://opsec-ping-relay.<your-subdomain>.workers.dev when it finishes. In OpSec's settings → Protection tab → turn on Lazy Server List Ping → turn on Cloudflare Ping Relay → Configure Ping Relay... → paste that URL into the Worker URL field at the bottom → Save.

Either way, saved servers will now show live status again, routed through your worker.

Limitations

  • MC 1.20.6+ only — see above.
  • The player-list hover tooltip isn't populated (MOTD, player count, and version still show correctly) — this trims a bit of per-version formatting complexity vanilla normally handles internally.
  • Cloudflare's free plan limits a Worker invocation to 10ms of CPU time and a handful of simultaneous TCP sockets; normally plenty for one-off status pings, but can be a bottleneck with a very large saved-server list refreshed all at once.
  • Large, security-hardened servers (Hypixel, 2b2t, and similar) commonly firewall off datacenter/cloud IP ranges, including Cloudflare's. Pinging one of these through the relay fails with "proxy request failed, cannot connect to the specified address" — this is the target server's own anti-bot filtering, not a bug in the relay. The relay itself works correctly for servers that don't block cloud ranges (which is most smaller/community servers).
  • Option A's auto-deploy needs a workers.dev subdomain already registered on the account — see the note under Option A above.

Troubleshooting

  • Everything still shows "can't resolve" / no preview — double check both Lazy Server List Ping and Cloudflare Ping Relay are on, and that the URL in Configure Ping Relay... is the bare https://...workers.dev address with no trailing /ping.
  • A specific server never loads — try opening https://your-worker.workers.dev/ping?host=<that server's address>&port=25565 directly in a browser. If you get {"ok":false,"error":"proxy request failed, cannot connect to the specified address"}, that server is blocking Cloudflare's IP ranges (see Limitations above) — nothing to fix on your end. Any other error, or no response at all, means the worker itself needs attention — re-deploy with wrangler deploy and check the output for errors.

Clone this wiki locally