---
title: "Velocity Proxy Setup: Connect Multiple Minecraft Servers | ZCS"
description: "Set up Velocity to connect multiple Minecraft servers: install, configure backends, forwarding, ports and tests for a safe network."
url: "https://www.zcraftstudios.com/blog/velocity-proxy-network-setup"
updated: "2026-10-20T07:16:50.972429+00:00"
source: "ZCraft Studios"
---

> Site index for AI agents: https://www.zcraftstudios.com/llms.txt (full reference: https://www.zcraftstudios.com/llms-full.txt). Every page is available as Markdown by adding `.md` to its URL or sending `Accept: text/markdown`.

1. [Home](https://www.zcraftstudios.com/)
2. [Blog](https://www.zcraftstudios.com/blog)
3. Velocity Proxy Setup: Connect Multiple Minecraft Servers

[ All posts](https://www.zcraftstudios.com/blog)

# Velocity Proxy Setup: Connect Multiple Minecraft Servers

ZCraft StudiosOct 3, 2026Updated Oct 20, 2026

Set up Velocity to connect multiple Minecraft servers: install, configure backends, forwarding, ports and tests for a safe network.

## In this guide

- [What a proxy does, and when you need one](#what-a-proxy-does-and-when-you-need-one)
- [What you need](#what-you-need)
- [Step 1: install and start Velocity](#step-1-install-and-start-velocity)
- [Step 2: configure velocity.toml](#step-2-configure-velocitytoml)
- [Step 3: configure each backend server](#step-3-configure-each-backend-server)
- [Step 4: lock down the backends (this is not optional)](#step-4-lock-down-the-backends-this-is-not-optional)
- [Moving players between servers](#moving-players-between-servers)
- [Common errors and what they mean](#common-errors-and-what-they-mean)
- [Mistakes to avoid](#mistakes-to-avoid)
- [Frequently asked questions](#frequently-asked-questions)
- [Related guides](#related-guides)
- [Proxy boundary verification](#proxy-boundary-verification)
- [Official documentation and links](#official-documentation-and-links)
- [Troubleshooting the first player connection](#troubleshooting-the-first-player-connection)

## 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](https://www.zcraftstudios.com/blog/velocity-vs-bungeecord-vs-waterfall-comparison) 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](https://www.zcraftstudios.com/blog/minecraft-server-firewall-hardening) 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](https://www.zcraftstudios.com/blog/mysql-cross-server-player-data).

## 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](https://www.zcraftstudios.com/blog/geyser-floodgate-bedrock-crossplay-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

- [Velocity vs BungeeCord vs Waterfall](https://www.zcraftstudios.com/blog/velocity-vs-bungeecord-vs-waterfall-comparison)
- [Building a hub or lobby server](https://www.zcraftstudios.com/blog/building-a-minecraft-hub-lobby-server)
- [Sharing player data across a network with MySQL](https://www.zcraftstudios.com/blog/mysql-cross-server-player-data)

## Proxy boundary verification

Ensure backend servers cannot be accessed directly by untrusted clients when relying on a proxy-based identity setup. Confirm player identity forwarding, chat behavior and reconnection to each backend. Test a full network restart and inspect authentication and proxy logs before public launch.

[![Velocity project artwork](https://repository-images.githubusercontent.com/142085119/ea2c0680-cc17-11eb-894c-501560eca79b)](https://papermc.io/software/velocity)

_Velocity project artwork. [Official source](https://github.com/PaperMC/Velocity). Illustrative publisher image._

## Official documentation and links

- [Official project repository](https://github.com/PaperMC/Velocity)
- [Hardening a Minecraft Server With a Firewall](https://www.zcraftstudios.com/blog/minecraft-server-firewall-hardening)

## Troubleshooting the first player connection

Check failures in order: can the proxy reach the backend address, does the backend accept the expected forwarding mode, and does the shared forwarding secret match? A successful ping to the proxy does not confirm authentication or backend forwarding.

Never expose backend game ports to arbitrary internet clients if they trust the proxy's forwarded identity. Apply network-level access restrictions, then test direct access from outside your network is blocked. Consult the [official Velocity documentation](https://docs.papermc.io/velocity/) for the forwarding setup required by your versions.

### Secure player identity forwarding

- [Velocity Modern Forwarding Setup](https://www.zcraftstudios.com/blog/velocity-modern-forwarding-setup-checklist)

## Continue reading

- [Sharing Player Data Across a Network With MySQL](https://www.zcraftstudios.com/blog/mysql-cross-server-player-data)
- [Setting Up Geyser and Floodgate for Bedrock Cross-Play](https://www.zcraftstudios.com/blog/geyser-floodgate-bedrock-crossplay-setup)
- [Velocity vs. BungeeCord vs. Waterfall: Choosing a Proxy](https://www.zcraftstudios.com/blog/velocity-vs-bungeecord-vs-waterfall-comparison)
- [Velocity Modern Forwarding Setup and Security Checklist](https://www.zcraftstudios.com/blog/velocity-modern-forwarding-setup-checklist)

[ Previous guide EssentialsX Commands Every Admin Should Know](https://www.zcraftstudios.com/blog/essentialsx-commands-cheat-sheet)[ Next guide A Minecraft Server Backup Script You Can Actually Set Up Today](https://www.zcraftstudios.com/blog/minecraft-server-backup-script-guide)