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

# Set up a Velocity proxy

> Connect multiple Purpify Minecraft Java servers through a Velocity proxy, including same-node routing with a server UUID.

Velocity lets players join multiple Minecraft Java backend servers through one proxy address. Run Velocity as its own Purpify server, then add each lobby, survival, minigame, or other backend to `velocity.toml`.

## Before you begin

You need:

* One Purpify server running Velocity
* At least one separate Minecraft Java backend server
* The address or server UUID and port for every backend
* File access to the proxy and backend servers
* A backup of every existing backend

<Warning>
  Players should connect through the Velocity proxy, not directly to a backend server. Configure player information forwarding before opening the network to players.
</Warning>

## Install Velocity

<Steps>
  <Step title="Create the proxy server">
    Create a separate server in the Purpify panel. Open **Versions** and select Velocity.
  </Step>

  <Step title="Start Velocity once">
    Start the proxy and wait for startup to complete. This creates `velocity.toml` and `forwarding.secret`.
  </Step>

  <Step title="Stop the proxy">
    Stop Velocity normally before editing its configuration.
  </Step>
</Steps>

## Find a backend address

<Tabs>
  <Tab title="Same Purpify node">
    When the Velocity proxy and backend server are on the same node, use the backend server UUID as its hostname.

    <Steps>
      <Step title="Open the backend server">
        Select the Minecraft backend server in the Purpify panel.
      </Step>

      <Step title="Open Settings">
        Go to **Settings** and copy the server UUID.
      </Step>

      <Step title="Copy the backend port">
        Copy the port assigned to the backend server.
      </Step>
    </Steps>

    Use the UUID and port together in `velocity.toml`:

    ```toml Same-node backend theme={"dark"}
    [servers]
    lobby = "your-server-uuid:25565"
    ```

    Replace `your-server-uuid` and `25565` with the backend server's values.
  </Tab>

  <Tab title="Different node">
    Use the backend server address and port shown in its Purpify server management view.

    ```toml Different-node backend theme={"dark"}
    [servers]
    lobby = "backend-address:25565"
    ```
  </Tab>
</Tabs>

<Info>
  For servers on the same node, do not use `127.0.0.1`. Use the backend server UUID from **Settings**.
</Info>

## Add backend servers

Open `velocity.toml` on the proxy and find `[servers]`. Give every backend a unique name and enter its connection value.

```toml velocity.toml theme={"dark"}
[servers]
lobby = "lobby-server-uuid:25565"
survival = "survival-server-uuid:25566"

try = [
  "lobby"
]
```

The `try` list controls which backend Velocity attempts first when a player joins the proxy.

## Configure modern forwarding

Modern forwarding passes player UUIDs, skins, and other connection information from Velocity to compatible backend software.

<Steps>
  <Step title="Configure Velocity">
    In `velocity.toml`, keep the proxy in online mode and set the forwarding mode to `modern`.

    ```toml velocity.toml theme={"dark"}
    online-mode = true
    player-info-forwarding-mode = "modern"
    ```
  </Step>

  <Step title="Copy the forwarding secret">
    Open `forwarding.secret` on the Velocity server and copy its complete value.
  </Step>

  <Step title="Prepare the Paper backend">
    Stop the backend. In `server.properties`, set `online-mode=false`. Then open `config/paper-global.yml` and enable Velocity forwarding.

    ```yaml paper-global.yml theme={"dark"}
    proxies:
      velocity:
        enabled: true
        online-mode: true
        secret: "paste-the-forwarding-secret-here"
    ```
  </Step>

  <Step title="Repeat for every backend">
    Configure the same forwarding secret on each Paper backend connected to this proxy.
  </Step>
</Steps>

<Warning>
  Never share `forwarding.secret`. A backend in offline mode must be protected by the proxy configuration and forwarding secret.
</Warning>

## Start and test the network

1. Start every backend server and wait until each one is running.
2. Start the Velocity proxy.
3. Check the Velocity console for backend or forwarding errors.
4. Connect to the public address and port of the Velocity proxy.
5. Confirm that you arrive on the first available server in `try`.

## Troubleshoot Velocity

<AccordionGroup>
  <Accordion title="Velocity cannot connect to a backend">
    Confirm that the backend is running and that its UUID or address and port exactly match the entry in `velocity.toml`. For a same-node backend, recopy the server UUID from **Settings**.
  </Accordion>

  <Accordion title="The UUID address does not work">
    Confirm that the proxy and backend are on the same Purpify node. Use the public backend address when they are on different nodes.
  </Accordion>

  <Accordion title="Player information forwarding failed">
    Confirm that the proxy uses `player-info-forwarding-mode = "modern"`, the Paper backend has Velocity forwarding enabled, and both servers use the exact same secret.
  </Accordion>

  <Accordion title="Players reach the wrong server">
    Check the order and spelling of the backend names in the `try` list. Every name must match a key in `[servers]`.
  </Accordion>

  <Accordion title="Players can join a backend directly">
    Do not share backend addresses with players. Review the forwarding and server-security configuration before using the network publicly.
  </Accordion>
</AccordionGroup>

For more configuration details, read the [official Velocity getting started guide](https://docs.papermc.io/velocity/getting-started/) and [player information forwarding guide](https://docs.papermc.io/velocity/player-information-forwarding/).