SiriusCloud-MC

▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬

What it is
SiriusCloud is a control plane for Minecraft servers. You describe a group once ("Lobby: 1024MB, keep 2 online, max 8, Paper latest") and the cloud keeps that true: it starts servers when you are below the minimum, adds more when they fill up, restarts them when they die, hands each one a free port, and registers it with your proxy the moment it is actually ready.

Three pieces:

• Node: the brain. Owns every group, service, port and scheduling decision, and the network's data. Has the console you type into.
• Wrapper: one per machine. Spawns the processes, downloads the jars, pipes the consoles. Holds no policy of its own, so adding machine number two is starting a second wrapper.
• API: one interface that behaves identically whether you call it from the node, a module, or a plugin inside a running server.

▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬

Features

Servers follow your players

• Autoscaling: when a group's servers are 80% full, another starts. A server that has sat empty for 5 minutes above the minimum is stopped. Both thresholds are per group, and one server starts at a time with a cooldown between, so a burst of joins does not start five servers for a load one would carry.
• Rolling restarts: the replacement starts first, players are moved across, and only then does the old server stop. Capacity never dips.
• Template rollouts: change a group's template and its servers are replaced one by one, automatically.
• Scheduled restarts: replace servers after a set uptime, for the plugin that leaks.
• Start timeouts: a server that never reports ready is killed and replaced instead of holding its slot forever.
• Groups that keep failing back off on a growing delay (5s, 15s, 30s, 60s, 120s) instead of crash-looping once a second. The delay caps rather than giving up, so a transient cause still recovers by itself.
• Static services keep their files between restarts; dynamic ones start from a clean template every time.

Your velocity.toml lists no servers at all

• The node tells the proxy about each backend as it becomes reachable, and tells it to forget one the moment it goes away. A static server list would be wrong within seconds of being written.
• A proxy that starts late or restarts is sent every server already running, so it converges on the same state as one that was there from the beginning.
• Groups marked fallback are lobbies. Joining players land on the least loaded one, and /hub sends them back. Least loaded, not random, so a freshly started lobby actually takes load.
• A server that disappears takes its players with it: they are moved to a lobby with a message rather than left on a dead connection until they time out.

Modern forwarding is configured for you, on both ends
Backends run online-mode=false so the proxy can authenticate for them. On its own that would let anyone who reaches a backend port connect as any player, so the node generates a forwarding secret and the wrapper writes it into the proxy's forwarding.secret and every backend's config. Nothing to copy by hand, and nothing left open by accident. Fabric servers get FabricProxy-Lite installed and configured for the same.

Slots follow the servers
show-max-players is a fixed number, which is wrong the moment a cloud scales. The proxy answers each ping with the sum of what its registered servers actually hold:
Everything a network needs, built in
These run on the node as modules. Their commands work on every server with nothing installed there, and every feature can be switched off in its config, or removed by deleting its jar, if you already run your own plugin for it.

• Display & maintenance: one MOTD, version text and tab list for every proxy, in MiniMessage. /maintenance with a whitelist, a bypass permission and its own MOTD.
• Parties: /party invite, warp and chat. Members follow the leader between servers.
• Friends & messages: /friend with join and leave notices, /msg and /r to anyone on any server, /seen and /playtime.
• Moderation: /ban and /mute, permanent or timed (7d, 12h), /kick, /staffchat, /find, /jump. Bans are checked at login on the proxy, so a banned player never reaches a server, and they are stored against the UUID, so changing name does not escape one.
• Matchmaking: /play <game> queues. Players fill the fullest open server first so games actually start, parties always land together, and a new server starts when nothing has room.
• Monitoring: TPS, MSPT and heap from every server, a Prometheus endpoint for Grafana, and Discord webhook alerts for crashes (with the last log lines), lost machines, failed backups and lag.

Ranks, without a second permissions plugin

• Permission groups owned by the node: a rank given on one server is in effect on every server, including ones that have not started yet.
• Shown in chat, above heads and in the tab list, sorted by rank:
  Admin | JavaRenamed: Hello, world.
• The chat format is set once for the whole network. Turn it off if a chat plugin should own chat.
• Prefer LuckPerms? The cloud replaces Redis as its sync channel: set messaging-service: custom and every server, empty ones included, stays in step.

Your data, in a real database

• JSON files by default, so there is nothing to install. MySQL, MariaDB, PostgreSQL or MongoDB when you want them.
• Player profiles for free: first and last seen, total playtime, last server and every name a player has used.
• A shared key-value store with expiry, for queues, counters and cross-server state.
• If the database you configured cannot be opened, the node refuses to start, rather than running on and silently losing every ban written until somebody notices.

Any server software, without waiting for an update

• Paper, Purpur, Folia and Fabric servers; Velocity proxies.
• Version lists are fetched from each project's API, never hardcoded, so a new Minecraft release is usable the day it appears. latest resolves to the newest stable release, not the release candidate sitting above it.
• Every download is checksummed and cached.

