10 min read

How to Set Up a Velocity Network (Link Multiple Servers Under One IP)

Set up a Velocity proxy network in Minecraft: put Paper backends behind one IP with modern forwarding, the secret, and the firewall step that seals it.

How to Set Up a Velocity Network (Link Multiple Servers Under One IP)

A Velocity network is one proxy jar sitting in front of several Paper servers, so a single IP drops everyone into a lobby and they hop between worlds without reconnecting. The build is short: download Velocity, run it once so it writes velocity.toml and a forwarding.secret, list your backend servers in the config, then on every backend set online-mode=false, paste that same secret into paper-global.yml, and firewall the backend ports so nothing but the proxy can reach them. That last step is the one people skip, and it's the one that gets an offline-mode backend hijacked.

Velocity vs BungeeCord, and what the proxy actually is

A proxy is a lightweight server that sits between players and your backend servers, forwarding traffic and letting people move between worlds on one connection. If you're fuzzy on how a lobby, a hub, and separate backend worlds fit together, what a server network is covers the concept without me re-explaining it here.

For the software, use Velocity. It's GPLv3-licensed, faster than the old options, and its "modern" forwarding is more secure than BungeeCord's legacy scheme. BungeeCord was the standard for years, and PaperMC's Waterfall fork used to be the go-to hardened version of it, but Waterfall went end-of-life in 2024. Don't start a new network on abandoned software. Velocity is what PaperMC actively develops, and it pairs cleanly with Paper backends.

The thing that surprises people: the proxy holds no world. It doesn't load chunks, doesn't tick entities, doesn't save region files. All it does is route connections. That means it needs almost nothing for memory. 512MB to 1GB is plenty, where each backend world wants gigabytes. Velocity runs as its own Java program, not a plugin you drop into a server, and it needs a modern JDK. Java 17 or newer works, and the same JDK you already installed for Paper is fine.

Step 1 — Run Velocity once to generate its configs

Grab the latest stable Velocity jar from papermc.io/downloads/velocity and drop it into its own empty folder, separate from every backend. Then launch it once:

java -Xms512M -Xmx512M -jar velocity.jar

On first run it binds to port 25565 and writes three things into the folder: velocity.toml (the main config), a forwarding.secret file containing a random auto-generated secret, and an empty plugins/ folder. Those -Xms512M -Xmx512M flags are the whole memory footprint, and they're that small for one reason: the proxy never loads a world, so there's nothing to hold in RAM. Once you see it start up, stop it with Ctrl+C (or type shutdown in its console) and open velocity.toml to edit.

Step 2 — Point velocity.toml at your backends

This is where you tell the proxy which servers exist and how it authenticates players. A handful of keys matter:

  • bind = "0.0.0.0:25565" — the one public port players actually connect to. This is the only address you'll expose to the internet.
  • online-mode = true — the proxy is now what checks players against Mojang's auth servers. Online-mode lives here, at the proxy, for the entire network. Leave it on.
  • player-info-forwarding-mode = "modern" — the four choices are none, legacy, bungeeguard, and modern. Use modern for Paper backends; it passes the player's real UUID and skin to the backend securely.
  • forwarding-secret-file = "forwarding.secret" — points at the secret file from Step 1. Don't paste the secret into the toml itself; this key just names the file.

Then the [servers] table, which maps friendly names to internal addresses:

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

try = ["lobby"]

Those 127.0.0.1 addresses are internal, reachable only from the same machine (more on why that matters shortly). The try list sets where players land first, so try = ["lobby"] makes the lobby your hub. Save and close.

Step 3 — Turn each backend into a proxy-mode Paper server

Each backend is a normal Paper server with two files adjusted. If you haven't stood one up before, the Paper setup walkthrough is the prerequisite here; build each backend that way first, then flip these settings.

In server.properties:

  • online-mode=false — the proxy handles auth now, so the backend stops checking Mojang itself. This looks alarming, and it is genuinely dangerous if you stop here, safe only once the secret and firewall from the next section are in place. Hold that thought.
  • server-port=25566 — give each backend a distinct port matching its [servers] entry. Lobby on 25566, survival on 25567, and so on.

In config/paper-global.yml, find the proxies: block and set the velocity section:

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: '<paste the contents of forwarding.secret>'

The online-mode: true here must match velocity.toml's online-mode. If one says true and the other false, forwarding breaks. And secret gets the literal contents of the forwarding.secret file copied over from the proxy folder, in quotes. If you ever had BungeeCord forwarding turned on, also open spigot.yml and set settings.bungeecord: false, or the two schemes fight.

Restart the backend. If the secret is wrong, missing, or forwarding is enabled on only one side, players connecting through the proxy get kicked instantly with "This server requires you to connect with Velocity." That message is your signal the two sides don't agree; recheck the secret first, since a stray space or a partial copy is the usual culprit.

