Web GUI

Web GUI

The GUI edits the blacklist in normal mode or the hash allowlist in advanced mode. Start it from the server console:

modseeker gui

Open the full link printed immediately afterward, including the part after #. Anyone with an active link has panel access; keep it private.

Local access

gui:
  port: 0
  externalUrl: ""

This listens on 127.0.0.1 and selects an available port. Open the link on the machine running Paper. localhost on your laptop refers to your laptop, not a remote server or its container.

For private access to a remote host with SSH, use a fixed local GUI port, leave externalUrl blank, and forward that same port from your computer. For example, with gui.port: 25581:

ssh -N -L 25581:127.0.0.1:25581 user@your-server

Keep the tunnel open and use the server's printed http://127.0.0.1:25581/#... link in your local browser. The SSH endpoint must be able to reach the GUI listener; this example assumes Paper is on that host rather than behind a separate container loopback.

LAN or public IP over HTTP

gui:
  port: 25581
  externalUrl: "http://YOUR_REAL_PUBLIC_IP:PORT"

Replace YOUR_REAL_PUBLIC_IP and PORT with the address and external TCP port the browser will use. For a LAN-only setup, use the server's LAN IP instead. The external port can differ from gui.port if your router or host maps it that way.

For a non-local HTTP address, ModSeeker listens on all IPv4 interfaces automatically. There is no separate bindAddress setting.

1. Allocate the GUI port to the server/container in the hosting panel, if applicable.
2. Allow that TCP port in the host firewall.
3. For a server behind a router, forward the external TCP port to the server host and GUI port.
4. Run /modseeker reload, then modseeker gui in the console.
5. Open the new printed link. Test public access from another network if your router does not support access to its own public address from the LAN.

The HTTP warning means the panel traffic is unencrypted; it does not mean the GUI failed to start. Use HTTPS for protected access over an untrusted network.

HTTPS with a domain

gui:
  port: 25581
  externalUrl: "https://panel.example.com"

This keeps ModSeeker's listener on 127.0.0.1:25581. A reverse proxy in the same network namespace must serve HTTPS for the domain and forward to that local HTTP listener. The plugin does not obtain certificates or serve TLS itself.

For example, a Caddy proxy using the same loopback interface can use:

panel.example.com {
    reverse_proxy 127.0.0.1:25581
}

Point the domain's DNS at the proxy and arrange its public HTTPS ports and certificate setup. Caddy documents its reverse proxy and automatic HTTPS requirements. Keep the original public Host header when using another proxy; the panel checks the configured host and origin.

On an ordinary VPS, two host processes can share loopback. A proxy on the host and Paper inside a Docker container do not share loopback by default. The HTTPS setting does not make a container-local listener reachable from the host. Use a deliberately configured shared namespace or local forwarding arrangement; ask the host to provide that if you cannot manage it.

Port and URL rules

• Use a separate GUI port. Minecraft and this HTTP listener cannot both bind the same address and TCP port.
• A nonblank externalUrl requires a fixed gui.port; 0 is only suitable for the blank local setting.
• externalUrl is the browser-facing origin: scheme, hostname/IP and optional port. Do not put a path, query, login details or access token in this setting.
• Setting an address does not allocate hosting ports, configure DNS, open firewalls or install a proxy.

After changing the GUI settings, reload ModSeeker and run the console GUI command again. Use the newly printed link.

Edit policies

Enter the Minecraft version and search for a mod. Results update as you type; Enter searches immediately. The search uses Modrinth.

Panel	Actions
Blacklist	Add resolves and blocks the mod ID. Versions shows matching releases for reference; the rule applies to the ID, not one selected file. Remove unblocks it.
Allowlist	Versions lets you select releases to add. Available releases begin selected; deselect versions you do not intend to approve. The current-list version selector similarly chooses hashes for Remove. Essential entries are protected.

The current-list Refresh button reloads the saved entries. Successful edits apply and save directly; a plugin reload is not needed. Test them with a reconnect. Mods not found on Modrinth can still be managed with the commands and bucket workflows in Policies and Lists.

Session lifetime

The access link lasts up to 15 minutes. Closing the last panel tab also ends the session after a short grace period; a lost browser can take longer to time out. Reloading ModSeeker, stopping Paper or changing the panel mode closes the old session.

If the panel becomes unavailable, run modseeker gui again and use the current full link. An update already accepted at expiry can finish before a replacement session starts. The link is printed in the console, not written to a text file.

For a failed start, read the console line beginning GUI server failed to start: for the actual cause. See Troubleshooting for port, host, proxy and expired-link checks.