Velocity Proxy Setup#

Velocity is a high-performance proxy that links multiple Minecraft servers under one IP address.

Proxy overview#

A proxy server acts as a gateway that forwards player connections to backend servers. Players connect once and can switch between servers (lobby, survival, creative, etc.) without disconnecting.

Prerequisites#

• Two or more Paper-based Minecraft servers
• A Velocity proxy server (contact QualityNode support to provision one)

Configuration steps#

Step 1: Configure the proxy#

1. Access your proxy server in the control panel
2. Go to the Files tab
3. Open velocity.toml
4. Edit the [servers] section to add your backend servers:

[servers]
lobby = "LOBBY_HOST_FROM_PANEL:LOBBY_PORT_FROM_PANEL"
survival = "SURVIVAL_HOST_FROM_PANEL:SURVIVAL_PORT_FROM_PANEL"
creative = "CREATIVE_HOST_FROM_PANEL:CREATIVE_PORT_FROM_PANEL"

try = ["lobby"]

Replace every placeholder with the host and port displayed for that backend server. Do not copy an address from another account or an example.

Step 2: Get the forwarding secret#

1. In your proxy's Files tab, open forwarding.secret
2. Copy the entire text content

This secret enables secure communication between the proxy and backend servers.

Step 3: Restart the proxy#

Restart your proxy to apply the configuration changes.

Step 4: Configure backend servers#

For each backend server:

Edit server.properties

online-mode=false
network-compression-threshold=-1

Edit config/paper-global.yml

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: "paste-your-forwarding-secret-here"

Step 5: Configure Fabric servers#

If any backend server runs Fabric, install FabricProxy-Lite and configure it with your forwarding secret.

Step 6: Configure Geyser (Bedrock support)#

To allow Bedrock players on your network:

1. Remove Geyser from backend servers
2. Install Geyser-Velocity on the proxy
3. Install Floodgate-Velocity on the proxy

Step 7: Launch and test#

Start all servers and connect through the proxy. Use /server <name> to switch between servers.

Useful proxy plugins#

Architecture example#

Players
   |
   v
[Velocity Proxy] ----+---- [Lobby Server]
                     |
                     +---- [Survival Server]
                     |
                     +---- [Creative Server]

Troubleshooting#

"If you see this error, a proxy is attempting to connect..."#

• Verify the forwarding secret matches between proxy and backend
• Ensure online-mode: true is set in paper-global.yml velocity section
• Check that velocity is enabled in paper-global.yml

Players can't switch servers#

• Verify server names in velocity.toml match exactly
• Check backend servers are running and accessible
• Review proxy logs for connection errors

High latency between servers#

• Use the backend connection values displayed by the server panel
• Ensure all servers are in the same datacenter

See also#

• Proxy Software Comparison
• MySQL Databases