Setup

Setup

A complete, from-zero walkthrough: get Portal running, connect one backend server to it, and have a player actually join through it. Every step links out to a deeper page for anyone who wants the full detail — this page stays deliberately simple.

What you'll end up with

Player ──▶ Portal (:19132) ──▶ your backend server

One proxy, one backend server registered with it, players joining through the proxy instead of the backend directly. Adding more backend servers and enabling transfers between them is step 5, once this base is working.

Prerequisites

• A Bedrock server you already have working on its own (any platform — see Client Libraries for which ones have a ready-made integration).
• Go 1.24+, only if building Portal from source instead of downloading a release.

Step 1 — Get Portal running

Download a release from the Releases page, or build from source:

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

Run it once:

./portal

It creates a config.json next to the binary and starts listening. Stop it (Ctrl+C) — you need to edit that file before it's actually useful.

Step 2 — Set a socket secret

Open config.json and set network.communication.secret to a real value (anything long and random):

"communication": {
  "address": ":19131",
  "secret": "change-me-to-something-real"
}

This is the password your backend server(s) use to authenticate with Portal — don't leave it empty, and don't reuse it anywhere else. Full field reference: Configuration.

Leave network.address (:19132, where players connect) as it is for now.

NetherNet vs RakNet

network.transport controls what players connect over — "nethernet" is the default. If you'd rather use the classic RakNet transport instead (no firewall/STUN setup needed for a LAN-only or already-working setup), set:

"network": {
  "transport": "raknet"
}

With "raknet", network.nethernet.* is ignored entirely and Portal behaves exactly like a traditional Bedrock proxy. Sticking with "nethernet" (the default) is recommended for anything reachable from outside the machine Portal runs on, but read NetherNet Transport first — it needs a firewall rule and usually a STUN server to actually work outside localhost.

Start Portal again so it picks up the secret (and transport choice, if you changed it).

Step 3 — Connect a backend server

This is the one step that's different per platform — pick yours, then follow that library's own documentation for the exact setup (it'll ask for the same four things: Portal's address, Portal's socket port, the shared secret from Step 2, and this server's own address):

• Dragonfly → PortalDF — see its own Wiki for the full setup and configuration reference.
• PocketMine-MP → PortalPM — drop into plugins/ and configure.
• GeyserMC → Portal-GeyserMC — drop into Geyser's extensions/ and configure.
• Anything else → implement Socket Protocol directly, using one of the libraries above as a reference implementation.

The one value worth calling out here, since it trips people up regardless of platform: the address you give the backend library is this server's own listening address, not Portal's — e.g. "127.0.0.1:19132" if it's on a different port than Portal, or a different machine's address entirely. If the backend also runs NetherNet, see Backend Transports for how that address's format changes.

Start (or restart) the backend server. Portal's own log should show it authenticate and register:

socket connection "Hub1" successfully authenticated
socket connection "Hub1" has registered itself as a server with the address "..."

If you don't see this, the backend and Portal disagree on the address/port or the secret — double check Step 2 and Step 3 match exactly.

Step 4 — Join

Add Portal's address (not the backend's) as a server in Minecraft and connect. You should land on your backend server, through Portal.

If nothing happens when you try to connect — especially from a phone or any device other than the one Portal is running on — this is almost always a firewall/NAT issue specific to NetherNet (the default transport). Read NetherNet Transport's firewall and STUN/TURN sections before anything else; Troubleshooting has the exact error messages if you're seeing something in the log.

Step 5 — Add a second backend (optional, but this is the whole point of Portal)

Repeat Step 3 for a second backend server with a different ServerName (e.g. "Hub2") and its own ServerAddress. Once it's registered too, players can move between the two without reconnecting — via a TransferRequest sent over the socket protocol (each client library exposes this as a normal function call; see its own docs), or manually for testing via the Admin Console:

transfer <player> Hub2

Mixing RakNet and NetherNet backend servers on the same proxy works the same way — see Backend Transports for the address-format differences that matter when one of them uses NetherNet.

What's next

Once the basics work, you'll probably want...	Go to
Groups, weighted load balancing, whitelisting, health checks	Configuration, Socket Protocol
Running Portal as a Go library instead of the binary	Library Usage
Hooking your own code into events (join/quit/transfer)	Event Bus
More than one Portal instance sharing player state	Clustering
A deeper understanding of the two listeners and how transfers work	Network Architecture