Linking servers with Velocity

Updated 4 Nov 2026

What you need

A Velocity proxy links several servers into one network. Players join the proxy and move between servers with /server.

  • One server running Velocity. 512 MB is plenty.
  • Two or more Paper servers.

Set up the proxy

  1. On a small server, choose Velocity on the Change Version tab.
  2. Start it once, then stop it.
  3. In velocity.toml, set player-info-forwarding-mode = "modern" and list your servers under [servers].
  4. Copy the text in forwarding.secret.

Set up each Paper server

On every backend server:

config/paper-global.yml
proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: 'paste-your-secret'

And in server.properties set online-mode=false. Restart.

Do both, always

online-mode=false without the Velocity setting lets anyone join as anyone.

Join through the proxy

Connect to the proxy's address only. Use /server name to move. Ask us in a ticket to block direct access to your backend servers.

Problems

Unable to connect you to the server

Check the backend is running and its address in [servers] is right.

Kicked about forwarding

The secret does not match. Copy it again with no spaces.

Everyone has a Steve skin

Set forwarding mode to modern on the proxy.

Still stuck? Open a ticket and we will take a look.
Open a ticket

More guides