Connect multiple backend servers (lobby, survival, minigames) under one IP with seamless switching, modern forwarding, and built-in security.
| Feature | Velocity | BungeeCord | Waterfall |
|---|---|---|---|
| Performance | ✓ Modern JVM | Older arch | Moderate |
| Encrypted forwarding | ✓ Built-in | Manual only | Partial |
| Latest MC versions | ✓ Always | Slow updates | Delayed |
| Actively maintained | ✓ PaperMC | Slow | Community |
| Large network support | ✓ Optimized | Resource-heavy | Moderate |
click to copyjava -jar velocity.jar
velocity.toml and forwarding.secret in the same directory. Stop the server — you need to configure both before running players through it.velocity.tomlLocated in your Velocity root directory. These are the key settings.
click to copybind = "0.0.0.0:25565"
0.0.0.0 binds to all network interfaces. Replace 25565 with your preferred port.
click to copyonline-mode = false
| Value | Behaviour |
|---|---|
true | Premium accounts only — Mojang authentication required |
false | Allows cracked clients — use with AuthMe or similar on backends |
click to copyplayer-info-forwarding-mode = "modern"
| Mode | When to use |
|---|---|
"modern" | Minecraft 1.13+ — recommended, uses Velocity's encrypted protocol |
"legacy" | Minecraft 1.7.2–1.12.2 |
"none" | Disables forwarding — not recommended |
click to copy[servers]
lobby = "127.0.0.1:25565"
survival = "127.0.0.1:25566"
minigames = "127.0.0.1:25567"
try = ["lobby", "survival", "minigames"]
Define each backend server by name and address. The try list sets the fallback order when a player joins — first available server wins.
127.0.0.1 with the numeric IP of each remote server. Don't use domain names here — use nslookup.io to find the IP.[servers] block. Keep it clean.click to copymotd = "&6Welcome to Your Network!&r\nJoin our &bcommunity&r today!"
Displayed in the Minecraft server list. Use & for color codes and \n for line breaks.
click to copyshow-max-players = 1000
compression-level = 4
compression-threshold = 256
| Setting | Description |
|---|---|
show-max-players | Max players shown in server list (display only) |
compression-level | 1–9. Higher = less bandwidth, more CPU. 4 is a safe default. |
compression-threshold | Minimum packet size in bytes before compressing. Default: 256. |
click to copy[forced-hosts]
"lobby.yourdomain.com" = ["lobby"]
"survival.yourdomain.com" = ["survival"]
Routes players connecting via a specific domain directly to a backend server. Leave empty if you're not using subdomains. DNS records must be set up first.
forwarding.secretThis key secures communication between Velocity and all backend servers. Every backend must use the same key.
forwarding.secret in your Velocity directory and replace its contents with your key:
click to copyxL9E!aaW#7Ef29pQ
Each backend server needs two changes: disable its own auth (Velocity handles it) and enable Velocity forwarding with your secret key.
server.propertiesclick to copyonline-mode=false
Mandatory for all backends in a proxy setup. Velocity handles authentication, so backends must not re-verify.
paper-global.yml (PaperMC)Location varies by version:
config/paper-global.ymlpaper.ymlclick to copyproxies:
velocity:
enabled: true
online-mode: false
secret: "xL9E!aaW#7Ef29pQ"
enabled is true ·
online-mode matches Velocity's setting ·
secret is identical to forwarding.secret
| Software | What to change |
|---|---|
| Spigot | Edit spigot.yml → set bungeecord: true for legacy forwarding |
| Fabric | Install FabricProxy Lite, configure with the same secret |
| Purpur | Edit purpur.yml → set velocity: true |
| NeoForge | Install NeoVelocity, configure with the same secret |
Apply steps 4 to every server in your network — lobby, survival, minigames, etc. Each one needs:
velocity.tomlonline-mode=false in server.propertiessecretOrder matters — Velocity connects to backends on startup, so they need to be online first.
Players can move between backend servers without disconnecting from the proxy.
| Command | What it does |
|---|---|
/server <name> | Switch to a named backend server |
/server lobby | Example — switch to lobby |
/glist | List all servers and connected player counts |
velocity.command.server to use /server. Granted by default, but can be restricted via a permissions plugin.plugins/ folder of your Velocity directory and restart the proxy. Check each plugin's docs for Velocity-specific versions.click to copymenus:
main:
title: "&6Choose a Server"
size: 27
items:
lobby:
material: GRASS_BLOCK
name: "&bLobby"
slot: 10
command: "server lobby"
survival:
material: DIAMOND_PICKAXE
name: "&2Survival"
slot: 12
command: "server survival"
minigames:
material: GOLDEN_SWORD
name: "&eMinigames"
slot: 14
command: "server minigames"
Players open this menu with /ssx open main. Make sure server names match exactly what's in velocity.toml.
click to copy/lpv user <player> permission set velocity.command.server.lobby true
/lpv user <player> permission set velocity.command.server.survival true
Run from the Velocity console or as an operator in-game. Omit a permission to block access to that server.
forwarding.secret across separate networks. Store it securely.compression-level based on your CPU. High values save bandwidth but cost processing power.velocity.toml, forwarding.secret, and all backend configs before any update.velocity.toml are correct and that each backend is actually running. Try connecting directly (by IP:port) to isolate whether it's a Velocity or backend issue.forwarding.secret exactly matches the secret value in every backend's config. Also verify online-mode is consistent — false on backends, and matching your intent on Velocity.compression-level — if CPU usage is high, lower it. Use Spark to profile where the bottleneck is. Also check your host's network quality.[forced-hosts] exactly matches what players connect from, including any subdomains.velocity.toml (case-sensitive). Check that the player has the velocity.command.server permission via LuckPerms. Make sure the target backend is online.plugins/ folder, not on the backend server. Also verify the config file has no YAML syntax errors and that the server names match velocity.toml.java -version). Read the startup log — it usually states the exact error. Common causes: port already in use, malformed velocity.toml, or missing backend server entries.