EN

Game servers

How to Connect Multiple Minecraft Servers with Velocity

Connect several Paper servers behind the Velocity proxy on a Linux VPS or dedicated server: secure player forwarding, closed internal ports and rollback.

10 min read, updated on 18 November 2026

On this page

Your values

Enter them once and the commands in this guide update.

Velocity is a Minecraft proxy: players connect to a single address, then move from one server to another without disconnecting. This guide places your existing server behind Velocity and adds a lobby server, on the same machine.

It follows on from the Create a Minecraft Server and Install and Update Plugins on Paper guides. It reuses the minecraft user, the /opt/minecraft/server folder, the minecraft.service service and the mc-console command.

By the end of this guide, you will have:

  • Velocity listening on public port 25565, so your players keep the same address
  • two Paper servers reachable only from the machine itself
  • secure forwarding of player identities, with their UUIDs and inventories preserved

Prerequisites

  • A Paper server, set up with the two guides mentioned above, with Java 25, curl and jq
  • SSH access with a user that has sudo privileges
  • About 2 GB of free memory on top of your current server: 1 GB for Velocity and up to 1 GB for the lobby
  • Enough disk space for a full copy of the server folder

Velocity, BungeeCord or Waterfall?

Velocity BungeeCord Waterfall
Project PaperMC, active development SpigotMC, the original proxy PaperMC, end of life
Secure identity forwarding Yes, signed with a secret No No
Plugins Velocity API BungeeCord API BungeeCord API

PaperMC recommends Velocity over BungeeCord and Waterfall, and no longer maintains Waterfall.

BungeeCord remains a defensible choice in only one case: an essential proxy plugin that does not exist for Velocity, since Velocity does not load BungeeCord plugins. Because its identity forwarding is not signed, closing the internal ports as described below matters even more.

Understand the Target Setup

Service Name in Velocity Folder Listen address Reachable from
velocity.service /opt/minecraft/velocity 0.0.0.0:25565 Internet
minecraft.service survie /opt/minecraft/server 127.0.0.1:25566 This machine only
minecraft-lobby.service lobby /opt/minecraft/lobby 127.0.0.1:25567 This machine only

Back Up the Server

Stop the server, then create a full archive. It stays stopped until the configuration is complete, because Velocity will take over port 25565:

Terminal
sudo systemctl stop minecraft.service
sudo mkdir -p /opt/minecraft/backups
sudo tar -czf /opt/minecraft/backups/avant-velocity-$(date +%F-%H%M).tar.gz -C /opt/minecraft server
sudo ls -lh /opt/minecraft/backups

Install Velocity

Create a script that downloads the latest stable build and verifies its checksum. You will reuse it for updates:

Terminal
sudo nano /opt/minecraft/velocity-update.sh
Terminal
#!/bin/bash
# Downloads the latest stable Velocity build and replaces velocity.jar
set -euo pipefail

VERSION="${1:?Specify the Velocity version, for example 4.3.1}"
UA="mon-serveur-minecraft/1.0 (https://your-domain.com)"
API="https://fill.papermc.io/v3/projects/velocity/versions/$VERSION/builds"

mkdir -p /opt/minecraft/velocity
cd /opt/minecraft/velocity

BUILD=$(curl -fsSL -H "User-Agent: $UA" "$API" | jq -c 'map(select(.channel == "STABLE")) | .[0]')
if [ "$BUILD" = "null" ]; then
    echo "No stable build found for Velocity $VERSION." >&2
    exit 1
fi

URL=$(echo "$BUILD" | jq -r '.downloads."server:default".url')
SHA256=$(echo "$BUILD" | jq -r '.downloads."server:default".checksums.sha256')

curl -fL -H "User-Agent: $UA" -o velocity.jar.new "$URL"
echo "$SHA256  velocity.jar.new" | sha256sum -c -

if [ -f velocity.jar ]; then
    mv velocity.jar velocity.jar.old
fi
mv velocity.jar.new velocity.jar
echo "Velocity $VERSION, build $(echo "$BUILD" | jq -r '.id'), is in place."

On the UA line, replace your-domain.com with your website address or a way to contact you. Then run the script:

