MuteCloud: add a node to your network

Step by step, how a second machine joins a running MuteCloud network and which groups it takes over.

A running network gets another machine in five steps. The leader prepares once, prints a join code, and the new machine only needs a single command. The setup on the new machine takes care of the rest, including which groups should run there. For the concepts behind it, see Cluster.

The join code is a key

The code contains the cloud's token. Whoever holds it has full control over the network, and the new node receives every template, including the plugin configurations with their database passwords. Only hand it to machines that you or your team operate.

1. Put both machines into one private network

For security reasons, nodes cannot be joined over the open internet. The cluster interface hands out commands, templates and passwords, and on the internet it would be an attack surface for the whole network. MuteCloud therefore only couples nodes inside a private network, and both the leader and the new node refuse anything else. The reasoning is explained under Private network only.

Put both machines into one shared network first. The quickest way is Tailscale: install it on both machines and log them into the same tailnet. Headscale, NetBird, ZeroTier, a hand-configured WireGuard tunnel, the private network of your host or a plain LAN work just as well. The address you use later is the one each machine has inside that network.

2. Open the leader's control port

By default the leader only listens on its own machine. In its mutecloud.toml:

mutecloud.toml (leader)

[api]
bind = "0.0.0.0:8770"

The port must not be reachable from the internet. On Linux with Tailscale, a small chain is enough. For other networks, replace 100.64.0.0/10 with the range of your private network:

iptables -N MC_API
iptables -A MC_API -s 127.0.0.0/8 -j ACCEPT
iptables -A MC_API -s 100.64.0.0/10 -j ACCEPT
iptables -A MC_API -j DROP
iptables -I INPUT -p tcp --dport 8770 -j MC_API

Make the rules survive a reboot, for example with a small systemd unit that runs before MuteCloud. Then restart the cloud once. Announce it first with announce, every game server restarts with it.

3. Decide what may run on the new node

Groups without a nodes entry run on every node. As soon as the new machine joins, the cloud would also start proxies and lobbies there. If that is not what you want, pin your groups to the leader first:

groups Proxy set nodes node-1
groups Lobby set nodes node-1
groups BedWars set nodes node-1

The change applies immediately, without a restart. During the join, the setup offers exactly these pinned groups for selection, so you can decide per group whether the new node helps out.

4. Print the join code

In the leader's console:

node join

Without an address the leader picks its best own address, a Tailscale address first. You can also name one yourself, for example node join 100.64.0.1. The output contains the code and a ready one-liner for Linux and one for Windows. The code stays valid as long as the leader's token does not change.

5. Run the one-liner on the new machine

Paste the Linux or Windows one-liner from step 4 on the new machine. The installer downloads MuteCloud, verifies the checksum and starts the setup, which already knows the code. It then asks:

Question	What to enter
What should be set up	preselected: add this machine to an existing network
Join code	preselected, confirm with Enter
Directory	where MuteCloud should live, for example `/opt/mutecloud`
Address of this machine	the address the proxy uses to reach this machine, usually its Tailscale address
Name of this node	must be unique in the network, the setup refuses taken names
Memory for all servers	how much RAM the game servers on this machine may use together
Groups to take over	select with space, confirm with Enter, empty is fine too
systemd service	on Linux yes, then MuteCloud starts on boot

After confirming, the setup writes the configuration, registers the selected groups with the leader and offers to start the cloud right away. On start the node connects to the leader, fetches the templates and takes over servers.

Checking the result

On any node:

node list

The new node should show up as worker with the state connected. service list shows which servers now run where. If nothing starts on the new node, check whether at least one group allows it (groups <name>) and whether its memory pool is large enough for one server of that group.

Changing assignments later

Groups can be moved at any time, from any node:

groups BedWars set nodes node-1,node-2   exactly these nodes
groups BedWars set nodes +node-3         add one node
groups BedWars set nodes -node-3         remove one node
groups BedWars set nodes all             run everywhere again

Servers that are already running on a removed node keep running until they end or are stopped. New ones only start on the listed nodes.

Removing a node

Take the node out of every group with groups <name> set nodes -<node>, wait until its servers are empty, then stop MuteCloud on that machine. The leader reports the lost connection through the webhook and removes the node's players from the player list.

Adding a node