Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/iFamishedX/HungerBridge/llms.txt

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

HungerBridge stores all of its settings in a single config.yaml file that is generated automatically the first time the server starts. You never need to create this file by hand, but you will almost always want to review it — at minimum to copy the generated auth key into HungerLib, and optionally to change the port or fine-tune which endpoints are active.

​
Config File Location

The config file path depends on your platform:
PlatformPath
Fabricconfig/HungerBridge/config.yaml
Paper / Purpurplugins/HungerBridge/config.yaml
Both platforms use the exact same YAML structure; only the directory differs.

​
Default config.yaml

The following is the complete configuration file that HungerBridge generates on first run. Every key shown here is the canonical default. 
port: 30007

auth:
  key: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

v2-endpoints:
  run: true
  log: true
  ping: true
  info: true
  status: true
  tps: true
  players: true

v1-endpoints:
  run: false
  log: false
  status: false
  version: false

legacy-endpoints:
  run: false
  log: false

players:
  max-list: 50
The auth.key value shown above is a placeholder. On first run, HungerBridge replaces it with a randomly generated UUID unique to your server. Copy the actual value from your generated file.

​
Configuration Reference

​
port

port: 30007
The TCP port the internal HTTP server binds to. HungerBridge uses Java’s built-in com.sun.net.httpserver.HttpServer, which binds directly to this port on all interfaces.
  • Type: integer
  • Default: 30007
  • Valid range: any valid, available TCP port (1–65535)
Changing the port requires a full server restart — the HTTP server is bound at startup and cannot be rebound while the server is running. Make sure no other service is already using the port you choose.

​
auth.key

auth:
  key: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
The shared secret that all API clients must supply in the X-Auth-Key HTTP request header. HungerBridge rejects any request that omits or incorrectly supplies this header with a 401 Unauthorized response.
  • Type: string
  • Default: randomly generated UUID (written once on first run)
  • Header name: X-Auth-Key
The auth key protects every endpoint across all API generations. There is a single key for the entire bridge — it is not configurable per-endpoint or per-generation.
Treat the auth key like a password. Anyone who obtains it can execute arbitrary commands on your server. Do not commit config.yaml to version control, and do not expose the HungerBridge port to the public internet without additional network-level protections (e.g., a firewall rule restricting access to localhost or a trusted private network).
You can rotate the auth key at any time by replacing the value in config.yaml and restarting the server. Remember to update the matching setting in HungerLib after rotating.

​
v2-endpoints

v2-endpoints:
  run: true
  log: true
  ping: true
  info: true
  status: true
  tps: true
  players: true
Controls which v2 JSON API endpoints are active. All v2 endpoints are enabled by default. Disabling an endpoint causes HungerBridge to respond with 403 Forbidden for requests to that path.
KeyHTTP methodPathDescription
runPOST/v2/runExecute a console command. Accepts command, silent, and show_console fields.
logPOST/v2/logWrite a message to the server console. Accepts message and optional level fields.
pingGET/v2/pingHealth check. Returns ok: true and the current server time in milliseconds.
infoGET/v2/infoReturns bridge version, platform, and Minecraft version.
statusGET/v2/statusMinimal liveness check. Returns ok: true when the server is reachable.
tpsGET/v2/tpsReturns TPS averages at 1-minute, 5-minute, and 15-minute windows plus raw tick time in milliseconds.
playersGET/v2/playersReturns the online player count and a list of player names, capped at players.max-list.

​
v1-endpoints

v1-endpoints:
  run: false
  log: false
  status: false
  version: false
Controls which v1 JSON API endpoints are active. All v1 endpoints are disabled by default. Enable individual endpoints only if you have a specific client that targets the v1 paths.
KeyHTTP methodPathDescription
runPOST/v1/runExecute a command. Same command / silent / show_console fields as v2.
logPOST/v1/logWrite to the server console with an optional level field.
statusGET/v1/statusReturns bridge version, platform, and Minecraft version in a flat JSON object.
versionGET/v1/versionReturns bridge version, platform, and Minecraft version (no ok field).
The v1 API requires the same X-Auth-Key header as v2. Requests without a valid key receive 401 Unauthorized.

​
legacy-endpoints

legacy-endpoints:
  run: false
  log: false
Controls the original plain-text endpoints. Both are disabled by default. These endpoints accept a raw text body rather than JSON and are preserved only for backward compatibility with very early HungerLib versions.
KeyHTTP methodPathDescription
runPOST/runExecute a command. The request body is the raw command string.
logPOST/logWrite a message. The request body is the raw log string.
The legacy endpoints offer no structured error responses. Unless you have an explicit requirement for them, leave both set to false.

​
players.max-list

players:
  max-list: 50
The maximum number of player names the /v2/players endpoint will include in its response. If more players than this limit are online, the list is truncated to the first max-list entries. The count field in the response always reflects the true total regardless of truncation.
  • Type: integer
  • Default: 50

​
Applying Changes

HungerBridge reads config.yaml once at startup. To apply any change:
1

Edit config.yaml

Open the config file in a text editor and make your changes. Preserve the YAML structure — incorrect indentation will prevent the file from loading and HungerBridge will throw a startup error.
2

Save the file

Save config.yaml. No reload command is available; changes only take effect after a restart.
3

Restart the server

Stop and start your Minecraft server. HungerBridge will read the updated config on the next startup and bind the HTTP server with the new settings.
4

Verify

Check the server log for the startup line confirming the port in use:
[HungerBridge] INFO HungerBridge HTTP server started on port 30007
If the config could not be parsed, HungerBridge logs an error and the HTTP server will not start.

Build docs developers (and LLMs) love

Get started for freeTalk to us