Getting Started

Requirements

Component	Requirement
Paper or a compatible fork	Minecraft 1.21.11 and later
Java	Java 25 or newer for every supported server version
Minecraft status listener	`enable-status=true` in `server.properties`
Network access	A reachable Bore relay; outbound HTTPS for the first managed download
Operating system	Windows x64/x86 or Linux/macOS x64/ARM64 for managed Bore downloads

Folia and Spigot are not supported. Other operating systems or architectures require a compatible custom bore.executable. See compatibility for the tested server builds and platform details.

Download

Download the plugin JAR from Hub, SpigotMC or GitHub Releases. Choose port-bridge-<version>.jar; the current Hub download is port-bridge-1.0.0.jar.

You do not need Gradle or Git to install a published build. The plain and Javadoc JARs are for developers; install the plugin JAR on your server.

Install

Use the same plugin JAR for every supported server version and run the server with Java 25 or newer.

Stop the server and place the plugin JAR in its plugins directory.
Keep enable-status=true in server.properties.
Start the server and check the console for a successful Port Bridge startup.
Run /port help as an operator or an account with the relevant permissions.

The first startup creates plugins/PortBridge/config.yml and messages.yml when they are missing. Existing files are retained. The first tunnel start downloads and verifies Bore v0.6.0 unless a verified cached executable or custom executable is available.

Open Your First Tunnel

Automatic startup is enabled by default. After the startup delay, Port Bridge checks your existing Minecraft listener, starts Bore, and verifies the public route.

/port status
/port address

The status panel shows the connection state, local target, relay, latency, and latest diagnostic. The address panel shows the public address once one is available.

If you disabled startup.auto-start, start the tunnel manually:

/port start

Wait for the connection result, then request the address again. See tunnels and relays for the difference between an allocated port and a verified Minecraft route.

Connect with Friends

Copy the address from /port address or click Copy Address in chat. Friends enter it in Minecraft Java’s Multiplayer > Direct Connection screen.

Keep your computer, Minecraft server, and tunnel running while people play. The server’s whitelist, account authentication, and Minecraft client-version requirements still apply.

/port stop

Stopping the tunnel disconnects remote players and cancels pending retries. A later /port start opens a new session; its public address can change.

Configure and Reload

Edit config.yml or messages.yml, then run:

/port reload

A reload validates both replacement files before applying them. Invalid values retain the previous configuration. An active tunnel reconnects with the new settings; an explicitly stopped tunnel stays stopped.

Update

Stop the server, replace the plugin JAR, and restart. Existing configuration files are preserved, and missing message keys use bundled defaults. Compare your files with the configuration references when you want to customize newly added settings.

Build from Source Optional

To build a local copy or contribute, install a Java 25 JDK and Git:

Clone the repository with git clone https://github.com/Despical/PortBridge.git.
Open the project directory with cd PortBridge.
Build using the included Gradle wrapper:

./gradlew clean build

On Windows PowerShell, use ./gradlew.bat clean build. Install build/libs/port-bridge-<version>.jar using the steps above. Run ./gradlew javadocJar separately to generate the Javadoc JAR and HTML documentation.