Minecraft Server Networks: Setting Up a Velocity Proxy

A Minecraft network is several servers sitting behind one address, with a proxy in front of them. Players connect to one IP, land on a lobby, and move to survival, creative or minigames without ever leaving the game. This guide covers what a proxy does, which proxy to run in 2026, how to connect your backend servers, and — most importantly — how to configure the security, because a proxy set up from a half-remembered tutorial lets anyone on the internet join your servers as any player they like.

This is a Java Edition topic. Single-server setup is in Getting started with your Minecraft server, and the plugin basics used below are in How to install plugins for Minecraft Java Edition.

What a Proxy Actually Does

A proxy is a small server that speaks the Minecraft protocol but has no world of its own. Players connect to it; it holds that connection open and relays traffic to whichever backend server the player is currently on. When they switch servers, the proxy swaps the backend behind the scenes and the client never disconnects.

What that buys you:

• One address for everything. Players save one IP. You can add, move or rebuild a backend without anyone having to update their server list.
• Server switching without a disconnect. /server survival moves a player instantly. No loading screen back to the multiplayer menu.
• Independent servers. Each backend runs its own jar type, its own version, its own mod or plugin set and its own memory allocation. A modded server and a plugin server can coexist on one network — something a single server cannot do at all.
• A network-wide layer. Chat, tab lists, bans, maintenance mode and player counts can be handled once on the proxy instead of separately on every backend.
• Restart isolation. Rebooting the minigames server does not touch survival.

What it does not buy you: performance. A proxy adds a hop; it does not make a server faster. If one server is lagging, splitting it into three servers behind a proxy will not fix the reason it lags. That is a tuning problem — see Diagnosing Minecraft Server Lag.

Velocity, BungeeCord or Waterfall?

This is where most guides are out of date, because the answer changed.

Use Velocity. PaperMC's own documentation states it plainly: "The Paper team strongly recommends using Velocity over Waterfall and BungeeCord. Waterfall has reached end of life. All future development by PaperMC is done on Velocity."

The short history: Waterfall was a fork of BungeeCord started in 2016 to improve it. It was retired on 26 March 2024 because too much of what needed fixing could not be fixed without breaking the BungeeCord plugins everyone depended on. Velocity was the clean break instead.

Two practical consequences of choosing Velocity:

• BungeeCord plugins do not work on Velocity. Many have Velocity ports or equivalents; check before you commit to a plugin. Plugins that only need to be installed on the backend server and talk over the BungeeCord plugin messaging channel generally do work, because Velocity supports that channel natively.
• Older clients still work. Velocity is compatible with Minecraft 1.7.2 through 26.2. What is not compatible with old clients is the secure forwarding mode — see below.

If you are already running BungeeCord or Waterfall

There is no urgency to rip it out mid-season, but nothing is being fixed on Waterfall and its security model is the weaker one. Plan the move at your next wipe or season boundary, when you can re-do the forwarding configuration cleanly rather than migrating it.

Which Velocity Version

Velocity 4.0.0 was released on 14 July 2026 and requires Java 25. The previous line's last release, 3.5.1 (11 July 2026), is still marked supported by PaperMC and runs on Java 21.

Check your proxy plugins before jumping to 4.0.0. At the time of writing, several widely used proxy plugins on PaperMC's own Hangar repository still list only Velocity 3.x in their supported platforms. If a plugin you depend on has not shipped a 4.0 build, stay on 3.5.1 until it does — the proxy is the one component on your network where a plugin failing to load takes everything offline at once.

Before You Start

A proxy is a separate server, not a setting on an existing one. You need:

• One instance for the proxy. It needs very little RAM — 1 GB is the figure in Velocity's own start scripts — but it needs its own port allocation, and that port is the one players will connect to.
• One instance per backend server. Each is a normal Minecraft server with its own RAM and its own port. This is why a network costs more than one big server: it is genuinely several servers.
• Paper on the backends. The Velocity project recommends Paper for public servers, and Paper supports Velocity's secure forwarding natively. Fabric and Forge servers can join a network too, with an extra mod — covered below. The trade-offs between jar types are in Minecraft Server Software Compared.

If Velocity is not one of the options in your Startup tab, or you need an extra port allocation for it, open a ticket and we will set it up.

Do not chain proxies

Running a proxy behind another proxy — Velocity behind BungeeCord, or Velocity behind Velocity — is explicitly unsupported by the Velocity project. One proxy, then servers.

Step 1: First Boot

Start the proxy once with no configuration. It generates two files in its root directory:

• velocity.toml — the configuration
• forwarding.secret — a randomly generated secret, created automatically on first startup

You will see something like this in the Console:

[05:41:13 INFO]: Booting up Velocity 4.0.0...
[05:41:13 WARN]: Player info forwarding is disabled! All players will appear to be connecting from the proxy and will have offline-mode UUIDs.
[05:41:13 INFO]: Loading plugins...
[05:41:13 INFO]: Loaded 1 plugins
[05:41:13 INFO]: Listening on /[0:0:0:0:0:0:0:0]:25565
[05:41:13 INFO]: Done (0.36s)!

Stop it again before configuring.

