Velocity Whitelist Worker

A simple remote whitelist plugin for Velocity proxy servers.

What it does

This plugin fetches a whitelist from a remote URL and controls which players can join your Velocity proxy. The whitelist is stored in a JSON file that you host somewhere (like a CDN or web server), so you can update it without restarting the server.

Features

• Fetches whitelist from a remote URL
• Username-based whitelisting
• Multiple list support (admin, vip, members, etc.)
• Special modes: allow everyone or deny everyone
• Auto-reload from URL every few seconds
• Kicks players when removed from whitelist
• Customizable messages

Installation

1. Download the JAR file
2. Place it in your Velocity plugins/ folder
3. Start the server (it will create example config files)
4. Stop the server
5. Edit plugins/velocity-whitelist-worker/config.json and set your URL
6. Create your whitelist JSON file at that URL
7. Start the server again

Configuration

Local config file: config.json

{
  "url": "https://your-domain.com/whitelist.json",
  "reloadIntervalSeconds": 10
}

• url - Where to fetch the whitelist from (required)
• reloadIntervalSeconds - How often to check for updates (default: 10)

Remote whitelist file

This is the JSON file at your configured URL:

{
  "customLists": ["admin", "vip"],
  "admin": [
    "Player1",
    "Player2"
  ],
  "vip": [
    "Player3",
    "Player4"
  ]
}

• customLists - Which lists to use (if empty or missing, everyone is allowed)
• Add your own list names with player usernames

Special modes

Set customLists to special values:

• ["all"] - Allow everyone
• ["none"] - Deny everyone (maintenance mode)
• [] or missing - Allow everyone (default)

Messages file: messages.json

Customize the messages players see:

{
  "deniedMessage": "Sorry, You don't fit the Vibe(SMP)...",
  "kickedMessage": "You no longer fit the Vibe(SMP)...",
  "maintenanceMessage": "Don't worry, we'll be right back, just some maintenance"
}

How it works

1. Plugin loads and reads your local config
2. Fetches the whitelist from your URL
3. Checks which mode/lists are active
4. Allows or denies players based on the whitelist
5. Automatically reloads every X seconds
6. Kicks players if they're removed from the whitelist

Examples

Allow only admins:

{
  "customLists": ["admin"],
  "admin": ["Admin1", "Admin2"]
}

Allow multiple groups:

{
  "customLists": ["admin", "member"],
  "admin": ["Admin1"],
  "member": ["Player1", "Player2", "Player3"]
}

Maintenance mode:

{
  "customLists": ["none"]
}

Allow everyone:

{
  "customLists": ["all"]
}

Or just leave it empty:

{}

Requirements

• Velocity 3.4.0 or higher
• Java 21 or higher
• A web server to host your whitelist JSON file