How to Link Servers With Velocity or BungeeCord

A Minecraft Velocity proxy setup has three parts: a Velocity server that players connect to, two or more Paper servers behind it (a lobby and, say, survival), and modern forwarding so the backends trust the proxy. You list the backends in velocity.toml, set online-mode=false plus the forwarding secret on each Paper server, and players move between them with /server.

Velocity is the proxy maintained by the PaperMC team, and it is the one this guide uses. BungeeCord still works and is covered briefly at the end, but its forwarding method is the less secure one.

How a Velocity network works

Players only ever see the proxy address. Velocity checks each account with Mojang (it keeps online-mode = true), then sends the player to the first server in its try list, usually the lobby. The backends run in offline mode because the proxy already did the check, and forwarding passes them the player's real UUID, IP and skin.

The PaperMC docs say Velocity requires Java 25 or newer, and modern forwarding needs Minecraft 1.13 or higher on the backends (Paper 1.14+ supports it natively).

Minecraft Velocity proxy setup, step by step

1. Create one server for the proxy and one for each backend (lobby, survival). Install Paper on the backends.
2. Start Velocity once so it creates velocity.toml and forwarding.secret, then stop it (type end in its console).
3. In velocity.toml, keep online-mode = true, set player-info-forwarding-mode = "modern", and list your backends under [servers] with their IP and port. Put "lobby" first in try.
4. Open forwarding.secret and copy the secret.
5. On each Paper backend, set online-mode=false in server.properties and make sure settings.bungeecord is false in spigot.yml.
6. On each backend, edit config/paper-global.yml: proxies.velocity.enabled: true, online-mode: true and the secret you copied.
7. Restart the backends, then start Velocity. Join using the proxy address and type /server survival to test the switch.

bind = "0.0.0.0:25565"
online-mode = true
player-info-forwarding-mode = "modern"
forwarding-secret-file = "forwarding.secret"

[servers]
lobby = "203.0.113.10:25601"
survival = "203.0.113.10:25602"
try = [
  "lobby"
]

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

The online-mode under proxies.velocity must match the proxy's. For Paper 1.18.2 or older the same keys live in paper.yml under settings.velocity-support. Keep the secret private: it is what lets a backend trust that a player really came through your proxy.

Velocity commands for players and admins

For more on seeing who is where, see how to see who is online on a Minecraft server.

Make the lobby feel like a lobby

The lobby is a normal Paper server, so you build it like any world: a small spawn with signs or portals pointing to each game. Set gamemode=adventure in its server.properties so visitors cannot break blocks, protect the area with WorldGuard (see how to protect builds) and keep it light: a lobby needs far less RAM than a survival world. If players should be able to switch by clicking an NPC or a sign, add a lobby plugin that calls the proxy.

What about BungeeCord?

BungeeCord and its forks use legacy forwarding, enabled with settings.bungeecord: true in spigot.yml. Velocity can also speak legacy forwarding if a backend needs it. The PaperMC docs call legacy forwarding “fundamentally insecure”, because it relies on nobody but the proxy being able to reach the backend. For a new network on Minecraft 1.13 or newer, Velocity with modern forwarding is the safer choice. If your network mixes in Bedrock players, Geyser also has a proxy build; start with our Geyser and Floodgate guide.

Build your network on TheGameHosting

A Velocity network is several servers working together, and each one is a plan you size on its own: a few GB for the proxy and lobby, more for survival. On TheGameHosting every server is ready about 60 seconds after payment, you edit velocity.toml and paper-global.yml in Files, and the Network tab shows each server's address to put in [servers]. Whether Velocity is offered directly in the Version tab for your plan is something our team can confirm by chat or ticket before you start. Servers run 24/7 on AMD Ryzen 9950X and 7950X3D with DDoS protection included.

Servers run on AMD Ryzen 9950X and 7950X3D processors with DDR5 memory and NVMe storage, with DDoS protection included and locations in Dallas and Amsterdam. Plans start at $1.90 a month for 2 GB, with unlimited slots and no setup fee, and support answers 24/7 by chat and tickets. Have a look at our Minecraft server hosting or go straight to plans and pricing, and use the code FULL2026 for 15% off for life.

FAQ

Hosting for these games

• Minecraft server hostingPaper backends sized per server
• Minecraft Bedrock server hostingFor phone and console players