Terminal
sudo chmod 755 /opt/minecraft/velocity-update.sh
sudo -u minecraft /opt/minecraft/velocity-update.sh 4.3.1

The line velocity.jar.new: OK confirms that the file is intact.

Create the service:

Terminal
sudo nano /etc/systemd/system/velocity.service
Configuration
[Unit]
Description=Velocity Minecraft Proxy
After=network.target

[Service]
User=minecraft
WorkingDirectory=/opt/minecraft/velocity
ExecStart=/usr/bin/java -Xms1G -Xmx1G -XX:+UseG1GC -XX:G1HeapRegionSize=4M -XX:+UnlockExperimentalVMOptions -XX:+ParallelRefProcEnabled -XX:+AlwaysPreTouch -XX:MaxInlineLevel=15 -jar /opt/minecraft/velocity/velocity.jar
SuccessExitStatus=130 143
Restart=on-failure
RestartSec=20
StandardInput=null

[Install]
WantedBy=multi-user.target

These Java options are the ones recommended by the Velocity documentation. Start the proxy once to generate its configuration:

Terminal
sudo systemctl daemon-reload
sudo systemctl start velocity.service
sudo journalctl -u velocity.service -n 30 --no-pager

Wait for the Done line. The Player info forwarding is disabled! warning is normal at this stage. Then stop the proxy and protect its folder, which contains the secret:

Terminal
sudo systemctl stop velocity.service
sudo chmod 700 /opt/minecraft/velocity
sudo ls -l /opt/minecraft/velocity

You should see velocity.toml and forwarding.secret.

Configure Velocity

Terminal
sudo -u minecraft nano /opt/minecraft/velocity/velocity.toml

Check or change these lines, at the top of the file:

toml
bind = "0.0.0.0:25565"
online-mode = true
player-info-forwarding-mode = "modern"
forwarding-secret-file = "forwarding.secret"

Then replace the entire contents of the [servers] and [forced-hosts] sections:

toml
[servers]
lobby = "127.0.0.1:25567"
survie = "127.0.0.1:25566"

try = [
    "lobby",
    "survie"
]

[forced-hosts]

try sets the order in which servers are tried at login, or when a player is kicked from a server. The [forced-hosts] section stays empty: the bundled examples point to factions and minigames servers that do not exist on your setup, and Velocity would refuse to start.

Connect the Existing Server

Make the server listen on the loopback interface, on its new port, and hand authentication over to the proxy:

Terminal
sudo -u minecraft sed -i \
    -e 's/^server-ip=.*/server-ip=127.0.0.1/' \
    -e 's/^server-port=.*/server-port=25566/' \
    -e 's/^online-mode=.*/online-mode=false/' \
    /opt/minecraft/server/server.properties
sudo grep -E '^(server-ip|server-port|online-mode)=' /opt/minecraft/server/server.properties

Next, enable modern forwarding in the Paper configuration, with the secret generated by Velocity:

Terminal
SECRET=$(sudo cat /opt/minecraft/velocity/forwarding.secret)
sudo -u minecraft sed -i "/^  velocity:/,/^ \{0,2\}[a-z]/{s/^    enabled: .*/    enabled: true/;s/^    online-mode: .*/    online-mode: true/;s/^    secret: .*/    secret: '$SECRET'/;}" /opt/minecraft/server/config/paper-global.yml
unset SECRET
sudo chmod 700 /opt/minecraft/server/config

Check the result without displaying the secret:

Terminal
sudo grep -A3 '^  velocity:' /opt/minecraft/server/config/paper-global.yml | sed 's/secret: .*/secret: (hidden)/'
sudo grep -qF "$(sudo cat /opt/minecraft/velocity/forwarding.secret)" /opt/minecraft/server/config/paper-global.yml && echo "Secret matches" || echo "Secret differs"
sudo grep 'bungeecord:' /opt/minecraft/server/spigot.yml

You should get enabled: true, online-mode: true, Secret matches and bungeecord: false. This last setting must stay at false with modern forwarding.

Create the Lobby Server

The lobby reuses the same server.jar and the same global Paper configuration:

