Installation

Installation

You need the same proxyforward.exe on both machines — the public one (gateway) and the one running Minecraft (agent). One binary, two roles; the role is chosen on first run.

Requirements

• Windows 10 or 11, x64. There is no Linux or macOS build that runs — see below.
• WebView2 runtime, for the GUI. It ships with Windows 11 and current Windows 10; if the window never appears, install the Evergreen runtime and see Troubleshooting.
• Administrator rights once, if you want the firewall rule added for you.

There are three ways to get the binary.

Option A — a published release

Nothing is published yet. No tag has been cut, so https://github.com/xeri/proxyforward/releases/latest currently 404s. When the first release lands, this is what it will contain. Until then use option B or C.

Each release carries:

Asset	What it is
proxyforward-<version>-windows-amd64-installer.exe	NSIS installer
proxyforward-<version>-windows-amd64.exe	portable exe — run it anywhere
SHA256SUMS.txt	checksums for both
proxyforward-<version>-sbom.spdx.json	SPDX software bill of materials

The binaries are not code-signed, so SmartScreen will say "unknown publisher" on first run. Rather than asking you to click through that on faith, every release is built by the release workflow and carries a provenance attestation you can verify yourself:

gh attestation verify proxyforward-<version>-windows-amd64.exe -R xeri/proxyforward

That proves the exe was produced by that workflow, from this repo, at that commit.

Option B — a development build from CI

Every push to master builds a Windows exe and uploads it as a workflow artifact. This is the easiest way to get a current binary today.

1. Open the CI workflow runs.
2. Click the most recent green run on master.
3. Download the proxyforward-windows-amd64-<sha> artifact and unzip it.

Two caveats:

• GitHub requires you to be signed in to download workflow artifacts. There is no anonymous download link.
• Artifacts are kept 14 days, then deleted.

These builds are unsigned and un-attested. They are development builds — treat them as such.

Option C — build from source

git clone https://github.com/xeri/proxyforward
cd proxyforward

cd frontend && npm ci && npm run build && cd ..   # MUST come first — see below
wails build                                       # → build/bin/proxyforward.exe

You need Go 1.25+, Node.js and the Wails v2 CLI (go install github.com/wailsapp/wails/v2/cmd/wails@latest).

The frontend must be built before any Go command. main.go embeds frontend/dist with go:embed, and frontend/dist is gitignored. A go:embed that matches zero files is a compile error, so on a fresh clone go build, go vet and go test all fail until you have run npm run build once. This trips up everyone exactly once.

To stamp a version into the binary:

wails build -ldflags "-X proxyforward/internal/version.Version=v0.1.0"
build/bin/proxyforward.exe --version

More build and test commands are in Contributing.

What gets written to disk

proxyforward keeps everything in one directory:

%APPDATA%\proxyforward\
├── config.toml        your settings (see Configuration)
├── gateway.crt/.key   gateway role only, generated on first start, mode 0600
├── analytics.db       local SQLite stats (see Analytics and Privacy)
├── avatars\           cached player heads
└── logs\
    ├── proxyforward.log   rotating, 10 MiB × 3 files kept
    ├── crash.log          startup failures land here — the GUI has no stderr
    └── wails.log

Running as a Windows service moves this to %ProgramData%\proxyforward\ — see Windows Service.

The portable exe writes nothing next to itself, so you can keep it on a USB stick; uninstalling means deleting the exe and, if you want your data gone, that directory.

About the Linux and macOS artifacts

CI also produces EXPERIMENTAL-linux-amd64-<sha> and EXPERIMENTAL-macos-universal-<sha> artifacts. They are named that way for a reason: they compile, but they do not run. The engine must serve a Windows named pipe to own its config and ports, and the IPC layer returns "unsupported" on every other platform — so the window opens and the engine immediately dies. They exist only to prove the tree still compiles off-Windows. Don't hand them to anyone. See Not Yet Implemented.

---

Next: Quick Start — pair the two machines and get players connecting.