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 sp-relay generates relayConfig.ini (and relays.txt) in the working directory on first launch. Edit relayConfig.ini to change the listen port, configure rate limiting, and restrict which client origins can use the relay. Edit relays.txt to configure the STUN/TURN servers sent to connecting clients.
The relay must be restarted for any configuration changes to take effect. Type stop in the relay console and re-run java -jar sp-relay.jar.

​
relayConfig.ini Fields

The config file uses key: value syntax. All keys are case-insensitive.

​
Network

​
address
string
default:"0.0.0.0"
The IP address the WebSocket server binds to. Use 0.0.0.0 to listen on all interfaces, or specify a single IP to restrict the bind to one network interface.
​
port
integer
default:"6699"
The port the relay WebSocket server listens on. Clients connect to your relay via wss://your-host:<port>/. Make sure this port is open in your firewall for external connections.

​
Join Code Generation

​
code-length
integer
default:"5"
The length (in characters) of the randomly generated join codes assigned to LAN worlds. Longer codes reduce the chance of collisions on a busy relay.
​
code-chars
string
default:"abcdefghijklmnopqrstuvwxyz0123456789"
The character set used when generating join codes. Must contain at least 2 characters.
​
code-mix-case
boolean
default:"false"
When true, generated join codes randomly mix upper and lower case characters from code-chars. Increases the effective code space without increasing code length.

​
Connection Limits

​
connections-per-ip
integer
default:"128"
Maximum number of simultaneous WebSocket connections allowed from a single IP address. Connections exceeding this limit are immediately closed.
​
worlds-per-ip
integer
default:"32"
Maximum number of simultaneously open LAN worlds allowed from a single IP address.

​
World (Open) Rate Limiting

These settings control how often a single IP can open new LAN worlds.
​
world-ratelimit-enable
boolean
default:"true"
Enable or disable rate limiting for world-open requests.
​
world-ratelimit-period
integer
default:"192"
The sliding window period in seconds over which world-open requests are counted.
​
world-ratelimit-limit
integer
default:"32"
Maximum number of world-open requests permitted from one IP within world-ratelimit-period seconds before the request is blocked.
​
world-ratelimit-lockout-limit
integer
default:"48"
If requests from an IP reach this count within the period, the IP is locked out for world-ratelimit-lockout-duration seconds.
​
world-ratelimit-lockout-duration
integer
default:"600"
Lockout duration in seconds applied when an IP exceeds world-ratelimit-lockout-limit.

​
Ping Rate Limiting

These settings control how often a single IP can ping (query) the relay.
​
ping-ratelimit-enable
boolean
default:"true"
Enable or disable rate limiting for relay ping/query requests.
​
ping-ratelimit-period
integer
default:"256"
The sliding window period in seconds over which ping requests are counted.
​
ping-ratelimit-limit
integer
default:"128"
Maximum number of ping requests permitted from one IP within ping-ratelimit-period seconds.
​
ping-ratelimit-lockout-limit
integer
default:"192"
Lockout trigger threshold for ping requests within the period.
​
ping-ratelimit-lockout-duration
integer
default:"300"
Lockout duration in seconds for IPs that exceed the ping lockout limit.

​
Origin Whitelist

​
origin-whitelist
string
default:""
A semicolon (;) separated list of domains used to restrict which sites are allowed to use your relay. When left blank, all origins are permitted.Special values:
  • offline — allow offline download clients (connections with Origin: null)
  • null — allow connections that do not specify an Origin: header at all
  • * wildcard prefix — e.g. *.deev.is allows all subdomains of deev.is
From the official README:
The origin-whitelist config variable is a semicolon (;) separated list of domains used to restrict what sites are to be allowed to use your relay. When left blank it allows all sites. Add offline to allow offline download clients to use your relay as well, and null to allow connections that do not specify an Origin: header. Use * as a wildcard, for example: *.deev.is allows all domains ending with “deev.is” to use the relay.

​
Reverse Proxy Support

​
enable-real-ip-header
boolean
default:"false"
When true, the relay reads the client’s real IP from an HTTP header forwarded by a reverse proxy (e.g. NGINX) instead of the raw socket address. Required for accurate rate limiting and connection limits when running behind a proxy.
​
real-ip-header-name
string
default:"X-Real-IP"
The name of the HTTP header that carries the real client IP when enable-real-ip-header is true. Matches the header set by proxy_set_header X-Real-IP $remote_addr in NGINX.

​
Miscellaneous

​
show-local-worlds
boolean
default:"true"
When true, the relay responds to local-world poll requests (PKT 0x04 connection type) with a list of LAN worlds open from the same IP address. This is what populates the Multiplayer screen with nearby LAN worlds.
​
server-comment
string
default:"Eags. Public LAN Relay"
A human-readable label returned in relay ping responses. Visible to clients that query the relay’s metadata.

​
Example Config

relayConfig.ini
[EaglerSPRelay]
address: 0.0.0.0
port: 6699
code-length: 5
code-chars: abcdefghijklmnopqrstuvwxyz0123456789
code-mix-case: false
connections-per-ip: 128
ping-ratelimit-enable: true
ping-ratelimit-period: 256
ping-ratelimit-limit: 128
ping-ratelimit-lockout-limit: 192
ping-ratelimit-lockout-duration: 300
worlds-per-ip: 32
world-ratelimit-enable: true
world-ratelimit-period: 192
world-ratelimit-limit: 32
world-ratelimit-lockout-limit: 48
world-ratelimit-lockout-duration: 600
origin-whitelist:
real-ip-header-name: X-Real-IP
enable-real-ip-header: false
show-local-worlds: true
server-comment: Eags. Public LAN Relay

​
relays.txt

relays.txt configures the STUN and TURN servers the relay reports to every connecting client via PKT 0x01. Clients use these servers to discover their public IP/port and to relay media when a direct P2P path is unavailable (strict NAT or symmetric NAT environments). The file uses INI-style sections. Each STUN entry requires a url field; each TURN entry requires url, username, and password.
relays.txt
[STUN]
url= stun:stun.l.google.com:19302

[STUN]
url= stun:stun1.l.google.com:19302

[TURN]
url= turn:turn.example.com:3478
username= myuser
password= mypassword
By default, relays.txt is populated with public Google STUN servers. Add your own TURN server entries for networks with strict or symmetric NAT where direct P2P connections cannot be established without a relay media path.

​
Firewall

The relay’s WebSocket port (default 6699) must be open in your firewall for external clients to reach it. On Linux with ufw: 
sudo ufw allow 6699/tcp
On Linux with firewalld: 
sudo firewall-cmd --permanent --add-port=6699/tcp
sudo firewall-cmd --reload
If you are running behind a router, also forward the port via your router’s NAT/port-forwarding settings.

​
Adding the Relay to Clients

Players must add your relay URL to their client before they can join or host worlds on it. They do this from the Multiplayer screen → Network Settings → Add Relay, then enter the full wss:// URL.

​
Pre-configuring the relay in eaglercraftOpts

If you are hosting your own Eaglercraft client, you can pre-populate the relay list by editing the window.eaglercraftOpts variable in your index.html: 
window.eaglercraftOpts = {
  // ... other options ...
  relays: [
    { addr: "wss://your-relay.example.com/", name: "My Relay", primary: true }
  ]
};
Setting primary: true makes this relay the default relay used when opening a world to LAN.

Build docs developers (and LLMs) love

Get started for freeTalk to us