> ## Documentation Index
> Fetch the complete documentation index at: https://help.freakhosting.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Velocity Proxy Setup: Link Minecraft Servers into a Network

> Velocity proxy setup step by step: install Velocity with Version Changer, turn on modern forwarding, add your Paper backends and keep the secret safe.

To set up a Velocity proxy on FREAKHOSTING, install **Velocity** on one server with **Version Changer**, set `player-info-forwarding-mode = "modern"` and list your backend servers in `velocity.toml`. Then, on every Paper backend, switch on **Allow cracked players** and enable Velocity in `config/paper-global.yml` with the secret from `forwarding.secret`. Players join with the proxy's address and move between servers with `/server`.

| Difficulty | Time | Servers you need | Panel pages |
| - | - | - | - |
| Advanced | 30 minutes | 1 proxy + 1 per backend | **Version Changer**, **Server Properties**, **Files** |

***

## How does a proxy network work?

| Part | What it is | How many |
| - | - | - |
| **Proxy** | Velocity. Players connect here and it passes them to a backend. | 1 server |
| **Backends** | Normal Paper servers, for example `lobby` and `survival`. | 1 server each |

Each part is its own FREAKHOSTING Minecraft server. For a lobby and a survival world you need three servers. The proxy itself needs little memory.

> [!NOTE]
>
> **BungeeCord** and **Waterfall** are also in **Version Changer**, but Waterfall is marked **DEPRECATED** and BungeeCord's forwarding is less secure. Use Velocity for new networks. If you must use BungeeCord, set `ip_forward: true` in its `config.yml` and `settings.bungeecord: true` in each backend's `spigot.yml`.

***

## Step 1: Install Velocity on the proxy server

**1. Open Version Changer**

On the server you want as the proxy, click **Version Changer**, then **Velocity**.

**2. Install**

Pick the newest version and click **Change Version**. Switch on **Delete Server Files** if this server had a game world on it before.

**3. Start once**

Start the server so Velocity creates `velocity.toml` and `forwarding.secret`, then stop it.

***

## Step 2: Configure velocity.toml

Open `velocity.toml` in **Files** on the proxy server.

**1. Check the bind port**

Make sure `bind` uses the port of this server as shown on its **Console** page (the **Copy address** card), for example `bind = "0.0.0.0:25565"`.

**2. Turn on modern forwarding**

```toml theme={null}
online-mode = true
player-info-forwarding-mode = "modern"
```

Modern forwarding passes each player's real name, UUID and skin to the backends. Velocity keeps the shared secret in `forwarding.secret`.

**3. List your backends**

In `[servers]`, add each backend with its address from the panel, and set the order players try them:

```toml theme={null}
[servers]
lobby = "203.0.113.10:25566"
survival = "203.0.113.20:25567"

try = [
  "lobby"
]
```

Delete the example servers Velocity adds by default, and remove or edit the `[forced-hosts]` entries that point to them.

**4. Copy the secret**

Open `forwarding.secret` and copy its content. You need it on every backend.

> [!WARNING]
>
> Treat `forwarding.secret` like a password. Anyone who has it can pretend to be any player on your backends.

***

## Step 3: Set up each Paper backend

**1. Turn off online mode**

Click **Server Properties**, switch on **Allow cracked players** and click **Save**. The proxy checks accounts, so the backend mustn't check them again.

**2. Enable Velocity support**

Stop the server. In **Files**, open `config/paper-global.yml` and set:

```yaml theme={null}
proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: 'paste-your-forwarding-secret-here'
```

`online-mode` here must match `online-mode` in `velocity.toml`.

**3. Check spigot.yml**

In `spigot.yml`, make sure `settings.bungeecord` is `false`. That setting is only for BungeeCord.

**4. Start everything**

Start each backend, then start the proxy.

With modern forwarding on, a backend refuses players who try to connect directly. Players always use the proxy's address.

***

## Step 4: Join and switch servers

| Command | What it does |
| - | - |
| `/server` | Lists the servers on the network. |
| `/server survival` | Moves you to the `survival` server. |
| `/glist` | Shows players on every server (needs permission). |

Velocity runs its own plugins. On the proxy server, filter the **Plugins** page by the **Velocity** loader.

***

## Which address and port goes where?

| Where | What to enter |
| - | - |
| Players' **Server Address** | The proxy server's address from its **Console** page, for example `203.0.113.10:25565`. |
| `velocity.toml` `bind` | `0.0.0.0` with the proxy server's own port. |
| `velocity.toml` `[servers]` | Each backend's full address and port from its own **Console** page. |
| Backends | Nothing to change in `server.properties` except **Allow cracked players**. |

***

## Frequently asked questions

### Velocity or BungeeCord: which should I use?

Velocity. It is actively developed and its modern forwarding is secure. BungeeCord still works but uses older forwarding, and Waterfall is deprecated.

### Why do players get "Unable to connect you to lobby"?

The proxy can't reach the backend. Check the address and port in `[servers]`, that the backend is running, and that the backend name is in `try`.

### What does "Unable to verify player details" mean?

The secret in `paper-global.yml` doesn't match `forwarding.secret`, or `proxies.velocity.enabled` is off. Copy the secret again and restart the backend.

### Does modern forwarding work with old Minecraft versions?

No. Modern forwarding needs Minecraft 1.13 or newer on the backends. Older backends need legacy (BungeeCord-style) forwarding.

### Can I run Fabric backends behind Velocity?

Yes, with a mod that adds Velocity forwarding on the backend. Paper backends are the simplest setup.

***

## Related guides

> **[Minecraft server guide](https://help.freakhosting.com/games/minecraft/minecraft-server-hosting-guide.md)**
>
> Every Minecraft guide in one place.

> **[Change your server version](https://help.freakhosting.com/games/minecraft/changing-your-minecraft-server-version.md)**
>
> How Version Changer works.

> **[Allow cracked players](https://help.freakhosting.com/games/minecraft/how-to-allow-non-premium-players-to-join-your-minecraft-server.md)**
>
> What online mode does.

> **[ViaVersion](https://help.freakhosting.com/games/minecraft/allow-older-clients-to-join-viaversion.md)**
>
> Let several game versions join the network.

> **[spigot.yml settings](https://help.freakhosting.com/games/minecraft/optimizing-spigotyml.md)**
>
> Where the bungeecord setting lives.

> [!NOTE]
>
> **Checked against the official [Velocity documentation](https://docs.papermc.io/velocity/player-information-forwarding/)** on 29 October 2026, and the Version Changer steps tested on our Game Panel (Minecraft 26.1, Paper and Fabric). Steps may differ slightly if Velocity or Paper change.

***

> [!NOTE]
>
> ### Need Extra Help?
>
> If you encounter any issues, our support team is ready to assist:
>
> * **Live Chat:** Quick assistance via our website.
> * **Support Ticket:** [Open a Ticket](https://freakhosting.com/clientarea/submitticket.php)
> * **Discord:** [Join our Community](https://discord.gg/freakhosting)
> * **Email:** [support@freakhosting.com](mailto:support@freakhosting.com)

> [!TIP]
>
> ### Save on Your Hosting
>
> Ready to upgrade your hosting? Use code **KB20** at checkout for **20% off** your first order!

***

**Last Updated:** October 2026


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.