BungeeCord and Velocity: Build a Minecraft Network

BoxToPlay-helper · July 28, 2026, 4:29pm

This tutorial guides you from creating links in the BoxToPlay panel to performing the first in-game transfers. You will choose the initial server, test commands, decide whether some backends should share player inventories, build a portal in the lobby, and learn when load distribution is useful.

If you have not chosen a proxy yet, read our BungeeCord vs Velocity comparison. You can also consult the official BungeeCord and Velocity documentation.

The shortest setup path is:

Link every Minecraft server to the proxy in the panel.
Restart the affected Minecraft servers first, then restart the proxy.
Connect with the proxy address and port.
Check every destination with /server.
If several backends must share inventories, configure one synchronization solution and back up player data first.
Install Advanced Portals on the lobby if you want an in-game portal.
Add a distribution plugin to the proxy only when several instances provide the same game mode.

Understand what the proxy does

BungeeCord and Velocity sit in front of your Minecraft servers. Players connect to one public address, the proxy address, which then sends them to one of the linked servers.

Player
  ↓
Proxy address
  ↓
BungeeCord or Velocity
  ├── lobby
  ├── survival
  ├── creative
  └── minigames

In this tutorial:

A backend is a Minecraft server placed behind the proxy.
A destination is the name of a link, such as survival.
An instance is one actual server among several servers offering the same game mode, such as survival-1.

Every backend keeps its own worlds, plugins, and data. The proxy lets players move between them, but it does not automatically synchronize inventories, economy, ranks, punishments, or chat.

1. Complete the BoxToPlay linking process

Open your BungeeCord or Velocity server in the BoxToPlay panel:

Click Server Links in the left menu.
Click Link a Minecraft Server.
In Server Name, enter a short identifier without spaces, such as lobby or survival.
Keep BoxToPlay selected if the Minecraft server belongs to the same account, then select it under Server Choice.
With BungeeCord, you can also set the MOTD associated with this entry and enable Restricted to require the bungeecord.server.server-name permission. These two fields are not available in the Velocity form.
Click Validate.

This first view lists the servers that are already linked. The Link a Minecraft Server button opens the window below.

The link name is a technical identifier. If you choose survival, write exactly survival in commands, portals, and plugins. It is not the world name, IP address, or server port.

Minecraft server hosted by BoxToPlay

When the backend belongs to the same BoxToPlay account, the panel registers the destination on the proxy and automatically prepares the compatible Minecraft server files. For a Paper, Purpur, or Spigot backend, this notably includes switching to offline mode and enabling the forwarding method supported by the proxy.

Offline mode is required because the proxy now authenticates the player. However, it makes any direct access to the backend dangerous: someone who bypasses the proxy could try to impersonate a player. Backend ports must therefore be reachable only from the proxy and the required technical services.

BungeeCord uses its legacy forwarding method. Velocity can use BungeeCord-compatible forwarding or Velocity modern forwarding, with a shared secret. Paper supports this modern protocol on the backend. The secret adds protection but does not replace network filtering.

BoxToPlay automates the settings that the backend software supports. A Forge, NeoForge, or Fabric server may require an additional compatibility mod: the panel does not change its server software or install that mod automatically.

Minecraft server hosted elsewhere

For an external server, the panel registers the destination on the proxy, but you must configure the backend manually at the other host. Use the same forwarding mode on both sides, enter the Velocity secret when required, and prevent direct access to the backend port.

Apply the changes

After adding or changing a link:

Restart the affected backends.
Restart BungeeCord or Velocity afterwards.
Confirm that every backend is running before the first test.

Velocity provides /velocity reload to reread velocity.toml, but the BoxToPlay linking process can change several elements. A full restart remains the expected method. With BungeeCord, do not rely on /greload to apply a significant change reliably.

2. Choose the initial server

The initial server is usually a lobby. Players can read network information there, select a game mode, and use a portal, NPC, or menu.

With BungeeCord

