NEW 📢 Black Friday: our launch offer ends 30 Nov. Up to 70% off your first month on every game!See plans
Black FridayUp to 70% off your first month, ends 30 NovEnds in 9d 01h 29mBlack FridayUp to 70% off your first month, ends 30 NovEnds in 9d 01h 29mBlack FridayUp to 70% off your first month, ends 30 NovEnds in 9d 01h 29m

How to build a Minecraft network with Velocity or BungeeCord

MinecraftUpdated Oct 28, 20268 min read

A proxy lets players join one address and move between several Minecraft servers, such as a lobby, a survival world and a minigame server. Set up one server as Velocity, copy its forwarding secret to each Paper server behind it, turn Online mode off on those servers, and list them in the proxy's settings. Players then join with the proxy's address only.

The proxy has no world of its own. The servers behind it are called backend servers. On PlayNHost the proxy and each backend are separate servers, each with its own plan and address. Instances cannot take their place, because only one instance of a server runs at a time.

Which proxy to choose

  • Velocity: the modern proxy from PaperMC. The panel describes it as what most networks run instead of BungeeCord. Choose it for any new network.
  • BungeeCord: the original proxy, for older networks.
  • Waterfall: a BungeeCord fork that is No longer developed upstream; new networks should prefer Velocity.

All three are server types you can choose. A proxy takes no Minecraft version: it works with the versions of the servers behind it. See How to change your Minecraft version or server type.

This guide uses Velocity with Paper backends. BungeeCord is at the end.

Before you start

  • Have the proxy server and your backend servers. Put them in the same region so players do not wait on long hops between them. See Where your server runs and how location works.
  • Run Paper or Purpur on the backends. Velocity's modern forwarding is built into Paper; PaperMC's documentation lists Paper 1.14 and newer (and late 1.13 builds).
  • Players only ever get the proxy's address. Keep backend addresses to yourself.

Step 1: start the proxy and copy its secret

  1. Set the proxy server's type to Velocity. Start it once, then stop it. It writes its settings, velocity.toml, and a secret file, forwarding.secret.
  2. In Files on the proxy, open forwarding.secret and copy the text. It is a password for your network: the panel describes it as a secret that, if anyone has it, lets them join as any player. Never share it or post it in a ticket.

Step 2: set up each backend server

On every Paper server behind the proxy:

  1. Start it once so its settings files exist, then stop it.
  2. Open Settings, then Paper's Global Settings. Search for velocity and set, under proxies.velocity:

    • enabled: on.
    • online-mode: the same as online-mode in the proxy's velocity.toml (on, unless you changed it).
    • secret: paste the text from forwarding.secret.

    Click Save only.

  3. Open Settings, then Server Properties (Java), and switch Online mode off. The window Turn off online mode? opens. Because of step 2 it says This server is set up to accept players from a Velocity proxy. Click Turn off online mode, then Save only. The proxy checks accounts instead, which is the one case where the panel says turning it off is right.
  4. Start the server.

Paper's Global Settings is listed when the server has the file config/paper-global.yml. Older Paper versions keep these settings in another file: update the server, or open a ticket.

With Online mode off, a backend lets anyone join under any name unless the proxy's secret protects it. Keep the secret private. See Online mode and offline mode on a Minecraft server.

Step 3: tell the proxy about the backends

  1. On the proxy, open Settings, then Velocity Settings. Set player-info-forwarding-mode to MODERN and click Save only.
  2. In the servers section, each backend has a name and an address as host:port. The panel describes it as its internal address - not the one players connect to, because Velocity connects to it directly. If you do not know a backend's internal address, open a ticket from the proxy server and name the backends: see How to open a support ticket.
  3. try lists the servers players land on first, in order: Velocity tries the next one if the first is down, so put your lobby first.
  4. Start the proxy.

The settings page edits the entries already in the file. To add a backend, stop the proxy, open velocity.toml in Files, add a line under [servers], save and start the proxy. If the proxy cannot reach a backend (players are sent back or kicked, and the proxy's Console shows a connection error), open a ticket from the proxy server, name the backend, and ask which address the proxy should use.

Join and test

  1. Start every backend and wait until each is online.
  2. Start the proxy.
  3. Join with the proxy's address. You arrive on the first server in try.
  4. Type /server and a backend's name to move. Velocity's documentation says every player may use /server, and /server alone lists the servers.
  5. If a player shows up with the wrong name, another UUID or no skin, forwarding is not working: check that the same secret is on the proxy and every backend, and that player-info-forwarding-mode is MODERN.

Things that catch people out

  • Backends have their own address. PaperMC's security guide recommends a firewall and says modern forwarding is not a replacement for a firewall. PaperMC says modern forwarding makes it much harder to trick a backend into accepting a player who did not come through your proxy, as long as the secret stays secret. Keep the secret and the backend addresses private.
  • Wrong secret: a backend with a different secret refuses the player, who is sent back or kicked. Copy the secret again.
  • Player limits: each backend still has the player slots of its own plan. See How to change the player limit on your Minecraft server.
  • Whitelist, operators and bans are per backend. Set them on each, or use a permissions plugin that spans the network, such as LuckPerms: see How to set up ranks and permissions with LuckPerms on your Minecraft server.
  • Modded backends need extra steps that depend on the loader. Open a ticket if you want to try one.

Plugins on the proxy

A proxy has only a Plugins tab on Modding, and it shows proxy plugins: A proxy sits in front of your servers and has no world of its own, so it takes proxy plugins and nothing else. Install them as on any server, then restart the proxy. See How to install plugins on Paper, Spigot and Purpur.

Bedrock players on a network

Turn on Bedrock crossplay on the proxy. Bedrock players get a port of their own there, because the proxy keeps its main port for Java players. Geyser's setup guide says every server on the network must accept the Java version Geyser speaks, for example with ViaVersion on a backend that runs another version. See How to let Bedrock players join your Java server with Geyser.

BungeeCord and Waterfall

The outline is the same, with other settings:

  1. Start the proxy once. Its settings are in Settings, Proxy Settings (config.yml).
  2. List each backend under servers with its address as host:port, and name the first one in priorities under listeners. Turn on ip_forward so players keep their identity.
  3. On each backend, first turn on bungeecord under settings in Settings, Spigot Settings, then switch Online mode off in Server Properties (Java). The window Turn off online mode? then says This server is set up to accept players from a BungeeCord proxy. Click Turn off online mode, then Save only.

BungeeCord's forwarding has no secret, so a backend that players reach directly accepts anyone under any name. That is a strong reason to pick Velocity for a new network.

Already hosting it somewhere else? Move your server to us

OUR LATEST BLOGS