13 min read Intermediate 36.9k

Velocity Proxy Setup Guide for Minecraft Server

Published on November 11, 2025 at 03:09 PM

This guide walks you through configuring a Velocity proxy for your Minecraft server network.

Velocity Proxy Setup Guide for Minecraft Server

Access your Wisp panel: https://panel.verycloud.fr/

Complete documentation: https://verycloud.fr/docs

What is Velocity?

Velocity is a modern, performant, and secure Minecraft proxy that allows you to:

Connect multiple Minecraft servers together
Allow players to move between servers without disconnecting
Reduce load on individual servers
Centralize player authentication
Improve security with modern forwarding
Full support for Minecraft 1.7.2 to 1.21+

Why Use Velocity?

Advantages:

Performance: Written in Java with modern optimizations
Security: Modern forwarding to protect backend servers
Compatibility: Supports Paper, Spigot, Bukkit, Fabric, Forge
Flexibility: Easy configuration with TOML files
Plugins: Growing plugin ecosystem

Velocity Network Architecture

Players → Velocity Proxy (Port 25565) → Backend Servers
                                        ├─ Lobby (Port 25566)
                                        ├─ Survival (Port 25567)
                                        ├─ Creative (Port 25568)
                                        └─ Minigames (Port 25569)

Prerequisites

Before starting, ensure you have:

Access to your VeryCloud Wisp panel
At least 2 Minecraft servers on Wisp:
- 1 server for Velocity (proxy)
- 1+ backend server(s) (Paper, Spigot, etc.)
Wisp login credentials
SSH connection or file manager access

Part 1: Installing Velocity Server

Step 1: Create a New Server for Velocity

