Velocity is a proxy developed by the Paper Team as a fast, modern replacement for BungeeCord and Waterfall. It’s under active development and is the recommended proxy for new networks.

Plugins

Velocity has its own plugin ecosystem separate from BungeeCord/Waterfall. Spigot/Paper plugins won’t work on Velocity, and most BungeeCord plugins won’t either unless they explicitly support both. You can find Velocity plugins here:

Setting Up Velocity

The basic setup involves installing Velocity on one server and configuring it to forward players to your backend servers.

Order a separate server for the proxy (or use an existing one with an available port)
Install Velocity using the Edition Installer or upload the Velocity jar from Paper’s downloads
Start the server once to generate config files, then stop it
Open velocity.toml in the File Manager
Under [servers], add your backend servers using their actual IP and port. For WinterNode servers, find these under Management → Allocations on each backend server:

[servers]
lobby = "your.backend.ip:port"
survival = "your.other.backend.ip:port"

Set try to the order players should be connected:

try = ["lobby", "survival"]

Save and restart Velocity

For the full configuration reference, see Paper’s Getting Started guide.

Securing Your Backend Servers

Without proper security, players could bypass the proxy and connect directly to your backend servers. Velocity uses modern forwarding to solve this.

In velocity.toml, set the forwarding mode:

player-info-forwarding-mode = "modern"

Open the forwarding.secret file in your Velocity server’s root directory and copy the secret string inside it
On each backend Paper server, open config/paper-global.yml and paste that secret string as the secret: value:

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: "paste-the-contents-of-forwarding.secret-here"

Copy the File Contents, Not the Filename

The secret: value must be the string inside the forwarding.secret file — not the filename itself. Open the file in File Manager and copy what’s in it.

Set online-mode=false in each backend server’s server.properties (the proxy handles authentication instead)
Restart all servers

For additional security options, see the Velocity Security docs.

Troubleshooting

`Backend server is online-mode!`

java.lang.IllegalStateException: Backend server is online-mode!

Your Paper backend still has online-mode=true in server.properties. Set it to false — the proxy handles authentication, so Paper does not verify players directly.

`Player info forwarding is disabled`

WARN: Player info forwarding is disabled! All players will appear to be connecting from the proxy and will have offline-mode UUIDs.

The velocity section in your Paper server’s config/paper-global.yml has enabled: false. Set it to enabled: true and restart Paper.

`Unable to verify player details`

ERROR: disconnected while connecting to lobby: Unable to verify player details

The forwarding secret doesn’t match between Velocity and Paper. Re-open forwarding.secret on your Velocity server, copy its contents, and paste the value into the secret: field in Paper’s config/paper-global.yml. Restart both servers.

`This server requires you to connect with Velocity`

Paper has modern forwarding enabled but Velocity is not configured to use it, or the secrets don’t match. Confirm player-info-forwarding-mode = "modern" is set in velocity.toml and that the secret matches on both sides.

Connection refused to backend

Connection refused: your.ip:port

The IP or port in velocity.toml under [servers] is incorrect. Check Management → Allocations on your Paper server for the correct values and update velocity.toml accordingly.