BungeeCordVelocityProxyNetworkPerformanceMinecraft Server

Minecraft Server Proxy Setup: How to Configure BungeeCord and Velocity for a Multi-Server Network

Published on August 14, 2026

# Minecraft Server Proxy Setup: How to Configure BungeeCord and Velocity for a Multi-Server Network

Running a single Minecraft server is straightforward — but if you want to host multiple game modes, route hundreds of players, or keep your backend servers protected, you need a proxy layer. BungeeCord and Velocity are the two dominant solutions, and choosing the right one (then configuring it correctly) makes a massive difference in stability, security, and performance.

This guide walks you through everything: installation, essential config settings, security hardening, and performance tuning for both proxies.

---

BungeeCord vs. Velocity: Which Should You Choose?

Before diving into config files, you need to pick your proxy.

BungeeCord (and its fork Waterfall) has been the industry standard for years. It has the largest plugin ecosystem and is widely documented. However, it carries legacy code, and its threading model can become a bottleneck on large networks.

Velocity (by PaperMC) is the modern alternative. It was built from scratch with performance and security in mind:

Faster player forwarding with a custom, cryptographically signed protocol (modern forwarding)
Better threading — connection handling is significantly more efficient
Actively maintained by the Paper team
Growing plugin ecosystem via the Velocity API

Recommendation: Use Velocity for any new network. Only choose BungeeCord/Waterfall if you depend on legacy plugins that haven't been ported.

---

Setting Up Velocity

1. Download and First Launch

Download the latest Velocity JAR from [papermc.io/downloads/velocity](https://papermc.io/downloads/velocity) and place it in its own directory.

mkdir velocity-proxy && cd velocity-proxy

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

Velocity generates a velocity.toml config file on first launch.

2. Configure `velocity.toml`

Here are the critical settings to adjust:

# The IP and port players connect to
bind = "0.0.0.0:25565"

# Your server's MOTD and max players
motd = "&3My Velocity Network"
show-max-players = 100

# IMPORTANT: Use 'modern' forwarding with Paper backends
player-info-forwarding-mode = "modern"

[servers]
  lobby = "127.0.0.1:25566"
  survival = "127.0.0.1:25567"
  minigames = "127.0.0.1:25568"

[forced-hosts]
  "lobby.yourserver.com" = ["lobby"]

try = ["lobby"]

The try list defines which server players connect to by default. List your lobby first.

3. Enable Modern Forwarding on Paper Backends

For each Paper backend server, open config/paper-global.yml and set:

proxies: velocity: enabled: true online-mode: true

secret: "your-forwarding-secret-here"

The secret must match the content of forwarding.secret in your Velocity directory. Treat this like a password — never share it publicly.

Also set online-mode=false in each backend's server.properties. Authentication is handled by the proxy.

---

Setting Up BungeeCord / Waterfall

If you're sticking with BungeeCord, use Waterfall (the Paper fork) for better performance. Download it from [papermc.io/downloads/waterfall](https://papermc.io/downloads/waterfall).

Key `config.yml` Settings

listeners: host: 0.0.0.0:25565 max_players: 500 motd: '&aMy BungeeCord Network' forced_hosts: lobby.yourserver.com: lobby default_server: lobby fallback_server: lobby servers: lobby: motd: '&bLobby' address: localhost:25566 restricted: false survival: address: localhost:25567 restricted: false ip_forward: true

online_mode: true

Enable ip_forward: true and set bungeecord: true in each backend's spigot.yml:

# spigot.yml on each backend settings:

bungeecord: true

---

Security: The Most Critical Step

A misconfigured proxy is a serious security hole. Follow these steps without exception:

1. Firewall Your Backend Servers

Your backend servers must only accept connections from the proxy, never from the public internet. Use iptables or your hosting panel's firewall:

# Allow only the proxy IP to connect on backend ports iptables -A INPUT -p tcp --dport 25566 -s YOUR_PROXY_IP -j ACCEPT

iptables -A INPUT -p tcp --dport 25566 -j DROP

If a player can connect directly to a backend server (bypassing the proxy), they can spoof any username — including admins.

2. Install a Security Plugin on BungeeCord

For BungeeCord networks, install BungeeGuard on both the proxy and all backends. It adds a token-based authentication layer so backends reject connections that didn't come through your proxy.

Velocity's modern forwarding already handles this cryptographically — no extra plugin needed.

3. Disable `online-mode` Safely

Backend servers run with online-mode=false — but this means they'd normally accept cracked clients. The proxy handles authentication, so as long as your firewall is correct, this is safe.

---

Performance Tuning

Velocity JVM Flags

Velocity is lightweight, but proper JVM flags still matter:

java -Xms512M -Xmx512M \ -XX:+UseG1GC \ -XX:G1HeapRegionSize=4M \ -XX:+UnlockExperimentalVMOptions \ -XX:+ParallelRefProcEnabled \

-jar velocity.jar

Keep Velocity's heap small (512MB–1GB is usually plenty). The proxy doesn't simulate worlds — it just routes packets.

Compression Settings

In velocity.toml:

# Compress packets larger than this (bytes). -1 disables compression.
compression-threshold = 256
compression-level = 6

If your proxy and backends are on the same machine, set compression-threshold = -1 to disable compression between proxy and backends. Compressing on localhost wastes CPU with no bandwidth benefit.

For BungeeCord, configure the same in config.yml:

network_compression_threshold: -1

Connection Throttling

In velocity.toml, configure login throttling to prevent bot floods:

[advanced]
  login-ratelimit = 2000  # ms between logins from same IP
  connection-timeout = 5000
  read-timeout = 30000

---

Common Mistakes to Avoid

Not firewalling backends — the single biggest security mistake on Minecraft networks
Using legacy forwarding when all backends support modern — legacy sends IPs as plaintext
Allocating too much RAM to the proxy — Velocity doesn't need more than 1GB for most networks
Running the proxy on the same port as a backend — always separate ports clearly
Forgetting to sync server.properties online-mode — backends must have online-mode=false

---

Monitoring Your Proxy Network

Once your network is running, you need visibility into what's happening across all servers. Which backend is lagging? Is a sudden player spike causing connection errors? Tools like [PulseNode](https://pulsenode.tech) give you real-time performance monitoring across your entire server network, making it easy to spot the bottleneck before your players notice.

---

Final Checklist

Before going live, verify:

[ ] Backends are firewalled — only proxy IP can connect
[ ] player-info-forwarding-mode = "modern" set in Velocity (or BungeeGuard installed for BungeeCord)
[ ] forwarding.secret matches on proxy and all backends
[ ] online-mode=false on all backends
[ ] Default/fallback server set to your lobby
[ ] Compression disabled if proxy and backends share a machine
[ ] Login rate limiting configured

A correctly configured Velocity or Waterfall proxy is the backbone of any serious Minecraft network. Get the security right first — performance tuning comes second.