Install on a Velocity network

This guide covers Velocity with Paper backends. For a modded backend, configure its forwarding support using the Velocity compatibility guide.

Before you start

You need access to the proxy and every backend. Players must connect through the proxy. Backend ports must accept connections only from trusted sources.

Modern forwarding requires compatible Minecraft versions and backends. Read the official forwarding instructions before you choose a different mode.

Configure modern forwarding

1. Stop the proxy and backends.
2. Set player-info-forwarding-mode to modern in velocity.toml.
3. Read the proxy's forwarding.secret file.
4. Configure each Paper backend with that same secret.

player-info-forwarding-mode = "modern"

online-mode=false

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: "YOUR_FORWARDING_SECRET"

Set proxies.velocity.online-mode to the proxy's online-mode value. The true value above assumes an authenticated proxy. Keep settings.bungeecord disabled in spigot.yml for modern forwarding.

Paper 1.18.2 and older use settings.velocity-support in paper.yml. Use the platform guide for those releases.

Install SkinsRestorer

1. Put the server/proxy SkinsRestorer JAR in the proxy's plugins folder.
2. Put the same release in every Bukkit backend's plugins folder.
3. Start the backends and proxy.
4. Read all startup logs for forwarding or SkinsRestorer errors.

For Fabric or NeoForge backends, install the matching mod artifact instead of a Bukkit JAR.

Leave server.proxyMode.detection: AUTO on the backends unless detection fails. Correct forwarding normally lets SkinsRestorer detect the proxy.

Check

Complete the first skin and server-switch check. Skin commands use proxy permissions, so grant access on the proxy.

The default file storage is enough for ordinary proxy-managed skins. A backend plugin that calls the API needs shared MySQL or PostgreSQL storage.

If it fails

An invalid forwarding secret is a connection problem. Fix it before you change skin configuration. For backend mode warnings or commands that work on one server only, use proxy troubleshooting.