mcwaiter

Minecraft server configurator and controller for Linux.

⚠️ Status: Early beta. Expect breaking changes. Please open issues or start a discussion if you find any bugs or would like to request a feature.

Create Minecraft servers and run each one as a sandboxed systemd service under its own system user (mcwaiter-<name>).

Features

• Create servers for many loaders (Vanilla, Fabric, Paper, ...) with one command, using the MCJars API
• Interactive prompts for anything you don't pass as an argument
• Finds a matching Java installation automatically (based on the Minecraft version)
• Generates a ready-to-use run.sh and a commented user_jvm_args.txt (Aikar flags)
• Service hardening and resource limits, configurable globally and per server
• Live console: follows the server log and sends commands via RCON
• Optional autostart of all servers on boot

Requirements

• Linux with systemd (other service managers are not supported yet)
• Python 3.10+
• Root privileges for most commands (mcwaiter re-runs itself with sudo when needed)
• Java (mcwaiter looks for installed JDKs in /usr/lib/jvm)

Installation

pipx install mcwaiter

or directly via git

pipx install git+https://github.com/Aintdev/mcwaiter.git

Quick start

# create a server (asks for anything you leave out)
mcwaiter create survival --version 1.20.1 --loader fabric

mcwaiter start survival
mcwaiter console survival
mcwaiter stop survival

Commands

mcwaiter [--version] <command> [options]

Every command accepts --debug. In debug mode, API responses are saved to <config dir>/.debug/api.

create

mcwaiter create <name> [--version MC_VERSION] [--loader LOADER[@BUILD]]

--loader takes the format loader@build, for example fabric@0.20.1. If you leave out the build (just fabric), mcwaiter lists the available ones and lets you choose; the latest stable build is marked [STBL]. Missing arguments are asked interactively.

mcwaiter picks a matching Java version (or asks), writes run.sh and user_jvm_args.txt (6 GB heap by default) and asks you to accept the Minecraft EULA. If anything fails, the half-created server is cleaned up again.

delete

mcwaiter delete <name>

You have to type a random confirmation string. For scripts you can skip that with --confirm-override (use at your own risk, this cannot be undone).

edit / config

mcwaiter edit survival server.properties   # file path is relative to the server root
mcwaiter config                            # global config
mcwaiter config -n survival                # per-server config
mcwaiter config -e nano                    # set the editor and use it
mcwaiter config -n survival -e nano        # per-server config with nano as editor

The editor is stored in the config ([DEFAULTS] editor) and asked for on first use. edit fixes file ownership afterwards.

console

Follows the server log (via journalctl) in a curses interface. If RCON is enabled in the server's server.properties, you can type commands at the bottom (up/down for history, PageUp/PageDown to scroll). Without RCON the log is read-only.

Enabling RCON

Open server.properties with mcwaiter edit <name> server.properties and set a port and a password of your choice:

enable-rcon=true
rcon.port=25575
rcon.password=your-safe-password

autostart

mcwaiter autostart --enable    # install a systemd unit that starts your servers on boot
mcwaiter autostart --disable   # remove it again
mcwaiter autostart --run       # start all servers with autostart enabled (what the unit runs)

A server takes part in autostart when autostart = true is set in its [OVERRIDES] section (mcwaiter config -n <name>). Servers are started in alphabetical order.

How it works

• Servers are in /opt/mcservers/<name> (configurable via serverpath).
• Each server runs as the system user mcwaiter-<name>.
• start launches run.sh as a transient systemd unit named minecraft-<name> (via systemd-run), so you can also use systemctl and journalctl on it directly.
• Per-server settings are stored next to the server directory in /opt/mcservers/<name>.ini.

Configuration

The global config is a config.ini in your user config directory (~/.config/mcwaiter/ on most systems).

[DEFAULTS]

[JAVA]

auto points to the default java binary and in the selection panel while creating a server, is listed under symlink. Detected JDKs are added automatically as <jdk-name> = <path> (for example java-21-openjdk = /usr/lib/jvm/java-21-openjdk/bin/java).

[SERVICE]

These are the defaults for all servers. Each server can override any of them in its own [OVERRIDES] section; an empty value falls back to the global one. A config file is owned by root and the minecraft-user cannot access it.

Boolean options accept the usual configparser values (true/false, yes/no, on/off, 1/0).

Example of a per-server config (/opt/mcservers/survival.ini):

[OVERRIDES]
autostart = true
memory-limit = 8G
private-devices =

Development

git clone https://github.com/Aintdev/mcwaiter.git
cd mcwaiter
pip install -e .
mcwaiter --help

License

MIT