In the BoxToPlay proxy configuration, select your default server. It becomes the first BungeeCord priority.

The Force default server setting changes reconnection behavior:

Enabled: the player always returns to the default server.
Disabled: BungeeCord can try to return the player to their last known server when it is available.

Priorities define an ordered list of attempts. If the first server is unavailable, BungeeCord can try the next one. They do not select a destination according to player count or resource usage.

With Velocity

Velocity uses an ordered list called try. The first available server becomes the initial destination. Later entries provide fallback destinations during login. They can also receive a player after an unexpected backend disconnect when failover-on-unexpected-server-disconnect is enabled.

In the BoxToPlay panel, the server selected as the priority is placed first, followed by the other links. Velocity also follows an order. It does not natively select the least loaded server.

3. Test transfers with commands

Commands let you validate the network before adding a portal or menu. Connect in-game with the proxy address and port, then use:

/server

This command reports the current server and offers the available destinations. To join one:

/server lobby
/server survival
/server minigames

To view connected players:

/glist

On Velocity, /glist requires velocity.command.glist, and /glist all shows players by server. On BungeeCord, /glist uses bungeecord.command.list.

An authorized administration team member can move one player or all players:

/send Steve survival
/send all lobby

BungeeCord and Velocity also accept current to move every player on the same backend as the person running the command:

/send current lobby

current must be run by a connected player because the proxy console has no current server. Keep bungeecord.command.send and velocity.command.send restricted to the administration team. The /server command is enough for normal player navigation.

4. Synchronize inventories across servers

BungeeCord and Velocity do not carry a player’s inventory between backends. A synchronization solution must be installed on every server that shares the same progression.

Every BoxToPlay Minecraft server plan already includes a MySQL database at no additional cost. Activate it from the MySQL Database page in the panel by choosing an administrator password, then use its credentials in the configuration below. You do not need to add an external database.

Paper, Spigot, Purpur, and Folia

MC-Data-Bridge supports Minecraft 1.21.x, 26.1.x, and 26.2 networks. Install the same JAR in the plugins folder of every relevant backend and on the BungeeCord or Velocity proxy. Configure the same MySQL or MariaDB database everywhere, then assign a unique server-id to each server.

MC-Data-Bridge versions 2.1.3 through 2.1.8 require Java 25, including with Minecraft 1.21.x. Versions 2.1.2 and earlier run on Java 21, but they do not include the latest transfer and item duplication protection fixes. Prefer the latest compatible stable version.

If your network must stay on Java 21, MySql Player Bridge is another option. Install NBT-API first, then place MySql Player Bridge in plugins on every backend that must synchronize. Configure the same MySQL or MariaDB database in plugins/MySqlPlayerBridge/mysql.yml, then enable only the required data in plugins/MySqlPlayerBridge/config.yml. No additional plugin is required on the proxy.

Forge and NeoForge

For Forge or NeoForge, PlayerSync provides builds for several Minecraft and loader combinations. Always select the file that exactly matches your Minecraft version and either Forge or NeoForge. Place it in mods on every backend, configure the same MySQL or MariaDB database in config/playersync.toml, then assign a different Server_id to each server.

Use the same modpack and mod versions throughout a synchronized group. Test items supplied by mods before opening the network.

Should the lobby be synchronized?

To keep the same inventory on the lobby and PvP server, both backends must use the same solution and storage. On most networks, keeping the lobby separate is preferable: its compass, menus, and cosmetic items should not replace the PvP or Survival inventory.

For example, keep lobby independent, synchronize pvp-1 and pvp-2 together, and place survival in a separate group.

Before enabling synchronization, back up player data and test several server changes with a secondary account. Keep the same Minecraft version within each group and do not combine multiple synchronization solutions in one group. Ranks, punishments, economy, and chat are shared separately with plugins designed for a network.

5. Create an in-game portal with Advanced Portals

The link in the panel tells the proxy that a destination exists. The /server survival command then asks the proxy to transfer a player to it. A plugin installed on the lobby can trigger the same transfer when a player enters an area.

