connection-guard

Connection Guard keeps VPN, proxy and Tor users off your Minecraft server, and tells you exactly why. It checks its own signed VPN lists on your server first, then free detection services one after another, and explains every decision. Free and MIT licensed, one JAR for Paper, Spigot, BungeeCord and Velocity.

Website · Download · Benchmark · Dashboard · Docs · Discord

An open benchmark

Connection Guard is compared with other plugins in the open mc-antivpn-bench suite. The author maintains the benchmark; its method, adapters and logs are public. The available results are preliminary and describe earlier candidates. The complete comparison for the released 0.6.0 JAR is still pending. Method and current status · Source and logs

Preliminary screenshot — 6 October 2026. Earlier PR #75 candidate 42e1594, Velocity, one round; simulated detection APIs and free-tier quotas; detection sample: 140 addresses. The five reported cases include the control case. These results do not qualify the final released 0.6.0 JAR.

What it does

• Connection Guard Intel. Signed lists of VPN servers, Tor exits and privacy relays, updated daily and checked on your server. No player IP, name or UUID is sent in the list fetch. Local lookups have no API quota; fresh valid lists keep listed VPN/Tor addresses blocked when detection APIs are down. Missing, stale or unlisted entries continue failover. iCloud Private Relay is let in by default, or treated as a VPN if you prefer. The lists are public.
• Detection services, one after another. By default ProxyCheck, Blackbox, zowi, IPQuery and IP-API, without any API key. When one fails or its free limit runs out, the next one answers. Add IPHub, VPNAPI, IPQualityScore or your own REST service if you have keys.
• Country rules. Block the countries you list, or allow only those, each with its own message.
• Your own exceptions. Allow, deny or exempt an IP, a CIDR range or a verified player, permanently or for a while: /cg allow add 192.0.2.0/24 vpn 2h School network.
• Your response. Refuse the connection, alert staff in chat, post to a Discord webhook or run a console command.
• Protects from the first login. New installs start in ENFORCE and refuse positive VPN/proxy/Tor signals right away; Blackbox matches can also include hosting/cloud. Set operation.mode: OBSERVE to only log whom Connection Guard would refuse.
• Safe changes. Policies are versioned and can be rolled back, and shadow mode compares a new policy with real logins before it decides anything.
• It explains itself. /cg explain <IP> shows why a connection was let in or refused, /cg doctor checks your setup, and /cg providers shows each service's health and limits.
• Your players' language. Messages ship in English, German and Spanish.

The free dashboard, if you want it

Open the highlighted link the plugin prints in its console, sign in with Discord, and the server is linked. A short setup assistant picks the services, countries and mode with you. Changes reach an online server at its next sync; /cg cloud sync requests that sync immediately in the background.

See every server at a glance. Checks, refusals, VPN rate, service health and limits across your whole network, for up to 13 months.

Every decision, explained. One sentence says why a player was refused, including which list or service answered. Let the player in for an hour, a day, a week or for good, allow the address, or trust their internet provider, right there. An explicit DENY takes priority over ALLOW.

Know before you switch. Before you save new settings, the dashboard estimates how they would have decided the last 7 days of logins, using the answers recorded at the time. Missing provider answers, managed access rules and other plugins limit the estimate.

You also get team access with owner, admin and viewer roles, and Discord alerts when a server goes offline, a service has trouble, a limit runs low or refusals spike.

Privacy and how to turn it off. The cloud link is on by default. Logins never wait on the dashboard.

• Before you link a server: it sends only anonymous installation and platform information, totals, service health and anonymous error reports, with no player IPs, names or UUIDs. Error reports contain bounded exception types and Connection Guard stack metadata, excluding exception messages and credentials; they are enabled with Cloud, including upgrades without the option. Error-report details.
• After you link it and accept the processing agreement: individual decisions, including IP addresses and verified UUIDs, are stored in the EU for 30 days.
• To turn it off, use any of these: cloud.enabled: false, /cg cloud disable or CONNECTIONGUARD_CLOUD=false. Error reports alone: cloud.error-reports: false.

What is sent, in detail. The dashboard is open source too (AGPL).

Get started

1. Download the JAR and put it into plugins/: on your server, or on the proxy if you run a network.
2. Restart. Connection Guard protects right away with Connection Guard Intel and the keyless services, without any API key. Country lookups are off on new installs; the dashboard turns them on when you add a country rule.
3. Open the link from the console to set it up in the dashboard, or edit config.yml.

Upgrading from 0.5? Back up the plugin data directory, stop the server/proxy, replace the JAR, keep only one main plugin JAR and restart. Your mode, services, order, keys and explicit limits stay as they are; Intel and the new services are offered once and only switched on if you choose them. Keep your existing configuration. /cg doctor shows the notices. Failover is the default when no strategy was selected; set provider.vpn-failover.enabled: false to restore parallel voting. Disable a service with provider.vpn.<id>.enabled: false; Intel has its own provider.local.connectionguard-intel.enabled switch.

Step-by-step guides: Paper and Spigot · BungeeCord · Velocity

Requirements

Follow your server software's Java requirements; these are plugin bytecode targets. Start, command, reload and shutdown checks passed on Paper 26.3, Folia 26.2, Velocity 4.2.0 and 4.2.1-SNAPSHOT with Java 25, and on Paper 1.21.11 and Velocity 3.4.0 with Java 21. They do not cover every login scenario or version in between. What was tested.

Commands

Use /connectionguard if /cg is taken. All commands and permissions.

Good to know

• Detection services receive player IPs. Every service that is asked learns the joining player's IP address, so name the ones you use in your server's privacy information. Blackbox is run by ipinfo.app, has no written terms, and its list also covers hosting and cloud networks. zowi is run by the developer of FoxGate. ip-check.net is off by default because it publishes no operator, terms or privacy policy. The free IP-API endpoint is for non-commercial use and uses HTTP. Choosing services.
• When several services hang at once, a login can reach the 5,000 ms whole-login budget while Connection Guard moves on to available services. The measured three-hanging-host case took about 4.52 seconds. Timed-out services are skipped temporarily, but an untested hanging service can still delay a later login. No universal first-outage limit below two seconds is promised.
• No detection is perfect. A flag is not proof that someone is doing anything wrong, which is why every refusal can be explained and reversed. A legitimate player is flagged?
• It isn't everything. Connection Guard is not an anticheat, a complete antibot system or DDoS protection.

Security software shouldn't be a black box

Connection Guard sees every login on your server, so you should be able to read exactly what it does. Every check it runs and every request it sends is public code under the MIT license, built in public CI; GitHub releases ship with SHA-256 checksums. Connection Guard Intel is built from public sources in a public repository, and the benchmark can be run by anyone. What the plugin sends to connectionguard.net is defined in the open dashboard source and off with one line.

Help

Get help on Discord or open an issue. Please include the plugin, server and Java versions. A star or an honest review is welcome, but never required.