Tunnels

Tunnels

A tunnel maps a port on the gateway to a server on your side:

players → gateway:public_port  ══tunnel══>  agent → local_addr

Tunnels are configured on the agent, not the gateway. The gateway has no tunnel list of its own — the agent tells it what to listen on, and the gateway decides whether to allow it. That's why you never touch the gateway again after pairing.

Manage them in the GUI at Tunnels (Ctrl+5), or by editing config.toml.

Fields

Field	Meaning
Name	Cosmetic. Shows up in the UI and the logs.
Protocol	TCP. It's the only choice, and the only one that works — see below.
Local address	Where your server actually listens: 127.0.0.1:25565. This never leaves the agent — the gateway is never told your internal address.
Public port	Where players connect on the gateway: 25565.
Enabled	Off = the gateway stops listening on that port.

Rules the config enforces:

• Two enabled tunnels may not claim the same public port.
• The gateway may restrict which ports you're allowed to ask for (gateway.port_allowlist — empty means any).

Multiple servers

Add one tunnel per server, each with its own public port:

Name	Local address	Public port
Survival	127.0.0.1:25565	25565
Creative	127.0.0.1:25566	25566

Both ride the same outbound connection to the gateway — you don't pay for a second link. Remember to open each public port on the gateway (Networking and Firewall).

Options

Under Advanced in the tunnel editor. All are off by default.

PROXY protocol v2 — real player IPs

Without this, every player appears to your Minecraft server as coming from the tunnel, so bans, per-IP limits and logs are all useless. Turn it on and the agent prepends a PROXY-protocol v2 header when it dials your server, carrying the player's true IP.

You must enable it on the Minecraft side too. For Paper, in paper-global.yml:

proxies:
  proxy-protocol: true

⚠️ Mutually exclusive with BungeeCord/Velocity IP forwarding on the same server. Turning on both makes the server try to read the player's address twice and produces confusing ghost errors. Pick one. If you already run Velocity or Bungee and it already sees real IPs, leave PROXY protocol off.

Minecraft-aware

Lets proxyforward attribute connections to player names — that's what fills in the Players screen and the head avatars.

Be precise about what this is: it is passive sniffing of the login handshake as it passes through the tunnel. proxyforward reads the username the client announces; it does not talk to your server, and it does not change the traffic.

The tunnel editor's hint currently claims this "polls the server for MOTD, player count and version". It does not — no such polling exists. See Not Yet Implemented.

On an online-mode server, the sniffed name is authenticated by Mojang, so it's trustworthy. On an offline-mode ("cracked") server, a client can claim any name it likes — the Players screen is then only as trustworthy as your server is. Consider also turning off analytics.mojang_lookups, since resolving unauthenticated names against Mojang is meaningless. See Analytics and Privacy.

Offline MOTD ⚠️

Does nothing. The field is stored and even sent to the gateway, but no responder is wired up: when the agent or your server is down, the gateway simply closes the connection. Players see a normal "can't connect", not a custom message. See Not Yet Implemented.

Bandwidth cap ⚠️

Does nothing. No rate limiter exists anywhere in the code. Setting a value has no effect on throughput. See Not Yet Implemented.

TCP only

The protocol dropdown offers only TCP, and that's the truth of it: there is no UDP support. The config parser will accept type = "udp" if you hand-edit the file, but the gateway rejects the tunnel outright, so it will simply never come up.

For Java Edition this is a non-issue — Minecraft Java is TCP. Bedrock Edition is UDP and is not supported.

When a port won't bind

If the gateway can't take the public port, it tells you who has it:

Port 25565 is in use by java.exe (PID 1234)

Usually that means you pointed a gateway at a machine that's already running Minecraft on the same port. Change the public port, or move the gateway.

Restarting an agent is safe: the gateway closes the old listener and waits for it to fully release the port before rebinding, so a reconnect never races its own dying listener.

Testing

Tunnels → Test player path walks the whole chain exactly as a player would — DNS, router, gateway, tunnel, your server — and names the hop that failed. Use it instead of guessing.