# How to run a Velocity proxy in front of several servers

> One address for players, several servers behind it: create the Velocity server, point it at your backends, turn on modern forwarding, and keep the backends closed to direct joins.

Source: https://fadehost.com/docs/velocity-proxy/

A proxy gives your players one address and moves them between servers with a command: a survival world, a creative world, a minigame, each its own server on your pool. Velocity is the proxy to use on current versions (Waterfall is in the catalog for old BungeeCord setups, but its authors point new networks at Velocity too). Every server here is a slot on the same subscription, so a network of three servers and a proxy is four slots, not four plans.

## What you need

- The proxy: a server created with the **Velocity** software. 1 GB is plenty; it forwards packets, it does not run a world.
- The backends: your existing servers, on Paper, Purpur, Spigot, Fabric or Forge. Each keeps its own RAM and its own address.
- Five minutes with the Files tab, because the proxy and each backend share one secret.

## 1. Create the proxy

**Servers**, **Create server**, pick **Minecraft: Java Edition** and the **Velocity** software, give it 1 GB, and start it once so it writes its files. Its address is the one you will give players.

## 2. Tell the proxy about the backends

Open the proxy's **Files** tab and edit `velocity.toml`. In the `[servers]` block, list each backend under a name, using the address and port shown on that backend's page:

```toml
[servers]
lobby = "alpha.fadehost.net:26010"
survival = "alpha.fadehost.net:26011"
creative = "alpha.fadehost.net:26012"

try = ["lobby"]
```

`try` is where a player lands first. Backends on your private network also resolve by their `srv-` name from the proxy, but the public address and port always work, so start with those.

Further up in the same file set the forwarding mode:

```toml
player-info-forwarding-mode = "modern"
```

The proxy writes a `forwarding.secret` file next to `velocity.toml` on its first start. Open it in the Files tab and copy the string; every backend needs it.

## 3. Prepare each backend

On a Paper, Purpur or Spigot backend, edit `config/paper-global.yml` under **Files**:

```yaml
proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: "the string from forwarding.secret"
```

Then set the backend's **Online mode** off under **Settings**, **Server**: the proxy does the Mojang check for the whole network, and a backend behind a proxy has to trust what the proxy forwards. Paper with Velocity forwarding enabled refuses a player who tries to join the backend directly, so switching online mode off here does not open the server to anyone with its address.

On Fabric or Forge backends the same job is done by a mod (FabricProxy-Lite, or Proxy Compatible Forge), with the secret in that mod's config. Drop it into `mods/` and restart.

Restart each backend after the edit; the panel regenerates `server.properties` on every boot from your settings, so the online mode switch belongs in the panel, not in the file.

## 4. Move players around

Velocity's `/server survival` command switches a player; give your lobby a plugin that runs it from a sign or a compass, or install a hub plugin on the proxy. Proxy plugins go into the proxy's `plugins/` folder like any other; see [Install plugins](/docs/install-plugins/).

## What to expect

- Players connect to the proxy's address only. Point your domain at it with an SRV record, see [Custom domains](/docs/custom-domains/).
- The player list, the whitelist and bans live on the backends; a whitelist on the proxy (`velocity.toml`, or a plugin) is the simpler way to keep a private network private.
- Backups run per server. Back up the proxy too: its `velocity.toml`, the secret and its plugins are the whole network layout.
- Sleeping: a backend that hibernates wakes when the proxy connects a player to it, the same way a direct join wakes it. The proxy itself should stay always on, which is what the 1 GB slot is for.

## Troubleshooting

- **"You must connect through a proxy" or "Unable to verify player details"**: the secret differs between the proxy and that backend, or forwarding is not enabled on the backend. Compare the two files character for character.
- **Players see their own skin missing or the wrong UUID**: forwarding mode is `legacy` or `none` on the proxy while the backend expects modern. Use `modern` on both sides.
- **The proxy connects but the backend kicks with "IP forwarding"**: the backend still has online mode on in the panel. Switch it off and restart the backend.
- **A backend is asleep**: the first player through the proxy waits while it wakes; the console on that backend shows the boot.