Velocity Networks: Setup and Best Practices

Minecraft

4 min readAdvancedLast updated Oct 30, 2026

A network joins several Minecraft servers (a lobby, survival, creative, minigames) behind one address. Players connect to a proxy, and the proxy moves them between back-end servers with commands like /server survival. We recommend Velocity, the modern, secure proxy from the Paper team.

Players ──► Velocity (public port) ──► Lobby        (private)
                                    ├─► Survival     (private)
                                    └─► Creative     (private)

What you need

One Velocity server, plus one server per game mode, in the panel. Ask us to add them to your plan.
Each server's address and port from its Network page.
Memory for Velocity: it's light. 1 GB handles small networks, and Velocity's own guidance is about 512 MB of heap per 500 players, plus headroom. Spend your memory on the back-ends.

Set up Velocity

Start the Velocity server once, then Stop it. It creates velocity.toml and forwarding.secret.

Edit velocity.toml:

online-mode = true
player-info-forwarding-mode = "modern"
forwarding-secret-file = "forwarding.secret"

[servers]
lobby    = "10.11.30.202:40005"   # use each back-end's address:port from its Network page
survival = "10.11.30.202:40008"
creative = "10.11.30.202:40004"
try = ["lobby"]

[forced-hosts]
# optional: send survival.yourdomain.com straight to survival

Open forwarding.secret and copy the long random text. Keep it private. Anyone with it can pretend to be your proxy.
Start Velocity.

Set up each Paper / Purpur back-end

Stop the server.
In server.properties: online-mode=false. Velocity checks logins; the back-end trusts Velocity.

In config/paper-global.yml, under proxies:

proxies:
  bungee-cord:
    online-mode: true
  proxy-protocol: false
  velocity:
    enabled: true
    online-mode: true          # must match online-mode in velocity.toml
    secret: 'paste-the-forwarding-secret-here'

In spigot.yml, leave settings.bungeecord: false. That's for BungeeCord, not Velocity.
Start the server.

Set up each Fabric back-end

Fabric has no built-in forwarding, so it needs the FabricProxy-Lite mod.

Install FabricProxy-Lite and Fabric API (from Minecraft Plugins).

Start once, then Stop. Edit config/FabricProxy-Lite.toml:

hackOnlineMode = true
secret = "paste-the-forwarding-secret-here"
disconnectMessage = "This server requires you to connect with Velocity."

In server.properties: online-mode=false.
Start.

Set up each Forge or NeoForge back-end

Forge and NeoForge also need a mod for forwarding: Proxy Compatible Forge (PCF). It supports Forge and NeoForge across a wide range of versions; pick the file for your loader and Minecraft version.

Install Proxy Compatible Forge in the back-end's mods/. Players don't need it.

Start once, then Stop. Edit config/proxy-compatible-forge.toml:

[forwarding]
enabled = true
mode = "MODERN"
secret = "paste-the-forwarding-secret-here"

In server.properties: online-mode=false.
Start.

Modded players through Velocity: for Minecraft 1.13 to 1.20.1 Forge, install the Ambassador plugin on Velocity, or modded players can't move between servers. Newer versions work without it.

Every back-end a modded player can reach must run the same modpack, or they're kicked for missing mods when they switch.

Test it

Join the Velocity address. You should land in the lobby.
Run /server survival. You should move servers with the same skin and UUID.
Try joining a back-end directly. It must refuse you, e.g. "This server requires you to connect with Velocity." If it lets you in, forwarding isn't set up and anyone could join as anyone.

Best practices

Velocity's port is the only public one. (Velocity defaults to port 25565; the panel sets it to your allocation.)
Back-end ports stay private. Back-end ports shouldn't be reachable from the internet. With forwarding set up they refuse direct joins, but they still answer pings and can be attacked. Ask us to keep back-end ports private.
online-mode=false only on back-ends, never on Velocity, and only with forwarding working.
The same secret everywhere. If you change it, update every back-end.
Same Minecraft version on every back-end where possible. Put ViaVersion on Velocity if you want players on newer clients to join.
Fabric and modded back-ends need modern forwarding. Legacy (BungeeCord-style) forwarding is insecure and only for very old versions; Velocity's docs say so too.
Lobbies: a light Paper server with few plugins and a small pre-generated world. Put try = ["lobby"] so players land there and return there if a server goes down.
Bedrock players: Geyser goes on Velocity only. See Bedrock crossplay.
Compression: set network-compression-threshold=-1 in each back-end's server.properties, so only the proxy compresses.
Plugins that span the network (chat, permissions, bans) need either a Velocity version or a shared MySQL database. Ask us for a database on your plan.
Back-end MOTDs and max-players don't show to players. Set them in velocity.toml.