How to Set Up a Velocity Proxy Network Safely

A proxy lets players join one address and move between servers, such as a lobby, a survival world and minigames, without reconnecting. The setup is short. The part that matters is the security, and it is the part most guides skip.

What you are building

Players connect to the proxy on the public address. The proxy checks their account with Mojang, then connects them to a backend server. Because the proxy has already authenticated the player, the backend runs with online mode off and trusts the information the proxy sends: the player's name and identity. If anyone can connect to a backend directly, they can send that information themselves and join as anyone, including an operator.

Step 1: install Velocity

Velocity needs a recent Java; its documentation says at least Java 25. Download the proxy, put it in its own folder and create a start script, start.sh on Linux and macOS or start.bat on Windows, containing a Java command that runs the jar. On Linux, make the script executable with chmod u+x start.sh and run it. By default the proxy listens on port 25565.

Step 2: register your servers

Open velocity.toml and find the servers section. Add one line per backend in the form name = "address:port". The try list names the servers new players are sent to first, usually the lobby.

Give the backends different ports if they run on the same machine, and keep 25565 for the proxy so players need no port in the address.

Step 3: turn on modern forwarding

Velocity offers several ways to pass player information to backends. Its documentation describes them:

• Modern forwarding, set with player-info-forwarding-mode = modern, uses a message authentication code and a secret, which makes it much harder to trick the backend. It requires Minecraft 1.13 or later.
• Legacy BungeeCord forwarding is described as fundamentally insecure.
• BungeeGuard improves on legacy forwarding but is less ideal than modern forwarding.

Use modern forwarding unless a very old backend forces another choice. Velocity writes a secret to a file called forwarding.secret. Keep it private.

Step 4: configure each Paper backend

On every backend, set online-mode to false in server.properties, because the proxy now authenticates players. Then, in Paper's global configuration under proxies and velocity, set enabled to true, set secret to the value in forwarding.secret and make sure online-mode matches the proxy's setting. Restart the backend.

If you have used the older BungeeCord setting in spigot.yml, set it to false when you use modern forwarding.

Step 5: lock the backends down

Modern forwarding is not enough on its own. The Velocity documentation says plainly that it is not a replacement for a firewall, and recommends layers:

• A firewall on the operating system that only lets the proxy reach the backend ports. This is the most effective step.
• On a single machine, set server-ip to 127.0.0.1 in server.properties so the backend listens only for local connections, and point velocity.toml at 127.0.0.1 and the backend's port.
• Between machines, an encrypted tunnel such as a VPN.

Test it. From a machine that is not the proxy, try to connect to a backend's port. It should fail. If it succeeds, fix that before you open the network.

Step 6: add compatibility and display

Players on other versions can be let in with the ViaVersion plugins, installed on the proxy so every backend benefits. A tab list plugin that supports proxies can show one list across the whole network, and a permissions plugin installed on the proxy and the backends with shared storage keeps ranks consistent.

Step 7: keep the secret secret

Treat forwarding.secret like a password. Do not post it in support requests or commit it to a repository, and change it if it leaks. After changing it, update every backend.

A checklist before launch

• Backends are unreachable except from the proxy.
• Modern forwarding is on and every backend has the same secret.
• Backends run with online mode off only because the proxy authenticates for them.
• You have tested joining, switching servers and rejoining after a restart.