How to run a Velocity proxy in front of several servers

A proxy gives your players one address and moves them between servers with a command: a survival world, a creative world, a minigame, each its own server on your pool. Velocity is the proxy to use on current versions (Waterfall is in the catalog for old BungeeCord setups, but its authors point new networks at Velocity too). Every server here is a slot on the same subscription, so a network of three servers and a proxy is four slots, not four plans.

What you need

• The proxy: a server created with the Velocity software. 1 GB is plenty; it forwards packets, it does not run a world.
• The backends: your existing servers, on Paper, Purpur, Spigot, Fabric or Forge. Each keeps its own RAM and its own address.
• Five minutes with the Files tab, because the proxy and each backend share one secret.

1. Create the proxy

Servers, Create server, pick Minecraft: Java Edition and the Velocity software, give it 1 GB, and start it once so it writes its files. Its address is the one you will give players.

2. Tell the proxy about the backends

Open the proxy’s Files tab and edit velocity.toml. In the [servers] block, list each backend under a name, using the address and port shown on that backend’s page:

[servers]
lobby = "alpha.fadehost.net:26010"
survival = "alpha.fadehost.net:26011"
creative = "alpha.fadehost.net:26012"

try = ["lobby"]

try is where a player lands first. Backends on your private network also resolve by their srv- name from the proxy, but the public address and port always work, so start with those.

Further up in the same file set the forwarding mode:

player-info-forwarding-mode = "modern"

The proxy writes a forwarding.secret file next to velocity.toml on its first start. Open it in the Files tab and copy the string; every backend needs it.

3. Prepare each backend

On a Paper, Purpur or Spigot backend, edit config/paper-global.yml under Files:

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: "the string from forwarding.secret"

Then set the backend’s Online mode off under Settings, Server: the proxy does the Mojang check for the whole network, and a backend behind a proxy has to trust what the proxy forwards. Paper with Velocity forwarding enabled refuses a player who tries to join the backend directly, so switching online mode off here does not open the server to anyone with its address.

On Fabric or Forge backends the same job is done by a mod (FabricProxy-Lite, or Proxy Compatible Forge), with the secret in that mod’s config. Drop it into mods/ and restart.

Restart each backend after the edit; the panel regenerates server.properties on every boot from your settings, so the online mode switch belongs in the panel, not in the file.

4. Move players around

Velocity’s /server survival command switches a player; give your lobby a plugin that runs it from a sign or a compass, or install a hub plugin on the proxy. Proxy plugins go into the proxy’s plugins/ folder like any other; see Install plugins.

What to expect

• Players connect to the proxy’s address only. Point your domain at it with an SRV record, see Custom domains.
• The player list, the whitelist and bans live on the backends; a whitelist on the proxy (velocity.toml, or a plugin) is the simpler way to keep a private network private.
• Backups run per server. Back up the proxy too: its velocity.toml, the secret and its plugins are the whole network layout.
• Sleeping: a backend that hibernates wakes when the proxy connects a player to it, the same way a direct join wakes it. The proxy itself should stay always on, which is what the 1 GB slot is for.

Troubleshooting

• “You must connect through a proxy” or “Unable to verify player details”: the secret differs between the proxy and that backend, or forwarding is not enabled on the backend. Compare the two files character for character.
• Players see their own skin missing or the wrong UUID: forwarding mode is legacy or none on the proxy while the backend expects modern. Use modern on both sides.
• The proxy connects but the backend kicks with “IP forwarding”: the backend still has online mode on in the panel. Switch it off and restart the backend.
• A backend is asleep: the first player through the proxy waits while it wakes; the console on that backend shows the boot.