BungeeCord and Velocity are both proxy software used to easily create a network of servers. Velocity is the more modern alternative, generally offering better performance and security, while BungeeCord remains widely used and has broader plugin compatibility. You can learn more about BungeeCord here and Velocity here.
To set up a proxy network, you must have a minimum of three servers with us at WitherHosting: one server for the proxy (BungeeCord or Velocity), your second server as your "hub" server, and your last server as your "smp" server. You can configure the proxy server to allow players to switch easily between the hub and smp servers.
In this article, we'll refer to the proxy server (BungeeCord or Velocity) as a proxy server, and the hub and smp servers as backend servers. Theoretically, you can set up a proxy with only two servers, one being the proxy and the other being the hub. However, the purpose of using a proxy, which is switching between servers in a network, becomes pointless in such a setup. Prerequisites for setting up the proxy server include knowing your non-proxy server IPs and ports.
A proxy server (BungeeCord or Velocity) requires very little RAM compared to other servers. It is not accessible in-game because it redirects users to the secondary and tertiary servers you have.
Note that it may require more RAM if you're supporting GeyserMC players. In such cases, 64MB of RAM per Bedrock player has been recommended.
First, navigate to your config.yml file in the root folder of your proxy server. We'll explain each line to help you understand its function. We'll skip discussing a few values in the config.yml as they are unnecessary for setup.
forge_support - Set to true if you want to allow players with Forge clients to join.
player_limit - Global player limit for your BungeeCord instance. If set to 0 or below, this allows an unlimited number of users to join.
online_mode - Set to true to disallow cracked players from joining, set to false to allow cracked players to join.
For Velocity, the equivalent file is velocity.toml in the root folder of your proxy server. Key options include:
online-mode - Set to true to disallow cracked players from joining, set to false to allow cracked players to join.
player-info-forwarding-mode - Determines how player information (UUID, properties) is forwarded to backend servers. Common options are legacy, bungeeguard, and modern (recommended for Paper/Velocity-native setups).
motd - Sets the message of the day for the proxy server.
show-max-players - Sets the max player limit displayed in the Minecraft client's multiplayer menu.
This is the most important section. Here, you'll list all your backend servers that the proxy server should listen to.
lobby:
motd: '&1Just another BungeeCord - Forced Host'
address: localhost:25565
restricted: falselobby is the name of your server.
motd is the message of the day for the specified backend server.
address is your backend server's IP address, along with the port.
restricted prevents players from joining the server unless they have the bungeecord.server.[servername] permission.
You can add as many servers as you like. In our case, we'll add the hub and smp servers:
hub:
motd: 'My hub server!'
address: localhost:20001
restricted: false
smp:
motd: 'My SMP server!'
address: localhost:20002
restricted: falseIn velocity.toml, servers are listed under the [servers] section:
[servers]
lobby = "localhost:25565"
hub = "localhost:20001"
smp = "localhost:20002"
try = [
"hub",
"smp"
]
Each entry maps a server name to its address and port.
The try list defines the order in which Velocity attempts to connect players on join (fallback order).
Now, let's cover the other components of your BungeeCord's config.yml file:
motd - Sets the message of the day for the proxy server, visible to players in their server list.
priorities - Specifies the order in which BungeeCord forwards connections to servers. Useful for supporting multiple client versions.
host - Enter your server IP followed by your port.
max_players - Sets the max player limit displayed in the Minecraft client's multiplayer menu.
ip_forward - Determines whether to allow IP or UUID forwarding. Recommended to set to true for online mode servers.
Additional options in velocity.toml:
bind - The IP and port the proxy listens on.
motd - Same as above, but supports MiniMessage formatting for richer text.
player-info-forwarding-mode - As mentioned above, this is Velocity's equivalent to BungeeCord's ip_forward, and must be matched on the backend (modern forwarding requires a shared forwarding secret, configured via forwarding.secret).
These are the settings you can tweak for your proxy server. Once you've adjusted the values according to your preference, save the file and restart the server. Now, let's set up the backend servers.
Setting up backend servers is relatively simpler compared to the proxy setup. The required values differ slightly depending on whether you're using BungeeCord or Velocity.
online-mode must be set to false in the server.properties file.
connection-throttle must be set to -1 in the bukkit.yml file.
bungeecord must be set to true in the spigot.yml file.
online-mode must be set to false in the server.properties file.
connection-throttle must be set to -1 in the bukkit.yml file.
In config/paper-global.yml (or spigot.yml for non-Paper servers), the proxy protocol setting must match your chosen player-info-forwarding-mode:
For legacy forwarding, set bungeecord: true in spigot.yml (same as BungeeCord).
For modern forwarding, enable velocity-support (with the matching secret) in config/paper-global.yml.
Once these configurations are done, restart your servers, and everything should be set up! In-game, switching between servers is as simple as using the command /server followed by the server name you want to go to.
Ensure you're a server operator while performing this command!
To prevent malicious users from bypassing your proxy connection and accessing your backend server unauthenticated:
BungeeCord: Set up a plugin like BungeeGuard. This is highly recommended.
Velocity: Using the built-in modern forwarding mode with a forwarding secret is generally sufficient, as it provides authenticated forwarding without needing an extra plugin. If using legacy or bungeeguard forwarding modes with Velocity, BungeeGuard is still recommended.
If you encounter issues with the proxy, consider these common troubleshooting points:
If you get an IP forwarding error while connecting, set ip_forward to true in the config.yml of your BungeeCord proxy server, or verify your player-info-forwarding-mode and matching backend settings for Velocity.
If you've connected but cannot switch to other servers with the error "Could not connect to a default or fallback server," ensure that your backend server is turned on and running.
If you can't ping your proxy server in the server list, check that the host/bind address in config.yml (BungeeCord) or bind in velocity.toml (Velocity) is configured correctly, and adjust your connection throttles and timeout time accordingly!
Updated on: 06/15/2026