Run a Minecraft network — lobby, survival, minigames — behind one address. This guide installs the Velocity proxy, links your Paper servers with modern forwarding and a shared secret, and locks the backends down so nobody can bypass the proxy.
A proxy sits between players and your servers. Players connect to Velocity on one public address; Velocity authenticates them with Mojang and moves them between your backend Paper servers — with /server, portals or menus — without disconnecting. It's how networks run a hub plus several game modes.
Velocity is PaperMC's proxy, built for performance and security. Its modern forwarding passes each player's real UUID, IP and skin to the backends and protects that data with a shared secret — something classic BungeeCord forwarding doesn't do. It does not run BungeeCord plugins, so look for Velocity versions of your proxy plugins (Hangar is the main source).
One rule matters above all: backends run in offline mode, so they must be reachable only through the proxy. Each server can be self-hosted or run on our Minecraft server hosting — Frankfurt, NVMe, always-on Anti-DDoS, and a panel with file manager and console for the configs below. Want Bedrock players too? Add Geyser and Floodgate on the proxy.
What you'll need
- A machine for the proxy and one or more Paper backends (they can share a machine on different ports).
- Java 25 or newer for current Velocity releases; each backend needs the Java version its Minecraft version requires.
- Paper on Minecraft 1.13 or newer for modern forwarding.
- One public TCP port for the proxy (25565 by default) and a private port per backend.
- Firewall access — or a localhost-only setup — so backends accept only the proxy.
Set up a Velocity network, step by step
Step 1: Plan your ports
Only the proxy is public. Velocity binds to port 25565 by default — the address players type. Every backend gets its own port that only the proxy uses; servers sharing one machine can't all sit on 25565. Java Minecraft runs over TCP, so these are all TCP ports.
proxy 0.0.0.0:25565 public - players connect here lobby 127.0.0.1:30066 private - proxy only survival 127.0.0.1:30067 private - proxy onlyStep 2: Download and start Velocity
Velocity is a separate Java program, not a plugin. Download the latest stable build from the official PaperMC downloads page into its own folder — current releases need Java 25 or newer. Start it once: it creates
velocity.tomland aforwarding.secretfile with a random secret. Typeendin the console to stop it.java -Xms1G -Xmx1G -XX:+UseG1GC -XX:G1HeapRegionSize=4M -XX:+UnlockExperimentalVMOptions -XX:+ParallelRefProcEnabled -XX:+AlwaysPreTouch -XX:MaxInlineLevel=15 -jar velocity.jar # first start creates velocity.toml and forwarding.secret # type end to stop the proxyStep 3: Configure velocity.toml
Set
bindto the address and port players use, keeponline-mode = true(the proxy authenticates players), and setplayer-info-forwarding-modetomodern. Under[servers], list each backend asname = "ip:port";tryis the order Velocity sends players to on login or after a kick. Delete the sample servers you don't use — and remove them fromtryand[forced-hosts]too, or the proxy refuses to start.bind = "0.0.0.0:25565" online-mode = true player-info-forwarding-mode = "modern" forwarding-secret-file = "forwarding.secret" [servers] lobby = "127.0.0.1:30066" survival = "127.0.0.1:30067" try = [ "lobby" ]Step 4: Set backends to offline mode
On every Paper backend, open
server.properties, setonline-mode=falseand give it the port you listed in[servers]. The proxy now does the authentication. This step alone is insecure — finish the next two steps before you open the network.online-mode=false server-port=30066Step 5: Enable Velocity forwarding in Paper
Open
config/paper-global.ymland, underproxies.velocity, setenabled: true,online-mode: true(to matchvelocity.toml) andsecretto the exact contents of the proxy'sforwarding.secret. Make suresettings.bungeecordisfalseinspigot.yml, then restart the backend. Older Paper versions (1.18.2 and below) keep these options inpaper.ymlundersettings.velocity-support.proxies: velocity: enabled: true online-mode: true secret: "paste-the-contents-of-forwarding.secret"Step 6: Firewall the backends — don't skip this
An offline-mode server that anyone can reach lets people join under any name, including yours. Modern forwarding adds a second check, but the Velocity docs are clear that it is not a replacement for a firewall. If a backend is on the same machine as the proxy, bind it to localhost with
server-ip=127.0.0.1. If it is on another machine, allow its port only from the proxy's IP.# backend on the same machine as the proxy (server.properties) server-ip=127.0.0.1 # backend on another machine: only the proxy may connect sudo ufw allow from 203.0.113.10 to any port 30066 proto tcp sudo ufw deny 30066/tcpStep 7: Start and test the network
Start the backends, then the proxy, and join the proxy address.
/serverlists servers and switches between them (all players can use it by default)./glist allshows players per server and/velocity reloadre-readsvelocity.toml— both need permissions, so run them from the proxy console. Finally, try to join a backend port directly from outside: it must fail./server survival # switch server /glist all # players per server /velocity reload # re-read velocity.toml
Run a secure, stable network
Firewall first, forwarding second
Modern forwarding rejects logins without the right secret, but a firewall (or localhost binding) stops strangers reaching offline-mode backends at all. Use both.
Keep the secret secret
forwarding.secret proves data came from your proxy. Never post it in screenshots or support chats; if it leaks, put a new random value in the file and in every backend's paper-global.yml.
Velocity plugins only
Velocity doesn't load BungeeCord plugins. Server-side plugins that only use the BungeeCord messaging channel usually keep working, because Velocity supports that channel natively.
One public door
With a proxy, only one address faces the internet. Put DDoS protection in front of the proxy and keep backend ports closed — attacks can't target servers they can't reach.
Common problems & fixes
"If you wish to use IP forwarding, please enable it in your BungeeCord config as well!"
The backend isn't receiving Velocity forwarding. Set proxies.velocity.enabled: true and the matching secret in config/paper-global.yml, keep bungeecord false in spigot.yml, and restart the backend.
"This server requires you to connect with Velocity."
The backend has modern forwarding on but the proxy doesn't — set player-info-forwarding-mode = "modern" in velocity.toml. You also see this when joining a backend port directly, which is expected.
Velocity refuses to start after editing velocity.toml
Check the log: every server named in try and [forced-hosts] must exist in [servers], every address must be valid, and modern forwarding needs a non-empty forwarding.secret.
"Can't connect to server" / connection refused from the proxy
The IP or port in [servers] is wrong, the backend is bound to 127.0.0.1 on a different machine, or a firewall blocks the proxy's IP. See fixing connection refused.
Players lose inventories or get the wrong skin between servers
UUIDs differ because forwarding is off or proxies.velocity.online-mode doesn't match the proxy's online-mode. Fix the forwarding setup on every backend so all servers see the same UUIDs.
Minecraft is a trademark of Mojang Studios and Microsoft. Velocity and Paper are open-source projects of PaperMC; BungeeCord, Snap and the other tools mentioned are projects of their respective authors. ESAGAMES is an independent hosting provider, not affiliated with or endorsed by Mojang, Microsoft or PaperMC.