How to Set Up a Velocity Proxy for Multiple Minecraft Servers
A proxy lets players connect to one address and move between several backend servers, such as a lobby and a survival world. Velocity is a modern, popular proxy. BungeeCord and Waterfall are older alternatives with different config files.
Plan the layout
Your players connect to the proxy, which listens on its own port. The backend servers should only accept connections from the proxy, so do not give them public access. Ask us on Discord about network setups for your plan.
Set up Velocity
- Create a server for Velocity and upload the Velocity jar.
- Start it once so velocity.toml and a forwarding.secret file are created.
- Stop it, and open velocity.toml.
- Under the servers section, list each backend with its address and port, for example lobby = "address:port".
- In the try list, name the server players join first.
- Check bind, which defaults to port 25577. Set it to the port assigned to your proxy.
- Set player-info-forwarding-mode to modern.
Configure each backend
For each Paper server:
- Set online-mode=false in server.properties, since the proxy handles authentication.
- In the Paper global config file, in the proxies section, set velocity enabled to true, online-mode to true, and set secret to the exact contents of forwarding.secret.
- Restart the backend.
Paths and key names can vary by Paper version, so check the Velocity documentation for your release.
Security warning
A backend with online-mode=false that is open to the internet lets people join with any name. Use modern forwarding with a secret and restrict access to the proxy.
Troubleshooting
- Unable to verify player details or similar errors: the secret does not match, or forwarding mode is mismatched.
- Cannot connect to a server: check the address and port in velocity.toml.
- Players see the wrong skins or UUIDs: forwarding is not enabled on the backend.
- Plugins that must be on both sides, like permission plugins, need configuring accordingly.
Ask on Discord for help.