Creating the link does not create a physical portal. A standard Nether portal changes dimension on the same backend: it does not send the player to another server.

We use Advanced Portals, a Bukkit plugin compatible with platforms including Paper, Spigot, Purpur, and Folia.

The method below uses the bungee: tag. For this use case, install the plugin on the backend used as the lobby, where the portal will be built. Do not install it on the destination server, and players do not need to add anything to their computers. Advanced Portals also offers a proxy component for its proxy: tag and advanced features, but it is not required for the simple portal in this tutorial.

If the lobby only runs Vanilla, Forge, NeoForge, or Fabric, this Bukkit plugin cannot be installed there directly. The modded server section explains which options to check.

Install Advanced Portals on the lobby

In the BoxToPlay panel:

Open the Minecraft server used as the lobby.
Open Plugins & Mods, then Plugin installation.
Select the Modrinth tab.
Search for Advanced Portals.
Install a version compatible with your Minecraft version.
Fully restart the lobby.

Prepare Velocity

If you use Velocity with the bungee: tag, check before creating the portal that bungee-plugin-message-channel is enabled in velocity.toml. This option allows backend plugins to use the BungeeCord-compatible messaging channel. It is independent from the player information forwarding mode.

It does not allow Velocity to load a BungeeCord plugin directly on the proxy.

Build the portal to `survival`

Connect through the proxy and first confirm that /server survival works. Then, from the lobby with an administrator account:

Build the frame and leave the inside empty.
Type /portal wand to receive the selection tool.
Left-click one inner corner, then right-click the opposite corner.
Create the portal:

/portal create name:survival_portal bungee:survival triggerblock:NETHER_PORTAL

Type /portal portalblock, then place the provided blocks inside the selected area.
Walk through the portal and confirm that you reach the correct destination.

In this command:

name:survival_portal is the unique portal name.
bungee:survival asks the proxy to join the survival destination.
survival must exactly match the name under Server Links.
triggerblock:NETHER_PORTAL triggers the transfer inside the purple portal blocks.

The historical bungee: name works with BungeeCord and Velocity when the compatibility channel is enabled. Use /portal show to display portal areas and /portal remove survival_portal to remove this example.

The following screenshot, taken from the official Advanced Portals command documentation, shows the result of /portal show. The green particles outline nearby portals and the currently selected area. They make it easier to spot a selection that is too large, too small, or misplaced.

Advanced Portals can also create local destinations with the /desti commands. The /desti show command represents them with a particle arrow, as shown in the official screenshot below.

This second command is not required for the portal in this tutorial: bungee:survival directly asks the proxy to transfer the player to the survival server. The /desti commands are only used for portals that teleport to a local position.

You can replace NETHER_PORTAL with WATER. For an NPC or menu, install a suitable plugin and configure it with the same destination identifier.

This portal points to one fixed destination. It does not automatically choose between survival-1 and survival-2.

6. Set up load distribution

Linking lobby, survival, and minigames distributes players by activity. It is not load distribution because every destination serves a different purpose.

The need appears when several instances provide the same Survival game mode:

survival-1: 78 players
survival-2: 24 players
survival-3: maintenance

Here, survival-1 is a destination identifier, while Survival is the game mode being offered.

A distribution plugin installed on the proxy can select an instance according to the features it provides. Before choosing one, check that it can handle:

The actual availability of instances.
Player count and maximum capacity.
Instances placed in maintenance.
Expected behavior when an instance fails.
The destination to use after a reconnection.

General setup principle

Link every instance with a distinct name, such as survival-1, survival-2, and survival-3.
Test every name with /server.
Install a plugin compatible with your proxy and version.
Follow its documentation to declare the instances and expose its distribution command or destination.
Configure the portal, NPC, or menu to call that feature.
Test an available instance, a full instance, and a stopped instance.

Distribution plugins do not all use the same group, alias, or health-check model. Do not copy configuration written for another plugin.

