How to Set Up a Velocity Proxy

  • 10 min read
  • Updated
  • ESAGAMES Team

Run a Minecraft network — lobby, survival, minigames — behind one address. This guide installs the Velocity proxy, links your Paper servers with modern forwarding and a shared secret, and locks the backends down so nobody can bypass the proxy.

A proxy sits between players and your servers. Players connect to Velocity on one public address; Velocity authenticates them with Mojang and moves them between your backend Paper servers — with /server, portals or menus — without disconnecting. It's how networks run a hub plus several game modes.

Velocity is PaperMC's proxy, built for performance and security. Its modern forwarding passes each player's real UUID, IP and skin to the backends and protects that data with a shared secret — something classic BungeeCord forwarding doesn't do. It does not run BungeeCord plugins, so look for Velocity versions of your proxy plugins (Hangar is the main source).

One rule matters above all: backends run in offline mode, so they must be reachable only through the proxy. Each server can be self-hosted or run on our Minecraft server hosting — Frankfurt, NVMe, always-on Anti-DDoS, and a panel with file manager and console for the configs below. Want Bedrock players too? Add Geyser and Floodgate on the proxy.

What you'll need

  • A machine for the proxy and one or more Paper backends (they can share a machine on different ports).
  • Java 25 or newer for current Velocity releases; each backend needs the Java version its Minecraft version requires.
  • Paper on Minecraft 1.13 or newer for modern forwarding.
  • One public TCP port for the proxy (25565 by default) and a private port per backend.
  • Firewall access — or a localhost-only setup — so backends accept only the proxy.

Set up a Velocity network, step by step

  1. Step 1: Plan your ports

    Only the proxy is public. Velocity binds to port 25565 by default — the address players type. Every backend gets its own port that only the proxy uses; servers sharing one machine can't all sit on 25565. Java Minecraft runs over TCP, so these are all TCP ports.

    proxy     0.0.0.0:25565     public  - players connect here
    lobby     127.0.0.1:30066   private - proxy only
    survival  127.0.0.1:30067   private - proxy only
  2. Step 2: Download and start Velocity

    Velocity is a separate Java program, not a plugin. Download the latest stable build from the official PaperMC downloads page into its own folder — current releases need Java 25 or newer. Start it once: it creates velocity.toml and a forwarding.secret file with a random secret. Type end in the console to stop it.

    java -Xms1G -Xmx1G -XX:+UseG1GC -XX:G1HeapRegionSize=4M -XX:+UnlockExperimentalVMOptions -XX:+ParallelRefProcEnabled -XX:+AlwaysPreTouch -XX:MaxInlineLevel=15 -jar velocity.jar
    # first start creates velocity.toml and forwarding.secret
    # type  end  to stop the proxy
  3. Step 3: Configure velocity.toml

    Set bind to the address and port players use, keep online-mode = true (the proxy authenticates players), and set player-info-forwarding-mode to modern. Under [servers], list each backend as name = "ip:port"; try is the order Velocity sends players to on login or after a kick. Delete the sample servers you don't use — and remove them from try and [forced-hosts] too, or the proxy refuses to start.

    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"
    try = [
      "lobby"
    ]
  4. Step 4: Set backends to offline mode

    On every Paper backend, open server.properties, set online-mode=false and give it the port you listed in [servers]. The proxy now does the authentication. This step alone is insecure — finish the next two steps before you open the network.

    online-mode=false
    server-port=30066
  5. Step 5: Enable Velocity forwarding in Paper

    Open config/paper-global.yml and, under proxies.velocity, set enabled: true, online-mode: true (to match velocity.toml) and secret to the exact contents of the proxy's forwarding.secret. Make sure settings.bungeecord is false in spigot.yml, then restart the backend. Older Paper versions (1.18.2 and below) keep these options in paper.yml under settings.velocity-support.

    proxies:
      velocity:
        enabled: true
        online-mode: true
        secret: "paste-the-contents-of-forwarding.secret"
  6. Step 6: Firewall the backends — don't skip this

    An offline-mode server that anyone can reach lets people join under any name, including yours. Modern forwarding adds a second check, but the Velocity docs are clear that it is not a replacement for a firewall. If a backend is on the same machine as the proxy, bind it to localhost with server-ip=127.0.0.1. If it is on another machine, allow its port only from the proxy's IP.

    # backend on the same machine as the proxy (server.properties)
    server-ip=127.0.0.1
    
    # backend on another machine: only the proxy may connect
    sudo ufw allow from 203.0.113.10 to any port 30066 proto tcp
    sudo ufw deny 30066/tcp
  7. Step 7: Start and test the network

    Start the backends, then the proxy, and join the proxy address. /server lists servers and switches between them (all players can use it by default). /glist all shows players per server and /velocity reload re-reads velocity.toml — both need permissions, so run them from the proxy console. Finally, try to join a backend port directly from outside: it must fail.

    /server survival    # switch server
    /glist all          # players per server
    /velocity reload    # re-read velocity.toml

