Skip to content
CatalystCatalyst Docs

Registering a Node

Registration introduces a machine to the panel: identity, credentials, and the network addresses it may hand out to servers. Do it before installing the agent, because the panel is what issues the agent’s credential.

Prerequisites

Section titled “Prerequisites”
  • Administrator access — registering a node needs the node.create permission (a role with admin.write also passes).
  • The target machine meets the node requirements.
  • The node’s hostname and public address (an IPv4 or IPv6 literal) to hand.
  • A location to group the node under; you can create one in the dialog.

Register the node

Section titled “Register the node”

  1. Open Admin → Nodes and select Register Node. The dialog is a single screen with numbered sections and a live summary of what you are about to create.

  2. 1 — Location: where the node physically sits. If no locations exist yet, select Create a location, then come back and pick it.

  3. Fill in the remaining sections — Node details, Connection, Capacity, and Advanced agent paths:

    Field Required Notes
    Name Yes Datacenter + purpose, for example eu-frankfurt-01.
    Description No Free text shown in the node list.
    Server data directory Pre-filled Where server files live on the node. Default /var/lib/catalyst/servers.
    Hostname Yes How the panel reaches the agent.
    Public address Yes Address players connect to — an IPv4 or IPv6 literal.
    Memory (MB) Yes Total memory the node may allocate. Default 16384.
    CPU cores Yes Total CPU cores the node may allocate. Default 8.
    Memory Over-allocation (%) No 0 = none, -1 = unlimited.
    CPU Over-allocation (%) No Same meaning.
    SFTP Access No On by default, port 2022. Change it later in Update node.
    Advanced agent paths No Container-runtime and CNI paths. Leave blank to use agent defaults.

  4. Select Register node. The panel creates the node record and its ID.

  5. The dialog switches to Deploy agent and shows the install command, which carries a new agent API key. Select Copy and run it on the machine — installing a node covers the details. Select Done to close the dialog.

The node’s first check-in flips it to online in Admin → Nodes. If you lose the command, open the node and select Deploy to generate a fresh one.

Add allocations

Section titled “Add allocations”

Servers need IP + port pairs. Open the node and select Allocations, then use the Port Allocations tab → Create Allocations. Enter one or more IPs and one or more ports; the field accepts a single value (25565), a range (25565-25664), or a comma-separated list.

  • Only add IPs actually configured on the node.
  • Reserve panel/agent/management ports — never hand them to game servers.
  • For dedicated-IP (MACVLAN) networking, create an IP Pool instead; each server then takes one IP from the pool automatically.

The node’s Allocations page also shows how many allocations are assigned and free, so you can see when a node is running out.

Credential hygiene

Section titled “Credential hygiene”
  • The agent API key is a long-lived secret issued with the install command and shown only there. If one leaks, rotate it: open the node, select Regenerate Key, and update /opt/catalyst-agent/config.toml on the node.
  • One key per node — never copy a key between machines.
  • The deployment token in the install command’s URL is single-use and expires after 24 hours; the API key in the command does not expire.
Section titled “Related”