How to Set Up a Velocity Proxy for Paper

Map the network before installing Velocity

Velocity gives players one public Minecraft address and routes them to separate backend servers such as a lobby, survival world and minigame server. It does not merge those worlds or replace Paper. Each backend remains its own server process, port, files, plugins and data. Draw the route first: player, public proxy listener, private network or host firewall, then named Paper backends. That map makes it clear which listener should be public and which ones must never accept ordinary internet connections.

Record the operating system, proxy host, backend hosts, Minecraft versions, Paper builds, Java runtimes, private addresses and planned ports. Velocity's current compatibility reference supports many game versions, but modern player-information forwarding requires Paper 1.13.2 or newer. Keep the first network build simple and version-compatible. Moving servers, updating Paper and adding a proxy in one maintenance window creates several rollback problems at once.

Decide whether all processes share one machine or communicate across a private network. On one trusted host, backends can bind to loopback and use distinct ports such as 30066, 30067 and 30068. Across hosts, use private addresses, firewall rules and, when the network is not already protected, an encrypted tunnel designed for that environment. Reserve the public game port for Velocity. Players should not need any backend address.

List one public Velocity endpoint and every private Paper endpoint.
Choose unique backend ports and stable private addresses before configuration.
Keep the initial change to proxying and forwarding; stage unrelated upgrades later.
Back up each backend and record its current direct connection path for rollback.

Install Velocity in its own service directory

Download the latest stable Velocity JAR from PaperMC's official downloads page and place it in a dedicated proxy directory. Do not put it inside a Paper server folder or reuse a backend startup script. The current Velocity getting-started guide requires at least Java 25, so run java -version through the exact service, container or panel allocation that will launch the proxy. A newer interactive shell does not prove that the managed service uses the same runtime.

Start Velocity once to generate velocity.toml and forwarding.secret, then stop it cleanly with the console end command before editing. Preserve the generated secret and configuration with restrictive file permissions. Do not paste the secret into a ticket, screenshot or repository. If a panel recreates containers, confirm that both files live on persistent storage before building the backends around them.

Review the bind value in velocity.toml. Velocity listens on the configured address and port, commonly the public game listener on port 25565. Publish only that TCP endpoint through the cloud firewall, container mapping or router. Leave query disabled unless it serves a deliberate monitored use. Keep the proxy's online-mode enabled so Velocity authenticates player identities before forwarding them to Paper.

Use PaperMC's stable Velocity download and verify the actual service Java runtime.
Run once, stop cleanly, then edit the generated velocity.toml.
Persist and protect forwarding.secret as a credential.
Expose only the intended Velocity game listener to players.

Register every Paper backend explicitly

Open the servers section of velocity.toml and assign each backend a short unique name plus its private address and port. A same-host example is lobby = "127.0.0.1:30066" and survival = "127.0.0.1:30067". Use the real private hostname or address when a backend runs elsewhere. Do not point a server entry at its public DNS name when that name resolves back to Velocity; the proxy would route toward itself instead of the backend.

Set the try list to the order Velocity should use when a player first joins or is kicked from a server. Put a small, dependable lobby first when the network has one. The list is routing policy, not a health guarantee: start each named backend and verify that its private listener is reachable from the proxy host. A typo or closed port will still fail when Velocity attempts the connection.

Avoid forced hosts until the base address works. They can route different hostnames to different server orders, but they add DNS and certificate-free Minecraft routing assumptions to the first test. Begin with one hostname, one proxy listener and explicit server switching. After the network passes acceptance, add host-specific routes one at a time and document which fallback list each name uses.

Give each backend one unique name and private host:port value.
Put the intended first destination at the start of the try list.
Confirm private reachability from the proxy host before testing with a player.
Add forced-host routing only after the ordinary join path is stable.

Enable modern forwarding on Velocity and Paper

A backend behind Velocity normally has online-mode=false because the proxy performs the public account authentication. That change alone is dangerously incomplete: without forwarding, Paper lacks the player's correct address, UUID and skin, and an exposed offline-mode backend can accept impersonated identities. For supported modern Paper versions, set player-info-forwarding-mode = "modern" in velocity.toml and configure every backend to validate the same forwarding secret.

On each Paper backend, stop the process and set online-mode=false in server.properties. In spigot.yml, keep settings.bungeecord false when using Velocity modern forwarding. In config/paper-global.yml, set proxies.velocity.enabled to true, copy the contents of Velocity's forwarding.secret into proxies.velocity.secret, and set proxies.velocity.online-mode to match the online-mode value in velocity.toml. Restart Paper fully after saving; do not rely on a reload command for identity settings.

Configure one forwarding format across the network. Velocity's current documentation recommends modern forwarding for Minecraft 1.13 and newer and describes legacy BungeeCord forwarding as less secure. If an old server, mod loader or protocol bridge prevents modern forwarding, stop and design that compatibility path from its current primary documentation. Do not mix modern and legacy settings until a connection happens to work.

