Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/lDEVinux/eaglercraft/llms.txt

Use this file to discover all available pages before exploring further.

The LAN relay brokers WebRTC peer-to-peer signaling between a browser hosting a LAN world and the clients joining it. Without a relay, browsers cannot establish direct connections to one another — the relay acts as a rendezvous point that exchanges the ICE candidates and session descriptions needed to set up a direct P2P connection. Once P2P is established, game traffic flows directly between players and the relay is no longer involved. You can use one of the existing public relays or host your own.

​
Public Relay Servers

The following public relay servers are available for use:
  • wss://relay.deev.is/ — lax1dude relay #1
  • wss://relay.lax1dude.net/ — lax1dude relay #2
  • wss://relay.shhnowisnottheti.me/ — ayunami relay #1
The public relays are provided for convenience and should remain available, but hosting your own relay gives you control over availability and performance.

​
Quick Start

1

Download sp-relay.jar

Download sp-relay.jar from the stable download: stable-download/sp-relay.jar
2

Run the relay

Launch the relay with a single Java command:
java -jar sp-relay.jar
3

Config files are generated

On first launch, two files are generated in the working directory:
  • relayConfig.ini — main relay configuration (port, rate limiting, origin whitelist)
  • relays.txt — list of STUN/TURN servers reported to connecting clients
4

Edit relayConfig.ini

Open relayConfig.ini to configure the listen port, rate limiting limits, and origin whitelist. See Relay Config for a full reference of every field.
5

Restart to apply changes

Stop the relay (type stop in the console and press Enter) and re-run java -jar sp-relay.jar for configuration changes to take effect.

​
Debug Mode

Pass --debug to enable verbose logging that includes the IP address of every incoming connection: 
java -jar sp-relay.jar --debug
Debug mode is disabled by default to reduce logging overhead when the relay is being pinged many times per second at higher traffic volumes.

​
How the Relay Works

The relay implements a lightweight binary WebSocket protocol to exchange the signaling data required for WebRTC. No game traffic ever passes through the relay — only the handshake packets needed to negotiate a direct P2P connection.

​
Signaling flow

Step 1 — LAN host opens the world
  1. The LAN host opens a WebSocket to the relay.
  2. Host → Relay: PKT 0x00 — identify as server, send protocol ID.
  3. Relay → Host: PKT 0x00 — confirm protocol version, assign join code.
  4. Relay → Host: PKT 0x01 — send ICE server (STUN/TURN) list.
Step 2 — Client connects with the join code
  1. A client opens a WebSocket to the relay and sends the join code.
  2. Client → Relay: PKT 0x00 — identify as client, send join code.
  3. Relay → Client: PKT 0x00 — confirm protocol version, assign client ID.
  4. Relay → Client: PKT 0x01 — send ICE server list.
  5. Relay → Host: PKT 0x02 — notify host of the new client and its ID.
Step 3 — ICE and SDP exchange The relay routes signaling packets bidirectionally between host and client until the P2P connection is fully negotiated:
  • Client → Relay → Host / Host → Relay → Client: PKT 0x03 — ICE candidate exchange.
  • Client → Relay → Host / Host → Relay → Client: PKT 0x04 — SDP description (offer/answer) exchange.
Step 4 — Connection result
  • Client → Relay → Host: PKT 0x05 — client signals P2P success.
  • Client → Relay → Host: PKT 0x06 — client signals P2P failure.
  • Relay → Client: PKT 0xFE — relay signals the client to close its relay WebSocket (P2P is now established).

​
Protocol summary

PKT 0x00  Handshake / identify (server→relay or client→relay)
PKT 0x01  ICE server list (relay→server, relay→client)
PKT 0x02  New client notification (relay→server)
PKT 0x03  ICE candidate exchange (bidirectional)
PKT 0x04  SDP description exchange (bidirectional)
PKT 0x05  Success signal (client→relay→server)
PKT 0x06  Failure signal (client→relay→server)
PKT 0xFE  Close signal (relay→client)
For the complete configuration reference, see Relay Config.

Build docs developers (and LLMs) love

Get started for freeTalk to us