Advanced Portals does not measure load. The bungee:survival-1 tag always sends the player to that exact destination. Likewise, BungeeCord priorities and Velocity try define an initial or fallback order: they do not automatically alternate players or select the least loaded instance.

Finally, several instances do not become interchangeable by simply copying a server. Inventories, permissions, currencies, punishments, and plugin data must be designed to work across a network, often with suitable plugins and a shared database.

7. Subdomains do not replace portals

An advanced configuration can associate addresses such as survival.example.com or minigames.example.com with different initial destinations. BungeeCord calls this mechanism forced_hosts, while Velocity provides an equivalent forced-hosts section.

This routing happens when a player joins the network. It does not move an already connected player and does not automatically choose the least loaded instance. Subdomains are an additional entry point, not a replacement for commands, portals, or menus.

With BungeeCord, Force default server must remain disabled for forced hosts to select the initial destination correctly.

8. Secure backend servers

Players must enter through the proxy. Backend ports must not provide a second public entry point.

Velocity modern forwarding verifies a shared secret, but it does not replace a firewall. With legacy BungeeCord-compatible forwarding, network restrictions, IP allowlisting, or BungeeGuard are especially important. In every case, only the proxy and required technical services should be able to reach the backends.

Only share the proxy address with players.

9. Special cases: Forge, NeoForge, and Fabric

The simplest path is to use a Paper or Purpur lobby with Advanced Portals, even when the destinations run Forge or NeoForge. Players must still have the version and modpack required by the destination.

With Velocity 3.3.0 or later:

Native Forge protocol support applies to versions strictly newer than 1.20.2.
For Forge 1.13 through 1.20.1, install Ambassador on the Velocity proxy.
Do not assume Forge 1.20.2 is covered by either range: check the documentation and the exact version of your server.

For Velocity modern forwarding to a Forge or NeoForge backend, install a compatible version of Proxy Compatible Forge on that backend and use the same secret as the proxy. For Fabric, the Velocity documentation recommends FabricProxy-Lite.

Ambassador handles Forge protocol compatibility with Velocity. Proxy Compatible Forge and FabricProxy-Lite handle player information forwarding. None of these components creates a portal.

If the lobby itself runs Forge or NeoForge, look for a maintained mod that explicitly provides two features for your exact version: detecting an in-game area and sending the player to a BungeeCord or Velocity server name. At the time of writing, we do not recommend one universal ready-to-use solution for this case. The forge-plugin-message project advertises several versions on its page, but it currently provides no public downloadable file on Modrinth. It therefore cannot serve as a general recommendation in this tutorial.

Validation checklist

Before opening the network:

Connecting to the proxy address reaches the expected lobby.
Every name under Server Links works with /server name.
Compatible BoxToPlay servers were prepared automatically, and external backends were configured manually.
Backends were restarted before the proxy.
If inventories are synchronized, each group uses one solution, the same storage, and distinct server identifiers, after backing up player data and testing with a secondary account.
The portal uses exactly the same destination identifier as the panel.
On Velocity, bungee-plugin-message-channel is enabled before using the bungee: tag.
A fallback destination works when a backend is stopped.
Direct connection to a backend address and port is refused.
/send, reload, and administration permissions remain restricted to the administration team.

Which method should you choose?

To check a link: use /server.
To share inventories across several backends: use a solution compatible with their server software, shared storage, and distinct server identifiers.
To guide players from a lobby: use a portal, NPC, or menu.
To choose a destination on connection: configure the initial server or advanced subdomains.
To distribute equivalent instances: add a compatible distribution plugin to the proxy.

Once these checks are complete, the proxy becomes the single entry point to the network. You can then improve the lobby, synchronize only the data that must be shared, and add load distribution when several instances genuinely serve the same role.

Useful resources

BungeeCord

Velocity

Plugins and mods

Ready to create the entry point for your network? Explore BoxToPlay BungeeCord and Velocity servers, link your Minecraft servers from the panel, and then validate every transfer with this tutorial.