Isolation and backups

• Docker isolation, optional: every server in its own container with a hard memory and CPU cap, so one runaway server cannot starve the machine.
• Backups of static servers on a schedule or on demand. Consistent ones: saving is paused and flushed before the zip is taken, and old archives are pruned.

Updates that migrate your files for you
Updating is: stop, replace the jars, start. On startup the node and every wrapper bring your files up to date with the new version before reading them, back up everything they change, and tell you exactly what that was. A migration that fails is undone. An older version refuses to start on files a newer one has migrated, so a downgrade cannot silently drop your settings.
Consoles you can actually read

• Service output never floods the node console. The wrapper buffers it locally and sends nothing over the network until you ask.
• attach Lobby-1 hands the console over to that server: the recent backlog replays first, then it goes live, and every line you type is forwarded to it. #detach or Ctrl+C returns.
• Crashes are the exception. A service that dies unasked pushes the tail of its console to the node unprompted, so you see why a server failed to start instead of "exited with code 1".

One player API across every proxy
The node keeps a cloud-wide registry of who is online and where. A plugin on one lobby can move, message or kick a player who is on a different server behind a different proxy, without knowing that any of that is true.
A proxy sends a snapshot of everyone connected right after it handshakes, so restarting the node under a busy cloud does not lose track of the players who stayed online.

REST API and web panel

• Token-authenticated HTTP API: nodes, wrappers, groups, services, players, plus start, stop, console command, send, message, kick and broadcast.
• A self-contained web panel served by the node itself, with a live overview of everything.
• Binds to 127.0.0.1 by default. This endpoint can run your cloud, so it is loopback-only until you deliberately widen it.

Modules, not forks
Features load from node/modules/ as jars with their own class loader and lifecycle. Every network feature above is one, and they use nothing but the public API, which keeps that API honest: anything they can do, your own module can too. Modules can register network-wide commands, check logins, and control the MOTD and tab list.

▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬

Requirements

• Node and wrapper: Java 21 or newer
• Minecraft services: Java 25 or newer, because Minecraft 26.x refuses to start on anything lower
• Servers: Paper, Purpur, Folia or Fabric. Proxies: Velocity.
• Optional: Docker for isolation; MySQL, MariaDB, PostgreSQL or MongoDB instead of JSON files.

These are genuinely different Java requirements, so the wrapper does not run servers on its own JVM. It finds a qualifying JDK on the machine at startup and refuses to start services with install instructions if there is not one, rather than spawning servers that exit instantly.

▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬

Setup
There is no JSON to hand-edit. Both halves ask you what they need on first start.

1. Start the node.
It asks for a name, how much RAM it may use (suggested from your actual machine), a port, and offers to create a first Lobby group and a Velocity proxy group, including which server software to run. Enter accepts every default. It prints a wrapper secret when it is done.

2. Start the wrapper.
It asks for the node address and that secret, how much RAM this machine may commit, and which installed JVM to run servers on, listing the ones it actually found, so it is a choice rather than a guess.

3. That is it. The provisioning loop sees the Lobby group below its minimum and starts one. Point your players at the proxy port.

Updating later: stop both, replace the jars, start them again. Your files are migrated on startup.

▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬

Commands
Node console
In game
Every command's permission is listed in the documentation on GitHub.

▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬

Honest status
I would rather you knew this before downloading than after.

• Working and tested end to end: node, wrappers, dynamic and static services, the provisioning loop, Velocity integration with dynamic registration and modern forwarding, the attach console, crash reporting, the cloud-wide player layer, the REST API and the panel.
• Newer and less proven: autoscaling, rollouts, the network features, ranks, databases, backups, Docker isolation and migrations. The logic is covered by unit tests and the node has been booted with every module, but they have had far less time on real networks. Reports very welcome.
• Single node, many wrappers. Multiple machines work today. Node clustering (several nodes sharing state with failover) is designed for but not built.
• Templates live on the wrapper. Running several machines means keeping template directories in sync yourself until node-side templates land.
• Tests, but no CI yet. There is now a unit test suite (51 tests) for the parts where logic can go quietly wrong: scaling decisions, matchmaking, storage, migrations. Run it with ./gradlew test; nothing runs it automatically on every push yet.
• Windows is written for but not yet exercised. Every cross-platform decision was made deliberately (stdin-driven shutdown, retrying deletes, UTF-8 streams), but it has not had a real Windows run.
• Known limits:
  • The built-in ranks apply on servers, not on the Velocity proxy. Staff commands that run on the proxy (/ban, /kick, /maintenance and so on) therefore need LuckPerms on the proxy, or can be run from the node console.
  • Fabric servers cannot run the cloud's plugin, so they report no player counts and do not autoscale.
  • Folia is supported by the core plugin, but not by the optional permissions plugin.

This is early software that is honest about being early. If you want a cloud you can read the source of and understand, that is exactly what it is built to be.

▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