Everything horizon-server offers a host or a tool: its commands, every server.toml key and the control API. How to host: hosting.md; the design: server.md; stability and versions: stability.md.
horizon-server help prints:
horizon-server: host a Horizon (Minecraft Java Edition 26.3) server
Usage: horizon-server [--dir DIR] <command>
init Set up a server here: the EULA, the world, the port, who may join (asks, or takes flags:
--eula --world NAME --seed SEED --port N --whitelist/--no-whitelist --player NAME... --op NAME
--offline --yes)
run Run the server in the foreground; type console commands, Ctrl-C stops it cleanly. It
restarts the game if it crashes.
start Run the server in the background (its output goes to logs/supervisor.log)
stop, restart
status [--json]
Up or not, TPS, MSPT, players, RAM and CPU
cmd COMMAND...
Run a console command on the running server and print what it answers
logs [-f] [-n N]
The last N lines of the log (default 50); -f follows it
backup [NAME]
Zip the world and the settings into backups/ (a running server saves first and stays up)
backups [--json]
List the backups
restore BACKUP [--yes]
Put a backup's world in place (the current one is kept in backups/); a running
server restarts with it
service install|uninstall|print [--system]
Start the server at boot or login: a systemd unit on Linux (--system: for every user,
with sudo), a launchd agent on macOS, a task at logon on Windows
panel A one-time login link for the web panel ([panel] in server.toml; 127.0.0.1:8130 by
default)
update [--check [--json]] [--version TAG] [--timeout SECONDS]
Install the newest release (checked against GitHub's SHA-256), back up the world and
restart on it; goes back by itself if the game isn't up within the timeout (300 s).
--archive FILE --version NAME installs an archive you have
rollback Back to the release used before the update
config [--json]
The settings in server.toml
config set KEY=VALUE... [--json]
Change settings (for example world.difficulty=hard server.max_players=10), checked first;
a running server takes the difficulty, default game mode and whitelist at once, the rest
at its next start
import FILE Write server.toml from a vanilla server.properties
op NAME, deop NAME
whitelist on|off|list, whitelist add|remove NAME
Who may join (on the running server, or in the files when it is stopped)
--dir DIR The server folder (default: the current folder)
Settings live in server.toml; the server writes server.properties from it before every start.
Horizon server settings (docs/server.md). The server writes them into server.properties before every start: edit this file, not that one. Unknown keys are refused. horizon-server init writes this file with these defaults; horizon-server config set SECTION.KEY=VALUE changes it.
| Key |
Default |
In server.properties |
What it does |
motd |
"A Minecraft Server" |
motd |
the line under the server's name in the server list |
port |
25565 |
server-port |
the port players connect to |
bind |
"" |
server-ip |
listen on every address, or only on this one (server-ip) |
max_players |
20 |
max-players |
how many players can be online at once |
online_mode |
true |
online-mode |
check players' Minecraft accounts (false: anyone joins under any name) |
whitelist |
true |
white-list |
only whitelisted players and operators can join |
enforce_whitelist |
false |
enforce-whitelist |
kick online players taken off the whitelist |
view_distance |
10 |
view-distance |
chunks sent around each player |
simulation_distance |
10 |
simulation-distance |
chunks around each player where mobs, crops and redstone tick |
| Key |
Default |
In server.properties |
What it does |
name |
"world" |
level-name |
the world folder |
seed |
"" |
level-seed |
empty: a random seed on the first start |
game_mode |
"survival" |
gamemode |
survival, creative, adventure or spectator |
difficulty |
"easy" |
difficulty |
peaceful, easy, normal or hard |
hardcore |
false |
hardcore |
one life: a player who dies becomes a spectator |
Any other server.properties key, spelled as vanilla spells it, for example: spawn-protection = 16
| Key |
Default |
In server.properties |
What it does |
path |
"" |
|
the game program; empty: the one installed beside horizon-server |
resources |
"" |
|
the prepared game files; empty: resources/ here, else the usual places |
restart_on_crash |
true |
|
start the game again when it crashes |
| Key |
Default |
In server.properties |
What it does |
every |
"6h" |
|
automatic backups while the server runs: 30m, 6h, 1d...; "0" turns them off |
keep |
12 |
|
automatic backups kept (backups made by hand are never deleted) |
| Key |
Default |
In server.properties |
What it does |
keep |
1 |
|
other releases kept by updates, besides the one in use and the one rollback goes to |
| Key |
Default |
In server.properties |
What it does |
bind |
"127.0.0.1:8130" |
|
the web panel: this computer only, or a tailnet address (100.x); "" turns it off |
allow_public |
false |
|
true lets bind be any address; never put the panel on the open internet |
HTTP and JSON on 127.0.0.1. A running server writes its address and a random token to .horizon/api.json, readable only by its own user; every request sends Authorization: Bearer <token> and a Host that is that address. Errors answer {"error": "..."} with 400, 401, 403, 404, 405 or 409. The web panel uses the same routes with its session.
| Method |
Path |
Takes |
Answers |
What it does |
GET |
/api/v1/status |
nothing |
phase, version, pid, uptime_seconds, engine_pid, engine_uptime_seconds, crashes, last_crash, sample (TPS, MSPT, players, RAM, CPU), update |
How the server does |
GET |
/api/v1/metrics |
?since=T (seconds since 1970) |
{"samples": [...]}: one a second, the last 10 minutes |
The samples taken after T, for graphs |
GET |
/api/v1/logs |
?since=N |
{"next": N, "lines": [...]} |
The log lines after the Nth (the last 2000 are kept) |
POST |
/api/v1/command |
{"line": "<one command>"} |
the lines the command logged |
Run a console command on the running game |
POST |
/api/v1/stop |
nothing |
{"ok": true} |
Stop the game and the supervisor |
POST |
/api/v1/restart |
nothing |
{"ok": true} |
Restart the game |
GET |
/api/v1/backups |
nothing |
{"backups": [{"name", "bytes"}]} |
List the backups |
POST |
/api/v1/backups |
{"name": "..."} (optional) |
{"name": "<file>"} |
Back up now (a running game saves first and stays up) |
POST |
/api/v1/restore |
{"name": "<backup>"} |
{"name": "<backup>"} |
Restart the game with that backup's world (the current one is kept in backups/) |
POST |
/api/v1/update |
{"tag": "...", "timeout": seconds} (both optional) |
{"ok": true}; status says how it went (update) |
Restart on that installed release, or download the newest first; goes back if the game isn't up within the timeout |
POST |
/api/v1/panel/login |
nothing |
{"url": "..."} |
A one-time login link for the web panel (with the token only, not from the panel) |