# Velocity Whitelist Worker<\/p>\n
A simple remote whitelist plugin for Velocity proxy servers.<\/p>\n
## What it does<\/p>\n
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.<\/p>\n
## Features<\/p>\n
– Fetches whitelist from a remote URL
\n– Username-based whitelisting
\n– Multiple list support (admin, vip, members, etc.)
\n– Special modes: allow everyone or deny everyone
\n– Auto-reload from URL every few seconds
\n– Kicks players when removed from whitelist
\n– Customizable messages<\/p>\n
## Installation<\/p>\n
1. Download the JAR file
\n2. Place it in your Velocity `plugins\/` folder
\n3. Start the server (it will create example config files)
\n4. Stop the server
\n5. Edit `plugins\/velocity-whitelist-worker\/config.json` and set your URL
\n6. Create your whitelist JSON file at that URL
\n7. Start the server again<\/p>\n
## Configuration<\/p>\n
### Local config file: `config.json`<\/p>\n
“`json
\n{
\n “url”: “https:\/\/your-domain.com\/whitelist.json”,
\n “reloadIntervalSeconds”: 10
\n}
\n“`<\/p>\n
– `url` – Where to fetch the whitelist from (required)
\n– `reloadIntervalSeconds` – How often to check for updates (default: 10)<\/p>\n
### Remote whitelist file<\/p>\n
This is the JSON file at your configured URL:<\/p>\n
“`json
\n{
\n “customLists”: [“admin”, “vip”],
\n “admin”: [
\n “Player1”,
\n “Player2”
\n ],
\n “vip”: [
\n “Player3”,
\n “Player4”
\n ]
\n}
\n“`<\/p>\n
– `customLists` – Which lists to use (if empty or missing, everyone is allowed)
\n– Add your own list names with player usernames<\/p>\n
### Special modes<\/p>\n
Set `customLists` to special values:<\/p>\n
– `[“all”]` – Allow everyone
\n– `[“none”]` – Deny everyone (maintenance mode)
\n– `[]` or missing – Allow everyone (default)<\/p>\n
### Messages file: `messages.json`<\/p>\n
Customize the messages players see:<\/p>\n
“`json
\n{
\n “deniedMessage”: “Sorry, You don’t fit the Vibe(SMP)…”,
\n “kickedMessage”: “You no longer fit the Vibe(SMP)…”,
\n “maintenanceMessage”: “Don’t worry, we’ll be right back, just some maintenance”
\n}
\n“`<\/p>\n
## How it works<\/p>\n
1. Plugin loads and reads your local config
\n2. Fetches the whitelist from your URL
\n3. Checks which mode\/lists are active
\n4. Allows or denies players based on the whitelist
\n5. Automatically reloads every X seconds
\n6. Kicks players if they’re removed from the whitelist<\/p>\n
## Examples<\/p>\n
**Allow only admins:**
\n“`json
\n{
\n “customLists”: [“admin”],
\n “admin”: [“Admin1”, “Admin2”]
\n}
\n“`<\/p>\n
**Allow multiple groups:**
\n“`json
\n{
\n “customLists”: [“admin”, “member”],
\n “admin”: [“Admin1”],
\n “member”: [“Player1”, “Player2”, “Player3”]
\n}
\n“`<\/p>\n
**Maintenance mode:**
\n“`json
\n{
\n “customLists”: [“none”]
\n}
\n“`<\/p>\n
**Allow everyone:**
\n“`json
\n{
\n “customLists”: [“all”]
\n}
\n“`<\/p>\n
Or just leave it empty:
\n“`json
\n{}
\n“`<\/p>\n
## Requirements<\/p>\n
– Velocity 3.4.0 or higher
\n– Java 21 or higher
\n– A web server to host your whitelist JSON file<\/p>\n","protected":false},"excerpt":{"rendered":"
Remote-managed whitelist plugin for Velocity proxy with support for multiple lists, maintenance mode, and customizable messages.<\/p>\n","protected":false},"featured_media":0,"template":"","meta":{"_minecraft_slug":"remote-velocity-whitelist","_minecraft_project_id":"T7731QEC","_minecraft_author":"soestin","_minecraft_license":"MIT","_minecraft_downloads":14,"_minecraft_follows":0,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"remote-velocity-whitelist.zip","_minecraft_size_bytes":10240,"_minecraft_version_count":1,"_minecraft_updated_at":"2026-05-15T22:54:37.011572Z","_minecraft_date_created":"2025-11-25T02:59:38.694554Z","_minecraft_date_modified":"2025-11-24T09:59:06.634566Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/remote-velocity-whitelist","_minecraft_icon_attachment_id":0,"_minecraft_imported_at":"2026-06-07T18:38:41+00:00","_minecraft_import_hash":"4a8ceb1faec646cac1118785a8b0ef1f","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[126,92,985],"mod_loader":[986],"minecraft_version":[118,119,120,46,47,48,49,50,51,52,53,54,55,56,57,58,59,36,60,93,94,101,102,62,37,40,73,74,38,78,79,80,81,82],"class_list":["post-131855","mod","type-mod","status-publish","hentry","mod_category-management","mod_category-utility","mod_category-velocity","mod_loader-velocity","minecraft_version-1-16","minecraft_version-1-16-1","minecraft_version-1-16-2","minecraft_version-1-16-3","minecraft_version-1-16-4","minecraft_version-1-16-5","minecraft_version-1-17","minecraft_version-1-17-1","minecraft_version-1-18","minecraft_version-1-18-1","minecraft_version-1-18-2","minecraft_version-1-19","minecraft_version-1-19-1","minecraft_version-1-19-2","minecraft_version-1-19-3","minecraft_version-1-19-4","minecraft_version-1-20","minecraft_version-1-20-1","minecraft_version-1-20-2","minecraft_version-1-20-3","minecraft_version-1-20-4","minecraft_version-1-20-5","minecraft_version-1-20-6","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n