Groups

A group is a file under groups/. It describes what should run, not what is running right now. MuteCloud reconciles the target state with reality every two seconds and never rewrites the file, which allows it to be kept under version control.

groups/lobby.toml

name = "Lobby"
memory = 1024
layers = ["global", "lobby"]
fallback = true
 
[software]
kind = "paper"
version = "26.2"
 
[scale]
min = 2
max = 6
keep_free = 1
full_at = 0.8
 
[restart]
at = ["04:00"]
 
[[plugins]]
modrinth = "luckperms"

Fields

Field	Meaning
`name`	name of the group, servers become Lobby-1, Lobby-2, ...
`kind`	`server` or `proxy`
`memory`	RAM per server in MB
`layers`	which templates get copied in, in this order
`persistent`	keep the world, the directory stays under `static/`
`fallback`	where players land on join and when a server fails
`maintenance`	group in maintenance, nobody gets in
`enabled`	`false` starts nothing new, running servers stay
`port_range`	range ports are taken from
`jvm_flags`	extra JVM switches
`env`	environment variables for the server process
`requires`	groups that must be ready first
`drain_secs`	how long a draining server waits for its players
`nodes`	which nodes may run this group
`rollout`	`auto` or `freigabe`, see below

`[software]`

kind is paper, purpur, folia or velocity, version the Minecraft version. Without a version MuteCloud takes the newest. build pins a build, default is latest. jar points at your own file when you bring software MuteCloud does not know.

`[java]`

major forces a Java version. Without it MuteCloud derives it from the Minecraft version: 1.8.8 gets Java 8, 26.2 gets Java 25. The runtime is downloaded on demand and lives under runtimes/.

`[scale]`

Field	Meaning
`min`	this many always run
`max`	never more than this
`keep_free`	this many should sit empty and ready
`full_at`	one more starts at this load, `0.8` is eighty percent
`cooldown_secs`	quiet time between two starts

`[restart]`

at = ["04:00"] restarts at fixed times, every_hours in fixed intervals. warn_seconds controls when players are warned, message the text. Restarts run one server at a time, nobody gets dropped.

`[backup]`

For persistent servers only. at = ["03:00"] saves at those times, keep says how many archives stay. Manual runs: groups <name> backup.

`[[plugins]]`

[[plugins]]
modrinth = "viaversion"
 
[[plugins]]
url = "https://example.com/Custom.jar"
sha256 = "..."

Plugins are placed in the last template of the group. groups <name> plugins update downloads them again.

Rolling out template changes

When a template changes, running servers are outdated. For game servers, MuteCloud starts the replacement alongside the existing server and drains the old one only once the new one accepts players, so the change remains invisible to players.

A proxy has no stand-in; replacing it disconnects every player. Proxy groups therefore wait for explicit approval:

groups Proxy rollout

While something is pending, the group list shows "Freigabe nötig" and a message goes to the webhook. Change it per group with groups <name> set rollout auto or freigabe, standard returns to the default.

Persistent and ephemeral

Without persistent, every server receives a fresh working directory under run/ that is removed when the server stops. This is the usual case for lobbies and match servers.

With persistent = true the directory resides under static/ and is kept. On start only the template files are refreshed while the world remains untouched. This applies to build servers and any installation whose state grows over time.

Groups

On this page