More machines

One panel can run servers on more than one computer: an old PC in the basement, a rented server, a friend’s spare machine. Each extra computer is a node and runs the NetherNode agent. The agent is the same program and image as the panel, started in a different mode.

Everything else stays on the panel: accounts, roles, the audit log, schedules, routes, bans and notifications. Players still join through the panel’s proxy at the same addresses, whichever machine runs the server.

What a node needs

Docker, like the panel’s machine.
A way to reach the panel’s web address. The agent always connects out to the panel, so the node needs no open ports. It works on another network, behind a home router, or over the internet.
The same NetherNode version as the panel (the same major and minor version; patch versions may differ).

If the panel sits behind a reverse proxy or a tunnel (Pangolin, Caddy, nginx, Cloudflare Tunnel), it must pass WebSocket connections through to /api/agent. Most do by default.

Add a node

On the panel, open Nodes and choose Add a node. Give it a name, like “Basement PC”.

The panel shows a command with a one-time join code that works for 30 minutes. Run it on the new machine:

docker run -d --name nethernode-agent --restart unless-stopped --network host \
  -v /var/run/docker.sock:/var/run/docker.sock -v nethernode-agent:/data \
  ghcr.io/ziggy46/nethernode:<version> agent --join https://panel.example.com --code nnj1.…

Within a few seconds the node shows as Online on the Nodes page, with its CPU, memory, disk and Docker version.

The join code is used up on the first connection. From then on the agent reconnects by itself whenever the connection drops, so the same command (with Docker’s restart policy) keeps working. Until then the node shows Waiting to join. If the code expires before it’s used, choose Make a join code.

Without Docker on the node, run the binary instead:

nethernode agent --join https://panel.example.com --code nnj1.…

The address and code can also be given as NETHERNODE_JOIN and NETHERNODE_JOIN_CODE. The agent keeps its servers, backups and identity in its data folder (NETHERNODE_DATA__DIR, /data in the image).

Servers on a node

When there’s more than one machine, Create server asks which one to use. Players still connect through the panel, so nothing changes for them.

Everything works the same as on the panel’s machine: the console, files and uploads, mods, players, backups and schedules. Backups of a server are kept on the machine it runs on.

A node’s servers show its name on their cards. Two states are particular to nodes:

State	What it means
Machine offline	The agent isn’t connected. The server may still be running there; it can be managed again once the agent reconnects. Players joining are told its machine is unreachable.
Machine needs update	The agent runs a different major or minor NetherNode version than the panel. Its servers’ status still updates, but nothing can be changed until it’s updated.

Player traffic

Every player’s connection goes from the panel’s proxy to the node and back, so it crosses the panel’s network connection twice. Minecraft uses roughly 50–300 kbit/s per player, so a home connection handles dozens of players.

Move a server

A server that isn’t running (stopped, sleeping or crashed) can move to another machine from its Configuration tab: Machine › Move…. Both machines must be online. On edge builds, remove a server’s modules first.

The server’s machine archives it. That archive stays there as a backup.
The archive is copied to the new machine, which sets the server up from it, with the same settings, addresses, schedules and routes.
The server is removed from the old machine.

While it moves, the server can’t be started, and its files and backups can’t be changed. If anything fails along the way, the server stays where it was.

Backups made before a move stay on the old machine. They can still be downloaded, but restored only on the machine that holds them.

Update a node

Nodes follow the panel’s version. When the panel is updated (or goes back from edge to stable), nodes on another version update themselves as they connect, and their servers keep running. A failed update is tried again at most once an hour. Turn this off with Update nodes automatically on the Nodes page; a node on another version then shows Update to v… instead.

Installed with Docker: the agent downloads the new image from the same place its current image came from, starts a copy of its container on it, and hands over. The copy keeps the container’s name and settings.
Installed as a binary: the agent downloads the release, checks it against the release’s checksums, and restarts in place. Set NETHERNODE_RELEASES_URL to download from a mirror instead of GitHub.

If an update doesn’t work, the node’s card says why, and the agent keeps running its current version. Agents from before 0.2.1 can’t update themselves yet: update those once by hand (pull the new image and recreate the container, or replace the binary).

Remove a node

On the Nodes page, choose Remove. The agent is disconnected and can’t come back without a new join code. Nothing on that machine is deleted.

If the node still has servers, move the ones you want to keep first. Removing it anyway makes the panel forget its servers and the backups kept there. If the machine is online, they’re stopped first. Their files stay on that machine.

Security

The panel and each agent check each other’s keys, exchanged when the agent joins. Their traffic is encrypted end to end (Noise), so a reverse proxy or tunnel in between sees only ciphertext.
An agent only takes requests from its panel, and only for its own servers. It has no shell, no access outside its servers’ folders, and no other use of Docker.
A compromised panel can control every node’s Docker, just as it controls Docker on its own machine.
A compromised node can’t reach the panel’s database or other nodes. It can only misreport its own servers.
Join codes are single use, expire after 30 minutes, are stored only as hashes, and every attempt is recorded in the audit log.