Skip to content
Connection Guard
Download

Anti-VPN for Velocity

Install Connection Guard once on your Velocity proxy and every player is checked before they reach a backend server. Free, open source, and you choose the detection services.

5.4 MB JAR for every platform, from ModrinthOther download options

Install on
The Velocity proxy
Java
17 or newer
Velocity API
3.3
Checked
At login, before any backend

Why check at the proxy

  • Players connect to Velocity first, so the proxy sees their real address. Checking there covers the whole network with one installation instead of one per backend.
  • A refused player never reaches a backend server, and every backend shares the same cache, rules and quota.
  • Backends behind the proxy don't need Connection Guard. They should only accept connections forwarded by Velocity, which Connection Guard doesn't replace.

Set up on Velocity

  1. Download the JAR

    The same file runs on every platform: Modrinth, Hangar, SpigotMC or GitHub.

  2. Put it into the proxy's plugins folder

    Only on the proxy. Remove older Connection Guard JARs first.

  3. Start the proxy

    New 0.6 installs protect right away with Connection Guard Intel and the keyless services. Upgrading keeps your mode, services and keys.

  4. Set it up

    Open the console link for the dashboard's setup assistant, or edit config.yml. To watch before blocking, set operation.mode to OBSERVE.

  5. Check an address

    Run the command below to see what each service reports for an address.

    cg info 203.0.113.7
# plugins/…/config.yml: warn staff first, block later
behavior:
  vpn:
    kick-player: false
    notify-staff: true
  geo:
    kick-player: false
    notify-staff: true
    type: 'BLACKLIST'
    list: []
A partial example from the configuration guide. Keep every other generated setting.

New to anti-VPN plugins? Read how to block VPNs on a Minecraft server and how country rules work.

What you control

Own VPN lists
Connection Guard Intel: signed lists of VPN servers, Tor exits and privacy relays, checked on the server. No quota, and it works when every API is down. About Intel
Detection services, one after another
ProxyCheck, Blackbox, zowi, IPQuery and IP-API without a key; IPHub, VPNAPI, IPQualityScore or your own REST API with one. If one fails, the next answers.
Country rules
A blocklist or an allowlist of countries, with its own action and message.
Your response
Refuse the connection, alert staff in chat, post to a Discord webhook or run a console command.
Caching
With caching enabled, unexpired SQLite or Redis results can be reused for the same address, reducing repeat lookups.
Exemptions
Let trusted players or addresses through by UUID, IP or LuckPerms permission.
Inspect any address
/cg info shows what each service reported, so you can see why a player was flagged.

Security software shouldn't be a black box. Everything above is public code under the MIT license, so you can read exactly what runs at every login on your Velocity proxy. Read the source

Velocity questions

Do I need to install it on my backend servers too?

No. Install Connection Guard on the Velocity proxy that receives player connections. Configure your backends to accept only forwarded connections from the proxy, as Velocity documents; Connection Guard doesn't replace that setup.

Which Java version does the Velocity version need?

Java 17 or newer. The Velocity adapter targets the Velocity 3.3 API. Follow Velocity's own Java requirements, which may be newer.

Is Connection Guard free?

Yes. The plugin is free and open source under the MIT license, and no Connection Guard account is needed. The detection services you choose have their own free plans and limits.

Will it slow down logins?

A new IP address is checked once during login with the services you enabled. With caching enabled, unexpired answers can be reused for the same address (VPN results for 24 hours and country results for 72 hours by default), reducing repeat lookups.

Can I warn staff instead of kicking players?

Yes. Set kick-player to false and notify-staff to true for VPN or country rules. Staff with connectionguard.notify.vpn or connectionguard.notify.geo then see an alert, and you can also post to a Discord webhook.

Can I let specific players through?

Yes. Add their UUID or IP address under behavior.vpn.exemptions and behavior.geo.exemptions. Permission-based exemptions use LuckPerms and need the matching use-permission-exemption switch.