Installation

Installation

Portal is a single Go binary. You can either grab a prebuilt release or build it from source.

From Releases

1. Download the latest binary for your platform from the Releases page.
2. Place it in a directory of your choice.
3. Run it from the command line.

Linux/macOS: run chmod +x portal first to make the binary executable.

From Source

Requires Go 1.24+.

git clone https://github.com/MEMOxiiii/portal.git
cd portal
go build -o portal ./examples/main.go

First run

On first run, Portal generates a config.json file next to the binary with sane defaults (see Configuration). Edit it to set:

• network.address — the port players connect to
• network.communication.address and network.communication.secret — the socket API your backend servers connect to (see Socket Protocol)

Then start Portal again to pick up the changes.

Players connect over NetherNet by default (network.transport: "nethernet") — if this is anything other than a localhost test, read NetherNet Transport before going further, particularly the firewall and STUN/TURN sections. Set network.transport to "raknet" instead if you need the classic UDP transport.

Upgrading an existing deployment

If you're upgrading a Portal binary that predates NetherNet support, check your existing config.json before restarting. Its "transport" key doesn't exist yet on an old config file, and Portal fills in missing keys with current defaults — which now means the player listener silently switches from RakNet to NetherNet on next start, with no warning, unless you explicitly add "transport": "raknet" (under "network") to keep the old behavior. See NetherNet Transport before deciding either way; NetherNet needs a UDP port opened (see its firewall section) that a RakNet-only deployment never required.

Connecting a backend server

Portal by itself only proxies players — you also need at least one backend server running a Portal client library so it can register itself and accept transfers. See Client Libraries for the available options (PocketMine-MP, Dragonfly, GeyserMC), or Socket Protocol if you're integrating custom server software directly.

Embedding Portal as a library

Portal can also be used directly as a Go library instead of running the prebuilt binary — see Library Usage for the full portal.Options/portal.New API, a minimal working example, and how the socket server, health checker, clustering, and metrics pieces plug in around it.