Velocity Setup: Connect Your Minecraft Servers into a Network

This guide is for server owners who want one address, such as play.example.com, that sends players to several servers: a lobby, a survival world, a minigame. By the end you will have a Velocity proxy running, a Paper lobby and a Paper game server connected to it with modern forwarding, and the backends closed to everyone except the proxy.

Plan the network before you install anything#

A Velocity network has one public server (the proxy) and any number of backend servers behind it. Players only ever connect to the proxy. It logs them in with Mojang, then passes them to a backend. Every backend needs its own port, and the proxy needs the public one.

We will use this layout in the examples. Change the numbers to suit your machine.

If you have not built a Paper server yet, start with our Paper server setup guide, then come back. You need two working Paper servers that start cleanly on their own.

Velocity is made by the PaperMC project. Its docs describe it as a modern, high-performance proxy and an alternative to Waterfall and BungeeCord.

Velocity The PaperMC project's Minecraft server proxy that links several servers behind one address and forwards player data to them. On PaperMC

Install and start Velocity#

The Velocity docs say it needs at least Java 25. Check that first, because an older Java will refuse to start the jar. Download the latest stable Velocity jar from the PaperMC downloads page, put it in its own empty folder (not inside a Paper folder), and start it once so it creates its files.

#!/bin/sh
java -Xms1G -Xmx1G -XX:+UseG1GC -XX:G1HeapRegionSize=4M -XX:+UnlockExperimentalVMOptions -XX:+ParallelRefProcEnabled -XX:+AlwaysPreTouch -XX:MaxInlineLevel=15 -jar velocity*.jar

chmod u+x start.sh
./start.sh

Register your servers in velocity.toml#

Open velocity.toml. Three parts matter for a first network: the server list, the try order and the forwarding mode.

bind = "0.0.0.0:25565"
player-info-forwarding-mode = "modern"

[servers]
lobby = "127.0.0.1:25566"
survival = "127.0.0.1:25567"

try = ["lobby"]

The 127.0.0.1 addresses above suit servers running side by side on one machine without containers, such as a VPS. On Pterodactyl use the address from the note below instead.

• [servers] maps a name you choose to an address and port.
• try lists where players land when they join or when their server closes. Put the lobby first. The docs show it as an array, so you can add a fallback such as ["lobby", "survival"].
• player-info-forwarding-mode set to modern is the setting Paper understands.
• online-mode stays on for the proxy, so Mojang accounts are checked once, at the front door.

Velocity also supports [forced-hosts], which sends players to a chosen server depending on the hostname they typed, for example "survival.example.com" = ["survival"]. Skip it until the basics work.

Turn on modern forwarding on each Paper server#

Velocity creates a forwarding.secret file. Its contents are a shared password between the proxy and every backend. Do the following on each Paper server (lobby and survival), with the server stopped.

1. server.properties#

online-mode=false
server-port=25566

Use the right port for each server. Backends must run in offline mode because the proxy does the login.

• VPS or your own machine (no containers): if the proxy and backends share the machine, you can also add server-ip=127.0.0.1, one of the options the Velocity docs suggest, so the backend only listens locally.
• Pterodactyl: leave server-ip empty. The server runs inside its own container, so binding it to the container's own loopback address would stop the proxy reaching it. Set the port to the backend's allocated port, and control who can reach it with the allocation (see the next section).

2. config/paper-global.yml#

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

Paper documents these three keys: enabled defaults to false, online-mode should match the proxy's online-mode, and secret must equal the proxy's forwarding.secret. Modern forwarding works with Paper 1.14 or later, or Paper 1.13.1 and 1.13.2 from build 377 onwards. On Paper 1.18.2 or older the keys live under settings.velocity-support in paper.yml.

3. spigot.yml#

Make sure settings.bungeecord is false. That switch is for the older forwarding method, and the Velocity docs say to turn it off when using modern forwarding.

Editing these files is the same on every host. On Pterodactyl use the File Manager, on Multicraft the Files page, on a VPS your editor of choice.

Close the backends to the public#

With online-mode=false, anyone who can reach a backend directly could pretend to be any player. The Velocity docs call this extremely dangerous and say modern forwarding is not a replacement for a firewall.

Start the network and test the first join#

1. Start the lobby and the survival server first, and wait until both say they are done loading.
2. Start Velocity.
3. Join the proxy address in Minecraft. You should land on the lobby, because it is first in try.
4. Type /server to see the configured servers, and use it to switch to survival.

If you change velocity.toml later, /velocity reload makes the proxy read it again. The built-in /send command moves other players, and /glist shows player counts per server, but it is granted to nobody by default, so give the permission to your staff.

Make the lobby worth landing in#

The lobby is the first thing every player sees. Give it a spawn, a way to reach each game server and a few leaderboards. Our lobby design guide covers navigation with NPCs, holograms and menus.

If you would rather not build one from scratch, the store sells ready-made lobby schematics. One example is Fantasy Lobby, made by our team, which the catalogue describes as a fantasy minigame lobby with NPC hub and leaderboard zones, compact and adaptable.

Made by our team Builds Fantasy Lobby | Minigames Hub 100x100 Fantasy minigame lobby with NPC hub and leaderboard zones, compact and adaptable. $2.15 $3.59 View product

Add another game server later#

Adding a server to a running network takes four steps:

1. Create a new Paper server with its own port and repeat the three Paper config steps, using the same forwarding secret.
2. Add a line to [servers], for example minigames = "127.0.0.1:25568" (or the 172.18.0.1 address on Pterodactyl).
3. Run /velocity reload or restart the proxy.
4. Allow the new port only for the proxy, as in the firewall step.

Back up each server before you change anything, and when you update Minecraft, follow our guide to updating Paper without breaking plugins one backend at a time.