Velocity

Last reviewed Sep 13, 2026 · 851 words

The mistake that gets Velocity setups hacked is not in Velocity. It is that the backend Paper servers behind a proxy must run with online-mode=false, because the proxy does the Mojang authentication, and if those backend ports are reachable from the internet anyone can connect as anyone. Every other part of a Velocity install is a config file and a restart; that one part is a firewall rule, and people skip it. With it in place, Velocity is the proxy that PaperMC built to replace BungeeCord, and for a home network with more than one Minecraft server it is the correct choice.

Why a proxy at all

One Minecraft server is one world and one port. The moment you want a creative build server and a survival server, or a lobby that fans out to minigames, players need to hop between processes without disconnecting. A proxy sits on port 25565, holds the player's connection, and hands their session to whichever backend they choose with /server survival or a portal plugin. Velocity does this in Java on a modern networking stack, with a plugin API that was designed rather than accreted, and it handles the version-translation plugins (ViaVersion, and Geyser for Bedrock clients) at the proxy layer so backends stay simple. If you run exactly one server, you do not need it; the games category has plenty of single-server panels.

Modern forwarding: the config on both sides

Velocity has to pass the real player identity to each backend, and the "modern" forwarding mode does so with a shared secret. On the proxy, velocity.toml:

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

[servers]
lobby = "10.0.0.11:25566"
survival = "10.0.0.12:25567"
try = ["lobby"]

The try list is where new players land. On each Paper backend, two edits: server.properties gets online-mode=false, and config/paper-global.yml gets proxies.velocity.enabled: true, proxies.velocity.online-mode: true, and the same secret string that Velocity generated in forwarding.secret. Restart both. If a backend rejects players with a forwarding error, the secret does not match, and that is the whole diagnosis 9 times out of 10. Legacy BungeeCord forwarding exists for plugins that predate Velocity, but it is less secure and I would not start there.

Lock the backends down, or the proxy is pointless

Back to the opening point. Ports 25566 and 25567 above must accept connections only from the proxy host. On a single Docker host, put the backends on an internal network and publish only Velocity's 25565. On separate machines, an iptables or ufw rule allowing the proxy's IP and dropping everything else is the minimum; a Velocity-aware plugin on the backend that refuses unforwarded connections is a second layer, not a substitute. This is also why I prefer running the whole thing under a panel: Pterodactyl and Crafty Controller both isolate each server and make the port exposure explicit, which keeps the mistake from creeping back in during a 2 a.m. tweak.

Plugins and RAM

The catalogue floor of 512 MB is real and generous. Velocity itself is light; what grows is the plugin set. LuckPerms for network-wide permissions, ViaVersion so older clients can join, Geyser and Floodgate for Bedrock, a tab-list or MOTD plugin, and you are at maybe 1 GB with headroom. The backends are where the memory goes, and each Paper instance wants 2 GB or more on its own. The plugin API is Velocity-native and not compatible with BungeeCord plugins, so check the Hangar listing for each one you rely on before migrating. Java 17 or newer is required; the Docker route is the itzg/mc-proxy image with TYPE=VELOCITY, which pulls the current build and mounts velocity.toml for you.

Velocity versus BungeeCord and Waterfall

BungeeCord is older, still maintained by SpigotMC, and has the larger legacy plugin catalogue. It also uses a forwarding scheme that is easier to spoof and a codebase that shows its age under load. Waterfall, PaperMC's improved fork of BungeeCord, was retired by the Paper team in favour of Velocity, which tells you where their effort goes. At 2,250 stars and GPL-3.0, Velocity is the actively developed option, and for a network built today there is no reason to pick the alternative unless a specific plugin holds you back; the BungeeCord alternatives page walks through the switch.

What I'd do

Velocity on its own small container or VM, modern forwarding, one lobby backend in try, backends on an internal network with only 25565 published. LuckPerms and ViaVersion from day one, Geyser only if someone actually owns a console or phone edition. Run the backends under Pterodactyl so each one's port exposure is visible in a UI rather than buried in a compose file. Test the lockdown by trying to connect directly to a backend port from outside; if that succeeds, nothing else you configured matters.