Terminal
sudo -u minecraft mkdir -p /opt/minecraft/lobby/config
sudo chmod 700 /opt/minecraft/lobby/config
sudo -u minecraft cp /opt/minecraft/server/server.jar /opt/minecraft/lobby/
sudo -u minecraft cp /opt/minecraft/server/config/paper-global.yml /opt/minecraft/lobby/config/
echo "eula=true" | sudo -u minecraft tee /opt/minecraft/lobby/eula.txt

Create its settings, with a flat world and no monsters:

Terminal
sudo -u minecraft tee /opt/minecraft/lobby/server.properties > /dev/null <<'EOF'
server-ip=127.0.0.1
server-port=25567
online-mode=false
motd=Lobby
max-players=50
level-type=minecraft\:flat
generate-structures=false
gamemode=adventure
force-gamemode=true
difficulty=peaceful
allow-nether=false
view-distance=6
simulation-distance=4
EOF

Create its service:

Terminal
sudo nano /etc/systemd/system/minecraft-lobby.service
Configuration
[Unit]
Description=Minecraft Lobby Server
After=network.target

[Service]
User=minecraft
WorkingDirectory=/opt/minecraft/lobby
ExecStart=/usr/bin/java -Xms512M -Xmx1G -jar /opt/minecraft/lobby/server.jar nogui
ExecStop=/bin/kill -SIGINT $MAINPID
SuccessExitStatus=130 143
TimeoutStopSec=180
Restart=on-failure
RestartSec=20
StandardInput=null

[Install]
WantedBy=multi-user.target

Start Everything

Start both servers, then follow the lobby's first startup until the Done line appears:

Terminal
sudo systemctl daemon-reload
sudo systemctl start minecraft.service
sudo systemctl enable --now minecraft-lobby.service
sudo journalctl -u minecraft-lobby.service -f

Exit the log view with Ctrl+C, then start the proxy:

Terminal
sudo systemctl enable --now velocity.service
sudo journalctl -u velocity.service -n 30 --no-pager

Check That the Internal Ports Are Closed

Terminal
sudo ss -ltnp | grep -E ':(25565|25566|25567)\b'

Port 25565 must listen on all addresses. Ports 25566 and 25567 must show 127.0.0.1 or [::ffff:127.0.0.1], never 0.0.0.0, * or [::].

The firewall does not change: only port 25565 stays open. With UFW, this command must display nothing:

Terminal
sudo ufw status | grep -E '2556[67]'

Then test the ports from another computer. The first must respond, and the second must fail:

Terminal
nc -zv -w 5 SERVER_IP 25565
nc -zv -w 5 SERVER_IP 25566

If a Server Is on Another Machine

The loopback interface only works within a single machine. On a second machine, make the server listen on a private address, ideally that of a WireGuard tunnel, enter this address in velocity.toml, then allow only the proxy. On that second machine, with UFW:

Terminal
sudo ufw allow from PROXY_IP to any port 25566 proto tcp

Or with iptables:

Terminal
sudo iptables -A INPUT -p tcp -s PROXY_IP --dport 25566 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 25566 -j DROP

Verify the Result

First, check the three services:

Terminal
systemctl is-active velocity.service minecraft.service minecraft-lobby.service

Then connect with your Minecraft client, using the same address as before. You should arrive in the lobby. Type:

Text
/server
/server survie

The first command lists the servers, and the second transfers you without disconnecting. Your builds and inventory should be there. Finally, check what the server received:

Terminal
sudo journalctl -u minecraft.service --since "10 minutes ago" --no-pager | grep -E 'UUID of player|logged in with entity id'

You should see your public IP address, not 127.0.0.1. The third block of the UUID must start with 4, which indicates an authenticated account.

Plugins and the Proxy

Paper plugins stay in each server's plugins folder. Velocity has its own plugins, which go in /opt/minecraft/velocity/plugins and are loaded by restarting the proxy.

If you use Geyser and Floodgate, their installation changes behind a proxy: follow the Floodgate documentation for Velocity.

Back Up the Proxy and the Lobby

The backup.sh script from the base guide does not cover these folders. First, protect the backups folder, since the archives will contain the secret:

Terminal
sudo chmod 700 /opt/minecraft/backups

Then add this line to /opt/minecraft/backup.sh, after the existing tar line. The world_ prefix lets the script's automatic cleanup take this archive into account:

