How to set up a Velocity network

A proxy network joins several Minecraft servers behind one address. Players connect to the proxy, land in a lobby, and can move to other servers such as survival or minigames without disconnecting. This guide covers a basic setup with Velocity and Paper servers.

How a network works

The proxy is the only server players connect to. Behind it run the backend servers, each a normal Paper server with its own world and plugins, for example a lobby and a survival server. The proxy handles logins and passes each player to a backend. Velocity is the modern, actively developed proxy from the Paper team. BungeeCord is the older proxy, and Waterfall was a fork of it that is no longer maintained. Velocity is the usual choice for new networks.

Configure velocity.toml

Start Velocity once to create velocity.toml. Set the address players connect to with bind (port 25565 by default), then list your backend servers:

[servers]
lobby = "127.0.0.1:30066"
survival = "127.0.0.1:30067"
try = ["lobby"]

Each name points to a backend's address and port. The try list is the order of servers a player is sent to when they join or when the server they are on goes down.

Modern forwarding

Backends need to know each player's real name, UUID and skin. Velocity sends this with modern forwarding, secured by a shared secret. In velocity.toml set:

player-info-forwarding-mode = "modern"

Velocity stores the secret in a file next to its config, usually forwarding.secret. Copy that value. Then on each Paper backend, open Paper's global config file (paper-global.yml in the config folder) and in the Velocity section under proxies set enabled: true, online-mode: true and secret: to the same value. Leave the BungeeCord option in spigot.yml off, because that is a different forwarding method.

Backends in offline mode, behind a firewall

Because the proxy checks accounts, each backend's server.properties needs online-mode=false. That is only safe if players can't reach the backends directly. Otherwise anyone could connect to a backend's port with any name, including an admin's.

• Run backends on ports that only the proxy can reach. Bind them to 127.0.0.1 if they are on the same machine, or block their ports in the firewall except from the proxy's IP.
• Modern forwarding with a secret adds another layer, because the backend rejects connections without the right secret.
• Keep the secret private, and change it if it ever leaks.

Votes and listing your network

For vote rewards on a network, install NuVotifier on the proxy and use its forwarding to send each vote to the backend servers, as described in how to set up Votifier. Test it with our Votifier tester. When you list the network on CraftRank, use the proxy's address, and check it from outside with our server status checker. Players connecting through Geyser can join a Velocity network too: install Geyser and Floodgate on the proxy, as explained in the crossplay guide.