The forwarding secret and the firewall bypass that gets servers hijacked

Here's the part nobody should skip. Every backend now runs online-mode=false, which means the backend verifies nobody. It trusts whatever username walks in. That's fine when the only thing that can reach it is your proxy. It is a disaster the moment a backend port is reachable from the open internet.

Picture it: your survival backend listens on 25567, and you (or your host's default firewall) leave that port open to the world. An attacker doesn't bother with the proxy. They connect straight to 25567, skipping the proxy and its Mojang check entirely, and log in as any username they type, including an op's. Offline mode won't stop them, because offline mode was never designed to. Modern forwarding plus a correct secret does make a raw direct connection get rejected with that Velocity kick message, but treat that as a backstop, not your only wall.

Defense in depth, two rules:

  1. Bind backends to 127.0.0.1 (or a private LAN IP if the proxy is on a different box on your network). That's what the 127.0.0.1:25566 addresses in [servers] do. A backend bound to loopback simply can't be reached from outside the machine.
  2. Only expose the proxy's 25565. When you port-forward, forward that one port and nothing else. Never forward 25566, 25567, or any backend port. If the router can't route to a backend, neither can an attacker.

The forwarding.secret is the single most valuable credential on the network. Anyone who has it can forge a legitimate-looking forwarded connection and impersonate any player. Keep it out of screenshots, out of pastebins, out of any backup archive you share. If it ever leaks, generate a new one and update every backend. While you're locking the box down, hardening the server against DDoS is a reasonable next read, since a single public port is also a single target.

Test it, add the hub, and match versions

Connect a client to your proxy's public IP on 25565. You should drop onto whatever try names, the lobby in our setup. From there, move between backends with Velocity's built-in /server <name> command: /server survival, /server lobby. There's also /glist, which lists who's connected and which backend they're on, handy for spotting whether a world is actually getting traffic.

One version detail trips people up. The proxy itself can speak a range of protocol versions, but each backend is pinned to whatever version its jar is built for. Players have to match that backend's version. For a plugin network that means the version you built your Paper backends on, which should be the newest one Paper's downloads page marks as stable rather than a brand-new drop still behind its experimental toggle. Tell players that exact version, and you can point them at the matching page, like /servers/version/26.2 or /servers/version/26.1, so they know which client to launch. If you want players on mixed client versions to all connect, that's a job for ViaVersion on the backends, not something the proxy solves for you.

The payoff of splitting worlds into separate processes is capacity. A busy survival world and a packed minigame each get their own CPU and RAM budget, and they can even live on separate hardware behind the same proxy. If you're sizing that out, how many players a server can hold walks through what one backend can realistically carry before you split the load.

FAQ

Do I need a separate machine for the proxy?

No. Velocity co-hosts fine on the same box as your backends, because it uses no world memory, so it isn't competing with them for RAM. Give it its own folder and hand it the public port (25565), while every backend binds to 127.0.0.1 on its own port. The loopback binding is doing double duty here: it keeps backends off the internet and keeps the local proxy-to-backend hop fast.

Isn't online-mode=false how servers get griefed?

It is, but only when the server is directly reachable from the internet. On a Velocity network the proxy runs the Mojang check and forwards the verified identity down, so the backend never authenticates anyone itself. What people miss is that modern forwarding hands the backend each player's real UUID, not a random offline one, so ops.json and whitelist.json keep matching the exact same players they would on a normal online server, and any plugin that keys off UUID does too. Nothing about running the backend in offline mode changes who's an op. If you want to prove the box is actually sealed, point a client straight at a backend port like 25567: on a correctly firewalled setup the connection just times out, and if it somehow lands it gets the Velocity kick. A raw connection that succeeds and logs you in means the firewall is broken, not that offline mode failed.

How do players keep one inventory across servers?

They don't, out of the box. Velocity syncs nothing, so each backend saves its own separate world, inventory, and ender chest. To share inventories you need a plugin that stores them in a shared database, MySQL or Redis, that every backend reads and writes. Network-wide ranks work the same way: LuckPerms in SQL mode, so a promotion on the lobby follows the player to survival. Those are plugin features, not anything the proxy provides.

Can Bedrock players join a Velocity network?

Yes. Install Geyser and Floodgate in the proxy's plugins/ folder, using the Velocity build of each, so the proxy is the single crossplay entry point on 19132. Then put Floodgate on every backend with the same key.pem file copied across, and set send-floodgate-data: true on the proxy so backends trust the forwarded Bedrock data. The wiring differs from a single-server setup; the Geyser and Floodgate crossplay guide covers the shared-key details.