Velocity: keep online-mode enabled and select modern player forwarding.
Paper server.properties: set online-mode=false only for the protected backend.
Paper global configuration: enable Velocity and use the exact forwarding secret.
spigot.yml: leave BungeeCord forwarding disabled for the modern setup.

Make direct backend connections impossible

Modern forwarding is a second identity check, not a substitute for network isolation. PaperMC strongly recommends a firewall for every proxy setup. Allow the public TCP port to reach Velocity, then allow each Paper port only from the proxy host or private tunnel. Do not publish backend container ports on every host interface, create broad allow rules, or leave an old public allocation active for convenience.

When Velocity and Paper share one trusted physical machine, bind each backend's server-ip to 127.0.0.1 and point velocity.toml at the matching loopback ports. When they run on separate machines, bind to the intended private interface and enforce source-address rules in the operating-system or cloud firewall. Test those rules from both sides: the proxy must reach the backend, while an outside client and an unrelated host must not.

Treat the forwarding secret like a password and the firewall like the perimeter. Run Velocity and Paper as unprivileged service accounts, restrict configuration reads, keep the panel and remote console off the game port, and back up all servers independently. The whitelist guide at /blog/minecraft-java-server-whitelist-guide can add membership control, but a whitelist does not make a directly exposed offline-mode backend safe.

Public access: Velocity's TCP game port only.
Backend access: loopback or private listeners allowed only from the proxy path.
Management access: separate authenticated panel, SSH and console channels.
Negative test: prove that a player cannot join a backend address directly.

Test identity and routing end to end

Start backends first, read each Paper log from the beginning, then start Velocity and inspect its full startup output. Confirm the expected proxy version, public listener and registered server names without configuration or bind errors. Join through the public Velocity address with a normal authenticated account. A successful result is not merely reaching a world: the proxy log and backend log should agree about the route and the backend should receive the expected player identity.

Use /server to view or switch among configured destinations; Velocity grants the basic server command to players by default. Visit every backend, reconnect, restart one backend and repeat the switch. Check UUID-based permissions, whitelist membership, inventories, chat, moderation, proxy-aware plugins and any shared database. If an identity changes between direct staging and proxied production, stop before players create valuable state under the wrong profile.

Run failure tests deliberately. Stop the first server in the try list and verify the documented fallback behavior you actually want. Attempt the public address with the wrong client version, attempt a backend from outside, and rotate through each private port check. Preserve timestamps and complete logs with addresses or secrets redacted. No direct backend access plus stable identity across every switch is the acceptance gate.

Join only through Velocity and verify the same UUID and permissions on every backend.
Switch servers, reconnect and repeat after a clean proxy restart.
Test the try-list fallback with one backend intentionally unavailable.
Confirm outside clients cannot reach any private Paper listener.

Deploy with a proxy rollback plan

Schedule the cutover with all backends stopped or access-controlled, take final consistent backups, and deploy the exact configuration that passed staging. Start Paper backends, then Velocity, run the acceptance route and only then update DNS or advertise the proxy address. Do not run the old direct endpoint and the new proxy path as two writable entrances to the same backend while deciding which one works.

Define rollback triggers before launch: forwarding-secret rejection, changed UUIDs, unreachable required backends, repeated proxy crashes or a firewall rule that cannot prevent direct joins. Stop the proxy path, preserve its logs and restore the former backend online-mode and listener configuration as one tested set. Do not simply flip online-mode while players are connected; identity changes can create separate player records.

After launch, monitor proxy and backend connection errors, update Velocity and Paper through separate staged changes, and test every firewall rule when hosts or private addresses change. Keep the topology, ports, forwarding mode, secret-rotation procedure and recovery order in the operations runbook. More hosting guides are available at /blog. If the network needs separate nodes, private connectivity or predictable support, compare the documented options at /pricing after the single-host design has been measured.

Back up and freeze backends before changing the public entry point.
Start backends before the proxy and run the complete acceptance path.
Roll back identity, listener and firewall settings together.
Retest routing and isolation after every host, address or software change.

Frequently asked questions

Quick answers

What does a Velocity proxy do for a Minecraft server?

It accepts players at one public address, authenticates them and routes them among named backend servers. Each Paper backend remains a separate process, world and private listener.

Should online-mode be true with Velocity?

Keep online-mode enabled in Velocity. Protected Paper backends normally use online-mode=false because the proxy authenticates players, then modern forwarding securely passes their identity.

How do I connect Paper to Velocity securely?

Use modern forwarding, enable Velocity support in paper-global.yml, match the forwarding secret and isolate backend ports with loopback, private networking and firewall rules.

Can players connect directly to a Velocity backend?

They should not. Only the proxy path should reach backend listeners. Prove that the proxy can connect and that an outside client cannot reach any Paper port directly.

Which Java version does Velocity need?

PaperMC's current getting-started guide requires at least Java 25. Verify the live requirement and the Java runtime used by the actual proxy service before installing.