🌐 QueryHy - The Ultimate Hytale Server Monitoring Suite

QueryHy is a lightweight Hytale server plugin that exposes your server's live data through a built-in HTTP API — no external software required. Connect server lists, Discord bots, status pages, Grafana dashboards, or any custom tool in seconds.

Features at a Glance

Interactive Web Dashboard

A modern, dark-themed dashboard is available directly in your browser at http://your-server:5523/. No setup required — just open it.

Real-time player list with session durations and UUIDs (click a player for details)
RAM usage bar and configurable critical-usage alert
Historical charts for player count and RAM (persisted across restarts)
Live chat log

Remote Console

Execute server commands directly from the dashboard — secured behind your API key. Results appear instantly without leaving the page.

JSON API

Query your server's state from any application:

{
  "currentPlayers": 3,
  "maxPlayers": 100,
  "players": [
    { "name": "Steve", "uuid": "...", "sessionDurationSeconds": 42, "sessionDurationFormatted": "42s" }
  ],
  "uptimeFormatted": "1h 4m 12s",
  "serverName": "My Hytale Server",
  "peakPlayers": 12,
  "totalJoins": 84,
  "ramUsage": { "usedMb": 512, "totalMb": 1024, "maxMb": 2048 }
}

Prometheus / Grafana Support

The /metrics endpoint delivers data in standard Prometheus text format — ready to scrape with no additional configuration.

Security First

API key is auto-generated on first launch using a cryptographically secure random generator
Keys are accepted only via the X-API-Key header (never via URL parameters)
Constant-time key comparison prevents timing-based attacks
Full XSS protection: all player names and chat messages are escaped before rendering
Per-IP rate limiting with a configurable token-bucket algorithm

Endpoints

Method	Path	Auth	Description
`GET`	`/`	—	Interactive web dashboard
`GET`	`/query`	Required	Full server data as JSON
`GET`	`/chat`	Required	Recent chat messages as JSON
`POST`	`/command`	Required	Execute a server command
`GET`	`/metrics`	—	Prometheus-compatible metrics
`GET`	`/health`	—	Lightweight uptime/health check

Installation

Drop QueryHy.jar into your server's mods/ folder
Start the server — config.json and a secure API key are generated automatically
Note the API key from the server log or config.json
Open http://your-server:5523/ in your browser

Done. No port forwarding setup needed beyond opening port 5523 (configurable).

Configuration

All settings live in config.json inside the plugin's data directory. Every value is validated on load — invalid entries are automatically corrected to safe defaults.

{
  "port": 5523,
  "apiKey": "AUTO_GENERATED",
  "enableDashboard": true,
  "dashboardRefreshSeconds": 3,
  "ramWarningPercentage": 90.0,
  "enableRateLimit": true,
  "rateLimitRequestsPerSecond": 5.0,
  "rateLimitBurstCapacity": 10,
  "enableCors": true,
  "maxChatLogEntries": 50,
  "maxChartEntries": 240
}

Each data field in the /query response can be toggled individually (showMaxPlayers, showPlayerNames, showRamUsage, etc.) to expose only what you need.

Commands

Command	Description
`/queryhy reload`	Reload config and restart the HTTP server
`/queryhy status`	Show current server status in-game

Use Cases

Server list websites — poll /query to display live player counts and server info
Discord bots — show online players and uptime in a status channel
Grafana dashboards — scrape /metrics and build professional monitoring boards
Custom admin tools — use the REST API to automate server management
Status pages — hit /health for a simple uptime indicator

Requirements

Hytale Server
Java 25+
Port 5523 accessible (configurable)

Compatibility

QueryHy embeds its own HTTP server (com.sun.net.httpserver) — it has no external runtime dependencies and does not conflict with other plugins.

Developed by BSoftware - Empowering Hytale Server Admins.

QueryHy - HTTP Server Query