server.json config

Server-side WebGUI settings are stored in config/webgui/server.json.

The file is created automatically on first launch. A config/webgui/server.example.json template is also written for reference. If tokenSecretBase64 is empty, a new secret is generated and saved automatically.

Full example

{
  "enableTokens": true,
  "tokenTtlSeconds": 900,
  "queryParamName": "webgui_token",
  "tokenSecretBase64": "<auto-generated or your secret>",

  "autoHudOnJoin": false,
  "autoHudUrl": "",

  "mainMenuUrl": "",
  "updateCheckUrl": "",

  "trustedCommandOrigins": []
}

Fields

Signed tokens

Signed tokens let your web backend verify that a request comes from a genuine WebGUI client.

Field	Type	Default	Description
enableTokens	bool	true	Attach a signed token to every page URL the mod opens.
tokenTtlSeconds	int	900	Token lifetime in seconds. Minimum enforced by the mod: 60.
queryParamName	string	"webgui_token"	Query parameter name used to carry the token.
tokenSecretBase64	string	auto	Base64 HMAC secret shared with your backend. Auto-generated if empty.

Auto HUD

Field	Type	Default	Description
autoHudOnJoin	bool	false	Automatically open the HUD overlay when a player joins the server.
autoHudUrl	string	""	URL to open as the auto HUD. Required when autoHudOnJoin is true.

Main menu

Field	Type	Default	Description
mainMenuUrl	string	""	URL sent to clients on join for the main menu screen (opened with F6). Empty = key does nothing.

Update check

Field	Type	Default	Description
updateCheckUrl	string	""	URL that returns version info. Supported formats: {"version":"1.2.3"} or {"tag_name":"v1.2.3","html_url":"..."}. Empty = disabled.

Trusted command origins

Pages can run Minecraft commands as the player (see runCommand). Because the webview can load arbitrary web content, this is gated by origin: a command is accepted only from the main frame of an origin listed here.

Field	Type	Default	Description
trustedCommandOrigins	string[]	[]	Origins (scheme://host[:port]) whose pages may run commands. Empty = no page may run commands.

{ "trustedCommandOrigins": ["https://ui.myserver.example", "http://localhost:3000"] }

• Commands run with the player's own permissions — exactly as if typed in chat, so there is no privilege escalation.
• Requests from any other origin (after a redirect, or from an <iframe>) are dropped.
• The list is sent to the client on join and cleared on disconnect, so trust never carries across servers.
• Default ports (443/80) are normalized: https://x ≡ https://x:443.

Notes

• If you use signed tokens, your backend must verify them with the same secret defined in tokenSecretBase64.
• The config path is config/webgui/server.json — note webgui, not webui.