Install an agent for Pterodactyl

An agent sells game servers, virtual machines, or both. The hypervisor is one of proxmox, virtfusion, or solusvm. Pterodactyl is the game-server panel, and an agent can run it alone or beside one hypervisor.

Panel screenshots for the keys, the user, the platform, and the node are in Get started (Pterodactyl). This page is the command reference.

Create both panel keys before you run an install command. nr cluster register --pterodactyl and nr cluster install-pterodactyl ask for the panel URL, both keys, and the panel user id. What you type stays on screen, including the keys. Export PTERODACTYL_PANEL_URL, PTERODACTYL_APPLICATION_KEY, PTERODACTYL_CLIENT_KEY, and PTERODACTYL_PANEL_USER_ID to skip the questions. Put the key itself in the variable. NodeRings stores the panel URL only. The keys stay on the agent.

Keys

Application API key (ptla_). In the panel, open Admin → Application API → Create New. The form uses Read, Read & Write, and None. Set them in this order:

Resource	Set this
Allocations	Read
Database Hosts	None
Eggs	Read
Locations	None
Nests	Read
Nodes	Read
Server Databases	None
Servers	Read & Write
Users	None

Servers → Read & Write creates, suspends, unsuspends, and deletes a game server. Read on Nodes, Allocations, Nests, and Eggs finds a node, a free port, and an egg. Leave the other rows on None. You cannot edit these permissions after the key is created.

Client API key (ptlc_). Log in to the panel as the user you will pass to --panel-user-id, then open that account's API credentials and create a client key. There is no permission checklist. The key acts as that user, and that user owns every server NodeRings creates. The client key is what power, the console, files, databases, schedules, backups, allocations, and startup use. An application key cannot do those. Use a service account for this, not a customer's panel login.

--panel-user-id is that user's numeric id from the panel.

Game servers only

Use this when the agent should not sell virtual machines.

nr cluster register \
  --pterodactyl \
  --name edge-ams-01 \
  --agent-ip 203.0.113.10 \
  --gateway-region AMS01 \
  --org-id <org-uuid>

No --hypervisor-driver. Nothing virtual-machine related is installed or offered.

Agent already has a hypervisor

Use this when nr cluster register already installed Proxmox, VirtFusion, or SolusVM. Do not register the agent again.

nr cluster install-pterodactyl

The hypervisor driver does not change. Game servers are added beside it.

Both at once

nr cluster register \
  --hypervisor-driver proxmox \
  --pterodactyl \
  --name edge-ams-01 \
  --agent-ip 203.0.113.10 \
  --gateway-region AMS01 \
  --org-id <org-uuid>

virtfusion and solusvm are the other two values for --hypervisor-driver.

Game servers first, hypervisor later

nr cluster install-hypervisor --hypervisor-driver proxmox --agent-id <agent-uuid>

--agent-id stores that driver on the agent. Omit it to install the operator on the current cluster only. A second hypervisor on the same cluster is rejected.

Panel flags

Flag	Rule
`--panel-url`	Optional. `http` or `https`, no path. Include the scheme. Otherwise `PTERODACTYL_PANEL_URL`, or a prompt.
Application key	The command asks for the `ptla_` key and shows it as you type. Skip that with `export PTERODACTYL_APPLICATION_KEY=<key>`.
Client key	The command asks for the `ptlc_` key and shows it as you type. Skip that with `export PTERODACTYL_CLIENT_KEY=<key>`.
`--panel-user-id`	Optional. Panel user that owns NodeRings servers. The client key must belong to this user. Otherwise `PTERODACTYL_PANEL_USER_ID`, or a prompt.
`--operator-chart`	On `install-pterodactyl`: local chart or `oci://harbor.noderings.com/nrings/pterodactyl-operator`.
`--pterodactyl-chart`	The same chart, when the flags are on `nr cluster register`.

install-pterodactyl writes Secret operator-pterodactyl-operator-panel-credentials in pterodactyl-system. It does not print the keys, and it does not send them to NodeRings.

To replace a wrong panel URL or key, unset PTERODACTYL_PANEL_URL, PTERODACTYL_APPLICATION_KEY, PTERODACTYL_CLIENT_KEY, and PTERODACTYL_PANEL_USER_ID, run nr cluster install-pterodactyl again, then k3s kubectl -n pterodactyl-system rollout restart deployment. If the platform form URL is also wrong, edit it to the same origin (no /admin). The form does not store the keys.

After the operator is installed, create a Pterodactyl platform in the console. A hypervisor platform is a separate step, and only after a hypervisor is installed.