Beacon

A self-hosted REST API for remotely controlling a vanilla Minecraft server - start/stop/restart the process, manage players (kick/ban/op/deop, even while the server is offline), toggle gamerules and difficulty, and tail the live console all without any Minecraft plugins or mods. Everything is driven through RCON and direct file access (server.properties, ops.json, logs/latest.log).

Built as the backend for a companion Flutter app, but usable from anything that can make HTTP requests (curl, Postman, your own client).

Security

There is no authentication on any endpoint. Anyone who can reach the port Beacon listens on (default 8080) can start/stop your server, kick or ban players, remove operators, and run arbitrary console commands via RCON. This is intentional for now. Beacon is designed to run on your own machine/LAN alongside the Minecraft server it controls, reachable only by devices you trust on your own network.

Do not expose this port to the public internet without putting your own authentication/reverse-proxy layer in front of it..

Features

• Dashboard live online/offline status, player count, version, MOTD, world seed
• Server control start / stop / restart the Minecraft process itself (not just RCON commands, this launches and kills the actual java process)
• Players see who's online (name, health, gamemode, ping), kick, ban, op, deop
• Operators full operator roster from ops.json, including operators who are currently offline, removing operator access works even while the Minecraft server itself isn't running (falls back to editing ops.json directly when RCON isn't reachable)
• Gamerules toggle Keep Inventory, change difficulty
• Console tails logs/latest.log directly (so it captures output regardless of whether Minecraft was started through Beacon, manually, or was already running), with cursor-based polling and the ability to send arbitrary commands via RCON
• Zero-config first run a one-time interactive setup wizard locates your Minecraft server folder, enables RCON in server.properties, and sets/generates an RCON password, no manual file editing or rebuilding required

Requirements

• Java 21
• Maven
• A Minecraft: Java Edition server (vanilla). RCON support is required this comes with vanilla server jars, no plugins needed.

Getting started

1. Build

mvn clean package

This produces target/beacon-server-<version>.jar. Copy it out of target/ to wherever you want to actually run it from.

2. First run (one-time setup)

Run the jar from a visible terminal this step needs a console to prompt into:

java -jar beacon-server-<version>.jar

You'll be asked for:

• The full path to your Minecraft server folder
• An RCON password (or press Enter to auto-generate a secure one)
• The RCON port (defaults to 25575)

Beacon then enables RCON in that folder's server.properties (preserving your existing comments/formatting, it edits line by line, not a full rewrite) and saves everything to beacon-config.properties next to the jar.

3. Every run after that

Config file already exists -> completely silent boot, no prompts. This means you can now run it headlessly:

javaw -jar beacon-server-<version>.jar

javaw runs without a console window, which makes it suitable for a Windows Task Scheduler entry ("run at startup") so Beacon comes up automatically in the background.

To reconfigure (new server folder, new password, etc.), just delete beacon-config.properties and run it from a terminal again.

Configuration

Everything lives in beacon-config.properties, created by the setup wizard:

minecraft.server.dir=/path/to/your/minecraft/server
minecraft.rcon.password=your-rcon-password
minecraft.rcon.port=25575

Delete this file to re-run the setup wizard from scratch.

API reference

All responses are JSON. Base URL: http://<host>:8080.

Method	Path	Description
GET	/dashboard	Online status, player count, version, MOTD
GET	/world	World seed and name
POST	/server/start	Launch the Minecraft process. 409 if already running
POST	/server/stop	Graceful RCON stop, falls back to force-kill if unresponsive. 409 if already stopped
POST	/server/restart	Stop then start. 409 if not running
GET	/players	Online players, name, health, gamemode, ping, op status
GET	/players/operators	Full operator roster from ops.json, online or not
POST	/players/{name}/kick	Kick a player
POST	/players/{name}/ban	Ban a player
POST	/players/{name}/op	Grant operator
DELETE	/players/{name}/op	Remove operator and works even if the server is offline
GET	/gamerules	Current Keep Inventory + difficulty
PUT	/gamerules/keep-inventory	Body: {"keepInventory": true|false}
PUT	/gamerules/difficulty	Body: {"difficulty": "peaceful|easy|normal|hard"}
GET	/console/logs?since=<id>	Buffered console lines newer than id (cursor-based polling)
POST	/console/command	Body: {"command": "..."} sends via RCON

Known limitations

• No authentication
• RCON commands are serialized through a single persistent connection fine for a personal server, may bottleneck under heavy concurrent use
• Console log parsing assumes the standard vanilla log format ([HH:mm:ss] [Thread/LEVEL]: message); heavily modified server output may not parse level/timestamp correctly but will still be captured as plain text
• Tested against vanilla servers only, behavior on modded/Paper/Spigot servers is untested

License

MIT - see LICENSE.