How to connect several Minecraft servers with a Velocity proxy

A proxy lets players join one address and move between several servers: a survival world, a creative plot world and a minigame lobby, for example, without reconnecting. Velocity is a modern, fast proxy that many networks use. This guide explains how the pieces fit together and the one security setting you must not skip.

How it works

Players connect to the proxy, not to your game servers. The proxy checks their account, then passes them to a backend server. When they run a command like /server survival, the proxy moves them to another backend without them leaving the game.

That means you run several separate Minecraft servers plus the proxy. On a managed host, each is its own server with its own memory allotment, so plan your total resources accordingly. How to choose the right plan can help you size them.

What you need

  • A Velocity download from the official Velocity site.
  • Two or more backend servers, usually Paper, all on the same Minecraft version or on versions your players can reach.
  • A way for the proxy to reach the backends. They can be on the same machine or on different ones, as long as the proxy can connect to each backend's address and port.
  • Only the proxy should be public. The backends should be reachable only by the proxy wherever your setup allows it.

Set up the proxy

  1. Run the Velocity jar once. It creates velocity.toml and a file called forwarding.secret.
  2. Open velocity.toml. The default bind port is 25577, which you can change to the port your host gives you.
  3. Under [servers], list each backend with its name and address, for example survival = "127.0.0.1:25566".
  4. Under the try setting, list the server players should land on first, such as your lobby.
  5. Set player-info-forwarding-mode to "modern". This is the secure mode, and it needs backend servers that support it, which current Paper does.

Set up each backend

Every backend needs to trust the proxy and nobody else:

  1. In server.properties, set online-mode=false. This looks alarming, and it is only safe because the proxy now does the account checking. Never do this on a server that is publicly reachable without a proxy.
  2. In Paper's global config, find the Velocity section, enable it, and paste in the secret from the proxy's forwarding.secret file. Online mode in that section should be true.
  3. Restart the backend. Its console confirms it is expecting proxy forwarding.

If the secret does not match, players are kicked with a message about missing or invalid forwarding data. Copy it again exactly.

The security rule

With online-mode=false on a backend, anybody who can connect to that backend directly can pretend to be any player, including an operator. So make sure the backend ports are not reachable from the internet. If your hosting setup gives every server a public address, the modern forwarding secret protects you, because a direct connection without the right secret is rejected, but you should still keep the backend addresses private where you can, and use a firewall on a VPS. See Set up a firewall on your VPS with UFW for how.

Never share the forwarding secret, and never use the legacy forwarding mode on a public server.

Moving players around

Players can switch with /server name. For a nicer experience, install a plugin on the proxy or backends that adds clickable menus or portals between servers, because making players type commands feels clunky.

You also need to decide what is shared. Permissions, bans and chat are separate per backend unless you use plugins that sync them. A shared database and the same permissions plugin on every server keeps ranks consistent. How to set up LuckPerms ranks and permissions supports a shared setup.

Troubleshooting

  • "Unable to connect to server". The address or port in [servers] is wrong, or the backend is offline. Test it as described in Connection timed out vs connection refused.
  • "Invalid player info forwarding". The secret differs between proxy and backend, or the backend was not configured for Velocity.
  • Players stuck on the proxy. The try list points to a server that is offline.
  • Different versions. The proxy can bridge some version gaps, but plugins and worlds cannot. Keep backends on compatible versions.

Still stuck? Open a ticket on Discord - run /ticket in any channel, pick a department, and include your Server ID or Invoice ID so we can jump straight in.