Minecraft server networks

Connect one public Minecraft proxy to private Paper or Spigot backend servers. ServerChirp includes Velocity and Waterfall templates, and this guide covers both on a single managed server.

Plan the network

Create one public proxy and give every backend a different private port:

The 127.0.0.1 bind is labeled Container network in ServerChirp. ServerChirp publishes that port privately on its managed container bridge and gives every managed container the host.docker.internal gateway name.

Do not use localhost or 127.0.0.1 in the proxy's backend list. Those addresses point back to the proxy container itself.

Create the proxy

Open the target server, choose New application, and select Game server. Choose one of the built-in proxy templates:

• Velocity uses modern, secret-backed player forwarding and is the recommended choice for current Paper networks.
• Waterfall uses the BungeeCord configuration format and legacy forwarding for networks that require BungeeCord compatibility.

Configure the primary game port:

• Port: 25565, or another public port players will use.
• Protocol: keep the protocol declared by the selected template.
• Bind address: 0.0.0.0 or a selected public server IP.

Finish creating the application and wait for installation to complete. Start it once so it generates its configuration, then stop it before editing files.

Create the backend servers

Create each Paper or Spigot server as a separate game-server application on the same ServerChirp server.

Give each backend a unique port. During creation, set its bind address to 127.0.0.1. For an existing stopped game server, open Settings → Published ports, edit the game port, and choose 127.0.0.1 as the bind address.

ServerChirp keeps a game server's host and container port matched. If the lobby is assigned 25566, its server.properties must also use 25566.

Velocity network

Velocity modern forwarding signs the player information sent to Paper with a shared secret. Use the same secret on the proxy and every backend.

Configure Velocity

Open the proxy's Files view and edit velocity.toml:

bind = "0.0.0.0:25565"
online-mode = true
player-info-forwarding-mode = "modern"
forwarding-secret-file = "forwarding.secret"

[servers]
lobby = "host.docker.internal:25566"
survival = "host.docker.internal:25567"
try = ["lobby", "survival"]

The built-in Velocity template creates forwarding.secret. Open that file and copy its complete value; every Paper backend needs the same value.

Configure Paper for Velocity

Stop each backend and update its assigned port in server.properties. The proxy performs public authentication, so the backend remains in offline mode.

server-ip=0.0.0.0
server-port=25566
online-mode=false

Keep settings.bungeecord disabled in spigot.yml:

settings:
  bungeecord: false

Then edit config/paper-global.yml. Replace the example secret with the exact contents of the proxy's forwarding.secret file.

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: 'replace-with-forwarding-secret'

Repeat the configuration for every backend, changing only its assigned server-port. Restart each backend after saving the forwarding settings.

Waterfall network

Waterfall uses the BungeeCord configuration format. Its proxy authenticates players and forwards their UUID and address to backends using BungeeCord-compatible forwarding.

Configure Waterfall

Open the proxy's Files view and edit config.yml. Preserve settings generated by the template, but update online_mode, ip_forward, servers, and the listener.

online_mode: true
ip_forward: true

servers:
  lobby:
    motd: '&bLobby'
    address: host.docker.internal:25566
    restricted: false
  survival:
    motd: '&aSurvival'
    address: host.docker.internal:25567
    restricted: false

listeners:
  - host: 0.0.0.0:25565
    query_port: 25565
    query_enabled: false
    motd: '&bMy Server Network'
    tab_list: GLOBAL_PING
    priorities:
      - lobby
      - survival
    force_default_server: true
    bind_local_address: true
    max_players: 200

If the proxy uses a public port other than 25565, use that port in listeners[].host and query_port when query support is enabled.

Configure Paper or Spigot for Waterfall

Stop each backend and update server.properties:

server-ip=0.0.0.0
server-port=25566
online-mode=false

Enable BungeeCord forwarding in spigot.yml:

settings:
  bungeecord: true

Repeat the configuration for each backend, changing only its assigned port and server-specific settings. Restart the proxy and backends after changing forwarding settings.

Legacy BungeeCord forwarding is not an access-control boundary. The private ServerChirp port binding is what prevents clients from bypassing the proxy and impersonating another player.

Start and verify the network

Start the backend servers first, then start the proxy. Watch each application's shared console until it reports ready.

Point the Minecraft hostname's DNS record at the ServerChirp server's public IP. Players connect only to the proxy address. They should never use a backend port directly.

Verify the setup:

1. Join through the public proxy address.
2. Confirm that the initial server is the first configured lobby or fallback.
3. Transfer to survival and confirm that the connection succeeds.
4. Check a backend log or plugin to confirm that the player's real UUID and address were forwarded.
5. Try the backend's public IP and private port from another machine; the connection should fail.

Networks across multiple servers

The container-network bind works only when the proxy and backends are on the same ServerChirp server. For backends on other machines, use a private network or VPN and firewall each backend port so only the proxy machine can reach it. Put those private addresses in the proxy configuration instead of host.docker.internal.

Never expose an offline-mode backend to the public internet.

Troubleshooting

The proxy reports Connection refused

Confirm that the backend is running, its assigned port matches server.properties, and the proxy uses host.docker.internal:<backend-port>. Do not use localhost between separate ServerChirp applications.

Velocity rejects a backend connection

Confirm that player-info-forwarding-mode is modern, Velocity and Paper contain the same forwarding secret, and Velocity support is enabled in paper-global.yml. Remove accidental whitespace when copying the secret.

Waterfall reports that a backend is in online mode

Set online-mode=false in that backend's server.properties, save the file, and restart the backend.

Players have the proxy address or the wrong UUID

For Velocity, verify the modern-forwarding settings and shared secret. For Waterfall, confirm ip_forward: true in config.yml and settings.bungeecord: true in every backend.

Players can connect directly to a backend

Stop the backend and change its published game port bind address to 127.0.0.1. A 0.0.0.0 bind creates a public raw port and must not be used for an offline-mode backend.

Upstream references

• Velocity configuration
• Velocity player-information forwarding
• BungeeCord configuration guide
• BungeeCord IP forwarding