Step 2: Register Your Backend Servers

Open velocity.toml in the File Manager. The [servers] section maps a name to an address:

[servers]
lobby = "127.0.0.1:30066"
factions = "127.0.0.1:30067"
minigames = "127.0.0.1:30068"

# In what order we should try servers when a player logs in or is kicked from a server.
try = [
    "lobby"
]

Replace the addresses with the IP and port of each of your backend servers — the same address you would use to join them directly, from the Address at the top left of each server's panel page. The names on the left are yours to choose; they are what players type after /server.

try is the list the proxy works through when a player first connects and when they get kicked from a backend. Put your lobby first. If nothing in try is reachable, players cannot log in at all, so keep it pointing at your most reliable server.

Forced hosts let different hostnames land on different servers:

[forced-hosts]
"creative.example.com" = [
    "creative"
]

One catch, straight from the Velocity FAQ: forced hosts match on the hostname the client sends, which is resolved before the connection. If you use an SRV record to hide a non-standard port, the client sends the SRV target, not the name the player typed — so the forced-host key must be the CNAME the SRV points at, not the address in the player's server list.

Set the proxy's own listen address and MOTD in the root section:

bind = "0.0.0.0:25565"
motd = "<#09add3>A Velocity Server"
online-mode = true

Change bind to the port allocated to your proxy instance. Leave online-mode = true — this is the proxy authenticating players with Mojang, and it is what makes everything below safe.

Step 3: The Dangerous Part

To let the proxy handle authentication, every backend server must stop doing it:

online-mode=false

Read that again, because it is the whole security story of this topic. online-mode=false means the server accepts whatever username a connecting client claims, without checking it against Mojang — the key is documented in full in the server.properties reference. Behind a correctly configured proxy that is fine, because the proxy already verified the player and the backend only ever hears from the proxy.

If someone can reach the backend server directly, it is not fine at all. Velocity's own security documentation puts it as: someone could impersonate any player on your server. They connect straight to the backend port, claim your administrator's username, and the server hands them their inventory and their permissions.

Velocity's setup guide flags the same thing about the bare minimum configuration:

This setup is not only not ergonomic (players will lack skins, proper UUIDs, and all connections will appear to come from the proxy) but also dangerously insecure.

So online-mode=false on the backends is step one of two. Step two is what makes it safe, and it is not optional.

Never publish a backend server's address

Once a backend is in offline mode, its IP and port are a credential. Do not put them in your Discord, your server listing, or a screenshot. Players connect to the proxy address only.

Step 4: Modern Forwarding

Velocity supports three ways of passing player identity to the backends:

You can only pick one; the modes cannot be mixed. Velocity's guidance: "if you are supporting clients using Minecraft 1.13 and newer only, use Velocity modern forwarding, else you must use BungeeCord forwarding."

On the proxy, in velocity.toml:

player-info-forwarding-mode = "modern"
forwarding-secret-file = "forwarding.secret"

Open forwarding.secret and copy its contents. Velocity created it on first startup; you can replace it with a longer random string of your own, and the file must be UTF-8 and not empty.

On every backend running Paper, in config/paper-global.yml:

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

Three rules that cause most of the failures:

1. secret must match forwarding.secret exactly. No quotes issues, no trailing whitespace, no line break in the middle.
2. proxies.velocity.online-mode must match the online-mode value in velocity.toml — both true if the proxy authenticates with Mojang, which it should. This is a different setting from online-mode in server.properties, which stays false.
3. If the server ever ran behind BungeeCord, set settings.bungeecord to false in spigot.yml. Leaving both enabled breaks the login.

Reboot the backend after editing. On Paper 1.18.2 or older the same three options live at settings.velocity-support.enabled, settings.velocity-support.secret and settings.velocity-support.online-mode in paper.yml instead.

Modded backends need a bridge:

• Fabric — install the FabricProxy-Lite mod. Add CrossStitch as well if your mods add custom command argument types.
• Forge — install ProxyCompatibleForge or SpongeForge. Velocity supports Forge servers on 1.20.2 and above from Velocity 3.3.0 onward.
• Vanilla — the Mojang server has no forwarding support at all. The Velocity team's recommendation is to run Fabric with FabricProxy-Lite instead, which does not change the vanilla experience or break vanilla clients.

The secret can also be supplied as the VELOCITY_FORWARDING_SECRET environment variable, which takes precedence over the file. Handy if you would rather it not sit in a file at all.

Step 5: Lock the Backends Down

Modern forwarding means an attacker cannot forge a login through the proxy. It does not mean they cannot reach the backend port. Velocity's security documentation is explicit that modern forwarding is "not a replacement for a firewall". It documents five options, which it notes can be combined; ordered here by strength:

• A firewall on the backend hosts. The strongest option, and the project's primary recommendation. It needs no Minecraft-side configuration and it is effective as long as untrusted machines cannot reach the port. It is also the hardest to arrange on shared hosting.
• Binding backends to localhost. If the proxy and the backend are on the same machine, set server-ip=127.0.0.1 in the backend's server.properties and point velocity.toml at 127.0.0.1:<port>. Simple and effectively foolproof — and it stops working the moment a backend moves to a different machine.
• Modern forwarding itself. Protection plus player-info forwarding in one, requiring Minecraft 1.13+ and Paper 1.13+ or FabricProxy-Lite.
• An encrypted tunnel — WireGuard, OpenVPN, spiped. Very effective, very complex, not usually workable on shared hosting.
• An IP-whitelisting plugin on the backends. A last line of defence, and still vulnerable if an attacker gets a server on the same node.

On managed hosting, where you do not control the host firewall, the realistic combination is: modern forwarding on every backend, backend addresses never published, and a plugin restricting backend connections to the proxy's IP. That is meaningfully safer than the default and weaker than a firewall — worth knowing which one you have.

Moving Players Around

Velocity ships a small set of commands:

/server is granted to everyone by default. /glist is granted to nobody by default, and the rest are permission-gated — velocity.command.send, velocity.command.reload and so on. velocity.toml has no permissions section, so granting those needs a permissions plugin on the proxy.

Two things worth setting up early on any real network:

• Network-wide permissions and chat. LuckPerms runs on Velocity as well as on the backends, and cross-server chat plugins for Velocity such as Carbon publish on Hangar, PaperMC's plugin repository. Plugin installation is in How to install plugins for Minecraft Java Edition, and how plugin permissions relate to the four op tiers is in Minecraft Op Permission Levels.
• Cross-server player data. Velocity does not synchronise inventories, ender chests or advancements — each backend keeps its own copy of every player, which is usually the point of having separate servers. If you want a shared inventory between two backends, that needs a plugin backed by a shared database. You can create one from the panel; see How to create a Database via your panel.

Geyser also runs as a Velocity plugin, so you can offer Bedrock cross-play once at the proxy instead of on every backend — see Setting up CrossPlay for Minecraft.

When a Network Is the Wrong Answer

Networks look impressive and cost more than one server. They are worth it when:

• You need different jar types or versions side by side — a modpack and a plugin survival server cannot be one server
• Your gamemodes are genuinely separate and players expect to move between them
• You want to restart or rebuild one gamemode without disturbing the others
• You have enough concurrent players that splitting them across servers actually reduces the load on each

They are the wrong answer when:

• You are trying to fix lag. Splitting one struggling server into three does not remove the work; it just moves some of it. Profile first
• Your player counts are small. Twelve players spread across four servers is four servers that all feel empty
• You want several worlds, not several servers. A resource world, a creative plot world or a minigame arena on one server is a Multiverse job, not a proxy job, and it is far less work
• You cannot secure the backends. A network you have not locked down is strictly worse than the single server you had before

The honest test: if every backend would still be busy on its own, you want a network. If not, one larger server with several worlds will serve players better and cost less.

Common Issues

• If you wish to use IP forwarding, please enable it in your BungeeCord config as well! — the backend expects BungeeCord-style forwarding but the proxy is not sending it. Velocity wraps the backend's message as Unable to connect to <server>: .... Check player-info-forwarding-mode on the proxy and settings.bungeecord in spigot.yml.
• Your server did not send a forwarding request to the proxy. Make sure the server is configured for Velocity forwarding. — forwarding is configured on one side only. Re-check both files.
• This server requires you to connect with Velocity. — modern forwarding is enabled on the backend but not on the proxy. Set player-info-forwarding-mode = "modern" in velocity.toml.
• Players join with no skin, and every connection appears to come from the proxy IP — forwarding is set to none. This is the default; it must be changed.
• Everyone gets a new, empty inventory after moving to the proxy — the backends were in online mode before and are in offline mode now, which changes player UUIDs unless forwarding is configured. Set up modern forwarding before letting players in, not after.
• Cannot register channel. Too many channels registered! in the backend console when a modded client joins, with that player disconnected — Paper caps a connection at 128 registered plugin messaging channels. Add -Dpaper.disableChannelLimit=true to the backend's startup flags.
• A plugin can no longer cancel or edit chat messages — since Minecraft 1.19.1 chat is signed. The SignedVelocity plugin restores that behaviour.
• Timeouts when switching to a large modpack server — raise read-timeout in velocity.toml and set -Dfml.readTimeout to the matching value in seconds on the Forge backend.
• Forced hosts do nothing — the client is sending the SRV target rather than the typed hostname. Key the forced host on the CNAME the SRV record points at.

What to Read Next

• Minecraft Server Software Compared for choosing what each backend should run
• Getting started with your Minecraft server for setting up each backend server
• How to install plugins for Minecraft Java Edition for proxy and backend plugins, including permissions
• Setting up CrossPlay for Minecraft for running Geyser on the proxy
• Diagnosing Minecraft Server Lag for the performance work a network does not replace
• Minecraft Server Commands for the op and moderation commands that still run per backend
• Minecraft World Management if you want several worlds on one server rather than several servers

Primary sources used for this guide (all checked 18 August 2026): the Velocity documentation on getting started, player information forwarding, securing your servers, configuration, server compatibility, comparisons to other proxies and the Velocity FAQ; PaperMC's global configuration reference; and PaperMC's Waterfall end-of-life announcement.

Made with 💜 by GameServerKings