Minecraft Velocity proxy setup, from one jar to a working network

A Minecraft Velocity proxy setup has four parts: install the proxy, tell it where your backend servers are, make the proxy and the backends agree on how player identity is forwarded, and block every path to a backend that does not go through the proxy. Most broken networks got the first two right and skipped the last two, which is why players show up with wrong skins or, worse, anyone can log in as anyone by connecting straight to a backend.

Velocity is the proxy the Paper team builds and recommends, and it has won the argument on our list: 983 online servers report Velocity in their version string, 147 report the Velocity-CTD fork, and only 77 report BungeeCord (23 for Waterfall). If you are choosing between them, read BungeeCord vs Velocity first. This guide assumes you have picked Velocity and have at least one Paper backend.

What a proxy changes

Without a proxy, a player connects to your server, Mojang authenticates them, and that server owns the session. With Velocity in front, the player connects to the proxy, the proxy authenticates them, then opens a second connection to a backend on the player's behalf. That means:

• Backends run in offline mode. They cannot authenticate a connection that arrives from the proxy, so online-mode=false is required on each one. This is the step that makes the firewall mandatory.
• The proxy forwards who the player is. Skin, UUID and IP address travel from proxy to backend in the handshake. If forwarding is off, every player has a Steve skin, an offline UUID, and the proxy's IP.
• The proxy owns the MOTD and the player count. What server lists and the multiplayer screen see comes from velocity.toml, not from any backend. Our pinger reads the proxy, so that is where your MOTD and icon now live.
• Some plugins move to the proxy. Permissions, vote receiving, version compatibility and Bedrock support all have a proxy-side install. Gameplay plugins stay on the backends.

Install Velocity

1. Install Java 25 or newer. The Velocity getting-started page states "Velocity requires at least Java 25." Check with java -version on the machine that will run the proxy.
2. Download the jar from papermc.io and put it in its own folder, not inside a backend's folder.
3. Start it once. The docs' recommended flags are java -Xms1G -Xmx1G -XX:+UseG1GC -XX:G1HeapRegionSize=4M -XX:+UnlockExperimentalVMOptions -XX:+ParallelRefProcEnabled -XX:+AlwaysPreTouch -XX:MaxInlineLevel=15 -jar velocity.jar. A proxy does not need much memory; 1 GB carries a lot of players because it holds no world data.
4. Stop it once the console prints that it is listening. It has generated velocity.toml and a forwarding.secret file next to the jar.
5. Note the port. Velocity binds 0.0.0.0:25565 by default, which is the normal Minecraft port. If a backend is on the same machine and already uses 25565, move the backend, not the proxy, so players can connect without typing a port.

velocity.toml, the keys that matter

The generated file has comments for every key. These are the ones you will actually touch:

A minimal working file for a hub plus one survival server on the same machine looks like this:

bind = "0.0.0.0:25565"
motd = "<gradient:#5e4fa2:#f79459>My Network</gradient> | Season 3 just started"
show-max-players = 100
online-mode = true
player-info-forwarding-mode = "modern"
forwarding-secret-file = "forwarding.secret"

[servers]
hub = "127.0.0.1:25566"
survival = "127.0.0.1:25567"
try = ["hub", "survival"]

[forced-hosts]
"survival.example.com" = ["survival"]

The full key reference is on the configuration page. After any change, /velocity reload re-reads the file without a restart.

Modern forwarding: the proxy and every backend must agree

Velocity's forwarding page lists four modes. legacy is the BungeeCord method and is described there as "fundamentally insecure"; bungeeguard is legacy plus a token; modern is the one to use with Paper 1.13 or newer. Do this on the proxy and then on each backend:

1. Proxy: set player-info-forwarding-mode = "modern" in velocity.toml. Open forwarding.secret and copy the string inside. It is your shared password.
2. Each backend, server.properties: set online-mode=false. If the backend is on the same machine as the proxy, also set server-ip=127.0.0.1 so it only listens locally.
3. Each backend, spigot.yml: make sure settings.bungeecord is false. Modern forwarding and BungeeCord forwarding cannot both be on.
4. Each backend, config/paper-global.yml: fill in the proxies.velocity block below. online-mode here must match the proxy's online-mode, so it stays true.
5. Restart the backends, then the proxy. Join through the proxy and check your skin and your UUID in the backend console. Both should be your real ones.

# config/paper-global.yml on every backend
proxies:
  bungee-cord:
    online-mode: true
  proxy-protocol: false
  velocity:
    enabled: true
    online-mode: true
    secret: "paste-the-contents-of-forwarding.secret-here"

Paper 1.18.2 and older keep these settings in paper.yml under settings.velocity-support. Fabric backends need the FabricProxy-Lite mod for forwarding; Forge backends need ProxyCompatibleForge. Spigot without Paper cannot do modern forwarding at all and has to fall back to legacy plus BungeeGuard.

Firewall the backends

The Velocity security page "strongly recommends the use of a firewall" and says modern forwarding "is not a replacement for a firewall." A backend in offline mode that is reachable from the internet lets anyone log in as any username, including yours. Pick the option that matches your setup:

Test it from a home connection: add a backend's public IP and port to your server list. If it pings, the firewall is not done.

Hub, try order and forced hosts

The try list is the order Velocity attempts when a player logs in. It also serves as the fallback: when a backend closes a player's connection (a restart, a kick, a crash), the proxy tries the next server in the list that it has not tried yet before disconnecting them. Two consequences:

• Put a lightweight hub first. A hub that holds a few chunks and a compass menu starts in seconds and never lags, so the first thing a new player sees is fast. On our list, servers tagged network number 207, and nearly all of them land players on a hub.
• Put your main mode second. If the hub is down for a restart, players still get in. If you only list the hub, a hub restart disconnects everyone.
• Give players /server. Velocity's built-in /server <name> is granted to everyone by default through velocity.command.server; /glist and /send are not, so give staff velocity.command.glist and velocity.command.send through LuckPerms on the proxy.
• Use forced hosts for direct addresses. With "survival.example.com" = ["survival"] and a DNS record for that name, players who type it skip the hub. The Velocity FAQ notes this only works when the client sends the hostname, so set it up with a real DNS record, not an IP.

Plugins that live on the proxy

Velocity does not load BungeeCord plugins; the FAQ answers that question with a flat "No." Look for a Velocity build on Hangar or Modrinth before you assume a plugin will not work. What goes where:

Test before you announce

• Join through the proxy and confirm your skin loads and the backend console shows your real UUID and IP, not the proxy's.
• Try each backend directly from outside. Every one should time out or refuse.
• Restart a backend while standing on it. You should land on the next try entry, not on the multiplayer screen.
• Ping the proxy from a server list. The MOTD, icon and count should be the proxy's. Our is it down checker shows exactly what our pinger sees, including the version string.
• Run /velocity dump if something is off; it produces an anonymized report you can paste in the PaperMC Discord.

Once the proxy is the only door in, list the proxy's address (never a backend's) on your listing, set the game modes each backend offers, and claim the listing from its server page so the description and the 7-day chart are yours to manage. If the network launches on a date, a coming-soon listing collects "Notify me" sign-ups until then.

Quick questions