Quick Start

Quick Start

Goal: players type your-host:25565 into Minecraft and land on the server sitting behind your NAT. This takes about five minutes.

Before you begin you need two machines with proxyforward installed:

• Server B — the gateway. Publicly reachable, or at least able to port-forward. A cheap VPS is ideal.
• Server A — the agent. The machine running Minecraft. It needs no inbound access at all; it only dials out.

---

1. On the gateway (Server B)

1. Launch proxyforward.exe. On first run the wizard asks which role this machine plays — choose "This faces the internet."

2. Enter the public hostname players will use. A stable DNS or DDNS name is strongly recommended over a bare IP — see Networking and Firewall for why a changing IP breaks already-connected players in a way nothing server-side can fix.

3. Click Start gateway. On first start it generates its certificate and auth token.

4. Copy the pairing code. It looks like this:

   pf1://mc.example.com:8474/3f9a…c1/#sha256:9b1e…7d
   

   That single string carries the gateway's address, the auth token, and the SHA-256 fingerprint of its certificate. Treat it like a password — anyone holding it can register tunnels on your gateway. Send it to yourself over something private.

5. Open the ports. The gateway needs two inbound TCP ports:

   • 8474 — the control port the agent dials.
   • 25565 — the port players connect to.

   Forward both on the router, and allow the Windows firewall rule (Settings → System → Firewall rule → Add rule, one UAC prompt). Full detail, including what to do when your gateway is a VPS with a cloud firewall, is in Networking and Firewall.

2. On the agent (Server A)

1. Launch proxyforward.exe and choose "This hosts Minecraft."
2. Paste the pairing code. It validates as you type — you should see the certificate fingerprint pinned before you go any further.
3. Confirm the local address of your Minecraft server (127.0.0.1:25565 unless you moved it) and the public port players will use (25565).
4. Click Connect.

The dashboard turns green when the tunnel is up. Players now join at your-host:25565.

3. Prove it works

Don't wait for a player to tell you it's broken. On the agent, go to Tunnels → Test player path (or Overview → Test public reachability). This walks the whole chain the way a real player does — DNS, router, firewall, gateway, tunnel, and finally your Minecraft server — and tells you which hop failed rather than just "it didn't work".

If it fails, go to Troubleshooting.

---

The same thing from the command line

Useful for a headless gateway on a VPS, or for scripting. Full flag list: CLI Reference.

Gateway:

proxyforward gateway

First run generates the token and certificate, writes config.toml, and starts serving. Set your public hostname first so pairing codes carry it:

# %APPDATA%\proxyforward\config.toml
role = "gateway"

[gateway]
public_host = "mc.example.com"

⚠️ Known wart: the pairing code printed in the console log at startup always contains the literal placeholder YOUR-PUBLIC-ADDRESS, even when public_host is set. Only the GUI substitutes the real hostname. From the console, replace that placeholder by hand — the token and fingerprint in the code are correct, only the host is a stand-in.

Agent:

proxyforward pair "pf1://mc.example.com:8474/3f9a…c1/#sha256:9b1e…7d"
proxyforward agent

pair only writes the config — it validates the code, stores the gateway address, token and pinned fingerprint, and creates a default Minecraft tunnel (127.0.0.1:25565 → public 25565) if you don't already have one. It starts nothing. proxyforward agent then runs the engine.

Override the defaults if your server isn't in the usual place:

proxyforward pair "<code>" --local 192.168.1.50:25565 --public-port 25566

---

What happens after that

• The agent holds one outbound TLS connection to the gateway and keeps it alive with a heartbeat. If it drops — flaky Wi-Fi, gateway reboot, laptop waking from sleep — it reconnects on its own with exponential backoff, and short-circuits that backoff the moment Windows reports the network came back.
• The gateway address is re-resolved on every attempt, so a gateway on a dynamic IP just works.
• You do not need to re-pair after a restart, a reboot, or an IP change. You only re-pair if the gateway's token or certificate is regenerated.

Next: Tunnels to expose more than one server or get real player IPs, or Windows Service to keep it running without anyone logged in.