BungeeCord and Velocity Setup: Proxy Network Guide

BungeeCord and Velocity setup is what you need when you want to merge several Minecraft servers into one network — lobby, survival, mini-games — under a shared IP, with switches between worlds and no reconnecting. For new projects today, people reach for Velocity instead of BungeeCord: it's faster and more secure. In this guide we'll cover both proxies, their configs, and build a network step by step.

Why you need a proxy at all

One Minecraft server means one world and one type of gameplay. The moment you want a lobby with portals into game modes, a dedicated survival server, and a set of mini-games, the trouble starts: each has its own IP, the player drops out and rejoins on every switch, and inventories and sessions aren't linked.

A proxy solves this. It becomes a single entry point: the player connects to one address while the proxy quietly holds the connection and shuttles them between backend servers with the /server command or through portals. From the player's side it looks like an instant teleport between worlds of one network — no relog, no re-entering the IP.

Lobby — the hub everyone lands in on join.
Survival / anarchy — a separate heavy world with its own economy.
Mini-games — BedWars, SkyWars and the like, often one server per mode.
Single entry — one IP, a shared ban list, and basic protection at the proxy level.

It's important to understand: a proxy does not pool server power and doesn't make "one big server." Each backend is still a separate JVM with its own TPS. The proxy only routes players. So if you just need a big survival server for 40 people, you don't need a network — one server is enough; for picking the right core for it, read our breakdown of Paper vs Purpur vs Vanilla.

BungeeCord (Waterfall) or Velocity

BungeeCord is the historical standard, battle-tested over the years. Waterfall is its PaperMC fork with optimizations, but in 2023 the Paper team put Waterfall into maintenance mode and shifted focus to Velocity. Velocity was written from scratch: it's lighter on resources, holds up better on large networks, and offers a modern mechanism for passing player data.

Criterion	BungeeCord / Waterfall	Velocity
Age / development	Mature, Waterfall in maintenance mode	Actively developed, recommended by PaperMC
Performance	Good	Higher on large networks
Forwarding	Legacy IP forwarding (spoofable if the backend is exposed)	Modern forwarding signed with a secret key
Plugins	Huge library, much of it BungeeCord-only	Growing ecosystem, different API
When to pick	You need an old plugin with no alternative	Any new project

Recommendation

For a new project, go with Velocity. It only makes sense to fall back to BungeeCord if a critical plugin exists exclusively for it and there's no Velocity equivalent.

Installation and the base config

Both proxies are just a regular JAR that runs in its own JVM. Download the latest build (Velocity from the PaperMC site, BungeeCord from SpigotMC), drop it into a separate folder, and run it once — the config will be generated.

velocity.toml

Velocity's main file. The key sections:

bind = "0.0.0.0:25565"
motd = "&3My network"
player-info-forwarding-mode = "modern"
forwarding-secret-file = "forwarding.secret"

[servers]
lobby = "127.0.0.1:30066"
survival = "127.0.0.1:30067"
try = ["lobby"]

[forced-hosts]
"play.example.com" = ["lobby"]

Here bind is the address and port the proxy listens on (and the one you expose to the outside). In [servers] you list the backends by their internal addresses. try is the list of servers to send the player to on join (the first lobby they manage to reach). forced-hosts lets you bind a domain to a specific server.

config.yml (BungeeCord)

BungeeCord follows the same logic but in YAML, with one important difference — ip_forward:

ip_forward: true
listeners:
- host: 0.0.0.0:25565
  priority:
  - lobby
servers:
  lobby:
    address: 127.0.0.1:30066
    restricted: false
  survival:
    address: 127.0.0.1:30067

The ip_forward: true option turns on passing the player's real IP and UUID to the backend — without it everyone shows up with one address and authentication breaks. This is what "forwarding" means in BungeeCord terms.

Linking to the backends — where everyone trips up

The most common beginner mistake. The backend servers (lobby, survival) must not verify the license themselves — the proxy does that. So on every backend, in server.properties, set:

online-mode=false

If you leave online-mode=true, the backend will try to re-authenticate the player with Microsoft and kick them with a Bad login error. But just disabling online-mode isn't enough — you need to "glue" the proxy and backend together with forwarding.

Velocity + Paper (modern forwarding)

This is the correct, secure way. The backend should run a Paper or Purpur core. Open config/paper-global.yml and, in the proxies section:

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: "paste_the_contents_of_forwarding.secret_here"

The value of secret is the contents of the forwarding.secret file Velocity created in its folder. The online-mode setting in paper-global.yml must match the proxy's online-mode (in velocity.toml): if the proxy checks licenses, set true; for cracked/offline mode, set false. It's this secret that prevents login spoofing.

BungeeCord + Paper

BungeeCord's forwarding is simpler and less secure. On the backend, in config/paper-global.yml, enable proxies.bungee-cord.online-mode as you like, and in spigot.yml set:

settings:
  bungeecord: true

There's no secret here — the backend trusts any data that arrives "as if from Bungee." From that follows the single most important security requirement.

