How to Set Up a Minecraft Velocity Network: Lobby and Multiple Servers

Requirements

• Java: The Java version required by the current releases of Velocity and Paper; both download pages list it.
• RAM: 512 MB–1 GB for Velocity, plus separate memory for each Paper server depending on player count and plugins. For a network with a lobby and two or three game servers, 16–32 GB in total is a good range.
• CPU: The main loop of each Paper server runs on its own core; a multi-core processor with a high clock speed comfortably carries several servers on the same machine.

Step 1: Install Velocity

Connect to your server over SSH, create a separate user and folder, download Velocity's .jar file from the PaperMC download page and run it once:

mkdir -p ~/network/velocity && cd ~/network/velocity
java -Xms1G -Xmx1G -jar velocity.jar

On the first start, the velocity.toml config file and the forwarding.secret file are created. Shut Velocity down with the end command.

Step 2: velocity.toml settings

bind = "0.0.0.0:25565"
motd = "<green>Welcome to our network"
show-max-players = 200
online-mode = true
player-info-forwarding-mode = "modern"
forwarding-secret-file = "forwarding.secret"

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

[forced-hosts]
"survival.yourdomain.com" = ["survival"]

• bind: The address and port Velocity listens on. Players connect to this port.
• online-mode = true: Makes sure players are authenticated with their Mojang account. Don't turn it off.
• player-info-forwarding-mode = "modern": Passes the player's identity and IP address to the backend servers in a signed, secure way. It's the recommended method for Paper 1.13 and later.
• [servers]: The names and addresses of the backend servers.
• try: The order of servers a player is sent to on joining; usually the lobby.
• [forced-hosts]: Sends players who connect with a specific domain name straight to a specific server.

Don't share the secret key in the forwarding.secret file with anyone.

Step 3: Configure the Paper backend servers

Install Paper in a separate folder for each backend server and apply these settings.

server.properties:

server-port=30066
online-mode=false

Give each server a different port (lobby 30066, survival 30067 ...). online-mode=false means the server leaves authentication to Velocity.

config/paper-global.yml:

proxies:
    velocity:
        enabled: true
        online-mode: true
        secret: 'the key from forwarding.secret'

Put the key from Velocity's forwarding.secret file in the secret value. With this setting, the backend server only accepts connections from Velocity that are signed with the correct key.

Forge or Fabric backend servers can work with Velocity too, but modern forwarding needs extra mods. We cover modded servers in our Minecraft modpack server guide.

Step 4: Start the servers

Start each server in its own tmux session; the backend servers first, then Velocity:

tmux new -d -s lobby -c ~/network/lobby 'java -Xms4G -Xmx4G -jar paper.jar --nogui'
tmux new -d -s survival -c ~/network/survival 'java -Xms8G -Xmx8G -jar paper.jar --nogui'
tmux new -d -s velocity -c ~/network/velocity 'java -Xms1G -Xmx1G -jar velocity.jar'

We recommend using Aikar's flags for the Paper servers; the details are in our Minecraft server lag guide. You can also use systemd services to start the servers automatically at boot.

Step 5: The firewall

This is the most critical step of a Velocity network. Because the backend servers run with online-mode=false, if they can be reached directly from the internet, attackers can try to bypass Velocity and join under any player's name. Modern forwarding prevents this, but close the backend ports to the outside anyway:

sudo ufw default deny incoming
sudo ufw allow OpenSSH
sudo ufw allow 25565/tcp

Only Velocity's port (25565) should be open. If the backend servers are on the same machine, they talk over 127.0.0.1 and no extra rule is needed. If they're on different machines, open the backend ports only to the proxy server's IP address, or connect the machines on a private network with WireGuard. We explain port settings in our What is a port? article.

Switching servers and domain names

• By command: Players switch servers with the /server survival command; /glist lists the players across the whole network.
• With a lobby menu: A menu, NPC or sign plugin in the lobby sends players to the other servers with a single click.
• By domain name: With the forced-hosts setting, players who connect to survival.yourdomain.com go straight to the survival server. All you need is an A record for each subdomain pointing to the Velocity server's IP address; the details are in our What is a subdomain? article.

Network-wide plugins

• Permissions: Keep permissions the same across the whole network by connecting the Velocity and Paper versions of LuckPerms to a shared MariaDB database. We cover setting up the database in our MySQL and MariaDB installation guide.
• Bedrock players: The Velocity versions of Geyser and Floodgate let Bedrock players connect to the network too; open UDP port 19132 on the proxy server.
• Proxy plugins: Velocity plugins are used for features such as network-wide chat, announcements and maintenance mode. Velocity plugins go in the plugins folder; Paper plugins don't run on Velocity.

Nodesty for your Velocity network

The 24 GB and 32 GB options of Nodesty Minecraft server hosting plans let you keep a lobby and several game servers on the same machine. The main loop of each Paper server runs on its own core of the Ryzen 9 9950X, which boosts up to 5.7 GHz; NVMe storage, L3–L7 DDoS protection and free daily backups kept for 7 days are included in the price. If you'd rather build your network entirely yourself, including server management, you can also take a look at our AMD Ryzen 9 9950X VPS plans.

Minecraft is a trademark of Mojang AB. Nodesty is not affiliated with or endorsed by Mojang or Microsoft.