Log in to https://panel.verycloud.fr/
In the dashboard, click Create Server (if you haven't created the Velocity server yet)
Select:
- Type: Java (Velocity)
- Version: Velocity (latest version)
- RAM: Minimum 512 MB (1 GB recommended for 50+ players)
- Name: "Proxy-Velocity" or similar
Click Create

Step 2: Select Velocity Server

If you already have a server dedicated to Velocity:

In your server list, click on your Velocity server
You arrive at the server console

Step 3: Downloading Velocity

Via Wisp panel:

Go to Files in the left menu
Check that the velocity.jar file is present
If not, download it:
- Go to https://papermc.io/downloads/velocity
- Download the latest version
- Upload it via panel to the root folder

Step 4: First Velocity Startup

Return to Console
Click Start
Velocity will generate configuration files
Wait for the message: Done! Velocity is ready to accept connections.
Click Stop to stop the server

Part 2: Velocity Configuration

Step 1: Access Configuration File

In Wisp panel, go to Files
Locate and open the velocity.toml file
The file opens in the integrated editor

Step 2: Basic Configuration

Here are the important sections to configure:

Network Configuration

# Bind configuration (generally don't modify)
bind = "0.0.0.0:25577"

# Server MOTD (message displayed in server list)
motd = "&3Welcome to My Minecraft Network\n&bPowered by Velocity"

# Maximum number of players
show-max-players = 100

# Protocol version to announce
# Leave empty for auto-detection
announce-forge = false

Note: Port 25577 is the internal port. Wisp will automatically map to external port (usually 25565).

Backend Server Configuration

This is the most important section. Add your backend servers:

[servers]
# Format: server-name = "address:port"

# Lobby server (default server)
lobby = "127.0.0.1:25566"

# Survival server
survival = "127.0.0.1:25567"

# Creative server
creative = "127.0.0.1:25568"

# Minigames server
minigames = "127.0.0.1:25569"

# You can add as many servers as needed

Important:

If your servers are on the same VPS as Velocity, use 127.0.0.1:PORT
If your servers are on different VPS, use public IP: 123.45.67.89:PORT

Connection Order (Try List)

Define player connection order:

[servers]
# ... your servers above ...

try = [
  "lobby",
  "survival"
]

Players will attempt to connect to lobby first, then to survival if lobby is unavailable.

Forwarding Configuration

CRITICAL for security:

[forwarding]
# Forwarding mode
# Options: "none", "legacy", "modern"
mode = "modern"

# Secret key for modern forwarding
# GENERATE A UNIQUE AND SECURE KEY
secret = "YOUR_SECRET_KEY_HERE"

# Maximum buffer size
forwarding-secret-file = ""

Generating a secret key:

Use a random key generator. Command line example:

openssl rand -base64 32

Or use an online generator: https://generate.plus/en/base64

Key example: dXJhbmRvbWtleWhlcmVmb3JzZWN1cml0eXB1cnBvc2Vz

Step 3: Advanced Configuration (Optional)

Custom Messages

[messages]
# Kick message when no server is available
no-available-servers = "&cNo server available. Try again later."

# Message when already connected to server
already-connected = "&cYou are already connected to this server!"

# Connection denied message
connection-denied = "&cConnection denied. Contact an administrator."

Query Configuration

[query]
# Enable Query protocol
enabled = true

# Port for queries (usually same as game port)
port = 25577

# Show plugins
show-plugins = false

Advanced Configuration

[advanced]
# Network compression size
compression-threshold = 256

# Compression level (1-9, higher = more CPU)
compression-level = -1

# Connection timeout (milliseconds)
connection-timeout = 5000

# Read timeout
read-timeout = 30000

# Enable HAProxy protocol
haproxy-protocol = false

# Enable TCP fast open
tcp-fast-open = false

# Enable BungeeCord plugin messaging channel
bungee-plugin-message-channel = true

# Show ping requests in server list
show-ping-requests = false

# Announce errors in console
announce-proxy-commands = true

# Enable player connection logging
log-player-connections = true

Step 4: Save Configuration

After modifying velocity.toml, click Save at top right
Restart Velocity server via console: Restart

Part 3: Backend Server Configuration

Each backend server (Paper, Spigot, etc.) must be configured to work with Velocity.

Step 1: Paper/Spigot Configuration

For each backend server, you must:

A. Configure Online Mode

In Wisp panel, select your backend server (e.g., Lobby)
Go to Files
Open server.properties
Modify this line:

online-mode=false

Important: Set online-mode=false on all backend servers!

Save

B. Configure Velocity Forwarding (Paper)

If using Paper (recommended):

In backend server, go to Files
Open file config/paper-global.yml (or paper.yml for older versions)
Find the proxies section and modify:

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: "YOUR_SECRET_KEY_HERE"

Important: Use the same secret key as defined in velocity.toml!

Save

C. Configure BungeeCord Mode (Spigot)

If using Spigot or Bukkit:

In backend server, open spigot.yml
Modify:

settings:
  bungeecord: true

Save

Note: Spigot uses BungeeCord legacy mode. Modern forwarding is only available on Paper.

Step 2: Port Configuration

Ensure each backend server listens on a different port:

In server.properties of each backend server:

# Lobby
server-port=25566

# Survival
server-port=25567

# Creative
server-port=25568

These ports must match those defined in velocity.toml

Step 3: Restart Backend Servers

For each backend server:

Go to Console
Click Restart
Verify it starts correctly

Part 4: Essential Velocity Plugins

Installing Plugins

Download plugins from:
In Wisp panel, Velocity server, go to Files
Navigate to plugins folder
Upload the plugin .jar file
Restart Velocity

Recommended Plugins

LuckPerms (Permissions)

Permission management across the entire network.

Installation:

Download from: https://luckperms.net/download
Install on Velocity AND all backend servers
Configure shared database (MySQL recommended)

Configuration:

# In LuckPerms config.yml
storage-method: mysql

data:
  address: localhost:3306
  database: luckperms
  username: root
  password: password

LibertyBans (Moderation)

Centralized ban system.

Download: https://github.com/A248/LibertyBans

Installation:

Install on Velocity only
Configure database
Use commands /ban, /mute, etc.

VelocityTab (Tab List)

Custom player list display.

Download: https://github.com/WiIIiam278/Velocitab

Installation:

Install on Velocity
Configure in plugins/velocitab/config.yml

LuckPerms Velocity (Configuration)

Configuration in plugins/LuckPerms/config.yml:

server: velocity

storage-method: mysql

data:
  address: your-db-host:3306
  database: luckperms
  username: luckperms_user
  password: your_password
  
  # Synchronization between servers
  sync-minutes: 3

Part 5: Commands and Management

Velocity Commands (Console or In-Game)

Basic Commands

/velocity dump
- Generate diagnostic dump

/velocity plugins
- List installed plugins

/velocity version
- Display Velocity version

/velocity reload
- Reload configuration (some changes require restart)

Player Commands

/server <name>
- Connect to specific server

/server
- View available servers

Permissions

Configure permissions with LuckPerms:

# Permission to use /server
velocity.command.server

# Permission to see all servers
velocity.command.server.list

# Admin permission
velocity.admin

Part 6: Network Security

Step 1: Firewall on Backend Servers

CRITICAL: Backend servers should NOT be directly accessible from Internet.

UFW Configuration (if applicable)

On each backend server:

# Block external access to server port
ufw deny 25566/tcp

# Allow only Velocity (same machine)
ufw allow from 127.0.0.1 to any port 25566

Note: With Wisp, this can be managed via port allocations.

Step 2: Wisp Allocation Configuration

In Wisp, for each backend server:
Go to Network
Ensure backend ports are not exposed publicly
Only Velocity port should be accessible from outside

Step 3: Modern Forwarding

Velocity's modern forwarding encrypts player information, preventing IP spoofing.

Verification:

In velocity.toml:

[forwarding]
mode = "modern"
secret = "your-secret-key"

In Paper paper-global.yml:

proxies:
  velocity:
    enabled: true
    secret: "your-secret-key"

Keys must match exactly!

Part 7: Connection and Testing

Step 1: Starting Servers

Start all backend servers first:
- Lobby
- Survival
- Creative
- etc.
Wait for them to fully start
Start Velocity last

Step 2: Console Verification

Velocity console should display:

[INFO] Listening on /0.0.0.0:25577
[INFO] Done! Velocity is ready to accept connections.

Step 3: Connect to Network

Launch Minecraft
Add server with:
- Address: your-vps-ip:25565 (or configured port)
- Name: Your network name
Connect
You should arrive at default server (lobby)

Test the /server command:

/server

You should see list of all your servers.

Test connection to another server:

/server survival

You should be teleported to survival server without disconnecting.

Part 8: Troubleshooting

Problem: "Can't connect to server"

Possible causes:

Velocity not started
- Solution: Check Velocity console
Incorrect port
- Solution: Check allocations in Wisp
Firewall blocking connection
- Solution: Check firewall rules

Problem: "Connection but immediate kick"

Possible causes:

No backend server available
- Solution: Check that backend servers are started
- Check Velocity logs to see if it can connect to backends
Bad forwarding configuration
- Solution: Verify secret keys match
- Verify online-mode=false on backends
Incorrect ports in velocity.toml
- Solution: Verify ports match backend servers

Problem: "Can't connect to backend server"

Solutions:

Verify backend server is started:
- In Wisp, go to backend server
- Check console
Verify ports in velocity.toml:
```
lobby = "127.0.0.1:25566"
```
Port must match server-port in backend's server.properties

Check Velocity logs:

[ERROR] Unable to connect to server lobby

Problem: "Player UUID mismatch"

Cause: Incorrect forwarding configuration

Solutions:

Verify online-mode=false on all backends
Check forwarding configuration:
- Velocity: velocity.toml → [forwarding] → secret
- Paper: paper-global.yml → proxies.velocity.secret
Secrets must be identical
Restart all servers after modification

Problem: "Can't use /server command"

Cause: Missing permissions

Solutions:

Install LuckPerms

Give permission:

/lp user <player> permission set velocity.command.server true

Or give to all players:

/lp group default permission set velocity.command.server true

Part 9: Optimization and Performance

JVM Configuration for Velocity

In Wisp, for your Velocity server:

Go to Startup
Modify JVM arguments:

-Xms512M -Xmx1G -XX:+UseG1GC -XX:G1HeapRegionSize=4M -XX:+UnlockExperimentalVMOptions -XX:+ParallelRefProcEnabled -XX:+AlwaysPreTouch

Backend Server Configuration

For each Paper backend server:

In paper-global.yml:

# Network optimizations
network:
  kick-on-oversized-packet-exception: true
  
# Chunk optimizations
chunk-loading:
  min-load-radius: 2
  max-concurrent-sends: 2
  
# Disable unnecessary network features
feature-seeds:
  generate-random-seeds-for-all: true

Performance Monitoring

Use these plugins to monitor:

Spark: Profiling and monitoring
- https://spark.lucko.me/
Tab: TPS and performance display
- https://github.com/NEZNAMY/TAB

Part 10: Advanced Configuration

Shared Database

To share data between servers (inventories, economy, etc.):

MySQL Configuration

Get a MySQL server (VeryCloud can provide)
Create a database
Configure each plugin to use MySQL:

LuckPerms:

storage-method: mysql
data:
  address: mysql.example.com:3306
  database: luckperms
  username: luckperms_user
  password: password

Multiple Lobby System

For multiple lobbies with load balancing:

In velocity.toml:

[servers]
lobby1 = "127.0.0.1:25566"
lobby2 = "127.0.0.1:25570"
lobby3 = "127.0.0.1:25571"
survival = "127.0.0.1:25567"

try = [
  "lobby1",
  "lobby2", 
  "lobby3"
]

Velocity will automatically distribute players among available lobbies.

Maintenance Messages

To display custom message during maintenance:

In velocity.toml:

[forced-hosts]
"maintenance.yourserver.com" = [
  "maintenance"
]

[servers]
maintenance = "127.0.0.1:25580"

Create a "maintenance" server that displays a message.

Part 11: Compatible Backend Plugins

Synchronization Plugins

These plugins work well with Velocity:

MySQLPlayerDataBridge - Inventory sync
RedisBungee - Redis synchronization
SkinsRestorer - Skin sync
BungeeGuard - Additional security
MultiChat - Global chat between servers

Installing Backend Plugins

For plugins that must communicate via Velocity:

Install plugin on all backend servers
Configure shared MySQL database
Restart all servers

Part 12: Backup and Maintenance

Backup Script

Create regular backups:

Velocity Configuration:

# Backup velocity.toml
cp velocity.toml velocity.toml.backup

Via Wisp:

Go to Backups
Create manual backup
Configure automatic backups

Updating Velocity

Download new Velocity version
Stop Velocity server
Replace velocity.jar with new version
Restart server
Check logs for errors

Regular Maintenance

Daily:

Check error logs
Monitor RAM/CPU usage
Check player connections

Weekly:

Backup configurations
Update plugins
Clean old logs

Monthly:

Update Velocity and backend servers
Review permissions and configurations
Test backups

VeryCloud Support

If you encounter difficulties:

Documentation: https://verycloud.fr/docs

Wisp Panel: https://panel.verycloud.fr/

Technical Support:

Open ticket from VeryCloud customer area
Contact support via Discord
Consult online knowledge base

When contacting support, provide:

Your Velocity server name
Console logs (last 100 lines)
Your velocity.toml file (mask secrets)
Detailed problem description

Additional Resources

Conclusion

Your Minecraft network with Velocity is now configured and operational! You can now:

Connect multiple servers together
Allow players to navigate between servers
Centralize permission management
Improve security with modern forwarding
Scale your network easily

Key points to remember:

Modern forwarding is essential for security
Backend servers must have online-mode=false
Velocity must start after backend servers
Backup configurations regularly
Monitor performance and logs

Happy gaming and good administration of your Minecraft network with VeryCloud!

Velocity Proxy Setup Guide for Minecraft Server

What is Velocity?

Why Use Velocity?

Velocity Network Architecture

Prerequisites

Part 1: Installing Velocity Server

Step 1: Create a New Server for Velocity

Step 2: Select Velocity Server

Step 3: Downloading Velocity

Step 4: First Velocity Startup

Part 2: Velocity Configuration

Step 1: Access Configuration File

Step 2: Basic Configuration

Network Configuration

Backend Server Configuration

Connection Order (Try List)

Forwarding Configuration

Step 3: Advanced Configuration (Optional)

Custom Messages

Query Configuration

Advanced Configuration

Step 4: Save Configuration

Part 3: Backend Server Configuration

Step 1: Paper/Spigot Configuration

A. Configure Online Mode

B. Configure Velocity Forwarding (Paper)

C. Configure BungeeCord Mode (Spigot)

Step 2: Port Configuration

Step 3: Restart Backend Servers

Part 4: Essential Velocity Plugins

Installing Plugins

Recommended Plugins

LuckPerms (Permissions)

LibertyBans (Moderation)

VelocityTab (Tab List)

LuckPerms Velocity (Configuration)

Part 5: Commands and Management

Velocity Commands (Console or In-Game)

Basic Commands

Player Commands

Permissions

Part 6: Network Security

Step 1: Firewall on Backend Servers

UFW Configuration (if applicable)

Step 2: Wisp Allocation Configuration

Step 3: Modern Forwarding

Part 7: Connection and Testing

Step 1: Starting Servers

Step 2: Console Verification

Step 3: Connect to Network

Step 4: Navigation Test

Part 8: Troubleshooting

Problem: "Can't connect to server"

Problem: "Connection but immediate kick"

Problem: "Can't connect to backend server"

Problem: "Player UUID mismatch"

Problem: "Can't use /server command"

Part 9: Optimization and Performance

JVM Configuration for Velocity

Backend Server Configuration

Performance Monitoring

Part 10: Advanced Configuration

Shared Database

MySQL Configuration

Multiple Lobby System

Maintenance Messages

Part 11: Compatible Backend Plugins

Synchronization Plugins

Installing Backend Plugins

Part 12: Backup and Maintenance

Backup Script

Updating Velocity

Regular Maintenance

VeryCloud Support

Additional Resources

Official Documentation

Community

Plugins and Resources

Conclusion

Join our Discord community server