How to Set Up a Velocity Proxy

How a Velocity network works

Players connect to Velocity, the proxy. Velocity authenticates them with Mojang and forwards them to one of your backend servers (for example a lobby and a survival server running Paper). Players can switch servers without reconnecting. The backends run in offline mode and must only be reachable from the proxy.

1. Install and start Velocity

1. Download Velocity from the Velocity page (newest stable: Velocity 4.3.1, needs Java 25). Versions ending in -SNAPSHOT are development lines.
2. Start it in its own folder. A proxy needs little memory; PaperMC's docs use 1 GB:

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

   There is no EULA step. The first start creates velocity.toml and forwarding.secret; type end to stop it.
3. Velocity listens on port 25565 by default (bind = "0.0.0.0:25565" in velocity.toml), so players connect to it with the normal address. Your backends therefore need other ports.

2. Register your backend servers

In velocity.toml, edit the [servers] section. Each entry is a name and an address; try is the order in which Velocity sends players on login (or when they are kicked from a server):

[servers]
lobby = "127.0.0.1:30066"
survival = "127.0.0.1:30067"

try = [
  "lobby"
]

Set each backend's server-port in its server.properties to match (30066, 30067 …). Remove the example servers you don't use from both lists.

3. Turn on modern forwarding

Without forwarding, backends see every player as coming from the proxy's IP with the wrong UUID — and offline-mode backends are insecure. Velocity's modern forwarding sends the real player data, signed with a secret. It works with Minecraft 1.13 and newer.

1. In velocity.toml set:

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

2. On every Paper backend, in server.properties: online-mode=false (the proxy checks accounts instead).
3. In spigot.yml make sure settings.bungeecord is false.
4. In config/paper-global.yml:

   proxies:
     velocity:
       enabled: true
       online-mode: true
       secret: 'paste the content of forwarding.secret here'

   online-mode here must match online-mode in velocity.toml. On Paper 1.18.2 and older the same options are settings.velocity-support.* in paper.yml.
5. Restart the backends, then Velocity. Players now join through the proxy with their real names, skins and UUIDs.

Backends on Minecraft 1.12.2 or older can't use modern forwarding; they need legacy (BungeeCord) forwarding. Fabric backends need a forwarding mod.

4. Lock the backends down

Because backends run with online-mode=false, anyone who can reach them directly could join as any player. Bind them to 127.0.0.1 (server-ip in server.properties) when they run on the same machine as Velocity, or firewall their ports so only the proxy's IP can connect. Modern forwarding adds a second layer: Paper rejects logins without a valid secret.

Velocity runs Velocity plugins only — not Bukkit or BungeeCord plugins. Coming from BungeeCord or Waterfall? See Velocity vs BungeeCord vs Waterfall.