Networking and ports

Connections

From	To	Port	What
Browsers, API clients	Controller	8080 (HTTPS)	Web UI and REST API
Agents	Controller	8444 (TLS)	Enrollment, once per Node, with a one-time token
Agents	Controller	8443 (mutual TLS)	The Agent’s session: specs, reports, console, files, backups through the Controller
Players	Proxy’s Node	Network port (25565)	Players joining the network
Proxy	Other Nodes	Servers’ published ports	Players forwarded to servers on other Nodes
Players	Any Node	Servers’ published ports	Servers joined directly (Vanilla, or without a proxy)
Controller	catalog.shardkeep.gg, publishers	443	Catalog sync and software downloads (off with -offline)

The Controller never connects to a Node, and Nodes never connect to each other except for Minecraft traffic from the proxy. Backups, migration and copying between servers travel through the Controller over the Agents’ own sessions. A Node therefore needs no inbound ports except Minecraft’s, works behind NAT, and never exposes its Docker Engine.

Game ports

Each server gets a host port from the Controller’s range (25565 to 25664 by default, -game-port-range), unique on its Node. The network’s proxy takes the network’s port, 25565 by default.

Servers on one Node

Servers on a Node share a private Docker network. The proxy reaches servers on its own Node through it, without going through published ports.

Servers in the network

Servers in the network still publish their ports, so a proxy on another Node can reach them. They accept only players the proxy forwarded, using a secret Shardkeep shares with the proxy (Velocity’s modern forwarding), so players connecting to them directly are refused.