Remote management for self-hosted Minecraft servers.

What does it do?

Flint is a simple tool enabling you to start or stop your Minecraft server from anywhere. It achieves this by wrapping your server in a REST API, exposing basic actions.

In addition to remote control, Flint can be used to autosave your Minecraft server on a custom interval. This can be helpful to reduce the frequency of stuttering caused by saving.

Installation

By design, Flint is optional and doesn't require you to change anything about your Minecraft server. Setup is as simple as dropping Flint in your server directory and pointing it at your startup script.

1. Download the latest version of Flint from the releases page
2. Move the executable into the root of your server directory
3. Create a flint-config.json file with the following contents:
   • Be sure to replace the startScript value with your own script

   {
     "mc": {
       "autoStart": true,
       "startScript": "./start.bat"
     }
   }

4. Double-click the Flint executable and watch the magic happen! ✨

Configuration

Flint's behavior is controlled by a simple configuration file, named flint-config.json. This file should be placed in the same directory as Flint.

Example directory structure:

mc-server/
├─ start.bat          // server start script
├─ server.jar
├─ flint-win.exe      // mac, windows, or linux executable
├─ flint-config.json
├─ ...

Properties

Field	Type	Required	Default	Description
api.port	Number		25585	Flint API port
mc.autoStart	Boolean		false	Start the Minecraft server when Flint is launched
mc.startScript	String	x		Relative path to start script
mc.autosave.enable	Boolean		false	Override the Minecraft server's default autosave interval
mc.autosave.interval	Number		60	Seconds between each autosave
api.auth.apiKey.enable	Boolean		false	Restrict API usage to only valid API keys
api.auth.apiKey.keys	String[]		[]	Keys that may be used to authenticate requests

Auth

Flint currently supports API Key authorization. This may be used to restrict access to only people who know a valid key. Please note that this method on its own should not be considered secure (Security of API keys).

To send authorized reqeusts, include the following header:

X-API-Key: <Your API key>

If you would like for us to add support for more auth methods, please create an issue.

Usage

There are two ways to interact with Flint. The first is via API endpoints, and the second is through its terminal.

API Endpoints

Controlling your Minecraft server is as easy as interacting with the following endpoints.

Start Server

POST /api/server

Response: HTTP 202 if the server will start; otherwise, HTTP 400 if it's already running.

Stop Server

DELETE /api/server

Response: HTTP 202 if the server will stop; otherwise, HTTP 400 if it's already stopped.

Get Server Details

GET /api/server

Response:

• Code: HTTP 200
• Content-Type: application/json
• Body: ServerDetails

Terminal Commands

At the moment, Flint does not yet support running specific Minecraft commands from the API. If you need to do this, please interact directly with Flint's terminal.

To start the server, simply type start. From here, terminal input is passed directly to the Minecraft server. That means commands like stop, list, op, etc. will behave as if you were running them directly on the server.

API Reference

ServerDetails

General information about the server's current state.

Properties

status (MCServerStatus)

Status of the server.

list (Players)

Player count and roster.

Examples

Minecraft server is offline:

{
  "status": {
    "name": "STOPPED",
    "canStart": true,
    "canStop": false
  },
  "list": {
    "online": 0,
    "max": 0,
    "roster": []
  }
}

Minecraft server is running and two players are connected:

{
  "status": {
    "name": "RUNNING",
    "canStart": false,
    "canStop": true
  },
  "list": {
    "online": 2,
    "max": 10,
    "roster": ["Steve", "Alex"]
  }
}

MCServerStatus

Enumeration of Minecraft server statuses.

Properties

canStart (boolean)

Whether the Minecraft server can be started.

canStop (boolean)

Whether the Minecraft server can be stopped.

Enumerations

name	canStart	canStop
CRASHED	true	false
RUNNING	false	true
STARTING	false	false
STOPPED	true	false
STOPPING	false	false

Players

Properties

online (number)

Amount of connected players.

max (number)

Maximum amount of players.

roster (string[])

List of connected players' names.

Examples

{
  "online": 4,
  "max": 20,
  "roster": ["Steve", "Alex", "Herobrine", "Notch"]
}