Run a secure, stable network

  • Firewall first, forwarding second

    Modern forwarding rejects logins without the right secret, but a firewall (or localhost binding) stops strangers reaching offline-mode backends at all. Use both.

  • Keep the secret secret

    forwarding.secret proves data came from your proxy. Never post it in screenshots or support chats; if it leaks, put a new random value in the file and in every backend's paper-global.yml.

  • Velocity plugins only

    Velocity doesn't load BungeeCord plugins. Server-side plugins that only use the BungeeCord messaging channel usually keep working, because Velocity supports that channel natively.

  • One public door

    With a proxy, only one address faces the internet. Put DDoS protection in front of the proxy and keep backend ports closed — attacks can't target servers they can't reach.

Common problems & fixes

"If you wish to use IP forwarding, please enable it in your BungeeCord config as well!"

The backend isn't receiving Velocity forwarding. Set proxies.velocity.enabled: true and the matching secret in config/paper-global.yml, keep bungeecord false in spigot.yml, and restart the backend.

"This server requires you to connect with Velocity."

The backend has modern forwarding on but the proxy doesn't — set player-info-forwarding-mode = "modern" in velocity.toml. You also see this when joining a backend port directly, which is expected.

Velocity refuses to start after editing velocity.toml

Check the log: every server named in try and [forced-hosts] must exist in [servers], every address must be valid, and modern forwarding needs a non-empty forwarding.secret.

"Can't connect to server" / connection refused from the proxy

The IP or port in [servers] is wrong, the backend is bound to 127.0.0.1 on a different machine, or a firewall blocks the proxy's IP. See fixing connection refused.

Players lose inventories or get the wrong skin between servers

UUIDs differ because forwarding is off or proxies.velocity.online-mode doesn't match the proxy's online-mode. Fix the forwarding setup on every backend so all servers see the same UUIDs.

Frequently asked questions

What is a Velocity proxy?

Velocity is an open-source Minecraft proxy from PaperMC. Players connect to it, it authenticates them, and it forwards them to your backend servers, so several servers act as one network with a single address.

Why do backend servers need online-mode=false?

Because the proxy already authenticates players with Mojang. With modern forwarding, the backend still gets each player's real UUID and skin. Never leave an offline-mode backend reachable from the internet.

Where do I find the forwarding secret?

Velocity creates forwarding.secret next to velocity.toml on first start. Copy its contents into proxies.velocity.secret in each backend's config/paper-global.yml.

Should I use modern or legacy forwarding?

Use modern if every backend runs Minecraft 1.13 or newer — it's the most secure option. legacy (BungeeCord-style) and bungeeguard exist for older versions or software that can't use modern forwarding. You can only pick one.

Which ports does a Velocity network need?

One public TCP port for the proxy (25565 by default) and one private port per backend, reachable only by the proxy. Players never connect to backend ports.

Can Velocity run BungeeCord plugins?

No. Use Velocity versions of your proxy plugins — Hangar is the main source. The third-party Snap project offers an experimental compatibility layer, but test it carefully.

Can the proxy and backends be on different machines?

Yes. Point each [servers] entry at the backend's IP and port, allow that port only from the proxy's IP, and keep modern forwarding on so a backend only accepts your proxy.

Fixes for when it goes wrong

Knowledge-base fixes that pair with this guide — the errors people hit after setup.

More guides

Skip the troubleshooting

Managed, protected hosting in Frankfurt — we handle the Linux, the network and the DDoS so you don't have to.