Critical: close your backends off from the internet

With online-mode=false, the backend doesn't verify the license. If it's reachable on a public IP, anyone can connect to it directly under the username Notch, admin, or yours — bypassing the proxy and authentication, with operator rights. Backends must listen only on the local/internal network and be closed off by a firewall. Only the proxy port is exposed to the outside. And guard the forwarding secret: with it, all of this protection is bypassed.

Step by step: building a network on Velocity

Let's assemble a minimal "lobby + survival" network. The same steps are mirrored in the FAQ block below.

Create the proxy server. Spin up a separate server for Velocity and download the latest build from PaperMC. Run it once — it generates velocity.toml and forwarding.secret.
Configure velocity.toml. Set bind = "0.0.0.0:25565", player-info-forwarding-mode = "modern", and in [servers] list the backends (lobby, survival) by internal IP and port, plus try = ["lobby"].
Prepare the backends. On each one install Paper or Purpur, and in server.properties set online-mode=false. The server must listen on an internal address, not the public internet.
Wire up the forwarding secret. In each backend's config/paper-global.yml, enable proxies.velocity.enabled: true, paste the contents of forwarding.secret into secret, and set online-mode to match the proxy.
Firewall off the backends. Only the proxy port (25565) is exposed. Close the backend ports so nothing can connect to them directly.
Launch and test. Start the backends first, then the proxy. Connect to the proxy address — you'll land in the lobby. Use /server survival to confirm the switch without a relog.

How this works on a host

On a VPS you set everything up by hand; on Elysium game hosting the scheme is simpler — each element of the network is a separate server in the Pterodactyl panel, installed in one click. You create a server for Velocity, one server per backend, and link them over the internal network within a single location (Moscow, Frankfurt, Amsterdam or Helsinki — by ping). Only the proxy is exposed to the outside; the backends sit isolated and protected.

The key thing for a proxy network is low ping between nodes and a strong single core: Minecraft barely parallelizes, so a backend's TPS comes down to core clock speed. On a Ryzen 9 boosting to 5.0+ GHz with NVMe Gen4 (reads ~7 GB/s), switches and chunk loading won't drag the tick. A network of 2-3 backends usually runs on Nexus (8 GB) or Apex (12 GB) plans — but estimate ahead of time exactly how much RAM to budget per node.

Build your network

Create the proxy and backends on the order page, and compare specs at /price. If you're unsure about the hardware for a multi-server setup, our guide on how to choose Minecraft hosting lays out the criteria clearly.

If you're just getting started and a network is still overkill, launch a single server first using our complete guide to creating a Minecraft server, and add a proxy once your project grows into several modes.

Frequently asked questions

Is Velocity better than BungeeCord?

Velocity is newer, written from scratch, and runs faster on large networks. Its modern forwarding is safer than BungeeCord's forwarding: player data is signed with a secret key, so a login can't be spoofed through the proxy. For a new network, go with Velocity; BungeeCord and its Waterfall fork only make sense if you need an old plugin that has no Velocity equivalent.

Why do backend servers need online-mode=false?

The proxy handles player authentication with Mojang/Microsoft, not the backend. If you leave online-mode=true on your survival or lobby server, it will try to verify the license a second time and kick the player with a 'Bad login' error. That's why every backend uses online-mode=false, while license checks stay on the proxy (online-mode=true in velocity.toml or BungeeCord).

Is setting online-mode=false dangerous?

It's only dangerous if the backend server is reachable directly from the internet. In that case anyone can connect to it by IP and port under any username, bypassing the proxy and authentication. So backends must listen only on the local network (127.0.0.1 or an internal IP) and be closed off by a firewall. Only the proxy port (usually 25565) is exposed to the outside.

What is a forwarding secret and where do I get it?

It's the secret key Velocity uses to sign player data when passing it to a backend. On first launch, Velocity creates a forwarding.secret file in its own folder. You paste the contents of that file into proxies.velocity.secret in each backend's paper-global.yml. Keep the key private: with it, anyone can join a backend under any username.

Can I run a multi-server network on a host?

Yes. On Elysium you create a separate server for the proxy (Velocity) plus one server per backend — lobby, survival, mini-games. They all sit in the same location, linked over the internal network, with only the proxy exposed to the outside. A network of 2-3 backends usually fits comfortably on a Nexus or Apex plan; check exact requirements against your expected load.

Does Velocity support Forge and mods?

Velocity works great with Paper, Purpur, Fabric and supports Forge/NeoForge backends, but modded networks are trickier to set up: mods must match across every server in the network, or the player gets kicked when switching. For vanilla-plus-plugin networks (lobby + mini-games), Velocity is the best choice; for heavy modpacks, first weigh whether you even need a network or whether a single server is enough.

🚀

Launch your server in 2 minutes

Pick a plan, server software and modpack — we'll spin up your server on fast Ryzen nodes with NVMe and DDoS protection. Migration from your old host is free.

Create a server View plans