Setting Up a Velocity or BungeeCord Proxy Network

Once a Minecraft community grows beyond one world — a lobby, survival, creative, minigames — you’ll want players to move between servers without disconnecting. That’s what a proxy does. This guide explains how proxies work, why Velocity is the recommended choice today, and how to set one up securely.

How a proxy network works

Players connect to one address: the proxy. The proxy handles login and forwards the connection to a backend server — say, the lobby. When a player runs /server survival or uses a portal, the proxy switches them to another backend without dropping the connection.

                 ┌──► lobby     (Paper)
Players ──► Proxy ├──► survival  (Paper)
                 └──► creative  (Paper)

Benefits:

• One address for the whole network.
• Spread load across several servers instead of one huge one.
• Isolation — a crash or restart on one backend doesn’t kick everyone off the network.
• Different setups per server — plugins, versions and configs tuned for each game mode.

Velocity, BungeeCord or Waterfall?

• Velocity — a modern proxy maintained by the PaperMC team, designed for performance and security, with a secure “modern forwarding” system. It’s the recommended choice for new networks.
• BungeeCord — the original proxy from the Spigot team. Mature and widely supported by older plugins.
• Waterfall — a BungeeCord fork formerly maintained by PaperMC, now end-of-life. Don’t start new networks on it.

Unless you depend on a plugin that only exists for BungeeCord, choose Velocity.

Setting up Velocity

1. Install and start the proxy

Download Velocity from PaperMC and run it (Velocity needs Java 17 or newer):

java -Xms512M -Xmx512M -jar velocity.jar

On first run it creates velocity.toml and a forwarding.secret file. A proxy is lightweight — 512 MB to 1 GB is plenty for most networks.

2. Configure velocity.toml

bind = "0.0.0.0:25565"
motd = "<green>Welcome to our network"
show-max-players = 200
online-mode = true
player-info-forwarding-mode = "modern"
forwarding-secret-file = "forwarding.secret"

[servers]
lobby = "127.0.0.1:30001"
survival = "127.0.0.1:30002"
creative = "127.0.0.1:30003"
try = ["lobby"]

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

• online-mode = true — the proxy verifies players with Mojang. This is where authentication happens.
• player-info-forwarding-mode = "modern" — Velocity’s secure forwarding, which signs player information with a shared secret.
• [servers] — each backend’s name and address. try lists where players land on join.
• [forced-hosts] — optionally route players to a server based on the hostname they connect with.

3. Configure each Paper backend

Each backend must trust the proxy and not authenticate players itself.

In server.properties:

online-mode=false
server-port=30001

In config/paper-global.yml:

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

With modern forwarding, the backend accepts only connections carrying valid player information signed with the secret. Restart each backend after changing these files.

4. Lock down the backends

This step is essential. A backend with online-mode=false will accept anyone who connects to it directly — including someone claiming to be your admin. Modern forwarding with a secret stops forged logins, but you should also make backends unreachable from the internet:

• Bind backends to 127.0.0.1 (via server-ip in server.properties) when they’re on the same machine as the proxy.
• Otherwise, use a firewall to allow the backend ports only from the proxy’s IP.

Treat forwarding.secret like a password: anyone with it can forge player identities to your backends.

Setting up BungeeCord (if you must)

BungeeCord uses config.yml with a servers: section and ip_forward: true. On each Spigot/Paper backend, set bungeecord: true in spigot.yml and online-mode=false in server.properties. BungeeCord’s legacy forwarding has no secret, so firewalling the backends is the only thing preventing forged logins — another reason Velocity is preferred. (Paper supports BungeeGuard-style tokens through plugins if you need extra protection.)

Plugins on a network

Some plugins run on the proxy, others on backends:

• Proxy plugins handle network-wide features: server selector commands, network chat, maintenance mode, anti-bot filtering. They must be Velocity (or BungeeCord) plugins.
• Backend plugins handle gameplay on each server.
• Shared data — permissions, economy, bans — usually goes in a MySQL database that every server connects to. LuckPerms, for example, can share one database across the whole network so a player’s rank follows them everywhere. See connecting Minecraft plugins to MySQL.

Resources for a network

• Proxy: 512 MB–1 GB RAM, light CPU.
• Lobby: small — 1–2 GB, low view distance, no world generation.
• Game servers: sized per mode; survival with exploration needs the most. See how much RAM a Minecraft server needs.

Running every backend on one machine is fine for small networks, as long as the machine has strong per-core CPU performance — each backend’s main tick uses a core. Larger networks spread backends across machines.

Common mistakes

• Backends reachable directly with online-mode=false, allowing forged logins.
• Mismatched forwarding modes — the proxy uses modern forwarding but a backend is configured for BungeeCord, or the secret doesn’t match. Players see “unable to verify” or “invalid forwarding” errors.
• Running proxy plugins on backends, or the reverse.
• Forgetting that the proxy is the entry point for DDoS. Protect the proxy’s address — see protecting your Minecraft server from DDoS and bot attacks.

Hosting a network

Kerit Cloud’s Minecraft hosting supports Velocity and BungeeCord alongside Paper, Purpur, Fabric and Forge. Because servers are custom-quoted, you can describe your whole network — proxy, lobby and game servers — and get resources sized for each part, with DDoS protection in front of the proxy, daily backups and a free database for shared data.

Summary

A proxy gives your network one address and moves players between backend servers without disconnecting them. Use Velocity with modern forwarding: online-mode=true on the proxy, online-mode=false plus the forwarding secret on each Paper backend, and backends unreachable except through the proxy. Put network-wide plugins on the proxy, gameplay plugins on backends, shared data in MySQL, and protect the proxy as your network’s front door.