Terminal
tar -czf $BACKUP_DIR/world_proxy_$DATE.tar.gz -C /opt/minecraft velocity lobby

Update

When a new version of Minecraft comes out, update Velocity before the servers so that it accepts the new clients. Players are disconnected during the operation:

Terminal
sudo systemctl stop velocity.service
sudo tar -czf /opt/minecraft/backups/velocity-$(date +%F-%H%M).tar.gz -C /opt/minecraft velocity
sudo -u minecraft /opt/minecraft/velocity-update.sh 4.3.1
sudo systemctl start velocity.service

Then update the survie server as explained in the Paper guide, and copy its file to the lobby:

Terminal
sudo systemctl stop minecraft-lobby.service
sudo tar -czf /opt/minecraft/backups/lobby-$(date +%F-%H%M).tar.gz -C /opt/minecraft lobby
sudo -u minecraft cp /opt/minecraft/server/server.jar /opt/minecraft/lobby/server.jar
sudo systemctl start minecraft-lobby.service

Roll Back

To return to a single server on port 25565, without losing what has been played since:

Terminal
sudo systemctl disable --now velocity.service minecraft-lobby.service
sudo systemctl stop minecraft.service
sudo -u minecraft sed -i \
    -e 's/^server-ip=.*/server-ip=/' \
    -e 's/^server-port=.*/server-port=25565/' \
    -e 's/^online-mode=.*/online-mode=true/' \
    /opt/minecraft/server/server.properties
sudo -u minecraft sed -i "/^  velocity:/,/^ \{0,2\}[a-z]/{s/^    enabled: .*/    enabled: false/;s/^    secret: .*/    secret: ''/;}" /opt/minecraft/server/config/paper-global.yml
sudo systemctl start minecraft.service

The velocity and lobby folders stay in place. If a more serious problem occurs, restore the avant-velocity-… archive as described in the Restore the Backup section of the Paper guide.

Troubleshooting

Start with the logs of the proxy and of the server concerned:

Terminal
sudo journalctl -u velocity.service -n 100 --no-pager
sudo journalctl -u minecraft.service -n 100 --no-pager
sudo journalctl -u minecraft-lobby.service -n 100 --no-pager

"Unable to connect you to lobby. Please try again later."

Velocity cannot reach this server. Check that it is started and has finished loading, then that the port in velocity.toml matches server-port. The ss command above shows the ports actually open.

"There are no available servers to connect you to."

No server in the try list accepted the player. Check this list and start at least one of these servers.

"Your server did not send a forwarding request to the proxy"

Modern forwarding is not active on the Paper server. Check for enabled: true in config/paper-global.yml, then restart the server. If its logs show Velocity is enabled, but no secret key was specified, the secret is empty: go back to the Connect the Existing Server section.

"Unable to verify player details"

The Paper secret does not match forwarding.secret. Run the secret copy command again on the server concerned, then restart it. For the lobby, use the path /opt/minecraft/lobby/config/paper-global.yml.

"This server requires you to connect with Velocity."

The player is reaching the Paper server without going through the proxy, or Velocity is not using modern mode. Check player-info-forwarding-mode and the address the player is using. If they were able to reach 25566 from the Internet, close this port immediately.

"This server is only compatible with Minecraft 1.13 and above."

Modern forwarding refuses clients older than 1.13. These players must move to a newer version.

Velocity does not start

Log message Cause Solution
Can't bind to …:25565 The port is already in use, often by a Minecraft server Check server-port and use sudo ss -ltnp
Server 'factions' for forced host '…' does not exist An example remains in [forced-hosts] Empty the section
Fallback server … is not registered in your configuration! A name in try is missing from [servers] Correct the name
You don't have a forwarding secret set The secret file is empty or cannot be found Check forwarding.secret
UnsupportedClassVersionError Java is too old Install Java 25

"FAILED TO BIND TO PORT" on a Paper server

Two services are using the same port. Check server-port in each server.properties: 25566 for survie, 25567 for the lobby.

Players have lost their inventory

The server assigned them a different UUID, usually because forwarding was not active or because proxies.velocity.online-mode does not match Velocity's online-mode. Stop the server, correct these settings and restart it: the original data remains in the world, under the old UUID.

To go further, see the official Velocity documentation, especially its pages on player information forwarding and security.