Skip to main content

Getting Started

CocoAntiVPN is a powerful multi-platform VPN and proxy detection plugin for Minecraft servers. It protects your server from VPN/proxy users and players from blocked countries.

Features​

  • 🛡️ Real-time VPN/Proxy Detection - Uses CocoStudios API for accurate detection
  • 🌍 Country Blocking - Block players from specific countries using ISO codes
  • ⚡ High Performance - Smooth rate limiting and intelligent caching (50,000 IPs)
  • 🔔 Staff Notifications - Alert staff when VPN users are detected
  • 💬 Discord Webhooks - Send detection alerts to Discord
  • 🔄 Bypass System - SQLite-based bypass list with commands
  • 🚫 IP Blacklist - Persistent blacklist with custom ping responses
  • 📦 Multi-Platform - Bukkit/Spigot, Paper, Folia, BungeeCord, Velocity

Requirements​

  • Java 17 or higher
  • Bukkit/Spigot/Paper 1.20+ (for single servers)
  • BungeeCord or Velocity (for proxy networks)
  • CocoStudios API Key (get one from CocoStudios)

Installation​

Single Server (Bukkit/Spigot/Paper/Folia)​

  1. Download the latest CocoAntiVPN.jar
  2. Place it in your plugins folder
  3. Start/restart your server
  4. Configure your API key in plugins/CocoAntiVPN/config.yml
  5. Reload with /antivpn reload

Proxy Network (BungeeCord)​

  1. Download the latest CocoAntiVPN.jar
  2. Place it in your BungeeCord's plugins folder
  3. Start/restart your proxy
  4. Configure your API key in plugins/CocoAntiVPN/config.yml
  5. Reload with /antivpn reload

Proxy Network (Velocity)​

  1. Download the latest CocoAntiVPN.jar
  2. Place it in your Velocity's plugins folder
  3. Start/restart your proxy
  4. Configure your API key in plugins/cocoantivpn/config.yml
  5. Reload with /antivpn reload
Important

For proxy networks, install CocoAntiVPN on the proxy only (BungeeCord/Velocity), not on backend servers. This ensures players are checked before they can access any server.

Quick Start​

After installation, edit your config.yml:

# Your CocoStudios API Key
api-key: "YOUR-API-KEY-HERE"

# Countries to block (ISO 3166-1 alpha-2 codes)
blocked-countries:
  - RU
  - CN
  - IR

That's it! Your server is now protected from VPN/proxy users.

How It Works​

  1. Player Connects - When a player attempts to join
  2. Rate Limiting - Smooth rate limiter checks if request is allowed
  3. Bypass Check - Skip VPN check if player is in bypass list
  4. Blacklist Check - Immediately kick if IP is already blacklisted
  5. API Check - Query CocoStudios API with player's IP (5 second timeout)
  6. Cache Check - Use cached result if available (up to 50,000 IPs)
  7. Decision - Allow or kick based on VPN/country detection
  8. Blacklist - Add detected IPs to persistent blacklist
  9. Notification - Alert staff and Discord if blocked

Support​

Need help? Join our Discord server for support!