ZCraft StudiosZCraft Studios

Velocity Proxy Setup: Connect Multiple Minecraft Servers

ZCraft Studios

A complete Velocity setup: install the proxy, link a lobby and survival server, enable modern forwarding with the secret, lock down the backends, and fix the errors you will hit.

Velocity Proxy Setup: Connect Multiple Minecraft Servers

Short answer: Velocity is a proxy that sits in front of your Minecraft servers. Players connect to Velocity on one address, and it sends them to a lobby, survival, or any other backend server. Setting it up takes four steps: run Velocity, add your servers to velocity.toml, enable modern forwarding with a shared secret, and make sure players can only reach the proxy and not the backends directly.

This guide uses Paper for the backend servers. If you are still choosing a proxy, read Velocity vs BungeeCord vs Waterfall first.

What a proxy does, and when you need one

A proxy lets you run several servers that feel like one network. Typical reasons:

  • A lobby that sends players to different game modes.
  • Separate servers for survival, creative, and minigames, so a crash in one does not take down the others.
  • Spreading load, because each backend is its own process (and can run on its own machine).

If you only run one server, you do not need a proxy. It adds a moving part, so only add it when you have a reason.

What you need

  • Two or more Paper servers (a lobby and one other is enough to test).
  • Java 17 or newer for Velocity. Use the Java version your Paper servers need; for Minecraft 1.20.5 and later that is Java 21.
  • A place to run the proxy. It uses little CPU and memory, so a small amount of RAM is fine.

Step 1: install and start Velocity

Download the latest Velocity jar from the PaperMC downloads page. Put it in its own empty folder and start it:

java -Xms512M -Xmx512M -XX:+UseG1GC -jar velocity.jar

On the first run Velocity creates velocity.toml and a file named forwarding.secret, then keeps running. Stop it with end in the console so you can edit the config.

Step 2: configure velocity.toml

Open velocity.toml. The settings you will touch:

bind = "0.0.0.0:25565"
online-mode = true
player-info-forwarding-mode = "modern"

[servers]
lobby = "127.0.0.1:25566"
survival = "127.0.0.1:25567"
try = ["lobby"]

[forced-hosts]
"survival.example.com" = ["survival"]

What each part means:

  • bind is the address players connect to. Velocity's default port is 25577; change it to 25565 if you want players to use the standard Minecraft port.
  • online-mode = true means Velocity checks accounts with Mojang. This is the correct setting for a normal server. The backends will run in offline mode, which is safe only because of the forwarding and firewall steps below.
  • player-info-forwarding-mode = "modern" passes the player's real UUID and IP to the backends using the secret. Always use modern forwarding with Paper.
  • [servers] lists your backend servers by name and address. The try list is where new players land, in order.
  • [forced-hosts] lets players join a specific server by using a different hostname. It is optional.

Step 3: configure each backend server

On every Paper backend, you change two places.

In server.properties:

online-mode=false
server-port=25566

Backends run in offline mode because Velocity handles authentication. Give each backend its own port.

In config/paper-global.yml, enable Velocity support and paste the secret from forwarding.secret:

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: "paste-the-contents-of-forwarding.secret-here"

online-mode: true here tells Paper that the proxy is verifying players, so it should trust the forwarded data. The secret must match exactly, with no extra spaces or line breaks.

Restart the backends, then start Velocity. Connect with a Minecraft client to the proxy address and you should land on the lobby.

Step 4: lock down the backends (this is not optional)

Because the backends run with online-mode=false, anyone who can reach a backend directly could try to join as any username, including an admin. Modern forwarding adds a signature that backends check, which helps, but you should never leave the backends open to the internet anyway.

  • If the proxy and backends are on the same machine, bind the backends to 127.0.0.1 in server.properties (server-ip=127.0.0.1).
  • If they are on different machines, use a firewall that allows backend ports only from the proxy's IP address.

Our firewall hardening guide walks through this.

Moving players between servers

Players can use /server survival if they have permission. Most networks add a compass menu, NPCs, or a command like /survival in the lobby. Velocity itself offers /server, /glist (players across the network), and /velocity reload (reload the config).

Plugins that need to work across servers (chat, bans, ranks) must be installed on the right layer. Permissions and punishments are usually stored in a shared database such as MySQL so every server sees the same data. See sharing player data across a network with MySQL.

Common errors and what they mean

"If you wish to use IP forwarding, please enable it in your BungeeCord config as well!" The backend has Bungee-style forwarding enabled but Velocity is set to modern, or the reverse. Make both sides use Velocity modern forwarding.

"Unable to verify player details" or the player is kicked on join. The secret in paper-global.yml does not match forwarding.secret. Copy it again, with no trailing whitespace.

"Could not connect to a default or fallback server." None of the servers in try are reachable. Check that the lobby is running, the port matches, and nothing blocks it.

Players join but have the wrong skin or UUID. Forwarding is not enabled correctly on that backend.

Mistakes to avoid

  • Leaving backend ports open to the internet.
  • Using player-info-forwarding-mode = "legacy" because an old guide said to.
  • Running the proxy and a backend on the same port.
  • Not copying the secret to all the backends.

Frequently asked questions

Do I need a proxy to run a lobby?

No. You can build a lobby on a single server. A proxy is useful when you want several separate servers that act like one network.

Is Velocity better than BungeeCord?

For new networks, yes. It is actively developed, faster, and has modern forwarding. Some older plugins are written only for BungeeCord, which is the main reason people stay on it.

Can Bedrock players join through Velocity?

Yes, with Geyser installed on the proxy or a backend. See Geyser and Floodgate setup.

Does Velocity need a lot of RAM?

No. Most small and medium networks run it comfortably on a few hundred MB to 1 GB.

Related guides

Share: