Velocity 4 Lobby Setup: velocity.toml, Backends and Plugins

Published on | Updated

Set up a Minecraft lobby network on Velocity 4.3.1 and Java 25: a download command that works, velocity.toml, Paper forwarding and the upgrade from 3.x.

Snowy Minecraft mountains at sunset with a campfire in the foreground

You want one address for your Minecraft network: players join, land in a lobby and walk from there to Survival, Creative or a minigame. Each of those is a separate server, and a proxy in front of them moves players between them without a reconnect. This guide builds that with Velocity, PaperMC's proxy, and was rewritten on 3 November 2026 for Velocity 4.3.1. If you followed an older version, its download step no longer works: PaperMC retired the v2 download API, and the old jar URL now returns HTTP 404.

Quick answer: For a Velocity lobby network in November 2026, install Java 25, download the latest stable Velocity 4 build (4.3.1, build 45) through PaperMC's fill v3 API and start it once to create velocity.toml. In velocity.toml, list your lobby and game servers under [servers], put the lobby in try and set player-info-forwarding-mode = "modern". On each Paper backend, set online-mode=false and server-ip=127.0.0.1, then enable proxies.velocity with the secret from forwarding.secret. Still on Velocity 3.x? Its support ended on 30 September 2026: install Java 25, check your plugins for 4.x support, back up the folder and swap the jar.

How a Velocity Lobby Network Works

Players connect to the proxy's address. Velocity logs them in with Mojang and passes them on to a backend server according to your config:

Player → Velocity proxy (port 25565) → lobby     (127.0.0.1:30066)
                                     → survival  (127.0.0.1:30067)
                                     → creative  (127.0.0.1:30068)

Each backend runs its own world, plugins and memory. The try list in velocity.toml says where players go when they log in and when a server kicks them, so when Survival goes down, Velocity tries to move its players to the lobby instead of disconnecting them.

Velocity or BungeeCord? Velocity's modern forwarding signs player data with a MAC code, so it is much harder for someone to pose as your proxy (Minecraft 1.13 and newer). PaperMC calls BungeeCord-style (legacy) forwarding "fundamentally insecure" and says that if you must use it, you have to make sure nothing but the proxy can reach your backends. Velocity does not run BungeeCord proxy plugins, so if you depend on those, read our BungeeCord vs Velocity comparison first.

What You Need

  • A Linux server. Velocity's tuning guide recommends x86_64 Linux for production, because its native compression and encryption libraries are only verified on Linux x86_64 and aarch64.
  • Java 25. Velocity 4 needs at least Java 25, and on PaperMC's download service Paper 26.3 lists Java 25 as its minimum too, so one install serves the proxy and the backends.
  • Memory for every heap plus the operating system. Velocity's rule of thumb is 512 MB of heap per 500 players plus about 1 GB extra. The start commands below give the proxy 1 GB, the lobby 1 GB, Survival 4 GB and Creative 2 GB.
  • curl and jq for the download command.

A Space-Node VPS gives you a KVM machine with full root access and NVMe storage. The RAM is dedicated and the vCores are shared with other VPSes on the node, so keep an eye on tick times as you add backends.

Install Java 25 with Amazon Corretto, as PaperMC's Java guide does for Ubuntu and Debian:

sudo apt-get update
sudo apt-get install ca-certificates apt-transport-https gnupg wget
wget -O - https://apt.corretto.aws/corretto.key | sudo gpg --dearmor -o /usr/share/keyrings/corretto-keyring.gpg && \
echo "deb [signed-by=/usr/share/keyrings/corretto-keyring.gpg] https://apt.corretto.aws stable main" | sudo tee /etc/apt/sources.list.d/corretto.list
sudo apt-get update
sudo apt-get install -y java-25-amazon-corretto-jdk libxi6 libxtst6 libxrender1
java -version

The last line should report version 25. PaperMC warns against the -headless Java packages.

Step 1: Download Velocity 4 With the fill v3 API

The old api.papermc.io/v2 address is gone: on 3 November 2026 the v2 project endpoint answered 410 Gone and the old 3.4.0 jar URL answered 404. Downloads now come from fill.papermc.io/v3, and PaperMC asks every script to send a User-Agent that names your project and a contact address. This picks the newest release version, takes its stable build and checks the SHA-256 checksum:

sudo apt-get install -y curl jq
mkdir -p ~/velocity && cd ~/velocity
UA="my-network-setup/1.0 (you@example.com)"
API="https://fill.papermc.io/v3/projects/velocity"
VERSION=$(curl -s -H "User-Agent: $UA" "$API" | jq -r '[.versions[][] | select(test("SNAPSHOT") | not)] | .[0]')
BUILD=$(curl -s -H "User-Agent: $UA" "$API/versions/$VERSION/builds" | jq -c 'first(.[] | select(.channel == "STABLE"))')
URL=$(printf '%s' "$BUILD" | jq -r '.downloads."server:default".url')
SHA=$(printf '%s' "$BUILD" | jq -r '.downloads."server:default".checksums.sha256')
curl -s -H "User-Agent: $UA" -o velocity.jar "$URL"
echo "$SHA  velocity.jar" | sha256sum -c
echo "Velocity $VERSION build $(printf '%s' "$BUILD" | jq -r '.id')"

On 3 November 2026 this picks velocity-4.3.1-45.jar, released on 27 October, and the file matches its published checksum, so the check line prints velocity.jar: OK. The script skips versions ending in -SNAPSHOT on purpose: those are development builds, and until 6 October 2026 PaperMC published them in the STABLE channel too, so a filter on the channel alone can pick one. To pin a version, replace the VERSION= line with VERSION="4.3.1". For Paper, change velocity to paper in the API line and set the Minecraft version by hand, for example VERSION="26.3", because Paper's list also holds release candidates.

Step 2: First Start and velocity.toml

Create start.sh next to the jar with the flags from Velocity's getting started page:

#!/bin/sh
java -Xms1G -Xmx1G -XX:+UseG1GC -XX:G1HeapRegionSize=4M -XX:+UnlockExperimentalVMOptions -XX:+ParallelRefProcEnabled -XX:+AlwaysPreTouch -XX:MaxInlineLevel=15 -jar velocity.jar

Run chmod u+x start.sh and ./start.sh. Velocity prints Booting up Velocity 4.3.1, writes velocity.toml and forwarding.secret, and listens on port 25565. Type shutdown (or end) in the console to stop it.

Velocity binds to port 25565 by default, so players need no port number. Some older guides, including the first version of this one, used 25577. Change these lines in velocity.toml:

bind = "0.0.0.0:25565"
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"
creative = "127.0.0.1:30068"
try = [
    "lobby"
]

[forced-hosts]
"play.example.com" = ["lobby"]
"survival.example.com" = ["survival"]
"creative.example.com" = ["creative"]

Replace the whole [forced-hosts] section rather than adding to it. The default file points factions.example.com at a server called factions; if that server no longer exists under [servers], Velocity logs "Server 'factions' for forced host 'factions.example.com' does not exist" and refuses to start. Forced hosts are optional: with DNS records for those names, survival.example.com drops players straight into Survival.

Step 3: Configure the Paper Backends

Every backend must accept forwarded player data from the proxy and nothing else. In each backend's server.properties, give it its own port and bind it to localhost. Velocity's security page calls binding to localhost a very simple protection when the proxy and backends share a machine:

# lobby; use 30067 for survival and 30068 for creative
online-mode=false
server-ip=127.0.0.1
server-port=30066

Keep comments on their own line: in a properties file, text after the value becomes part of the value. Make sure settings.bungeecord is false in spigot.yml, then open config/paper-global.yml:

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: "paste the contents of forwarding.secret here"

Print the secret with cat ~/velocity/forwarding.secret. online-mode here must match online-mode in velocity.toml. Restart each backend afterwards. If your backends run on other machines, drop the server-ip line and let a firewall accept the backend ports from the proxy's IP only. If you use UFW on a single machine, allow SSH before you enable it (sudo ufw allow OpenSSH), then open only the proxy port with sudo ufw allow 25565/tcp; the backends need no rule, since they only listen on 127.0.0.1.

Step 4: Build the Lobby and Pick a Lobby Plugin

The lobby is a waiting room, so keep it small: a void world or a compact pre-built hub loads fast and costs little CPU. Then give players a way to move:

  • The built-in /server command. Velocity grants velocity.command.server to all players by default, so /server survival works without any plugin, and /server alone lists the servers.
  • A /lobby or /hub plugin on the proxy. Search Hangar with the Velocity filter and read which versions each upload lists. On 3 November 2026, VLobby, a popular lobby plugin there with over 2,000 downloads, listed only Velocity 3.2 and 3.4, so test such a plugin before you rely on it on 4.x.
  • Plugins on the lobby server. A protection plugin such as WorldGuard stops building, EssentialsX Spawn sets the spawn point, and Citizens can make NPCs that send players on. Citizens documents /npc command add -p server survival for BungeeCord and says it might also work on a proxy that implements the Bungee protocol. Velocity keeps the BungeeCord plugin message channel on by default (bungee-plugin-message-channel = true), so test one NPC before you build the whole hub around it.

Step 5: Start the Network

Start the backends first, so the lobby is ready when the first player arrives:

cd ~/servers/lobby && java -Xms1G -Xmx1G -jar paper.jar nogui
cd ~/servers/survival && java -Xms4G -Xmx4G -jar paper.jar nogui
cd ~/servers/creative && java -Xms2G -Xmx2G -jar paper.jar nogui
cd ~/velocity && ./start.sh

Run each line in its own screen or tmux window, or as a systemd service. Players join on your address without a port and land in the lobby.

Keeping Server Switches Smooth

  • Keep backends running. Velocity waits 5 seconds by default (connection-timeout = 5000) for a backend, so a server that is still loading its world makes the switch fail.
  • Size the proxy with the formula. At 512 MB per 500 players plus about 1 GB, 1 GB of heap suits a small network. Velocity's tuning page adds that the proxy benefits from more cores rather than higher clock speed, and that disk speed does not matter to it.
  • Watch the destination server. A switch ends with the target backend sending the player the chunks around them, so keep spawn areas small and give the backends the CPU time.

Upgrading From Velocity 3.x to Velocity 4

On PaperMC's download service, 3.5.1, the last 3.x release (11 July 2026), is marked deprecated with a support end date of 30 September 2026, and the 3.x source code knows Minecraft versions up to 26.2. The 4.x releases so far:

VersionStable buildStatus on 3 November 2026Note
4.0.014 July 2026Unsupported since 24 AugustFirst 4.x: Java 25, Adventure 5
4.1.024 August 2026Unsupported since 14 September
4.1.126 August 2026Supported
4.2.014 September 2026SupportedAdds Minecraft 26.3
4.3.018 October 2026Supported
4.3.127 October 2026Supported"Recommended security update for all users"

Two changes in 4.0.0 matter for an upgrade. Velocity moved to Java 25, and it moved to Adventure 5, the text library proxy plugins use for chat, which its authors call a major update with breaking changes. Upgrade in this order:

  1. Java. Install Java 25 as above. Velocity 4 is compiled for Java 25 (class file version 69), so on Java 21 it stops at once with an UnsupportedClassVersionError that says the runtime only recognizes class file versions up to 65.0.
  2. Plugins. Type velocity plugins in the proxy console to list every plugin with its version. Open each plugin's own page on Hangar, Modrinth or GitHub and look for a release that lists Velocity 4. Test a plugin that only lists 3.x on a copy first, or replace it.
  3. Backup. Stop the proxy and copy the whole folder: cp -a ~/velocity ~/velocity-3x-backup. That keeps the old jar, velocity.toml, forwarding.secret and plugin data.
  4. Swap. Run the download command from step 1 in ~/velocity and start the proxy. On its first start, 4.3.1 rewrites velocity.toml: it moves the old ping-passthrough = "..." line into a [ping-passthrough] section and sets config-version to "2.9".
  5. Test. Join, run /server to each backend and read the console for plugin errors.

Rolling back. Stop the proxy, run mv ~/velocity ~/velocity-4-failed and cp -a ~/velocity-3x-backup ~/velocity, then start it with your old command. Use the backup copy of velocity.toml, not the file 4.x rewrote. Treat this as a stopgap: 3.x is out of support and does not know Minecraft 26.3. If only the newest 4.x build causes trouble, set VERSION="4.3.0" in the download command instead.

On Minecraft 26.4 release day. 26.4 Snapshot 5 (20 October 2026) changed the login protocol: the server now has to switch on encryption and compression explicitly, and the client confirms it. Velocity added and then reverted 26.4 snapshot support on 23 October, so 4.3.1 does not speak 26.4. Wait for a new Velocity build that lists 26.4 and update the proxy before you move backends to 26.4.

Where to Run It

Everything above runs on one Linux machine you control. If you would rather not manage Java and firewalls yourself, our Minecraft network hosting supports both Velocity and BungeeCord, and support can place the proxy and all backends on the same node so their traffic stays inside one machine.

FAQ

Why does the Velocity download command return 404? Old guides use api.papermc.io/v2, which PaperMC retired. Use the fill v3 command from step 1 or the Velocity download page.

Does Velocity 4 need Java 25? Yes. Velocity's FAQ says 4.0.x and above needs at least Java 25. On an older Java the proxy stops at once with an UnsupportedClassVersionError. See our Java version guide for the backends.

What does "This server requires you to connect with Velocity" mean? The backend has proxies.velocity.enabled: true, but the proxy is not sending modern forwarding data. Set player-info-forwarding-mode = "modern" in velocity.toml and check the secret. The reverse error, "Your server did not send a forwarding request to the proxy", means the backend side is missing. Our IP forwarding error guide covers both.

What is a good lobby plugin for Velocity? Start with the built-in /server command, which every player can use by default. For a /lobby or /hub command, pick a Hangar plugin whose page lists Velocity 4, and use WorldGuard, EssentialsX Spawn and Citizens NPCs on the lobby server itself.

Can I keep running Velocity 3.5.1? PaperMC lists it as deprecated with support ending on 30 September 2026, and it does not know Minecraft 26.3, which Velocity 4.2.0 added. Move to 4.3.1.

Will Velocity 4.3.1 work with Minecraft 26.4? No. 26.4 changes the login protocol, and Velocity removed its 26.4 snapshot support again before 4.3.1. Wait for a build that lists 26.4.

Sources

All opened on 3 November 2026: